Metadata-Version: 2.4
Name: enhanced-drf-jsonapi
Version: 1.1.0
Summary: Shared Django REST framework JSON:API primitives and hardened error handling
Author: Iñigo R.
License-Expression: MIT
Project-URL: Repository, https://git.ruiz.wang/Public/enhanced-drf-jsonapi
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: Django
Classifier: Framework :: Django :: 5.2
Classifier: Framework :: Django :: 6.0
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: djangorestframework-jsonapi<9,>=7.1
Provides-Extra: test
Requires-Dist: pytest<10,>=8; extra == "test"
Requires-Dist: pytest-cov<8,>=5; extra == "test"
Provides-Extra: dev
Requires-Dist: build<2,>=1.3; extra == "dev"
Requires-Dist: pytest<10,>=8; extra == "dev"
Requires-Dist: pytest-cov<8,>=5; extra == "dev"
Requires-Dist: ruff<1,>=0.12; extra == "dev"
Requires-Dist: tox<5,>=4.30; extra == "dev"
Requires-Dist: twine<7,>=6; extra == "dev"
Dynamic: license-file

# Enhanced Django REST framework JSON:API

Shared, tested primitives used by SUKI, Gigtonic, Diveclick, and God-i on top of
[`djangorestframework-jsonapi`](https://github.com/django-json-api/django-rest-framework-json-api).

## Compatibility

- Python 3.10–3.14
- `djangorestframework-jsonapi` 7.1 and 8.1
- The Django and Django REST framework releases accepted by the selected
  `djangorestframework-jsonapi` version

The GitLab test matrix exercises every supported Python/DRF JSON:API
combination. Applications may stay on 7.1 while upgrading independently, then
move to 8.1 without changing imports from this package.

## API primitives

```python
from enhanced_drf_jsonapi.api import (
    ReasonableModelSerializer,
    ReasonableModelViewSet,
    basic_filter,
    date_filter,
    int_filter,
    text_filter,
)
from enhanced_drf_jsonapi.pagination import NgxJsonApiPageNumberPagination
```

- `PreloadIncludesMixin` applies `select_for_includes` and
  `prefetch_for_includes` rules for requested JSON:API relationships.
- `ReasonableModelViewSet` exposes the standard resource methods and combines
  the JSON:API relationship/prefetch mixins.
- `ReasonableModelSerializer` includes declared relationship fields requested
  through GET includes and POST/PATCH payloads.
- `NgxJsonApiPageNumberPagination` preserves the pagination metadata and link
  shape expected by `ngx-jsonapi` clients.

## Hardened exception handling

Use the handler globally so every DRF view, including plain `APIView` classes,
returns the same JSON:API error shape:

```python
REST_FRAMEWORK = {
    "EXCEPTION_HANDLER": (
        "enhanced_drf_jsonapi.exceptions.hardened_exception_handler"
    ),
}
```

Alternatively, opt individual classes in:

```python
from enhanced_drf_jsonapi.api import HardenedGenericAPIView, HardenedModelViewSet
```

Expected DRF exceptions retain their status and detail. Unexpected exceptions
are logged with a generated error identifier and returned as a sanitized HTTP
500 response carrying the same identifier in `X-Error-ID`. Internal exception
messages and tracebacks are never included in the response.

Known application conflicts must be raised deliberately rather than treating
every database integrity failure as a client error:

```python
from enhanced_drf_jsonapi.exceptions import APIConflictException

raise APIConflictException()
```

## Development

```bash
python -m pip install -e ".[dev]"
python -m pytest
python -m ruff check .
python -m build
python -m twine check dist/*
```

Run all locally available compatibility environments with `tox`. CI runs the
complete Python 3.10–3.14 × DRF JSON:API 7.1/8.1 matrix.
