django-ninja-aio-crud 0.10.2__py3-none-any.whl → 2.4.0__py3-none-any.whl

django_ninja_aio_crud-2.4.0.dist-info/METADATA

@@ -0,0 +1,382 @@
+Metadata-Version: 2.4
+Name: django-ninja-aio-crud
+Version: 2.4.0
+Summary: Django Ninja AIO CRUD - Rest Framework
+Author: Giuseppe Casillo
+Requires-Python: >=3.10, <3.15
+Description-Content-Type: text/markdown
+Classifier: Operating System :: OS Independent
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Software Development :: Libraries
+Classifier: Topic :: Software Development
+Classifier: Environment :: Web Environment
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+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
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Framework :: Django
+Classifier: Framework :: AsyncIO
+Classifier: Topic :: Internet :: WWW/HTTP :: HTTP Servers
+Classifier: Topic :: Internet :: WWW/HTTP
+License-File: LICENSE
+Requires-Dist: django-ninja >=1.3.0, <1.6
+Requires-Dist: joserfc >=1.0.0, <= 1.4.1
+Requires-Dist: orjson >= 3.10.7, <= 3.11.5
+Requires-Dist: coverage ; extra == "test"
+Project-URL: Documentation, https://django-ninja-aio.com
+Project-URL: Repository, https://github.com/caspel26/django-ninja-aio-crud
+Provides-Extra: test
+
+# 🥷 django-ninja-aio-crud
+
+![Tests](https://github.com/caspel26/django-ninja-aio-crud/actions/workflows/coverage.yml/badge.svg)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=caspel26_django-ninja-aio-crud&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=caspel26_django-ninja-aio-crud)
+[![codecov](https://codecov.io/gh/caspel26/django-ninja-aio-crud/graph/badge.svg?token=DZ5WDT3S20)](https://codecov.io/gh/caspel26/django-ninja-aio-crud/)
+[![PyPI - Version](https://img.shields.io/pypi/v/django-ninja-aio-crud?color=g&logo=pypi&logoColor=white)](https://pypi.org/project/django-ninja-aio-crud/)
+[![PyPI - License](https://img.shields.io/pypi/l/django-ninja-aio-crud)](LICENSE)
+[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
+
+> Lightweight async CRUD layer on top of **[Django Ninja](https://django-ninja.dev/)** with automatic schema generation, filtering, pagination, auth & Many‑to‑Many management.
+
+---
+
+## ✨ Features
+
+- Async CRUD ViewSets (create, list, retrieve, update, delete)
+- Automatic Pydantic schemas from `ModelSerializer` (read/create/update)
+- Dynamic query params (runtime schema via `pydantic.create_model`)
+- Per-method authentication (`auth`, `get_auth`, `post_auth`, etc.)
+- Async pagination (customizable)
+- M2M relation endpoints via `M2MRelationSchema` (add/remove/get + filters)
+- Reverse relation serialization
+- Hook methods (`query_params_handler`, `<related>_query_params_handler`, `custom_actions`, lifecycle hooks)
+- ORJSON renderer through `NinjaAIO`
+- Clean, minimal integration
+
+---
+
+## 📦 Installation
+
+```bash
+pip install django-ninja-aio-crud
+```
+
+Add to your project’s dependencies and ensure Django Ninja is installed.
+
+---
+
+## 🚀 Quick Start
+
+models.py
+
+```python
+from django.db import models
+from ninja_aio.models import ModelSerializer
+
+class Book(ModelSerializer):
+    title = models.CharField(max_length=120)
+    published = models.BooleanField(default=True)
+
+    class ReadSerializer:
+        fields = ["id", "title", "published"]
+
+    class CreateSerializer:
+        fields = ["title", "published"]
+
+    class UpdateSerializer:
+        optionals = [("title", str), ("published", bool)]
+```
+
+views.py
+
+```python
+from ninja_aio import NinjaAIO
+from ninja_aio.views import APIViewSet
+from .models import Book
+
+api = NinjaAIO()
+
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
+    pass
+
+```
+
+Visit `/docs` → CRUD endpoints ready.
+
+---
+
+## 🔄 Query Filtering
+
+```python
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
+    query_params = {"published": (bool, None), "title": (str, None)}
+
+    async def query_params_handler(self, queryset, filters):
+        if filters.get("published") is not None:
+            queryset = queryset.filter(published=filters["published"])
+        if filters.get("title"):
+            queryset = queryset.filter(title__icontains=filters["title"])
+        return queryset
+```
+
+Request:
+
+```
+GET /book/?published=true&title=python
+```
+
+---
+
+## 🤝 Many-to-Many Example (with filters)
+
+```python
+from ninja_aio.schemas import M2MRelationSchema
+
+class Tag(ModelSerializer):
+    name = models.CharField(max_length=50)
+    class ReadSerializer:
+        fields = ["id", "name"]
+
+class Article(ModelSerializer):
+    title = models.CharField(max_length=120)
+    tags = models.ManyToManyField(Tag, related_name="articles")
+
+    class ReadSerializer:
+        fields = ["id", "title", "tags"]
+
+@api.viewset(Article)
+class ArticleViewSet(APIViewSet):
+    m2m_relations = [
+        M2MRelationSchema(
+            model=Tag,
+            related_name="tags",
+            filters={"name": (str, "")}
+        )
+    ]
+
+    async def tags_query_params_handler(self, queryset, filters):
+        n = filters.get("name")
+        if n:
+            queryset = queryset.filter(name__icontains=n)
+        return queryset
+
+```
+
+Endpoints:
+
+- `GET /article/{pk}/tag?name=dev`
+- `POST /article/{pk}/tag/` body: `{"add":[1,2],"remove":[3]}`
+
+---
+
+## 🔐 Authentication (JWT example)
+
+```python
+from ninja_aio.auth import AsyncJwtBearer
+from joserfc import jwk
+from .models import Book
+
+PUBLIC_KEY = "-----BEGIN PUBLIC KEY----- ..."
+
+class JWTAuth(AsyncJwtBearer):
+    jwt_public = jwk.RSAKey.import_key(PUBLIC_KEY)
+    jwt_alg = "RS256"
+    claims = {"sub": {"essential": True}}
+
+    async def auth_handler(self, request):
+        book_id = self.dcd.claims.get("sub")
+        return await Book.objects.aget(id=book_id)
+
+@api.viewset(Book)
+class SecureBookViewSet(APIViewSet):
+    auth = [JWTAuth()]
+    get_auth = None  # list/retrieve public
+```
+
+---
+
+## 📑 Lifecycle Hooks (ModelSerializer)
+
+Available on every save/delete:
+
+- `on_create_before_save`
+- `on_create_after_save`
+- `before_save`
+- `after_save`
+- `on_delete`
+- `custom_actions(payload)` (create/update custom field logic)
+- `post_create()` (after create commit)
+
+---
+
+## 🧩 Adding Custom Endpoints
+
+```python
+from ninja_aio.decorators import api_get
+
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
+    @api_get("/stats/")
+    async def stats(self, request):
+        total = await Book.objects.acount()
+        return {"total": total}
+```
+
+Or
+
+```python
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
+    def views(self):
+        @self.router.get("/stats/")
+        async def stats(request):
+            total = await Book.objects.acount()
+            return {"total": total}
+```
+
+---
+
+## 📄 Pagination
+
+Default: `PageNumberPagination`. Override:
+
+```python
+from ninja.pagination import PageNumberPagination
+
+class LargePagination(PageNumberPagination):
+    page_size = 50
+    max_page_size = 200
+
+@api.viewset(Book)
+class BookViewSet(APIViewSet):
+    pagination_class = LargePagination
+```
+
+---
+
+## Meta-driven Serializer (for vanilla Django models)
+
+If you already have Django models and don't want to inherit from ModelSerializer, use the Meta-driven Serializer to generate dynamic schemas and integrate with APIViewSet.
+
+Example:
+
+```python
+from ninja_aio.models import serializers
+from . import models
+
+class BookSerializer(serializers.Serializer):
+    class Meta:
+        model = models.Book
+        schema_in = serializers.SchemaModelConfig(fields=["title", "published"])
+        schema_out = serializers.SchemaModelConfig(fields=["id", "title", "published"])
+        schema_update = serializers.SchemaModelConfig(optionals=[("title", str), ("published", bool)])
+
+@api.viewset(models.Book)
+class BookViewSet(APIViewSet):
+    serializer_class = BookSerializer
+```
+
+- Works without modifying existing models
+- Supports nested relations via relations_serializers
+- APIViewSet will auto-generate missing schemas from the serializer
+
+---
+
+## 🛠 Project Structure & Docs
+
+Documentation (MkDocs + Material):
+
+```
+docs/
+  getting_started/
+  tutorial/
+  api/
+    views/
+    models/
+    authentication.md
+    pagination.md
+```
+
+Browse full reference:
+
+- APIViewSet: `docs/api/views/api_view_set.md`
+- APIView: `docs/api/views/api_view.md`
+- ModelSerializer: `docs/api/models/model_serializer.md`
+- Authentication: `docs/api/authentication.md`
+- Example repository: https://github.com/caspel26/ninja-aio-blog-example
+
+---
+
+## 🧪 Tests
+
+Use Django test runner + async ORM patterns. Example async pattern:
+
+```python
+obj = await Book.objects.acreate(title="T1", published=True)
+count = await Book.objects.acount()
+```
+
+---
+
+## 🚫 Disable Operations
+
+```python
+@api.viewset(Book)
+class ReadOnlyBookViewSet(APIViewSet):
+    disable = ["update", "delete"]
+```
+
+---
+
+## 📌 Performance Tips
+
+- Use `queryset_request` classmethod to prefetch
+- Index frequently filtered fields
+- Keep pagination enabled
+- Limit slices (`queryset = queryset[:1000]`) for heavy searches
+
+---
+
+## 🤲 Contributing
+
+1. Fork
+2. Create branch
+3. Add tests
+4. Run lint (`ruff check .`)
+5. Open PR
+
+---
+
+## ⭐ Support
+
+Star the repo or donate:
+
+- [Buy me a coffee](https://buymeacoffee.com/caspel26)
+
+---
+
+## 📜 License
+
+MIT License. See [LICENSE](LICENSE).
+
+---
+
+## 🔗 Quick Links
+
+| Item    | Link                                                     |
+| ------- | -------------------------------------------------------- |
+| PyPI    | https://pypi.org/project/django-ninja-aio-crud/          |
+| Docs    | https://django-ninja-aio.com                             |
+| Issues  | https://github.com/caspel26/django-ninja-aio-crud/issues |
+| Example | https://github.com/caspel26/ninja-aio-blog-example       |
+
+---
+

django_ninja_aio_crud-2.4.0.dist-info/RECORD

@@ -0,0 +1,29 @@
+ninja_aio/__init__.py,sha256=Ms2GNzuORIvMqPlxF2wzxTHgoQBL_OpaeqByF4LtwhI,119
+ninja_aio/api.py,sha256=tuC7vdvn7s1GkCnSFy9Kn1zv0glZfYptRQVvo8ZRtGQ,2429
+ninja_aio/auth.py,sha256=4sWdFPjKiQgUL1d_CSGDblVjnY5ptP6LQha6XXdluJA,9157
+ninja_aio/exceptions.py,sha256=_3xFqfFCOfrrMhSA0xbMqgXy8R0UQjhXaExrFvaDAjY,3891
+ninja_aio/parsers.py,sha256=e_4lGCPV7zs-HTqtdJTc8yQD2KPAn9njbL8nF_Mmgkc,153
+ninja_aio/renders.py,sha256=89g46NWUT8nmDG-rG0nxUYbAQWhuXcYKrPh7e1r_Fc4,1735
+ninja_aio/types.py,sha256=nFqWEopm7eoEaHRzbi6EyA9WZ5Cneyd602ilFKypeQI,577
+ninja_aio/decorators/__init__.py,sha256=cDDHD_9EI4CP7c5eL1m2mGNl9bR24i8FAkQsT3_RNGM,371
+ninja_aio/decorators/operations.py,sha256=L9yt2ku5oo4CpOLixCADmkcFjLGsWAn-cg-sDcjFhMA,343
+ninja_aio/decorators/views.py,sha256=0RVU4XaM1HvTQ-BOt_NwUtbhwfHau06lh-O8El1LqQk,8139
+ninja_aio/factory/__init__.py,sha256=IdH2z1ZZpv_IqonaDfVo7IsMzkgop6lHqz42RphUYBU,72
+ninja_aio/factory/operations.py,sha256=OgWGqq4WJ4arSQrH9FGAby9kx-HTdS7MOITxHdYMk18,12051
+ninja_aio/helpers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+ninja_aio/helpers/api.py,sha256=YMzuZ4-ZpUrJBQIabE26gb_GYwsH2rVosWRE95YfdPQ,20775
+ninja_aio/helpers/query.py,sha256=YJMdEonCuqx1XjmszCK74mg5hcUPh84ynXrsuoSQdNA,4519
+ninja_aio/models/__init__.py,sha256=L3UQnQAlKoI3F7jinadL-Nn55hkPvnSRPYW0JtnbWFo,114
+ninja_aio/models/serializers.py,sha256=wFEG6QrOPN4TiDEIRkOxExIKkjAQ0I432czaELZZxdI,25110
+ninja_aio/models/utils.py,sha256=PkvdByNuZKnTzQhdkbqZuG6CEIMIZTCO4QkCUgvqBjs,28776
+ninja_aio/schemas/__init__.py,sha256=iLBwHg0pmL9k_UkIui5Q8QIl_gO4fgxSv2JHxDzqnSI,549
+ninja_aio/schemas/api.py,sha256=-VwXhBRhmMsZLIAmWJ-P7tB5klxXS75eukjabeKKYsc,360
+ninja_aio/schemas/generics.py,sha256=frjJsKJMAdM_NdNKv-9ddZNGxYy5PNzjIRGtuycgr-w,112
+ninja_aio/schemas/helpers.py,sha256=W6IeHi5Tmbjh3FXwDYqjqlLBTVj5uTYq3_JVkNUWayo,7355
+ninja_aio/views/__init__.py,sha256=DEzjWA6y3WF0V10nNF8eEurLNEodgxKzyFd09AqVp3s,148
+ninja_aio/views/api.py,sha256=AQWtu8oI9R0blk-PW8BpwXLuejj1Z8vqpoNqlU_WrGs,20953
+ninja_aio/views/mixins.py,sha256=Jh6BG8Cs823nurVlODlzCquTxKrLH7Pmo5udPqUGZek,11378
+django_ninja_aio_crud-2.4.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-2.4.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-2.4.0.dist-info/METADATA,sha256=qRTfA6me4WsclgqfdyVKL7nPOfv3rRasiLNQdVUeZpM,9988
+django_ninja_aio_crud-2.4.0.dist-info/RECORD,,

ninja_aio/__init__.py

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

ninja_aio/api.py

@@ -5,10 +5,13 @@ from ninja.throttling import BaseThrottle
 from ninja import NinjaAPI
 from ninja.openapi.docs import DocsBase, Swagger
 from ninja.constants import NOT_SET, NOT_SET_TYPE
+from django.db import models
 
 from .parsers import ORJSONParser
 from .renders import ORJSONRenderer
 from .exceptions import set_api_exception_handlers
+from .views import APIView, APIViewSet
+from .models import ModelSerializer
 
 
 class NinjaAIO(NinjaAPI):
@@ -23,7 +26,6 @@ class NinjaAIO(NinjaAPI):
         docs_decorator=None,
         servers: list[dict[str, Any]] | None = None,
         urls_namespace: str | None = None,
-        csrf: bool = False,
         auth: Sequence[Any] | NOT_SET_TYPE = NOT_SET,
         throttle: BaseThrottle | list[BaseThrottle] | NOT_SET_TYPE = NOT_SET,
         default_router: Router | None = None,
@@ -39,7 +41,6 @@ class NinjaAIO(NinjaAPI):
             docs_decorator=docs_decorator,
             servers=servers,
             urls_namespace=urls_namespace,
-            csrf=csrf,
             auth=auth,
             throttle=throttle,
             default_router=default_router,
@@ -51,3 +52,24 @@ class NinjaAIO(NinjaAPI):
     def set_default_exception_handlers(self):
         set_api_exception_handlers(self)
         super().set_default_exception_handlers()
+
+    def view(self, prefix: str, tags: list[str] = None) -> Any:
+        def wrapper(view: type[APIView]):
+            instance = view(api=self, prefix=prefix, tags=tags)
+            instance.add_views_to_route()
+            return instance
+
+        return wrapper
+
+    def viewset(
+        self,
+        model: models.Model | ModelSerializer,
+        prefix: str = None,
+        tags: list[str] = None,
+    ) -> None:
+        def wrapper(viewset: type[APIViewSet]):
+            instance = viewset(api=self, model=model, prefix=prefix, tags=tags)
+            instance.add_views_to_route()
+            return instance
+
+        return wrapper

ninja_aio/auth.py

@@ -1,12 +1,88 @@
+import datetime
+from typing import Optional
+
 from joserfc import jwt, jwk, errors
 from django.http.request import HttpRequest
+from django.utils import timezone
+from django.conf import settings
 from ninja.security.http import HttpBearer
 
-from .exceptions import AuthError
+from ninja_aio.types import JwtKeys
+
+JWT_MANDATORY_CLAIMS = [
+    ("iss", "JWT_ISSUER"),
+    ("aud", "JWT_AUDIENCE"),
+]
 
 
 class AsyncJwtBearer(HttpBearer):
-    jwt_public: jwk.RSAKey
+    """
+    AsyncJwtBearer provides asynchronous JWT-based authentication for Django Ninja endpoints
+    using HTTP Bearer tokens. It decodes and validates JWTs against a configured public key
+    and claim registry, then delegates user retrieval to an overridable async handler.
+    Attributes:
+        jwt_public (jwk.RSAKey | jwk.ECKey):
+            The public key (JWK format) used to verify the JWT signature.
+            Must be set externally before authentication occurs.
+        claims (dict[str, dict]):
+            A mapping defining expected JWT claims passed to jwt.JWTClaimsRegistry.
+            Each key corresponds to a claim name; values configure validation rules
+            (e.g., {'iss': {'value': 'https://issuer.example'}}).
+        algorithms (list[str]):
+            List of permitted JWT algorithms for signature verification. Defaults to ["RS256"].
+        dcd (jwt.Token | None):
+            Set after successful decode; holds the decoded token object (assigned dynamically).
+    Class Methods:
+        get_claims() -> jwt.JWTClaimsRegistry:
+            Constructs and returns a claims registry from the class-level claims definition.
+    Instance Methods:
+        validate_claims(claims: jwt.Claims) -> None:
+            Validates the provided claims object against the registry. Raises jose.errors.JoseError
+            or ValueError-derived exceptions if validation fails.
+        auth_handler(request: HttpRequest) -> Any:
+            Asynchronous hook to be overridden by subclasses to implement application-specific
+            user resolution (e.g., fetching a user model instance). Must return a user-like object
+            on success or raise / return False on failure.
+        authenticate(request: HttpRequest, token: str) -> Any | bool:
+            Orchestrates authentication:
+                1. Attempts to decode the JWT using the configured public key and algorithms.
+                2. Validates claims via validate_claims.
+                3. Delegates to auth_handler for domain-specific user retrieval.
+            Returns the user object on success; returns False if decoding or claim validation fails.
+    Usage Notes:
+        - You must assign jwt_public (jwk.RSAKey) and populate claims before calling authenticate.
+        - Override auth_handler to integrate with your user persistence layer.
+        - Token decoding failures (e.g., signature mismatch, malformed token) result in False.
+        - Claim validation errors (e.g., expired token, issuer mismatch) result in False.
+        - This class does not itself raise HTTP errors; caller may translate False into an HTTP response.
+    Example Extension:
+        class MyBearer(AsyncJwtBearer):
+            jwt_public = jwk.RSAKey.import_key(open("pub.pem").read())
+            claims = {
+                "iss": {"value": "https://auth.example"},
+                "aud": {"value": "my-api"},
+            }
+            async def auth_handler(self, request):
+                sub = self.dcd.claims.get("sub")
+                return await get_user_by_id(sub)
+    Thread Safety:
+        - Instances are not inherently thread-safe if mutable shared state is attached.
+        - Prefer per-request instantiation or ensure read-only shared configuration.
+    Security Considerations:
+        - Ensure jwt_public key rotation strategy is in place.
+        - Validate critical claims (exp, nbf, iss, aud) via the claims registry configuration.
+        - Avoid logging raw tokens or sensitive claim contents.
+    Raises:
+        jose.errors.JoseError:
+            Propagated from validate_claims if claim checks fail.
+        ValueError:
+            May occur during token decoding (e.g., invalid structure) but is internally caught
+            and converted to a False return value.
+    Return Semantics:
+        - authenticate -> user object (success) | False (failure)
+    """
+
+    jwt_public: JwtKeys
     claims: dict[str, dict]
     algorithms: list[str] = ["RS256"]
 
@@ -31,13 +107,119 @@ class AsyncJwtBearer(HttpBearer):
         """
         try:
             self.dcd = jwt.decode(token, self.jwt_public, algorithms=self.algorithms)
-        except ValueError as exc:
+        except ValueError:
             # raise AuthError(", ".join(exc.args), 401)
             return False
 
         try:
             self.validate_claims(self.dcd.claims)
-        except errors.JoseError as exc:
+        except errors.JoseError:
             return False
 
         return await self.auth_handler(request)
+
+
+def validate_key(key: Optional[JwtKeys], setting_name: str) -> JwtKeys:
+    if key is None:
+        key = getattr(settings, setting_name, None)
+    if key is None:
+        raise ValueError(f"{setting_name} is required")
+    if not isinstance(key, (jwk.RSAKey, jwk.ECKey, jwk.OctKey)):
+        raise ValueError(
+            f"{setting_name} must be an instance of jwk.RSAKey or jwk.ECKey"
+        )
+    return key
+
+
+def validate_mandatory_claims(claims: dict) -> dict:
+    for claim_key, setting_name in JWT_MANDATORY_CLAIMS:
+        if claims.get(claim_key) is not None:
+            continue
+        value = getattr(settings, setting_name, None)
+        if value is None:
+            raise ValueError(f"jwt {claim_key} is required")
+        claims[claim_key] = value
+    return claims
+
+
+def encode_jwt(
+    claims: dict, duration: int, private_key: JwtKeys = None, algorithm: str = None
+) -> str:
+    """
+    Encode and sign a JWT.
+
+    Adds time-based claims and ensures mandatory issuer/audience:
+      - iat: current time (timezone-aware)
+      - nbf: current time
+      - exp: current time + duration (seconds)
+      - iss/aud: from claims if provided; otherwise from settings.JWT_ISSUER and settings.JWT_AUDIENCE
+
+    Parameters:
+      - claims (dict): additional claims to merge into the payload (can override defaults)
+      - duration (int): token lifetime in seconds
+      - private_key (jwk.RSAKey): RSA/EC JWK for signing; defaults to settings.JWT_PRIVATE_KEY
+      - algorithm (str): JWS algorithm (default "RS256")
+
+    Returns:
+      - str: JWT compact string
+
+    Raises:
+      - ValueError: if private_key is missing or not jwk.RSAKey/jwk.ECKey
+      - ValueError: if mandatory claims (iss, aud) are missing and not in settings
+
+    Notes:
+      - Header includes alg, typ=JWT, and kid from the private key (if available).
+      - Uses timezone-aware timestamps from django.utils.timezone.
+    """
+    now = timezone.now()
+    nbf = now
+    pkey = validate_key(private_key, "JWT_PRIVATE_KEY")
+    algorithm = algorithm or "RS256"
+    claims = validate_mandatory_claims(claims)
+    kid_h = {"kid": pkey.kid} if pkey.kid else {}
+    return jwt.encode(
+        header={"alg": algorithm, "typ": "JWT"} | kid_h,
+        claims={
+            "iat": now,
+            "nbf": nbf,
+            "exp": now + datetime.timedelta(seconds=duration),
+        }
+        | claims,
+        key=pkey,
+        algorithms=[algorithm],
+    )
+
+
+def decode_jwt(
+    token: str,
+    public_key: JwtKeys = None,
+    algorithms: list[str] = None,
+) -> jwt.Token:
+    """
+    Decode and verify a JSON Web Token (JWT) using the provided RSA public key.
+    This function decodes the JWT, verifies its signature, and returns the decoded token object.
+    Parameters:
+    - token (str): The JWT string to decode.
+    - public_key (jwk.RSAKey, optional): RSA public key used to verify the token's signature.
+        If not provided, settings.JWT_PUBLIC_KEY will be used. Must be an instance of jwk.RSAKey.
+    - algorithms (list[str], optional): List of permitted algorithms for signature verification.
+        Defaults to ["RS256"] if not provided.
+    Returns:
+    - jwt.Token: The decoded JWT token object containing header and claims.
+    Raises:
+    - ValueError: If no public key is provided or if the provided key is not an instance of jwk.RSAKey.
+    - jose.errors.JoseError: If the token is invalid or fails verification.
+    Notes:
+    - The function uses the specified algorithms to restrict acceptable signing methods.
+    Example:
+        decoded_token = decode_jwt(
+            token=my_jwt,
+            public_key=my_rsa_jwk,
+            algorithms=["RS256"],
+        )
+    """
+    return jwt.decode(
+        token,
+        validate_key(public_key, "JWT_PUBLIC_KEY"),
+        algorithms=algorithms or ["RS256"],
+    )