django-ninja-aio-crud 2.0.0rc7__tar.gz → 2.1.0__tar.gz

{django_ninja_aio_crud-2.0.0rc7 → django_ninja_aio_crud-2.1.0}/.github/workflows/coverage.yml

@@ -27,6 +27,6 @@ jobs:
           coverage xml
 
       - name: Coverage
-        uses: codecov/codecov-action@v5.5.1
+        uses: codecov/codecov-action@v5.5.2
         with:
           token: ${{ secrets.CODECOV_TOKEN }}

{django_ninja_aio_crud-2.0.0rc7 → django_ninja_aio_crud-2.1.0}/.github/workflows/docs.yml

@@ -7,7 +7,7 @@ on:
         description: 'Docs version to deploy (e.g. v1.0.0)'
         required: true
         default: 'dev'
-        type: choice  # ← SonarQube compliant: predefined safe options
+        type: choice
         options:
           - dev
           - stable
@@ -16,12 +16,23 @@ on:
       make_latest:
         description: 'Set as "latest" and default?'
         type: boolean
-        default: true
+        default: false
 
       delete_version:
-          description: 'Version to DELETE (leave empty to skip)'
-          required: false
-          default: ''
+        description: 'Docs version to delete'
+        required: false
+        default: ''
+        type: choice
+        options:
+          - ''
+          - dev
+          - stable
+          - "1.0"
+          - "2.0"
+      delete_confirm:
+        description: 'Confirm deletion of the selected version'
+        type: boolean
+        default: false
 
 permissions:
   contents: write
@@ -29,8 +40,6 @@ permissions:
 jobs:
   deploy:
     runs-on: ubuntu-latest
-    
-    # Only trusted events (SonarQube safe)
     if: github.event_name == 'push' || github.event_name == 'workflow_dispatch'
 
     steps:
@@ -52,18 +61,15 @@ jobs:
       - name: Compute VERSION and MAKE_LATEST
         id: vars
         env:
-          # Assign untrusted input to env var FIRST (SonarQube compliant)
           INPUT_VERSION: ${{ inputs.docs_version }}
         shell: bash
         run: |
-          # Now use safe shell variable $INPUT_VERSION
           if [ "${{ github.event_name }}" = "workflow_dispatch" ] && [ -n "$INPUT_VERSION" ]; then
             VERSION="$INPUT_VERSION"
           else
             VERSION="dev"
           fi
 
-          # Boolean input is always safe ("true"/"false")
           if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
             MAKE_LATEST="${{ inputs.make_latest }}"
           else
@@ -82,29 +88,54 @@ jobs:
           git fetch --all --tags
           git fetch origin gh-pages --depth=1 || true
           
-          # Idempotent worktree setup
           if git worktree list | grep -q " gh-pages "; then
             git worktree remove gh-pages --force
           fi
           git worktree add gh-pages gh-pages 2>/dev/null || git worktree add gh-pages origin/gh-pages
 
           if [ "$MAKE_LATEST" = "true" ]; then
-            echo "🚀 Deploying $VERSION as latest and default"
+            echo "Deploying $VERSION as latest and default"
             mike deploy --push --update-aliases "$VERSION" latest --ignore-remote-status
             mike set-default "$VERSION"
           else
-            echo "📦 Deploying $VERSION (non-latest)"
+            echo "Deploying $VERSION (non-latest)"
             mike deploy --push "$VERSION" --ignore-remote-status
           fi
 
           git worktree remove gh-pages --force
 
-      - name: Delete version
-        if: inputs.delete_version != ''
+      - name: Delete version (safe)
+        if: github.event_name == 'workflow_dispatch' && inputs.delete_version != '' && inputs.delete_confirm == true
+        env:
+          DELETE_VERSION: ${{ inputs.delete_version }}
+        shell: bash
         run: |
