django-ninja-jsonapi 0.2.0__tar.gz

django_ninja_jsonapi-0.2.0/PKG-INFO

@@ -0,0 +1,174 @@
+Metadata-Version: 2.3
+Name: django-ninja-jsonapi
+Version: 0.2.0
+Summary: JSON:API toolkit for Django Ninja
+Author: Ignace Maes
+Author-email: Ignace Maes <10243652+IgnaceMaes@users.noreply.github.com>
+Requires-Dist: django>=4.2
+Requires-Dist: django-ninja>=1.0
+Requires-Dist: orjson>=3.10.0
+Requires-Dist: pydantic>=2.6.0
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# django-ninja-jsonapi
+
+JSON:API toolkit for Django Ninja.
+
+[![CI](https://github.com/ignacemaes/django-ninja-jsonapi/actions/workflows/ci.yml/badge.svg)](https://github.com/ignacemaes/django-ninja-jsonapi/actions/workflows/ci.yml)
+[![Package](https://github.com/ignacemaes/django-ninja-jsonapi/actions/workflows/package.yml/badge.svg)](https://github.com/ignacemaes/django-ninja-jsonapi/actions/workflows/package.yml)
+
+This project ports the core ideas of `fastapi-jsonapi` to a Django Ninja + Django ORM stack.
+
+Full documentation is available in [docs/index.md](docs/index.md).
+
+## Status
+
+- Working baseline for resource registration and route generation (`GET`, `GET LIST`, `POST`, `PATCH`, `DELETE`).
+- Strict query parsing for JSON:API-style `filter`, `sort`, `include`, `fields`, and `page` parameters.
+- JSON:API exception payload handling.
+- Atomic operations endpoint wiring (`/operations`).
+- Django ORM data-layer baseline for CRUD + basic relationship handling.
+- Top-level/resource/relationship `links` in responses.
+- Django ORM include optimization (`select_related`/`prefetch_related` split) with optional include mapping overrides.
+- Logical filter groups (`and`/`or`/`not`) and cursor pagination (`page[cursor]`).
+
+## Requirements
+
+- Python 3.10+
+- Django 4.2+
+- Django Ninja 1.0+
+
+## Install
+
+```bash
+uv add django-ninja-jsonapi
+```
+
+or
+
+- `pip install django-ninja-jsonapi`
+- `poetry add django-ninja-jsonapi`
+- `pdm add django-ninja-jsonapi`
+
+## Quick start
+
+### 1) Define a Django model and a schema
+
+```python
+from django.db import models
+from pydantic import BaseModel
+
+
+class Customer(models.Model):
+    name = models.CharField(max_length=128)
+
+
+class CustomerSchema(BaseModel):
+    name: str
+```
+
+### 2) Create a JSON:API view class
+
+```python
+from django_ninja_jsonapi import ViewBaseGeneric
+
+
+class CustomerView(ViewBaseGeneric):
+    pass
+```
+
+### 3) Register resources with `ApplicationBuilder`
+
+```python
+from ninja import NinjaAPI
+
+from django_ninja_jsonapi import ApplicationBuilder
+
+api = NinjaAPI()
+builder = ApplicationBuilder(api)
+
+builder.add_resource(
+    path="/customers",
+    tags=["customers"],
+    resource_type="customer",
+    view=CustomerView,
+    model=Customer,
+    schema=CustomerSchema,
+)
+
+builder.initialize()
+```
+
+### 4) Mount API in Django URLs
+
+```python
+from django.urls import path
+from .api import api
+
+urlpatterns = [
+    path("api/", api.urls),
+]
+```
+
+## Configuration
+
+Set JSON:API options in Django settings:
+
+```python
+NINJA_JSONAPI = {
+    "MAX_INCLUDE_DEPTH": 3,
+    "MAX_PAGE_SIZE": 100,
+    "ALLOW_DISABLE_PAGINATION": True,
+}
+```
+
+## Exported public API
+
+```python
+from django_ninja_jsonapi import ApplicationBuilder, QueryStringManager, HTTPException, BadRequest, ViewBaseGeneric
+```
+
+## Development
+
+```bash
+uv run ruff format src tests
+uv run ruff check src tests
+uv run pytest --cov=src/django_ninja_jsonapi --cov-report=term-missing
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution workflow.
+
+## Release process
+
+Releases are automated with GitHub Actions:
+
+1. Merge conventional-commit PRs into `main`.
+2. `Release Please` opens or updates a release PR with version bump + changelog updates.
+3. Merge the release PR to create a GitHub Release.
+4. `Publish to PyPI` runs on `release: published` and uploads the built package to PyPI.
+
+Workflows:
+
+- `.github/workflows/release-please.yml`
+- `.github/workflows/publish.yml`
+
+Required repository secrets:
+
+- `REPO_ADMIN_TOKEN` (used by Release Please)
+- `PYPI_API_TOKEN` (used for PyPI publishing)
+
+## Test coverage
+
+Current tests cover:
+
+- Application builder initialization and route registration behavior
+- Query-string parsing behavior
+- Django ORM query-building mapping (`filter`/`sort` translation)
+- Exception handler response shape
+
+## Notes
+
+- This project is Django Ninja + Django ORM focused.
+- SQLAlchemy-specific modules have been removed to keep the codebase simpler and consistent.
+- CI runs on pull requests and pushes to `main`.

django_ninja_jsonapi-0.2.0/README.md

@@ -0,0 +1,161 @@
+# django-ninja-jsonapi
+
+JSON:API toolkit for Django Ninja.
+
+[![CI](https://github.com/ignacemaes/django-ninja-jsonapi/actions/workflows/ci.yml/badge.svg)](https://github.com/ignacemaes/django-ninja-jsonapi/actions/workflows/ci.yml)
+[![Package](https://github.com/ignacemaes/django-ninja-jsonapi/actions/workflows/package.yml/badge.svg)](https://github.com/ignacemaes/django-ninja-jsonapi/actions/workflows/package.yml)
+
+This project ports the core ideas of `fastapi-jsonapi` to a Django Ninja + Django ORM stack.
+
+Full documentation is available in [docs/index.md](docs/index.md).
+
+## Status
+
+- Working baseline for resource registration and route generation (`GET`, `GET LIST`, `POST`, `PATCH`, `DELETE`).
+- Strict query parsing for JSON:API-style `filter`, `sort`, `include`, `fields`, and `page` parameters.
+- JSON:API exception payload handling.
+- Atomic operations endpoint wiring (`/operations`).
+- Django ORM data-layer baseline for CRUD + basic relationship handling.
+- Top-level/resource/relationship `links` in responses.
+- Django ORM include optimization (`select_related`/`prefetch_related` split) with optional include mapping overrides.
+- Logical filter groups (`and`/`or`/`not`) and cursor pagination (`page[cursor]`).
+
+## Requirements
+
+- Python 3.10+
+- Django 4.2+
+- Django Ninja 1.0+
+
+## Install
+
+```bash
+uv add django-ninja-jsonapi
+```
+
+or
+
+- `pip install django-ninja-jsonapi`
+- `poetry add django-ninja-jsonapi`
+- `pdm add django-ninja-jsonapi`
+
+## Quick start
+
+### 1) Define a Django model and a schema
+
+```python
+from django.db import models
+from pydantic import BaseModel
+
+
+class Customer(models.Model):
+    name = models.CharField(max_length=128)
+
+
+class CustomerSchema(BaseModel):
+    name: str
+```
+
+### 2) Create a JSON:API view class
+
+```python
+from django_ninja_jsonapi import ViewBaseGeneric
+
+
+class CustomerView(ViewBaseGeneric):
+    pass
+```
+
+### 3) Register resources with `ApplicationBuilder`
+
+```python
+from ninja import NinjaAPI
+
+from django_ninja_jsonapi import ApplicationBuilder
+
+api = NinjaAPI()
+builder = ApplicationBuilder(api)
+
+builder.add_resource(
+    path="/customers",
+    tags=["customers"],
+    resource_type="customer",
+    view=CustomerView,
+    model=Customer,
+    schema=CustomerSchema,
+)
+
+builder.initialize()
+```
+
+### 4) Mount API in Django URLs
+
+```python
+from django.urls import path
+from .api import api
+
+urlpatterns = [
+    path("api/", api.urls),
+]
+```
+
+## Configuration
+
+Set JSON:API options in Django settings:
+
+```python
+NINJA_JSONAPI = {
+    "MAX_INCLUDE_DEPTH": 3,
+    "MAX_PAGE_SIZE": 100,
+    "ALLOW_DISABLE_PAGINATION": True,
+}
+```
+
+## Exported public API
+
+```python
+from django_ninja_jsonapi import ApplicationBuilder, QueryStringManager, HTTPException, BadRequest, ViewBaseGeneric
+```
+
+## Development
+
+```bash
+uv run ruff format src tests
+uv run ruff check src tests
+uv run pytest --cov=src/django_ninja_jsonapi --cov-report=term-missing
+```
+
+See [CONTRIBUTING.md](CONTRIBUTING.md) for the full contribution workflow.
+
+## Release process
+
+Releases are automated with GitHub Actions:
+
+1. Merge conventional-commit PRs into `main`.
+2. `Release Please` opens or updates a release PR with version bump + changelog updates.
+3. Merge the release PR to create a GitHub Release.
+4. `Publish to PyPI` runs on `release: published` and uploads the built package to PyPI.
+
+Workflows:
+
+- `.github/workflows/release-please.yml`
+- `.github/workflows/publish.yml`
+
+Required repository secrets:
+
+- `REPO_ADMIN_TOKEN` (used by Release Please)
+- `PYPI_API_TOKEN` (used for PyPI publishing)
+
+## Test coverage
+
+Current tests cover:
+
+- Application builder initialization and route registration behavior
+- Query-string parsing behavior
+- Django ORM query-building mapping (`filter`/`sort` translation)
+- Exception handler response shape
+
+## Notes
+
+- This project is Django Ninja + Django ORM focused.
+- SQLAlchemy-specific modules have been removed to keep the codebase simpler and consistent.
+- CI runs on pull requests and pushes to `main`.

django_ninja_jsonapi-0.2.0/pyproject.toml

@@ -0,0 +1,49 @@
+[project]
+name = "django-ninja-jsonapi"
+version = "0.2.0"
+description = "JSON:API toolkit for Django Ninja"
+readme = "README.md"
+authors = [
+    { name = "Ignace Maes", email = "10243652+IgnaceMaes@users.noreply.github.com" }
+]
+requires-python = ">=3.10"
+dependencies = [
+    "django>=4.2",
+    "django-ninja>=1.0",
+    "orjson>=3.10.0",
+    "pydantic>=2.6.0",
+]
+
+[build-system]
+requires = ["uv_build>=0.10.3,<0.11.0"]
+build-backend = "uv_build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+    "pytest-asyncio>=1.3.0",
+    "pytest-cov>=6.0.0",
+    "pytest-django>=4.12.0",
+    "ruff>=0.15.2",
+]
+
+[tool.ruff]
+target-version = "py310"
+line-length = 120
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "B"]
+
+[tool.pytest.ini_options]
+DJANGO_SETTINGS_MODULE = "tests.settings"
+pythonpath = [".", "src"]
+django_find_project = false
+
+[tool.coverage.run]
+branch = true
+source = ["src/django_ninja_jsonapi"]
+
+[tool.coverage.report]
+show_missing = true
+skip_covered = true
+fail_under = 45

django_ninja_jsonapi-0.2.0/src/django_ninja_jsonapi/VERSION

@@ -0,0 +1 @@
+0.1.0

django_ninja_jsonapi-0.2.0/src/django_ninja_jsonapi/__init__.py

@@ -0,0 +1,34 @@
+"""JSON API utils package."""
+
+from pathlib import Path
+from typing import Any
+
+from django_ninja_jsonapi.exceptions import BadRequest
+from django_ninja_jsonapi.exceptions.json_api import HTTPException
+from django_ninja_jsonapi.querystring import QueryStringManager
+from django_ninja_jsonapi.renderers import JSONAPIRenderer
+
+__version__ = Path(__file__).parent.joinpath("VERSION").read_text().strip()
+
+__all__ = [
+    "ApplicationBuilder",
+    "BadRequest",
+    "HTTPException",
+    "JSONAPIRenderer",
+    "QueryStringManager",
+    "ViewBaseGeneric",
+]
+
+
+def __getattr__(name: str) -> Any:
+    if name == "ApplicationBuilder":
+        from django_ninja_jsonapi.api.application_builder import ApplicationBuilder
+
+        return ApplicationBuilder
+
+    if name == "ViewBaseGeneric":
+        from django_ninja_jsonapi.generics import ViewBaseGeneric
+
+        return ViewBaseGeneric
+
+    raise AttributeError(name)

django_ninja_jsonapi-0.2.0/src/django_ninja_jsonapi/api/application_builder.py

@@ -0,0 +1,216 @@
+from http import HTTPStatus
+from typing import Any, Callable, Iterable, Optional, Type
+
+from ninja import NinjaAPI, Router
+from pydantic import BaseModel
+
+from django_ninja_jsonapi.api.endpoint_builder import EndpointsBuilder
+from django_ninja_jsonapi.api.schemas import ResourceData
+from django_ninja_jsonapi.atomic.atomic import AtomicOperations
+from django_ninja_jsonapi.data_typing import TypeModel
+from django_ninja_jsonapi.exceptions import HTTPException
+from django_ninja_jsonapi.exceptions.handlers import base_exception_handler
+from django_ninja_jsonapi.renderers import JSONAPIRenderer
+from django_ninja_jsonapi.schema_builder import SchemaBuilder
+from django_ninja_jsonapi.storages.models_storage import models_storage
+from django_ninja_jsonapi.storages.schemas_storage import schemas_storage
+from django_ninja_jsonapi.storages.views_storage import views_storage
+from django_ninja_jsonapi.views.enums import Operation
+
+
+class ApplicationBuilderError(Exception):
+    pass
+
+
+class ApplicationBuilder:
+    def __init__(
+        self,
+        api: NinjaAPI,
+        base_router: Optional[Router] = None,
+        exception_handler: Optional[Callable] = None,
+        **base_router_include_kwargs,
+    ):
+        self._api = api
+        self._base_router = base_router or Router()
+        self._base_router_include_kwargs = base_router_include_kwargs
+        self._routers: dict[str, Router] = {}
+        self._router_include_kwargs: dict[str, dict[str, Any]] = {}
+        self._resource_data: dict[str, ResourceData] = {}
+        self._exception_handler: Callable = exception_handler or base_exception_handler
+        self._initialized = False
+        self._api.renderer = JSONAPIRenderer()
+
+    def add_resource(
+        self,
+        path: str,
+        tags: Iterable[str],
+        resource_type: str,
+        view: Type[Any],
+        model: Type[TypeModel],
+        schema: Type[BaseModel],
+        router: Optional[Router] = None,
+        schema_in_post: Optional[Type[BaseModel]] = None,
+        schema_in_patch: Optional[Type[BaseModel]] = None,
+        pagination_default_size: Optional[int] = 25,
+        pagination_default_number: Optional[int] = 1,
+        pagination_default_offset: Optional[int] = None,
+        pagination_default_limit: Optional[int] = None,
+        operations: Iterable[Operation] = (),
+        ending_slash: bool = True,
+        model_id_field_name: str = "id",
+        include_router_kwargs: Optional[dict] = None,
+    ):
+        if self._initialized:
+            raise ApplicationBuilderError("Can't add resource after app initialization")
+
+        if resource_type in self._resource_data:
+            raise ApplicationBuilderError(f"Resource {resource_type!r} already registered")
+
+        if include_router_kwargs is not None and router is None:
+            raise ApplicationBuilderError(
+                "The argument 'include_router_kwargs' is not allowed when 'router' is missing"
+            )
+
+        models_storage.add_model(resource_type, model, model_id_field_name, path)
+        views_storage.add_view(resource_type, view)
+
+        dto = SchemaBuilder(resource_type).create_schemas(
+            schema=schema,
+            schema_in_post=schema_in_post,
+            schema_in_patch=schema_in_patch,
+        )
+
+        resource_operations = list(operations) or Operation.real_operations()
+        if Operation.ALL in resource_operations:
+            resource_operations = Operation.real_operations()
+
+        self._resource_data[resource_type] = ResourceData(
+            path=path,
+            tags=list(tags),
+            view=view,
+            model=model,
+            source_schema=schema,
+            schema_in_post=schema_in_post,
+            schema_in_post_data=dto.schema_in_post_data,
+            schema_in_patch=schema_in_patch,
+            schema_in_patch_data=dto.schema_in_patch_data,
+            detail_response_schema=dto.detail_response_schema,
+            list_response_schema=dto.list_response_schema,
+            pagination_default_size=pagination_default_size,
+            pagination_default_number=pagination_default_number,
+            pagination_default_offset=pagination_default_offset,
+            pagination_default_limit=pagination_default_limit,
+            operations=resource_operations,
+            ending_slash=ending_slash,
+        )
+
+        resolved_router = router or self._base_router
+        self._routers[resource_type] = resolved_router
+        self._router_include_kwargs[resource_type] = include_router_kwargs or {}
+
+    def initialize(self) -> NinjaAPI:
+        if self._initialized:
+            raise ApplicationBuilderError("Application already initialized")
+
+        self._initialized = True
+        self._register_exception_handler()
+
+        for resource_type, data in self._resource_data.items():
+            builder = EndpointsBuilder(resource_type, data)
+            router = self._routers[resource_type]
+
+            for operation in data.operations:
+                name, endpoint = builder.create_common_ninja_endpoint(operation)
+                method = operation.http_method().lower()
+                path = self._create_path(
+                    path=data.path,
+                    include_object_id=operation in {Operation.GET, Operation.UPDATE, Operation.DELETE},
+                    ending_slash=data.ending_slash,
+                )
+
+                response_schema = self._response_for(data, operation)
+                route = getattr(router, method)
+                route(
+                    path,
+                    response=response_schema,
+                    tags=data.tags,
+                    operation_id=name,
+                )(endpoint)
+
+            relationships_info = schemas_storage.get_relationships_info(
+                resource_type=resource_type,
+                operation_type="get",
+            )
+            for relationship_name, info in relationships_info.items():
+                if not views_storage.has_view(info.resource_type):
+                    continue
+
+                operation = Operation.GET_LIST if info.many else Operation.GET
+                relationship_name_id, relationship_endpoint = builder.create_relationship_endpoint(
+                    parent_resource_type=resource_type,
+                    relationship_name=relationship_name,
+                    operation=operation,
+                )
+                relationship_path = self._create_relationship_path(
+                    resource_path=data.path,
+                    relationship_name=relationship_name,
+                    ending_slash=data.ending_slash,
+                )
+
+                related_data = self._resource_data.get(info.resource_type, data)
+                relationship_response = (
+                    related_data.list_response_schema if info.many else related_data.detail_response_schema
+                )
+                getattr(router, operation.http_method().lower())(
+                    relationship_path,
+                    response=relationship_response,
+                    tags=data.tags,
+                    operation_id=relationship_name_id,
+                )(relationship_endpoint)
+
+        registered_routers = set()
+        for resource_type, router in self._routers.items():
+            if id(router) in registered_routers:
+                continue
+
+            include_kwargs = self._router_include_kwargs.get(resource_type, {})
+            if router is self._base_router:
+                include_kwargs = self._base_router_include_kwargs
+
+            self._api.add_router("", router, **include_kwargs)
+            registered_routers.add(id(router))
+
+        atomic = AtomicOperations()
+        self._api.add_router("", atomic.router)
+
+        return self._api
+
+    def _register_exception_handler(self):
+        add_handler = getattr(self._api, "add_exception_handler", None)
+        if callable(add_handler):
+            add_handler(HTTPException, self._exception_handler)
+
+    @staticmethod
+    def _response_for(data: ResourceData, operation: Operation):
+        if operation == Operation.DELETE:
+            return {HTTPStatus.NO_CONTENT: None}
+        if operation == Operation.GET_LIST:
+            return data.list_response_schema
+        return data.detail_response_schema
+
+    @staticmethod
+    def _create_path(path: str, include_object_id: bool, ending_slash: bool) -> str:
+        base_path = path.rstrip("/")
+        if include_object_id:
+            base_path = f"{base_path}/{{obj_id}}"
+        if ending_slash:
+            return f"{base_path}/"
+        return base_path
+
+    @staticmethod
+    def _create_relationship_path(resource_path: str, relationship_name: str, ending_slash: bool) -> str:
+        base_path = resource_path.rstrip("/")
+        path = f"{base_path}/{{obj_id}}/relationships/{relationship_name}"
+        if ending_slash:
+            return f"{path}/"
+        return path