django-ninja-aio-crud 0.10.3__py3-none-any.whl → 0.11.0__py3-none-any.whl

{django_ninja_aio_crud-0.10.3.dist-info → django_ninja_aio_crud-0.11.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: django-ninja-aio-crud
-Version: 0.10.3
+Version: 0.11.0
 Summary: Django Ninja AIO CRUD - Rest Framework
 Author: Giuseppe Casillo
 Requires-Python: >=3.10
@@ -27,6 +27,7 @@ Requires-Dist: django-ninja >=1.3.0
 Requires-Dist: joserfc >=1.0.0
 Requires-Dist: orjson >= 3.10.7
 Requires-Dist: coverage ; extra == "test"
+Project-URL: Documentation, https://caspel26.github.io/django-ninja-aio-crud/
 Project-URL: Repository, https://github.com/caspel26/django-ninja-aio-crud
 Provides-Extra: test
 

django_ninja_aio_crud-0.11.0.dist-info/RECORD

@@ -0,0 +1,15 @@
+ninja_aio/__init__.py,sha256=ImDLFWPLZMYkYRZ7pVVcxj0pL4w9uOQRFNmGg6QZVHg,120
+ninja_aio/api.py,sha256=Fe6l3YCy7MW5TY4-Lbl80CFuK2NT2Y7tHfmqPk6Mqak,1735
+ninja_aio/auth.py,sha256=zUwruKcz7MXuOnWp5k1CCSwEc8s2Lyqqk7Qm9kPbJ3o,5149
+ninja_aio/decoratos.py,sha256=LsvHbMxmw_So8NV0ey5NRRvSbfYkOZLeLQ4Fix7rQAY,5519
+ninja_aio/exceptions.py,sha256=iEX4PNqtRXXr75M8veOynmFZcIE5lGURHU_ISSgzX0Y,2578
+ninja_aio/models.py,sha256=-p1wgOg-r5bYWQ9DzUSNKxsUvWiDg6kruMQ_LxZFvQE,32948
+ninja_aio/parsers.py,sha256=e_4lGCPV7zs-HTqtdJTc8yQD2KPAn9njbL8nF_Mmgkc,153
+ninja_aio/renders.py,sha256=0eYklRKd59aV4cZDom5vLZyA99Ob17OwkpMybsRXvyg,1970
+ninja_aio/schemas.py,sha256=Fzu2ko3kUxkOnrjG5QYdmOXZd2gcpYGjVuocCW44NfQ,473
+ninja_aio/types.py,sha256=TJSGlA7bt4g9fvPhJ7gzH5tKbLagPmZUzfgttEOp4xs,468
+ninja_aio/views.py,sha256=OipMCYxT9JHWdmffCkV2OLXYFA4ODXBb94aLAFnOhFo,20780
+django_ninja_aio_crud-0.11.0.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
+django_ninja_aio_crud-0.11.0.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
+django_ninja_aio_crud-0.11.0.dist-info/METADATA,sha256=XDeQA1BFDGiwCEckt18BGyrJncXtqqe7DNj6oH5fagQ,14217
+django_ninja_aio_crud-0.11.0.dist-info/RECORD,,

ninja_aio/__init__.py

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

ninja_aio/auth.py

@@ -6,6 +6,71 @@ from .exceptions import AuthError
 
 
 class AsyncJwtBearer(HttpBearer):
+    """
+    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):
+            The RSA 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: jwk.RSAKey
     claims: dict[str, dict]
     algorithms: list[str] = ["RS256"]

ninja_aio/decoratos.py

@@ -0,0 +1,142 @@
+from django.db.transaction import Atomic
+from functools import wraps
+from asgiref.sync import sync_to_async
+
+
+class AsyncAtomicContextManager(Atomic):
+    def __init__(self, using=None, savepoint=True, durable=False):
+        super().__init__(using, savepoint, durable)
+
+    async def __aenter__(self):
+        await sync_to_async(super().__enter__)()
+        return self
+
+    async def __aexit__(self, exc_type, exc_value, traceback):
+        await sync_to_async(super().__exit__)(exc_type, exc_value, traceback)
+
+
+def aatomic(func):
+    """
+    Decorator that executes the wrapped async function inside an asynchronous atomic
+    database transaction context.
+
+    This is useful when you want all ORM write operations performed by the coroutine
+    to either fully succeed or fully roll back on error, preserving data integrity.
+
+    Parameters:
+        func (Callable): The asynchronous function to wrap.
+
+    Returns:
+        Callable: A new async function that, when awaited, runs inside an
+        AsyncAtomicContextManager transaction.
+
+    Behavior:
+        - Opens an async atomic transaction before invoking the wrapped coroutine.
+        - Commits if the coroutine completes successfully.
+        - Rolls back if an exception is raised and propagates the original exception.
+
+    Example:
+        @aatomic
+        async def create_order(user_id: int, items: list[Item]):
+            # Perform multiple related DB writes atomically
+            ...
+
+    Notes:
+        - Ensure AsyncAtomicContextManager is properly implemented to integrate with
+          your async ORM / database backend.
+        - Only use on async functions.
+    """
+    @wraps(func)
+    async def wrapper(*args, **kwargs):
+        async with AsyncAtomicContextManager():
+            return await func(*args, **kwargs)
+    return wrapper
+
+
+def unique_view(self: object | str, plural: bool = False):
+    """
+    Return a decorator that appends a model-specific suffix to a function's __name__ for uniqueness.
+
+    This is helpful when multiple view functions share a common base name but must be
+    distinct (e.g., for route registration, debugging, or introspection) per model context.
+
+    self : object | str
+        - If a string, it is used directly as the suffix.
+        - If an object, its `model_util` attribute is inspected for:
+            * model_util.model_name (when plural is False)
+            * model_util.verbose_name_view_resolver() (when plural is True)
+          Missing attributes or call failures result in no suffix being applied.
+    plural : bool, default False
+        If True and `self` is an object with `model_util.verbose_name_view_resolver`,
+        the resolved pluralized verbose name is used; otherwise the singular model name
+        (model_util.model_name) is used.
+
+    Callable[[Callable], Callable]
+        A decorator. When applied, it mutates the target function's __name__ in place to:
+        "<original_name>_<suffix>" if a suffix is resolved. If no suffix is found, the
+        function is returned unchanged.
+
+    - Does NOT wrap or alter the call signature or async/sync nature of the function.
+    - Performs a simple in-place mutation of func.__name__ before returning the original function.
+    - No metadata (e.g., __doc__, __qualname__) is altered besides __name__.
+
+    Suffix Resolution Logic
+    -----------------------
+    1. If `self` is a str: suffix = self
+    2. Else if `self` has `model_util`:
+       - plural == True: suffix = model_util.verbose_name_view_resolver()
+       - plural == False: suffix = model_util.model_name
+    3. If resolution fails or yields a falsy value, no mutation occurs.
+
+    Side Effects
+    ------------
+    - Modifies function.__name__, which can affect:
+      - Debugging output
+      - Route registration relying on function names
+      - Tools expecting the original name
+    - Because mutation is in place, reusing the original function object elsewhere
+      may produce unexpected naming.
+
+    Examples
+    # Using a string suffix directly
+    @unique_view("book")
+    def list_items():
+
+    # Using an object with model_util.model_name
+    @unique_view(viewset_instance)  # where viewset_instance.model_util.model_name == "author"
+    def retrieve():
+    # Resulting function name: "retrieve_author"
+
+    # Using plural form via verbose_name_view_resolver()
+    @unique_view(viewset_instance, plural=True)  # e.g., returns "authors"
+    def list():
+    # Resulting function name: "list_authors"
+
+    Caveats
+    - If the underlying attributes or resolver callable raise exceptions, they are not caught.
+    - Ensure that the modified name does not conflict with other functions after decoration.
+    - Use cautiously when decorators relying on original __name__ appear earlier in the chain.
+    """
+    def decorator(func):
+        # Allow usage as unique_view(self_instance) or unique_view("model_name")
+        if isinstance(self, str):
+            suffix = self
+        else:
+            suffix = (
+                getattr(
+                    getattr(self, "model_util", None),
+                    "verbose_name_view_resolver",
+                    None,
+                )()
+                if plural
+                else getattr(
+                    getattr(self, "model_util", None),
+                    "model_name",
+                    None,
+                )
+            )
+        if suffix:
+            func.__name__ = f"{func.__name__}_{suffix}"
+        return func  # Return original function (no wrapper)
+
+    return decorator

ninja_aio/exceptions.py

@@ -4,6 +4,7 @@ from joserfc.errors import JoseError
 from ninja import NinjaAPI
 from django.http import HttpRequest, HttpResponse
 from pydantic import ValidationError
+from django.db.models import Model
 
 
 class BaseException(Exception):
@@ -35,6 +36,18 @@ class AuthError(BaseException):
     pass
 
 
+class NotFoundError(BaseException):
+    status_code = 404
+    error = "not found"
+
+    def __init__(self, model: Model, details=None):
+        super().__init__(
+            error={model._meta.verbose_name: self.error},
+            status_code=self.status_code,
+            details=details,
+        )
+
+
 class PydanticValidationError(BaseException):
     def __init__(self, details=None):
         super().__init__("Validation Error", 400, details)

ninja_aio/models.py

@@ -17,7 +17,7 @@ from django.db.models.fields.related_descriptors import (
     ForwardOneToOneDescriptor,
 )
 
-from .exceptions import SerializeError
+from .exceptions import SerializeError, NotFoundError
 from .types import S_TYPES, F_TYPES, SCHEMA_TYPES, ModelSerializerMeta
 
 
@@ -26,6 +26,79 @@ async def agetattr(obj, name: str, default=None):
 
 
 class ModelUtil:
+    """
+    ModelUtil
+    =========
+    Async utility bound to a Django model class (or a ModelSerializer subclass)
+    providing high‑level CRUD helpers plus (de)serialization glue for Django Ninja.
+
+    Overview
+    --------
+    Central responsibilities:
+    - Introspect model metadata (field list, pk name, verbose names).
+    - Normalize inbound payloads (custom / optional fields, FK resolution, base64 decoding).
+    - Normalize outbound payloads (resolve nested relation dicts into model instances).
+    - Prefetch reverse relations to mitigate N+1 issues.
+    - Invoke optional serializer hooks: custom_actions(), post_create(), queryset_request().
+
+    Compatible With
+    ---------------
+    - Plain Django models.
+    - Models using ModelSerializerMeta exposing:
+        get_fields(mode), is_custom(name), is_optional(name),
+        queryset_request(request), custom_actions(payload), post_create().
+
+    Key Methods
+    -----------
+    - get_object(request, pk=None, filters=None, getters=None, with_qs_request=True)
+        Returns a single object (when pk/getters) or a queryset (otherwise), with
+        select_related + prefetch_related applied.
+    - get_reverse_relations()
+        Discovers reverse relation names for safe prefetch_related usage.
+    - parse_input_data(request, data)
+        Converts a Schema into a model-ready dict:
+          * Strips custom + ignored optionals.
+          * Decodes BinaryField (base64 -> bytes).
+          * Replaces FK ids with related instances.
+        Returns (payload, customs_dict).
+    - parse_output_data(request, data)
+        Post-processes serialized output; replaces nested FK/OneToOne dicts
+        with authoritative related instances and rewrites nested FK keys to <name>_id.
+    - create_s / read_s / update_s / delete_s
+        High-level async CRUD operations wrapping the above transformations and hooks.
+
+    Error Handling
+    --------------
+    - Missing objects -> SerializeError({...}, 404).
+    - Bad base64 -> SerializeError({...}, 400).
+
+    Performance Notes
+    -----------------
+    - Each FK in parse_input_data triggers its own async fetch.
+    - Reverse relation prefetching is opportunistic; trim serializable fields
+      if over-fetching becomes an issue.
+
+    Return Shapes
+    -------------
+    - create_s / read_s / update_s -> dict (post-processed schema dump).
+    - delete_s -> None.
+    - get_object -> model instance or queryset.
+
+    Design Choices
+    --------------
+    - Stateless aside from holding the target model (safe to instantiate per request).
+    - Avoids caching; callers may add caching where profiling justifies it.
+    - Treats absent optional fields as "leave unchanged" (update) or "omit" (create).
+
+    Assumptions
+    -----------
+    - Schema provides model_dump(mode="json").
+    - Django async ORM (Django 4.1+).
+    - BinaryField inputs are base64 strings.
+    - Related primary keys are simple scalars on input.
+
+    """
+
     def __init__(self, model: type["ModelSerializer"] | models.Model):
         self.model = model
 
@@ -87,7 +160,7 @@ class ModelUtil:
         try:
             obj = await obj_qs.aget(**get_q)
         except ObjectDoesNotExist:
-            raise SerializeError({self.model_name: "not found"}, 404)
+            raise NotFoundError(self.model)
 
         return obj
 
@@ -214,21 +287,278 @@ class ModelUtil:
 
 
 class ModelSerializer(models.Model, metaclass=ModelSerializerMeta):
+    """
+    ModelSerializer
+    =================
+    Abstract mixin for Django models centralizing (on the model class itself) the
+    declarative configuration required to auto-generate create / update / read /
+    related schemas.
+
+    Goals
+    - Remove duplication between Model and separate serializer classes.
+    - Provide clear extension points (sync + async hooks, custom synthetic fields).
+
+    Inner configuration classes
+    - CreateSerializer
+        fields    : required model fields on create
+        optionals : optional model fields (accepted if present; ignored if None)
+        customs   : [(name, type, default)] synthetic (non‑model) inputs
+        excludes  : model fields disallowed on create
+    - UpdateSerializer (same structure; usually use optionals for PATCH-like behavior)
+    - ReadSerializer
+        fields    : model fields to expose
+        excludes  : fields always excluded (e.g. password)
+        customs   : [(name, type, default)] computed outputs (property > callable > default)
+
+    Generated schema helpers
+    - generate_create_s()   -> input schema ("In")
+    - generate_update_s()   -> input schema for partial/full update ("Patch")
+    - generate_read_s()     -> detailed output schema ("Out")
+    - generate_related_s()  -> compact nested schema ("Related")
+
+    Relation handling (only if related model is also a ModelSerializer)
+    - Forward FK / OneToOne serialized as single nested objects
+    - Reverse OneToOne / Reverse FK / M2M serialized as single or list
+    - Relations skipped if related model exposes no read/custom fields
+
+    Classification helpers
+    - is_custom(field)   -> True if declared in create/update customs
+    - is_optional(field) -> True if declared in create/update optionals
+
+    Sync lifecycle hooks (override as needed)
+      save():
+        on_create_before_save()  (only first insert)
+        before_save()
+        super().save()
+        on_create_after_save()   (only first insert)
+        after_save()
+      delete():
+        super().delete()
+        on_delete()
+
+    Async extension points
+    - queryset_request(request): request-scoped queryset filtering
+    - post_create(): async logic after creation
+    - custom_actions(payload_customs): react to synthetic fields
+
+    Utilities
+    - has_changed(field): compares in-memory value vs DB persisted value
+    - verbose_name_path_resolver(): slugified plural verbose name
+
+    Implementation notes
+    - If both fields and excludes are empty (create/update), optionals are used as the base.
+    - customs + optionals are passed as custom_fields to the schema factory.
+    - Nested relation schemas generated only if the related model explicitly declares
+      readable or custom fields.
+
+    Minimal example
+    ```python
+    from django.db import models
+    from ninja_aio.models import ModelSerializer
+    
+    
+    class User(ModelSerializer):
+        username = models.CharField(max_length=150, unique=True)
+        email = models.EmailField(unique=True)
+
+        class CreateSerializer:
+            fields = ["username", "email"]
+
+        class ReadSerializer:
+            fields = ["id", "username", "email"]
+
+        def __str__(self):
+            return self.username
+    ```
+    -------------------------------------
+    Conceptual Equivalent (Ninja example)
+    Using django-ninja you might otherwise write:
+    ```python
+    from ninja import ModelSchema
+    from api.models import User
+    
+    
+    class UserIn(ModelSchema):
+        class Meta:
+            model = User
+            fields = ["username", "email"]
+    
+    
+    class UserOut(ModelSchema):
+        class Meta:
+            model = User
+            model_fields = ["id", "username", "email"]
+    ```
+
+    Summary
+    Centralizes serialization intent on the model, reducing boilerplate and keeping
+    API and model definitions consistent.
+    """
     class Meta:
         abstract = True
 
     class CreateSerializer:
+        """Configuration container describing how to build a create (input) schema for a model.
+
+        Purpose
+        -------
+        Describes which fields are accepted (and in what form) when creating a new
+        instance. A factory/metaclass can read this configuration to generate a
+        Pydantic / Ninja input schema.
+
+        Attributes
+        ----------
+        fields : list[str]
+            Explicit REQUIRED model field names for creation. If empty, the
+            implementation may infer required fields from the model (excluding
+            auto / read-only fields). Prefer being explicit.
+        optionals : list[tuple[str, type]]
+            Model fields allowed on create but not required. Each tuple:
+                (field_name, python_type)
+            If omitted in the payload they are ignored; if present with null/None
+            the caller signals an intentional null (subject to model constraints).
+        customs : list[tuple[str, type, Any]]
+            Non-model / synthetic input fields driving creation logic (e.g.,
+            password confirmation, initial related IDs, flags). Each tuple:
+                (name, python_type, default_value)
+            Resolution order (implementation-dependent):
+                1. Value provided by the incoming payload.
+                2. If default_value is callable -> invoked (passing model class or
+                   context if supported).
+                3. Literal default_value.
+            These values are typically consumed inside custom_actions or post_create
+            hooks and are NOT persisted directly unless you do so manually.
+        excludes : list[str]
+            Model field names that must be rejected on create (e.g., "id",
+            audit fields, computed columns).
+
+        Recommended Conventions
+        -----------------------
+        - Always exclude primary keys and auto-managed timestamps.
+        - Keep customs minimal and clearly documented.
+        - Use optionals instead of putting nullable fields in fields if they are
+          not logically required for initial creation.
+
+        Extensibility
+        -------------
+        A higher-level builder can:
+            1. Collect fields + optionals + customs.
+            2. Build a schema where fields are required, optionals are Optional[…],
+               and customs become additional inputs not mapped directly to the model.
+        """
         fields: list[str] = []
         customs: list[tuple[str, type, Any]] = []
         optionals: list[tuple[str, type]] = []
         excludes: list[str] = []
 
     class ReadSerializer:
+        """Configuration container describing how to build a read (output) schema for a model.
+
+        Attributes
+        ---------
+        fields : list[str]
+            Explicit model field names to include in the read schema. If empty, an
+            implementation may choose to include all model fields (or none, depending
+            on the consuming logic).
+        excludes : list[str]
+            Model field names to force-exclude even if they would otherwise be included
+            (e.g., sensitive columns like password, secrets, internal flags).
+        customs : list[tuple[str, type, Any]]
+            Additional computed / synthetic attributes to append to the serialized
+            output. Each tuple is:
+                (attribute_name, python_type, default_value)
+            The attribute is resolved in the following preferred order (implementation
+            dependent):
+                1. Attribute / property on the model instance with that name.
+                2. Callable (if the default_value is a callable) invoked to produce a value.
+                3. Fallback to the literal default_value.
+            Example:
+                customs = [
+                    ("full_name", str, lambda obj: f"{obj.first_name} {obj.last_name}".strip())
+                ]
+
+        Conceptual Equivalent (Ninja example)
+        -------------------------------------
+        Using django-ninja you might otherwise write:
+        
+        ```python
+        from ninja import ModelSchema
+        from api.models import User
+
+
+        class UserOut(ModelSchema):            
+            class Meta:
+                model = User
+                model_fields = ["id", "username", "email"]
+        ```
+        
+        This ReadSerializer object centralizes the same intent in a lightweight,
+        framework-agnostic configuration primitive that can be inspected to build
+        schemas dynamically.
+
+        Recommended Conventions
+        -----------------------
+        - Keep fields minimal; prefer explicit inclusion over implicit broad exposure.
+        - Use excludes as a safety net (e.g., always exclude "password").
+        - For customs, always specify a concrete python_type for better downstream
+          validation / OpenAPI generation.
+        - Prefer callables as default_value when computing derived data; use simple
+          literals only for static fallbacks.
+
+        Extensibility Notes
+        -------------------
+        A higher-level factory or metaclass can:
+            1. Read these lists.
+            2. Reflect on the model.
+            3. Generate a Pydantic / Ninja schema class at runtime.
+        This separation enables cleaner unit testing (the config is pure data) and
+        reduces coupling to a specific serialization framework."""
         fields: list[str] = []
         excludes: list[str] = []
         customs: list[tuple[str, type, Any]] = []
 
     class UpdateSerializer:
+        """Configuration container describing how to build an update (partial/full) input schema.
+
+        Purpose
+        -------
+        Defines which fields can be changed and how they are treated when updating
+        an existing instance (PATCH / PUT–style operations).
+
+        Attributes
+        ----------
+        fields : list[str]
+            Explicit REQUIRED fields for an update operation (rare; most updates are
+            partial so this is often left empty). If non-empty, these must be present
+            in the payload.
+        optionals : list[tuple[str, type]]
+            Updatable fields that are optional (most typical case). Omitted fields
+            are left untouched. Provided null/None values indicate an explicit attempt
+            to nullify (subject to model constraints).
+        customs : list[tuple[str, type, Any]]
+            Non-model / instruction fields guiding update behavior (e.g., "rotate_key",
+            "regenerate_token"). Each tuple:
+                (name, python_type, default_value)
+            Resolution order mirrors CreateSerializer (payload > callable > literal).
+            Typically consumed in custom_actions before or after saving.
+        excludes : list[str]
+            Fields that must never be updated (immutable or managed fields).
+
+        Recommended Conventions
+        -----------------------
+        - Prefer listing editable columns in optionals rather than fields to facilitate
+          partial updates.
+        - Use customs for operational flags (e.g., "reset_password": bool).
+        - Keep excludes synchronized with CreateSerializer excludes where appropriate.
+
+        Extensibility
+        -------------
+        A schema builder can:
+            1. Treat fields as required.
+            2. Treat optionals as Optional[…].
+            3. Inject customs as additional validated inputs.
+            4. Enforce excludes by rejecting them if present in incoming data.
+        """
         fields: list[str] = []
         customs: list[tuple[str, type, Any]] = []
         optionals: list[tuple[str, type]] = []

ninja_aio/views.py

@@ -17,6 +17,7 @@ from .schemas import (
     M2MRemoveSchemaIn,
 )
 from .types import ModelSerializerMeta, VIEW_TYPES
+from .decoratos import unique_view
 
 ERROR_CODES = frozenset({400, 401, 404, 428})
 
@@ -243,10 +244,9 @@ class APIViewSet:
             description=self.create_docs,
             response={201: self.schema_out, self.error_codes: GenericMessageSchema},
         )
+        @unique_view(self)
         async def create(request: HttpRequest, data: self.schema_in):  # type: ignore
             return 201, await self.model_util.create_s(request, data, self.schema_out)
-
-        create.__name__ = f"create_{self.model_util.model_name}"
         return create
 
     def list_view(self):
@@ -260,6 +260,7 @@ class APIViewSet:
                 self.error_codes: GenericMessageSchema,
             },
         )
+        @unique_view(self, plural=True)
         @paginate(self.pagination_class)
         async def list(
             request: HttpRequest,
@@ -278,8 +279,6 @@ class APIViewSet:
                 async for obj in qs.all()
             ]
             return objs
-
-        list.__name__ = f"list_{self.model_util.verbose_name_view_resolver()}"
         return list
 
     def retrieve_view(self):
@@ -290,11 +289,10 @@ class APIViewSet:
             description=self.retrieve_docs,
             response={200: self.schema_out, self.error_codes: GenericMessageSchema},
         )
+        @unique_view(self)
         async def retrieve(request: HttpRequest, pk: Path[self.path_schema]):  # type: ignore
             obj = await self.model_util.get_object(request, self._get_pk(pk))
             return await self.model_util.read_s(request, obj, self.schema_out)
-
-        retrieve.__name__ = f"retrieve_{self.model_util.model_name}"
         return retrieve
 
     def update_view(self):
@@ -305,6 +303,7 @@ class APIViewSet:
             description=self.update_docs,
             response={200: self.schema_out, self.error_codes: GenericMessageSchema},
         )
+        @unique_view(self)
         async def update(
             request: HttpRequest,
             data: self.schema_update,  # type: ignore
@@ -313,8 +312,6 @@ class APIViewSet:
             return await self.model_util.update_s(
                 request, data, self._get_pk(pk), self.schema_out
             )
-
-        update.__name__ = f"update_{self.model_util.model_name}"
         return update
 
     def delete_view(self):
@@ -325,10 +322,10 @@ class APIViewSet:
             description=self.delete_docs,
             response={204: None, self.error_codes: GenericMessageSchema},
         )
+
+        @unique_view(self)
         async def delete(request: HttpRequest, pk: Path[self.path_schema]):  # type: ignore
             return 204, await self.model_util.delete_s(request, self._get_pk(pk))
-
-        delete.__name__ = f"delete_{self.model_util.model_name}"
         return delete
 
     def views(self):

django_ninja_aio_crud-0.10.3.dist-info/RECORD

@@ -1,14 +0,0 @@
-ninja_aio/__init__.py,sha256=fZFssPDWLCd-cBFhbchuSNtmVBoW_DIr8XNcWxN2Y_4,120
-ninja_aio/api.py,sha256=Fe6l3YCy7MW5TY4-Lbl80CFuK2NT2Y7tHfmqPk6Mqak,1735
-ninja_aio/auth.py,sha256=c_ILAySswjbSIqnE9Y0G5n1qreXzAtSAaWfrhyer-i8,1283
-ninja_aio/exceptions.py,sha256=gPnZX1Do2GXudbU8wDYkwhO70Qj0ZNrIJJ2UXRs9vYk,2241
-ninja_aio/models.py,sha256=r-Ku5EOSTq1eAeXZHVz0ILTyXBmbS4o46JYA_Cp_B8w,18969
-ninja_aio/parsers.py,sha256=e_4lGCPV7zs-HTqtdJTc8yQD2KPAn9njbL8nF_Mmgkc,153
-ninja_aio/renders.py,sha256=0eYklRKd59aV4cZDom5vLZyA99Ob17OwkpMybsRXvyg,1970
-ninja_aio/schemas.py,sha256=Fzu2ko3kUxkOnrjG5QYdmOXZd2gcpYGjVuocCW44NfQ,473
-ninja_aio/types.py,sha256=TJSGlA7bt4g9fvPhJ7gzH5tKbLagPmZUzfgttEOp4xs,468
-ninja_aio/views.py,sha256=Mb38z0QS9Iwe-qB9wuuxcfCOJymRI9SppbHOfns6yHg,20944
-django_ninja_aio_crud-0.10.3.dist-info/licenses/LICENSE,sha256=yrDAYcm0gRp_Qyzo3GQa4BjYjWRkAhGC8QRva__RYq0,1073
-django_ninja_aio_crud-0.10.3.dist-info/WHEEL,sha256=G2gURzTEtmeR8nrdXUJfNiB3VYVxigPQ-bEQujpNiNs,82
-django_ninja_aio_crud-0.10.3.dist-info/METADATA,sha256=FoNR5DJfYjhC9C9wJyLRsUZnww65ScjS7RpT-av5OxQ,14139
-django_ninja_aio_crud-0.10.3.dist-info/RECORD,,