-          echo "Deleting version: ${{ inputs.delete_version }}"
-          mike delete "${{ inputs.delete_version }}" --push
-          echo "Version ${{ inputs.delete_version }} deleted successfully"
+          set -euo pipefail
+
+          echo "Requested delete: $DELETE_VERSION"
+
+          # Protect aliases and default
+          if [ "$DELETE_VERSION" = "latest" ] || [ "$DELETE_VERSION" = "stable" ]; then
+            echo "Refusing to delete protected alias: $DELETE_VERSION"
+            exit 1
+          fi
+
+          # Load current default; fail if attempting to delete it
+          CURRENT_DEFAULT="$(mike default || true)"
+          if [ -n "$CURRENT_DEFAULT" ] && [ "$DELETE_VERSION" = "$CURRENT_DEFAULT" ]; then
+            echo "Refusing to delete current default docs version: $DELETE_VERSION"
+            exit 1
+          fi
+
+          # Ensure version exists before deleting
+          if ! mike list | awk '{print $1}' | grep -Fxq "$DELETE_VERSION"; then
+            echo "Version '$DELETE_VERSION' not found. Nothing to delete."
+            exit 0
+          fi
+
+          echo "Deleting version: $DELETE_VERSION"
+          mike delete "$DELETE_VERSION" --push
+          echo "Version '$DELETE_VERSION' deleted successfully"
 
       - name: List versions
         run: mike list

