FEAT: Modernized to support latest Pythons and DRF JSONAPI

README.md

@@ -1,26 +1,84 @@
-# Enhanced Django Rest Framework JSON Api
+# Enhanced Django REST framework JSON:API
 
-This is a library aimed to fix some classes in Django Rest Framework and Django Rest Framework JSON Api libraries.
+Shared, tested primitives used by several django projects on top of
+[`djangorestframework-jsonapi`](https://github.com/django-json-api/django-rest-framework-json-api).
 
-## Contents
+## Compatibility
 
-### enhanced_drf_jsonapi module
+- 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
 
-#### API
-- ##### class PreloadIncludesMixin
-  Overwrites the method get_queryset(self, *args, **kwarg)
-- ##### class ReasonableModelViewSet
-  Overwrites the attribute http_method_names 
+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.
 
-- ##### class ReasonableModelSerializer 
-  Overwrites the method get_field_names(self, declared_fields, info)
+## API primitives
 
-#### PAGINATION
-- ##### class NgxJsonApiPageNumberPagination
-  Overwrites the method get_paginated_response(self, data)
+```python
+from enhanced_drf_jsonapi.api import (
+    ReasonableModelSerializer,
+    ReasonableModelViewSet,
+    basic_filter,
+    date_filter,
+    int_filter,
+    text_filter,
+)
+from enhanced_drf_jsonapi.pagination import NgxJsonApiPageNumberPagination
+```
 
-## Build the library
-In root directory, run `python setup.py bdist_wheel`. This will create a wheel file in `dist` folder.
+- `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.
 
-## Install 
-Run this command in the desired python environment `pip install path/to/wheelfile.whl`.
+## 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.