django-display-ids 0.1.3__py3-none-any.whl → 0.1.4__py3-none-any.whl

django_display_ids/__init__.py

@@ -30,6 +30,12 @@ from .encoding import (
     encode_display_id,
     encode_uuid,
 )
+from .examples import (
+    example_display_id,
+    example_display_id_for_prefix,
+    example_uuid,
+    example_uuid_for_prefix,
+)
 from .exceptions import (
     AmbiguousIdentifierError,
     InvalidIdentifierError,
@@ -50,6 +56,11 @@ __all__ = [  # noqa: RUF022 - keep categorized order for readability
     "decode_uuid",
     "encode_display_id",
     "decode_display_id",
+    # Examples (for OpenAPI schemas, documentation)
+    "example_uuid",
+    "example_display_id",
+    "example_uuid_for_prefix",  # alias
+    "example_display_id_for_prefix",  # alias
     # Core resolver
     "resolve_object",
     # Errors

django_display_ids/contrib/drf_spectacular/__init__.py

@@ -0,0 +1,93 @@
+"""drf-spectacular extension for DisplayIDField.
+
+This extension auto-registers when drf-spectacular is installed, providing
+proper OpenAPI schema generation for DisplayIDField.
+"""
+
+from __future__ import annotations
+
+try:
+    from drf_spectacular.extensions import OpenApiSerializerFieldExtension
+except ImportError:
+    # drf-spectacular not installed, skip extension registration
+    pass
+else:
+    from django_display_ids.encoding import ENCODED_UUID_LENGTH, encode_uuid
+    from django_display_ids.examples import example_uuid_for_prefix
+
+    class DisplayIDFieldExtension(OpenApiSerializerFieldExtension):
+        """OpenAPI schema extension for DisplayIDField.
+
+        Generates schema with correct prefix example based on the field's
+        configuration or the model's display_id_prefix.
+        """
+
+        target_class = (
+            "django_display_ids.contrib.rest_framework.serializers.DisplayIDField"
+        )
+        match_subclasses = True
+
+        def _get_model_from_view(self, auto_schema):
+            """Try to get model from the view's queryset."""
+            if auto_schema is None:
+                return None
+            view = getattr(auto_schema, "view", None)
+            if view is None:
+                return None
+            # Try get_queryset first
+            if hasattr(view, "get_queryset"):
+                try:
+                    queryset = view.get_queryset()
+                    if hasattr(queryset, "model"):
+                        return queryset.model
+                except Exception:
+                    pass
+            # Try queryset attribute
+            queryset = getattr(view, "queryset", None)
+            if queryset is not None and hasattr(queryset, "model"):
+                return queryset.model
+            return None
+
+        def map_serializer_field(self, auto_schema, direction):
+            """Generate OpenAPI schema for DisplayIDField."""
+            # Get prefix from field override or try to get from model
+            prefix = self.target._prefix_override
+
+            if prefix is None:
+                parent = self.target.parent
+                if parent is not None:
+                    # Try serializer's display_id_prefix attribute first
+                    prefix = getattr(parent, "display_id_prefix", None)
+
+                    # Then try Meta.model.display_id_prefix
+                    if prefix is None:
+                        meta = getattr(parent, "Meta", None)
+                        model = getattr(meta, "model", None) if meta else None
+                        if model is not None:
+                            prefix = getattr(model, "display_id_prefix", None)
+
+            # Try to get prefix from view's queryset model
+            if prefix is None:
+                model = self._get_model_from_view(auto_schema)
+                if model is not None:
+                    prefix = getattr(model, "display_id_prefix", None)
+
+            # Build schema
+            if prefix:
+                example_uuid = example_uuid_for_prefix(prefix)
+                example_encoded = encode_uuid(example_uuid)
+                example = f"{prefix}_{example_encoded}"
+                description = f"Human-readable identifier with '{prefix}_' prefix"
+            else:
+                example_uuid = example_uuid_for_prefix("type")
+                example_encoded = encode_uuid(example_uuid)
+                example = f"type_{example_encoded}"
+                description = "Human-readable identifier with type prefix"
+
+            return {
+                "type": "string",
+                "description": description,
+                "example": example,
+                "pattern": f"^[a-z]{{1,16}}_[0-9A-Za-z]{{{ENCODED_UUID_LENGTH}}}$",
+                "readOnly": True,
+            }

django_display_ids/contrib/rest_framework/__init__.py

@@ -1,7 +1,48 @@
 """Django REST Framework integration for django-display-ids."""
 
+import contextlib
+
+from .serializers import DisplayIDField
 from .views import DisplayIDLookupMixin
 
-__all__ = [
+# Register drf-spectacular extension if available
+# The extension auto-registers when the module is imported
+with contextlib.suppress(ImportError):
+    from django_display_ids.contrib import (
+        drf_spectacular as _drf_spectacular,  # noqa: F401
+    )
+
+# OpenAPI parameter descriptions for consistent documentation
+ID_PARAM_DESCRIPTION = "Identifier: display_id (prefix_xxx) or UUID"
+ID_PARAM_DESCRIPTION_WITH_SLUG = "Identifier: display_id (prefix_xxx), UUID, or slug"
+
+
+def id_param_description(prefix: str, *, with_slug: bool = False) -> str:
+    """Generate ID parameter description with the actual prefix.
+
+    Args:
+        prefix: The display_id prefix (e.g., "user", "app").
+        with_slug: Include slug as an identifier option.
+
+    Returns:
+        Description string for OpenAPI parameter.
+
+    Example:
+        >>> id_param_description("user")
+        'Identifier: display_id (user_xxx) or UUID'
+
+        >>> id_param_description("app", with_slug=True)
+        'Identifier: display_id (app_xxx), UUID, or slug'
+    """
+    if with_slug:
+        return f"Identifier: display_id ({prefix}_xxx), UUID, or slug"
+    return f"Identifier: display_id ({prefix}_xxx) or UUID"
+
+
+__all__ = [  # noqa: RUF022 - keep logical order for readability
+    "DisplayIDField",
     "DisplayIDLookupMixin",
+    "ID_PARAM_DESCRIPTION",
+    "ID_PARAM_DESCRIPTION_WITH_SLUG",
+    "id_param_description",
 ]

django_display_ids/contrib/rest_framework/serializers.py

@@ -0,0 +1,116 @@
+"""Django REST Framework serializer fields for display IDs."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING, Any
+
+from rest_framework import serializers
+
+from django_display_ids.conf import get_setting
+from django_display_ids.encoding import PREFIX_PATTERN, encode_display_id
+
+if TYPE_CHECKING:
+    from django.db import models
+
+__all__ = [
+    "DisplayIDField",
+]
+
+
+class DisplayIDField(serializers.SerializerMethodField):
+    """Serializer field that returns the display_id from a model.
+
+    Automatically generates OpenAPI schema with the correct prefix example
+    when drf-spectacular is installed.
+
+    The field reads `display_id_prefix` from the model to determine the prefix.
+    If the model has no prefix, the field returns None and can be excluded
+    from serialization.
+
+    Example:
+        class UserSerializer(serializers.Serializer):
+            id = serializers.UUIDField(source="uid", read_only=True)
+            display_id = DisplayIDField()
+
+        # Output: {"id": "...", "display_id": "user_2nBm7K8xYq1pLwZj"}
+
+    Example with custom prefix (overrides model's prefix):
+        class UserSerializer(serializers.Serializer):
+            display_id = DisplayIDField(prefix="usr")
+
+    Attributes:
+        prefix: Optional prefix override. If not set, uses model's
+            display_id_prefix attribute.
+    """
+
+    def __init__(self, prefix: str | None = None, **kwargs: Any) -> None:
+        """Initialize the field.
+
+        Args:
+            prefix: Optional prefix override. If not set, uses model's
+                display_id_prefix attribute.
+            **kwargs: Additional arguments passed to SerializerMethodField.
+
+        Raises:
+            ValueError: If prefix is invalid (must be 1-16 lowercase letters).
+        """
+        if prefix is not None and not PREFIX_PATTERN.match(prefix):
+            raise ValueError(f"prefix must be 1-16 lowercase letters, got: {prefix!r}")
+        self._prefix_override = prefix
+        kwargs["read_only"] = True
+        super().__init__(**kwargs)
+
+    def get_prefix(self, obj: models.Model) -> str | None:
+        """Get the prefix for the display ID.
+
+        Args:
+            obj: The model instance.
+
+        Returns:
+            The prefix string or None if not available.
+        """
+        if self._prefix_override is not None:
+            return self._prefix_override
+        return getattr(obj, "display_id_prefix", None)
+
+    def to_representation(self, obj: models.Model) -> str:
+        """Return the display_id from the model.
+
+        Args:
+            obj: The model instance.
+
+        Returns:
+            The display_id string.
+
+        Raises:
+            ValueError: If no prefix is available (neither on field nor model).
+        """
+        prefix = self.get_prefix(obj)
+        if prefix is None:
+            raise ValueError(
+                f"DisplayIDField requires a prefix. Either set prefix= on the "
+                f"field or add display_id_prefix to {obj.__class__.__name__}."
+            )
+
+        # If using prefix override, generate display_id with that prefix
+        if self._prefix_override is not None:
+            # Get uuid_field name from model, then fall back to settings
+            uuid_field_name = getattr(obj, "uuid_field", None)
+            if uuid_field_name is None:
+                uuid_field_name = get_setting("UUID_FIELD")
+            uuid_value = getattr(obj, uuid_field_name, None)
+            if uuid_value is None:
+                raise ValueError(
+                    f"Cannot generate display_id: {obj.__class__.__name__} "
+                    f"has no '{uuid_field_name}' field."
+                )
+            return encode_display_id(prefix, uuid_value)
+
+        # Use the model's display_id property
+        if hasattr(obj, "display_id"):
+            return obj.display_id
+
+        raise ValueError(
+            f"Cannot generate display_id: {obj.__class__.__name__} "
+            f"has no display_id property."
+        )

django_display_ids/examples.py

@@ -0,0 +1,88 @@
+"""Deterministic example generation for display IDs.
+
+These functions generate consistent example UUIDs and display IDs based on
+a prefix or model, useful for OpenAPI schema examples and documentation.
+"""
+
+from __future__ import annotations
+
+import hashlib
+import uuid
+from typing import TYPE_CHECKING
+
+from .encoding import encode_uuid
+
+if TYPE_CHECKING:
+    from django.db.models import Model
+
+__all__ = [
+    "example_display_id",
+    "example_uuid",
+]
+
+
+def _get_prefix(prefix_or_model: str | type[Model]) -> str:
+    """Extract prefix from string or model class."""
+    if isinstance(prefix_or_model, str):
+        return prefix_or_model
+    # It's a model class
+    prefix = getattr(prefix_or_model, "display_id_prefix", None)
+    if prefix is None:
+        raise ValueError(f"Model {prefix_or_model.__name__} has no display_id_prefix")
+    return prefix
+
+
+def example_uuid(prefix_or_model: str | type[Model]) -> uuid.UUID:
+    """Generate a deterministic UUID from a prefix or model.
+
+    Uses SHA-256 hash of the prefix to generate a consistent UUID.
+    This ensures the same prefix always produces the same example UUID.
+
+    Args:
+        prefix_or_model: Either a display ID prefix string (e.g., "app")
+            or a model class with a display_id_prefix attribute.
+
+    Returns:
+        A deterministic UUID based on the prefix.
+
+    Example:
+        >>> example_uuid("app")
+        UUID('a172cedc-ae47-474b-615c-54d510a5d84a')
+
+        >>> example_uuid(App)  # Model with display_id_prefix = "app"
+        UUID('a172cedc-ae47-474b-615c-54d510a5d84a')
+    """
+    prefix = _get_prefix(prefix_or_model)
+    hash_bytes = hashlib.sha256(prefix.encode()).digest()[:16]
+    return uuid.UUID(bytes=hash_bytes)
+
+
+def example_display_id(prefix_or_model: str | type[Model]) -> str:
+    """Generate a deterministic display ID example from a prefix or model.
+
+    Combines the prefix with a base62-encoded UUID derived from
+    the prefix itself.
+
+    Args:
+        prefix_or_model: Either a display ID prefix string (e.g., "app")
+            or a model class with a display_id_prefix attribute.
+
+    Returns:
+        A complete display ID example (e.g., "app_4ueEO5Nz4X7u9qc3FVHokM").
+
+    Example:
+        >>> example_display_id("app")
+        'app_4ueEO5Nz4X7u9qc3FVHokM'
+
+        >>> example_display_id(App)  # Model with display_id_prefix = "app"
+        'app_4ueEO5Nz4X7u9qc3FVHokM'
+    """
+    prefix = _get_prefix(prefix_or_model)
+    ex_uuid = example_uuid(prefix)
+    encoded = encode_uuid(ex_uuid)
+    return f"{prefix}_{encoded}"
+
+
+# Aliases for backwards compatibility
+example_uuid_for_prefix = example_uuid
+example_display_id_for_prefix = example_display_id

{django_display_ids-0.1.3.dist-info → django_display_ids-0.1.4.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-display-ids
-Version: 0.1.3
+Version: 0.1.4
 Summary: Stripe-like prefixed IDs for Django. Works with existing UUIDs — no schema changes.
 Keywords: django,stripe,uuid,base62,prefixed-id,drf,shortuuid,nanoid,ulid
 License: ISC
@@ -122,6 +122,93 @@ class InvoiceView(DisplayIDLookupMixin, APIView):
         return Response({"id": str(invoice.id)})
 ```
 
+#### Serializer Field
+
+Include `display_id` in your API responses:
+
+```python
+from rest_framework import serializers
+from django_display_ids.contrib.rest_framework import DisplayIDField
+
+class InvoiceSerializer(serializers.Serializer):
+    id = serializers.UUIDField(read_only=True)
+    display_id = DisplayIDField()
+    name = serializers.CharField()
+
+# Output: {"id": "...", "display_id": "inv_2aUyqjCzEIiEcYMKj7TZtw", ...}
+```
+
+The field reads `display_id_prefix` from the model. You can override it:
+
+```python
+display_id = DisplayIDField(prefix="inv")  # Use custom prefix
+```
+
+Prefix must be 1-16 lowercase letters. Invalid prefixes raise `ValueError` at initialization.
+
+**OpenAPI/drf-spectacular**: When drf-spectacular is installed, the field automatically generates proper schema with prefix-specific examples (e.g., `inv_2aUyqjCzEIiEcYMKj7TZtw`). The prefix is resolved from (in order): field's `prefix=` argument, serializer's `Meta.model.display_id_prefix`, or the view's queryset model.
+
+#### OpenAPI Parameter Descriptions
+
+For consistent API documentation, use the provided description helpers:
+
+```python
+from django_display_ids.contrib.rest_framework import id_param_description
+from drf_spectacular.utils import extend_schema, OpenApiParameter
+from drf_spectacular.types import OpenApiTypes
+
+@extend_schema(
+    parameters=[
+        OpenApiParameter(
+            "id",
+            OpenApiTypes.STR,
+            OpenApiParameter.PATH,
+            description=id_param_description("inv"),
+            # -> "Identifier: display_id (inv_xxx) or UUID"
+        )
+    ],
+)
+class InvoiceViewSet(DisplayIDLookupMixin, ModelViewSet):
+    ...
+```
+
+For endpoints that also accept slugs:
+
+```python
+description=id_param_description("app", with_slug=True)
+# -> "Identifier: display_id (app_xxx), UUID, or slug"
+```
+
+Generic constants are also available:
+
+```python
+from django_display_ids.contrib.rest_framework import (
+    ID_PARAM_DESCRIPTION,           # "Identifier: display_id (prefix_xxx) or UUID"
+    ID_PARAM_DESCRIPTION_WITH_SLUG, # "Identifier: display_id (prefix_xxx), UUID, or slug"
+)
+```
+
+#### Deterministic Examples for OpenAPI
+
+Generate consistent example UUIDs and display IDs for OpenAPI schemas:
+
+```python
+from django_display_ids import example_uuid, example_display_id
+
+# Generate deterministic UUID for a prefix
+example_uuid("inv")
+# -> UUID('a172cedc-ae47-474b-615c-54d510a5d84a')
+
+# Generate deterministic display ID
+example_display_id("inv")
+# -> "inv_4ueEO5Nz4X7u9qc3FVHokM"
+
+# Also works with model classes
+example_uuid(Invoice)  # Uses Invoice.display_id_prefix
+```
+
+The same prefix always produces the same example, ensuring consistent documentation across regenerations.
+
 ### Model Mixin
 
 Add a `display_id` property to your models:

{django_display_ids-0.1.3.dist-info → django_display_ids-0.1.4.dist-info}/RECORD

@@ -1,10 +1,13 @@
-django_display_ids/__init__.py,sha256=Iy-JKsXmO4IfF-F9HU4MnGPHLWiixBxXp4ACU2rWrWQ,2334
+django_display_ids/__init__.py,sha256=7_rl0cA0LWGIbhg5SbnWAZfKAWyXEpA5XzKDmPnoM8U,2650
 django_display_ids/admin.py,sha256=uRyPH3q5e9D5oMxs6PtCHq0syBXs--i1alRoe-EcIJo,2935
 django_display_ids/conf.py,sha256=qTsCzKeNBdJpEVeEkx2kFeWHBFa_NZwV_tpt-UTyRR0,1132
 django_display_ids/contrib/__init__.py,sha256=sxGJK8Whb6cL7RqACqGRYrIZvaMwP3l6dYk3mIYWzDY,62
-django_display_ids/contrib/rest_framework/__init__.py,sha256=hBk-6m01T66J5bar3GKwApktOnHhDtK-gUpjghlKoJo,148
+django_display_ids/contrib/drf_spectacular/__init__.py,sha256=uPA1foQ8BjyHX3SS9Ta9yI7wp0y3sLdQ4EPOx4KIBlI,3770
+django_display_ids/contrib/rest_framework/__init__.py,sha256=Xun6zMhCZzQJZQ7ywvBYoKhTJIZEV84AntrbSWfBjYI,1567
+django_display_ids/contrib/rest_framework/serializers.py,sha256=zsYDmXVbra5gUkOnupwJd_vEQnLbgXVWNwehHje2GTs,3991
 django_display_ids/contrib/rest_framework/views.py,sha256=mu-twvdRbJedzSfLWVNn2BazFpAQzwRB5Eq3w2bxvvs,6056
 django_display_ids/encoding.py,sha256=csIwUZaQKSOLwRU6-DWGTNGvSxmroyK0Yt7TBCo0AFE,2945
+django_display_ids/examples.py,sha256=rrZgL-EoWz0mC32T-RNWCo45Y8_BXV_6r_5tRIz77gs,2677
 django_display_ids/exceptions.py,sha256=nmyRfpsqVvz226Zcu_QANwr8MudbfoX09mAgOCwuPuQ,3022
 django_display_ids/managers.py,sha256=EFvlQxsSFXeM8TVvV4NZKeKMC7QB3C0zYGgZ6bvSr4k,6884
 django_display_ids/models.py,sha256=_IXxaFlVw2MqobQUw4Cy4rB66LsTz6kiI5YpoSpnkCY,4156
@@ -13,6 +16,6 @@ django_display_ids/resolver.py,sha256=oCoA6jbGCFS8SMrkfD_oSSBQNrSxnxdooK5j933eA9
 django_display_ids/strategies.py,sha256=Rq00-AW_FB8-K04u2oBK5J6kPiYgsE3TdYlLyK_zro0,4436
 django_display_ids/typing.py,sha256=2O3kT7XKkiE7WI9A5KkILPM-Zi7-zCy5gVvXQL_J2mI,478
 django_display_ids/views.py,sha256=sLsJm8Tpe3Qk1gOLcDzfpazxuaVqTCAdgVIXOONFnKQ,5096
-django_display_ids-0.1.3.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
-django_display_ids-0.1.3.dist-info/METADATA,sha256=AjMU5ctNag1QVDINfx4gggW0VWfYkkIEE1brlokAUqo,9649
-django_display_ids-0.1.3.dist-info/RECORD,,
+django_display_ids-0.1.4.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
+django_display_ids-0.1.4.dist-info/METADATA,sha256=46ob0brsZSBW7QFrmISYvNkD7mQGu3NkIXRe3ueae6g,12356
+django_display_ids-0.1.4.dist-info/RECORD,,