{django_ninja_aio_crud-2.0.0rc7 → django_ninja_aio_crud-2.1.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 2.0.0rc7
+Version: 2.1.0
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
 Requires-Python: >=3.10

{django_ninja_aio_crud-2.0.0rc7 → django_ninja_aio_crud-2.1.0}/docs/api/views/api_view_set.md

@@ -402,6 +402,57 @@ class UserViewSet(APIViewSet):
         return queryset
 ```
 
+---
+
+## ReadOnlyViewSet
+
+ReadOnlyViewSet is a convenience subclass of APIViewSet that enables only list and retrieve endpoints. It is equivalent to setting `disable = ["create", "update", "delete"]`.
+
+Generated endpoints:
+
+- GET `/{base}/` -> List
+- GET `/{base}/{pk}` -> Retrieve
+
+Minimal usage:
+
+```python
+class MyModelReadOnlyViewSet(ReadOnlyViewSet):
+    model = MyModel
+    api = api
+
+MyModelReadOnlyViewSet().add_views_to_route()
+```
+
+Notes:
+
+- Supports all features of APIViewSet relevant to read operations (pagination, list filters, auth per verb, dynamic schema generation when using ModelSerializer).
+- M2M endpoints can still be added via `m2m_relations` if desired.
+
+## WriteOnlyViewSet
+
+WriteOnlyViewSet is a convenience subclass of APIViewSet that enables only create, update, and delete endpoints. It is equivalent to setting `disable = ["list", "retrieve"]`.
+
+Generated endpoints:
+
+- POST `/{base}/` -> Create
+- PATCH `/{base}/{pk}/` -> Update
+- DELETE `/{base}/{pk}/` -> Delete
+
+Minimal usage:
+
+```python
+class MyModelWriteOnlyViewSet(WriteOnlyViewSet):
+    model = MyModel
+    api = api
+
+MyModelWriteOnlyViewSet().add_views_to_route()
+```
+
+Notes:
+
+- Supports auth per verb and dynamic schema generation for write operations when using ModelSerializer.
+- M2M endpoints can still be added via `m2m_relations` if desired.
+
 ## See Also
 
 - [ModelSerializer](../models/model_serializer.md)

django_ninja_aio_crud-2.1.0/docs/auth.md

@@ -0,0 +1,225 @@
+# JWT Authentication and AsyncJwtBearer
+
+This page documents the JWT helpers and the `AsyncJwtBearer` class in `ninja_aio/auth.py`, including configuration, validation, and usage in Django Ninja.
+
+## Overview
+
+- `AsyncJwtBearer`: Asynchronous HTTP Bearer auth that verifies JWTs, validates claims via a registry, and delegates user resolution to `auth_handler`.
+- Helpers:
+  - `validate_key`: Ensures JWK keys are present and of the correct type.
+  - `validate_mandatory_claims`: Ensures `iss` and `aud` are present (from settings if not provided).
+  - `encode_jwt`: Signs a JWT with time-based claims (`iat`, `nbf`, `exp`) and mandatory `iss/aud`.
+  - `decode_jwt`: Verifies and decodes a JWT with a public key and allowed algorithms.
+
+## Configuration without settings
+
+Settings are not required. Provide keys and claims explicitly:
+
+- Pass `private_key` to `encode_jwt` and `public_key` to `decode_jwt`/`AsyncJwtBearer.jwt_public`.
+- Include `iss` and `aud` directly in the `claims` you encode if you are not using settings.
+
+Example key usage without settings:
+
+```python
+# ...existing code...
+from joserfc import jwk
+from ninja_aio.auth import encode_jwt, decode_jwt
+
+private_key = jwk.RSAKey.import_key(open("priv.jwk").read())
+public_key = jwk.RSAKey.import_key(open("pub.jwk").read())
+
+token = encode_jwt(
+    claims={"sub": "123", "iss": "https://auth.example", "aud": "my-api"},
+    duration=3600,
+    private_key=private_key,
+    algorithm="RS256",
+)
+
+decoded = decode_jwt(token=token, public_key=public_key, algorithms=["RS256"])
+# ...existing code...
+```
+
+### Mandatory claims
+
+The library enforces `iss` and `aud` via `JWT_MANDATORY_CLAIMS`. If you do not use settings, include them in the payload you pass to `encode_jwt`.
+
+## Configuration with settings (optional)
+
+You can centralize configuration in Django settings and omit explicit keys/claims:
+
+- `JWT_PRIVATE_KEY`: jwk.RSAKey or jwk.ECKey for signing
+- `JWT_PUBLIC_KEY`: jwk.RSAKey or jwk.ECKey for verification
+- `JWT_ISSUER`: issuer string
+- `JWT_AUDIENCE`: audience string
+
+When present:
+
+- `encode_jwt` reads `JWT_PRIVATE_KEY` if `private_key` is not passed, and fills `iss`/`aud` via `validate_mandatory_claims` if missing.
+- `decode_jwt` reads `JWT_PUBLIC_KEY` if `public_key` is not passed.
+- `AsyncJwtBearer` can read the public key from settings by assigning `jwt_public = settings.JWT_PUBLIC_KEY`.
+
+```python
+# settings.py (example)
+JWT_PRIVATE_KEY = jwk.RSAKey.import_key(open("priv.jwk").read())
+JWT_PUBLIC_KEY = jwk.RSAKey.import_key(open("pub.jwk").read())
+JWT_ISSUER = "https://auth.example"
+JWT_AUDIENCE = "my-api"
+```
+
+Usage without passing keys/claims explicitly:
+
+```python
+from ninja_aio.auth import encode_jwt, decode_jwt
+# claims missing iss/aud will be completed from settings
+token = encode_jwt(claims={"sub": "123"}, duration=3600)
+
+decoded = decode_jwt(token=token)  # uses settings.JWT_PUBLIC_KEY
+```
+
+AsyncJwtBearer wired to settings:
+
+```python
+from django.conf import settings
+from ninja_aio.auth import AsyncJwtBearer
+
+class SettingsBearer(AsyncJwtBearer):
+    jwt_public = settings.JWT_PUBLIC_KEY
+    claims = {
+        "iss": {"value": settings.JWT_ISSUER},
+        "aud": {"value": settings.JWT_AUDIENCE},
+        # Optionally require time-based claims:
+        # "exp": {"essential": True},
+        # "nbf": {"essential": True},
+    }
+
+    async def auth_handler(self, request):
+        sub = self.dcd.claims.get("sub")
+        return {"user_id": sub}
+```
+
+## AsyncJwtBearer
+
+### Key points
+
+- `jwt_public`: Must be a JWK (RSA or EC) used to verify signatures.
+- `claims`: Dict passed to `jwt.JWTClaimsRegistry` defining validations (e.g., `iss`, `aud`, `exp`, `nbf`).
+- `algorithms`: Allowed algorithms (default `["RS256"]`).
+- `dcd`: Set after successful decode; instance of `jwt.Token` containing `header` and `claims`.
+- `get_claims()`: Builds the claim registry from `claims`.
+- `validate_claims(claims)`: Validates decoded claims; raises `jose.errors.JoseError` on failure.
+- `auth_handler(request)`: Async hook to resolve application user given the decoded token (`self.dcd`).
+- `authenticate(request, token)`: Decodes, validates, and delegates to `auth_handler`. Returns user or `False`.
+
+### Example
+
+```python
+from joserfc import jwk
+from ninja import NinjaAPI
+from ninja_aio.auth import AsyncJwtBearer
+
+class MyBearer(AsyncJwtBearer):
+    jwt_public = jwk.RSAKey.import_key(open("pub.jwk").read())
+    claims = {
+        "iss": {"value": "https://auth.example"},
+        "aud": {"value": "my-api"},
+        # You can add time-based checks if needed:
+        # "exp": {"essential": True},
+        # "nbf": {"essential": True},
+    }
+
+    async def auth_handler(self, request):
+        sub = self.dcd.claims.get("sub")
+        return {"user_id": sub}
+
+api = NinjaAPI()
+
+@api.get("/secure", auth=MyBearer())
+def secure_endpoint(request):
+    return {"ok": True}
+```
+
+### Claims registry helper
+
+You can construct and reuse a registry from your class-level `claims`:
+
+```python
+registry = MyBearer.get_claims()
+# registry.validate(token_claims)  # raises JoseError on failure
+```
+
+## encode_jwt
+
+Signs a JWT with safe defaults:
+
+- Adds `iat`, `nbf`, and `exp` using timezone-aware `timezone.now()`.
+- Ensures `iss` and `aud` are present via `validate_mandatory_claims` (include them in `claims` if not using settings).
+- Header includes `alg`, `typ=JWT`, and optional `kid`.
+
+```python
+from joserfc import jwk
+from ninja_aio.auth import encode_jwt
+
+private_key = jwk.RSAKey.import_key(open("priv.jwk").read())
+
+claims = {"sub": "123", "scope": "read", "iss": "https://auth.example", "aud": "my-api"}
+token = encode_jwt(
+    claims=claims,
+    duration=3600,
+    private_key=private_key,
+    algorithm="RS256",
+)
+```
+
+## decode_jwt
+
+Verifies and decodes a JWT with a public key and algorithm allow-list.
+
+```python
+from joserfc import jwk
+from ninja_aio.auth import decode_jwt
+
+public_key = jwk.RSAKey.import_key(open("pub.jwk").read())
+
+decoded = decode_jwt(
+    token=token,
+    public_key=public_key,
+    algorithms=["RS256"],
+)
+
+claims = decoded.claims
+sub = claims.get("sub")
+```
+
+## validate_key
+
+If you do not use settings, pass keys directly. `validate_key` will raise `ValueError` only when neither an explicit key nor a configured setting is provided.
+
+```python
+from ninja_aio.auth import validate_key
+from joserfc import jwk
+
+pkey = validate_key(jwk.RSAKey.import_key(open("priv.jwk").read()), "JWT_PRIVATE_KEY")
+```
+
+## validate_mandatory_claims
+
+Ensures `iss` and `aud` are present; if settings are not used, include them in your input claims.
+
+```python
+from ninja_aio.auth import validate_mandatory_claims
+
+claims = {"sub": "123", "iss": "https://auth.example", "aud": "my-api"}
+claims = validate_mandatory_claims(claims)
+```
+
+## Error handling
+
+- `authenticate` returns `False` on decode (`ValueError`) or claim validation failure (`JoseError`). Map this to 401/403 in your views as needed.
+- `validate_claims` raises `jose.errors.JoseError` for invalid claims.
+- `encode_jwt` and `decode_jwt` raise `ValueError` for missing/invalid keys or configuration.
+
+## Security notes
+
+- Rotate keys and use `kid` headers to support key rotation.
+- Validate critical claims (`exp`, `nbf`, `iss`, `aud`) via the registry.
+- Do not log raw tokens or sensitive claims.

django_ninja_aio_crud-2.1.0/docs/mixins.md

@@ -0,0 +1,147 @@
+# ViewSet Mixins
+
+These mixins implement a query_params_handler to apply common filtering patterns to Django QuerySets. Import from `ninja_aio.views.mixins`. Values used for filtering come from validated query params in your viewset’s `query_params`.
+
+Note: Each mixin overrides `query_params_handler`. When composing multiple mixins, define your own `query_params_handler` and call `super()` in the desired order.
+
+## IcontainsFilterViewSetMixin
+
+Applies case-insensitive substring filters (`__icontains`) for string values.
+
+- Behavior: For each `str` value in `filters`, applies `field__icontains=value`.
+- Ignores non-string values.
+
+Example:
+
+```python
+from ninja_aio.views.mixins import IcontainsFilterViewSetMixin
+from ninja_aio.views.api import APIViewSet
+
+class UserViewSet(IcontainsFilterViewSetMixin, APIViewSet):
+    model = models.User
+    api = api
+    query_params = {"name": (str, ""), "email": (str, "")}
+```
+
+## BooleanFilterViewSetMixin
+
+Filters boolean fields using exact match.
+
+- Behavior: Applies `{key: value}` only for `bool` values.
+
+Example:
+
+```python
+from ninja_aio.views.mixins import BooleanFilterViewSetMixin
+
+class FeatureViewSet(BooleanFilterViewSetMixin, APIViewSet):
+    model = models.FeatureFlag
+    api = api
+    query_params = {"enabled": (bool, False)}
+```
+
+<!-- Removed ReverseBooleanFilterViewSetMixin: not implemented in code -->
+
+## NumericFilterViewSetMixin
+
+Applies exact filters for numeric values.
+
+- Behavior: Filters only `int` and `float` values.
+
+Example:
+
+```python
+from ninja_aio.views.mixins import NumericFilterViewSetMixin
+
+class OrderViewSet(NumericFilterViewSetMixin, APIViewSet):
+    model = models.Order
+    api = api
+    query_params = {"amount": (float, 0.0), "quantity": (int, 0)}
+```
+
+## DateFilterViewSetMixin
+
+Base mixin for date/datetime filtering with custom comparisons.
+
+- Attributes:
+  - `_compare_attr`: comparison operator suffix (e.g., `__gt`, `__lt`, `__gte`, `__lte`).
+- Behavior: Applies filters for values that implement `isoformat` (date/datetime-like). Prefer using Pydantic `date`/`datetime` types in `query_params`.
+
+Example:
+
+```python
+from ninja_aio.views.mixins import DateFilterViewSetMixin
+
+class EventViewSet(DateFilterViewSetMixin, APIViewSet):
+    model = models.Event
+    api = api
+    # Use date/datetime types so values have `isoformat`.
+    query_params = {"created_at": (datetime, None)}
+    _compare_attr = "__gt"
+```
+
+## GreaterDateFilterViewSetMixin
+
+Sets comparison to strict greater-than (`__gt`).
+
+Example:
+
+```python
+from ninja_aio.views.mixins import GreaterDateFilterViewSetMixin
+
+class EventViewSet(GreaterDateFilterViewSetMixin, APIViewSet):
+    model = models.Event
+    api = api
+    query_params = {"created_at": (datetime, None)}
+```
+
+## LessDateFilterViewSetMixin
+
+Sets comparison to strict less-than (`__lt`).
+
+Example:
+
+```python
+from ninja_aio.views.mixins import LessDateFilterViewSetMixin
+
+class EventViewSet(LessDateFilterViewSetMixin, APIViewSet):
+    model = models.Event
+    api = api
+    query_params = {"created_at": (datetime, None)}
+```
+
+## GreaterEqualDateFilterViewSetMixin
+
+Sets comparison to greater-than-or-equal (`__gte`).
+
+Example:
+
+```python
+from ninja_aio.views.mixins import GreaterEqualDateFilterViewSetMixin
+
+class EventViewSet(GreaterEqualDateFilterViewSetMixin, APIViewSet):
+    model = models.Event
+    api = api
+    query_params = {"created_at": (datetime, None)}
+```
+
+## LessEqualDateFilterViewSetMixin
+
+Sets comparison to less-than-or-equal (`__lte`).
+
+Example:
+
+```python
+from ninja_aio.views.mixins import LessEqualDateFilterViewSetMixin
+
+class EventViewSet(LessEqualDateFilterViewSetMixin, APIViewSet):
+    model = models.Event
+    api = api
+    query_params = {"created_at": (datetime, None)}
+```
+
+## Tips
+
+- Align `query_params` types with expected filter values; prefer Pydantic `date`/`datetime` for date filters so values implement `isoformat`.
+- Validate field names and lookups to avoid runtime errors.
+- For multiple mixins, implement your own `async def query_params_handler(...)` and chain with `await super().query_params_handler(...)` to combine behaviors.

{django_ninja_aio_crud-2.0.0rc7 → django_ninja_aio_crud-2.1.0}/mkdocs.yml

@@ -19,11 +19,15 @@ nav:
     - Views:
       - APIView: api/views/api_view.md
       - APIViewSet: api/views/api_view_set.md
+      - Decorators: api/views/decorators.md
+      - Mixins: docs/mixins.md
     - Models:
       - ModelSerializer: api/models/model_serializer.md
       - ModelUtil: api/models/model_util.md
     - Authentication: api/authentication.md
     - Pagination: api/pagination.md
+  - Authentication:
+      - JWT & AsyncJwtBearer: auth.md
   - Contributing: contributing.md
   - Release Notes: release_notes.md
 
@@ -94,6 +98,7 @@ extra:
     provider: mike
     repo: caspel26/django-ninja-aio-crud
     stable: true
+    default: latest
 
 plugins:
   - macros:

{django_ninja_aio_crud-2.0.0rc7 → django_ninja_aio_crud-2.1.0}/ninja_aio/__init__.py

@@ -1,6 +1,6 @@
 """Django Ninja AIO CRUD - Rest Framework"""
 
-__version__ = "2.0.0-rc7"
+__version__ = "2.1.0"
 
 from .api import NinjaAIO