django-display-ids 0.1.3__py3-none-any.whl → 0.2.0__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.2.0.dist-info/METADATA

@@ -0,0 +1,111 @@
+Metadata-Version: 2.3
+Name: django-display-ids
+Version: 0.2.0
+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
+Classifier: Development Status :: 4 - Beta
+Classifier: Framework :: Django
+Classifier: Framework :: Django :: 4.2
+Classifier: Framework :: Django :: 5.2
+Classifier: Framework :: Django :: 6.0
+Classifier: License :: OSI Approved :: ISC License (ISCL)
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Typing :: Typed
+Requires-Dist: django>=4.2
+Requires-Python: >=3.12
+Project-URL: Documentation, https://django-display-ids.readthedocs.io/
+Project-URL: Repository, https://github.com/josephabrahams/django-display-ids
+Description-Content-Type: text/markdown
+
+# django-display-ids
+
+[![PyPI](https://img.shields.io/pypi/v/django-display-ids)](https://pypi.org/project/django-display-ids/)
+[![Python](https://img.shields.io/pypi/pyversions/django-display-ids)](https://pypi.org/project/django-display-ids/)
+[![Django](https://img.shields.io/badge/django-4.2%20%7C%205.2%20%7C%206.0-blue)](https://pypi.org/project/django-display-ids/)
+
+Stripe-like prefixed IDs for Django. Works with existing UUIDs — no schema changes.
+
+**Documentation**: [django-display-ids.readthedocs.io](https://django-display-ids.readthedocs.io/)
+
+## Installation
+
+```bash
+pip install django-display-ids
+```
+
+No `INSTALLED_APPS` entry required.
+
+## Quick Start
+
+```python
+from django.views.generic import DetailView
+from django_display_ids import DisplayIDObjectMixin
+
+class InvoiceDetailView(DisplayIDObjectMixin, DetailView):
+    model = Invoice
+    lookup_param = "id"
+    lookup_strategies = ("display_id", "uuid")
+    display_id_prefix = "inv"
+```
+
+```python
+# urls.py
+urlpatterns = [
+    path("invoices/<str:id>/", InvoiceDetailView.as_view()),
+]
+```
+
+Now your view accepts:
+- `inv_2aUyqjCzEIiEcYMKj7TZtw` (display ID)
+- `550e8400-e29b-41d4-a716-446655440000` (UUID)
+
+## Features
+
+- **Multiple identifier formats**: display ID (`prefix_base62uuid`), UUID (v4/v7), slug
+- **Framework support**: Django CBVs and Django REST Framework
+- **Zero model changes required**: Works with any existing UUID field
+- **OpenAPI integration**: Automatic schema generation with drf-spectacular
+
+## Development
+
+```bash
+git clone https://github.com/josephabrahams/django-display-ids.git
+cd django-display-ids
+uv sync
+```
+
+Run tests:
+
+```bash
+uv run pytest
+```
+
+Run tests across Python and Django versions:
+
+```bash
+uvx nox
+```
+
+Lint and format:
+
+```bash
+uvx pre-commit run --all-files
+```
+
+## Related Projects
+
+If you need ID generation and storage (custom model fields), consider:
+
+- **[django-prefix-id](https://github.com/jaddison/django-prefix-id)** — PrefixIDField that generates and stores base62-encoded UUIDs
+- **[django-spicy-id](https://github.com/mik3y/django-spicy-id)** — Drop-in AutoField replacement
+- **[django-charid-field](https://github.com/yunojuno/django-charid-field)** — CharField wrapper supporting cuid, ksuid, ulid
+
+**django-display-ids** works with existing UUID fields and handles resolution only — no migrations required.
+
+## License
+
+ISC

{django_display_ids-0.1.3.dist-info → django_display_ids-0.2.0.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.2.0.dist-info/WHEEL,sha256=e_m4S054HL0hyR3CpOk-b7Q7fDX6BuFkgL5OjAExXas,80
+django_display_ids-0.2.0.dist-info/METADATA,sha256=cXxwTVjdSXtYv0ghEid7n-udEjrdZrZWhbEWSkvFr6M,3342
+django_display_ids-0.2.0.dist-info/RECORD,,

{django_display_ids-0.1.3.dist-info → django_display_ids-0.2.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: uv 0.9.26
+Generator: uv 0.9.27
 Root-Is-Purelib: true
 Tag: py3-none-any

django_display_ids-0.1.3.dist-info/METADATA

@@ -1,335 +0,0 @@
-Metadata-Version: 2.3
-Name: django-display-ids
-Version: 0.1.3
-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
-Classifier: Development Status :: 4 - Beta
-Classifier: Framework :: Django
-Classifier: Framework :: Django :: 4.2
-Classifier: Framework :: Django :: 5.2
-Classifier: Framework :: Django :: 6.0
-Classifier: License :: OSI Approved :: ISC License (ISCL)
-Classifier: Programming Language :: Python :: 3
-Classifier: Programming Language :: Python :: 3.12
-Classifier: Programming Language :: Python :: 3.13
-Classifier: Programming Language :: Python :: 3.14
-Classifier: Typing :: Typed
-Requires-Dist: django>=4.2
-Requires-Python: >=3.12
-Project-URL: Homepage, https://joseph.is/django-display-ids
-Description-Content-Type: text/markdown
-
-# django-display-ids
-
-Stripe-like prefixed IDs for Django. Works with existing UUIDs — no schema changes.
-
-Display IDs are human-friendly identifiers like `inv_2aUyqjCzEIiEcYMKj7TZtw` — a short prefix indicating the object type, followed by a base62-encoded UUID. This format, popularized by Stripe, makes IDs recognizable at a glance while remaining URL-safe and compact.
-
-This library focuses on **lookup only** — it works with your existing UUID fields and requires no migrations or schema changes.
-
-## Installation
-
-```bash
-pip install django-display-ids
-```
-
-No `INSTALLED_APPS` entry required — just import and use.
-
-## Quick Start
-
-```python
-from django.views.generic import DetailView
-from django_display_ids import DisplayIDObjectMixin
-
-class InvoiceDetailView(DisplayIDObjectMixin, DetailView):
-    model = Invoice
-    lookup_param = "id"
-    lookup_strategies = ("display_id", "uuid")
-    display_id_prefix = "inv"
-```
-
-```python
-# urls.py
-urlpatterns = [
-    path("invoices/<str:id>/", InvoiceDetailView.as_view()),
-]
-```
-
-Now your view accepts both formats:
-- `inv_2aUyqjCzEIiEcYMKj7TZtw` (display ID)
-- `550e8400-e29b-41d4-a716-446655440000` (UUID)
-
-## Features
-
-- **Multiple identifier formats**: display ID (`prefix_base62uuid`), UUID (v4/v7), slug
-- **Framework support**: Django CBVs and Django REST Framework
-- **Zero model changes required**: Works with any existing UUID field
-- **Stateless**: Pure lookup, no database writes
-
-## Usage
-
-### Django Class-Based Views
-
-```python
-from django.views.generic import DetailView, UpdateView, DeleteView
-from django_display_ids import DisplayIDObjectMixin
-
-class InvoiceDetailView(DisplayIDObjectMixin, DetailView):
-    model = Invoice
-    lookup_param = "id"
-    lookup_strategies = ("display_id", "uuid")
-    display_id_prefix = "inv"
-
-# Works with any view that uses get_object()
-class InvoiceUpdateView(DisplayIDObjectMixin, UpdateView):
-    model = Invoice
-    lookup_param = "id"
-    display_id_prefix = "inv"
-```
-
-### Django REST Framework
-
-```python
-from rest_framework.viewsets import ModelViewSet
-from django_display_ids.contrib.rest_framework import DisplayIDLookupMixin
-
-class InvoiceViewSet(DisplayIDLookupMixin, ModelViewSet):
-    queryset = Invoice.objects.all()
-    serializer_class = InvoiceSerializer
-    lookup_url_kwarg = "id"
-    lookup_strategies = ("display_id", "uuid")
-    display_id_prefix = "inv"
-```
-
-Or with APIView:
-
-```python
-from rest_framework.views import APIView
-from rest_framework.response import Response
-from django_display_ids.contrib.rest_framework import DisplayIDLookupMixin
-
-class InvoiceView(DisplayIDLookupMixin, APIView):
-    lookup_url_kwarg = "id"
-    lookup_strategies = ("display_id", "uuid")
-    display_id_prefix = "inv"
-
-    def get_queryset(self):
-        return Invoice.objects.all()
-
-    def get(self, request, *args, **kwargs):
-        invoice = self.get_object()
-        return Response({"id": str(invoice.id)})
-```
-
-### Model Mixin
-
-Add a `display_id` property to your models:
-
-```python
-import uuid
-from django.db import models
-from django_display_ids import DisplayIDMixin
-
-class Invoice(DisplayIDMixin, models.Model):
-    display_id_prefix = "inv"
-    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
-
-invoice = Invoice.objects.first()
-invoice.display_id  # -> "inv_2aUyqjCzEIiEcYMKj7TZtw"
-```
-
-### Model Manager
-
-```python
-from django_display_ids import DisplayIDMixin, DisplayIDManager
-
-class Invoice(DisplayIDMixin, models.Model):
-    display_id_prefix = "inv"
-    objects = DisplayIDManager()
-    id = models.UUIDField(primary_key=True, default=uuid.uuid4)
-
-# Get by display ID
-invoice = Invoice.objects.get_by_display_id("inv_2aUyqjCzEIiEcYMKj7TZtw")
-
-# Get by any identifier type
-invoice = Invoice.objects.get_by_identifier("inv_2aUyqjCzEIiEcYMKj7TZtw")
-invoice = Invoice.objects.get_by_identifier("550e8400-e29b-41d4-a716-446655440000")
-
-# Works with filtered querysets
-invoice = Invoice.objects.filter(active=True).get_by_identifier("inv_xxx")
-```
-
-### Django Admin
-
-Enable searching by display ID or raw UUID in the admin:
-
-```python
-from django.contrib import admin
-from django_display_ids import DisplayIDSearchMixin
-
-@admin.register(Invoice)
-class InvoiceAdmin(DisplayIDSearchMixin, admin.ModelAdmin):
-    list_display = ["id", "display_id", "name", "created"]
-    search_fields = ["name"]  # display_id/UUID search is automatic
-```
-
-Now you can search by either format in the admin search box:
-- `inv_2aUyqjCzEIiEcYMKj7TZtw` (display ID)
-- `550e8400-e29b-41d4-a716-446655440000` (raw UUID from logs)
-
-The mixin automatically detects the UUID field from your model's `uuid_field`
-attribute (if using `DisplayIDMixin`), or defaults to `id`. Override with:
-
-```python
-class InvoiceAdmin(DisplayIDSearchMixin, admin.ModelAdmin):
-    uuid_field = "uid"  # custom UUID field name
-```
-
-### Encoding and Decoding
-
-```python
-import uuid
-from django_display_ids import encode_display_id, decode_display_id
-
-# Create a display ID from a UUID
-invoice_id = uuid.uuid4()
-display_id = encode_display_id("inv", invoice_id)
-# -> "inv_2aUyqjCzEIiEcYMKj7TZtw"
-
-# Decode back to prefix and UUID
-prefix, decoded_uuid = decode_display_id(display_id)
-```
-
-### Direct Resolution
-
-```python
-from django_display_ids import resolve_object
-
-invoice = resolve_object(
-    model=Invoice,
-    value="inv_2aUyqjCzEIiEcYMKj7TZtw",
-    strategies=("display_id", "uuid", "slug"),
-    prefix="inv",
-)
-```
-
-## Identifier Formats
-
-| Format | Example | Description |
-|--------|---------|-------------|
-| Display ID | `inv_2aUyqjCzEIiEcYMKj7TZtw` | Prefix + base62-encoded UUID |
-| UUID | `550e8400-e29b-41d4-a716-446655440000` | Standard UUID (v4/v7) |
-| Slug | `my-invoice-slug` | Human-readable identifier |
-
-Display ID format:
-- Prefix: 1-16 lowercase letters
-- Separator: underscore
-- Encoded UUID: 22 base62 characters (fixed length)
-
-## Lookup Strategies
-
-Strategies are tried in order. The first successful match is returned.
-
-| Strategy | Description |
-|----------|-------------|
-| `display_id` | Decode display ID, lookup by UUID field |
-| `uuid` | Parse as UUID, lookup by UUID field |
-| `slug` | Lookup by slug field |
-
-Default: `("display_id", "uuid")`
-
-The slug strategy is a catch-all, so it should always be last.
-
-The `display_id` strategy requires a prefix. If no prefix is configured, the strategy is skipped.
-
-## Configuration
-
-### View/Mixin Attributes
-
-| Attribute | Default | Description |
-|-----------|---------|-------------|
-| `lookup_param` / `lookup_url_kwarg` | `"pk"` | URL parameter name |
-| `lookup_strategies` | from settings | Strategies to try |
-| `display_id_prefix` | from model | Expected prefix (falls back to model's `display_id_prefix`) |
-| `uuid_field` | `"id"` | UUID field name on model |
-| `slug_field` | `"slug"` | Slug field name on model |
-
-### Django Settings (Optional)
-
-All settings have sensible defaults. Only add this if you need to override them:
-
-```python
-# settings.py
-DISPLAY_IDS = {
-    "UUID_FIELD": "id",                     # default
-    "SLUG_FIELD": "slug",                   # default
-    "STRATEGIES": ("display_id", "uuid"),   # default
-}
-```
-
-## Error Handling
-
-| Exception | When Raised |
-|-----------|-------------|
-| `InvalidIdentifierError` | Identifier cannot be parsed |
-| `UnknownPrefixError` | Display ID prefix doesn't match expected |
-| `ObjectNotFoundError` | No matching database record |
-
-In views, errors are converted to HTTP responses:
-- Django CBV: `Http404`
-- DRF: `NotFound` (404) or `ParseError` (400)
-
-## Requirements
-
-- Python 3.12+
-- Django 4.2+
-- Django REST Framework 3.14+ (optional)
-
-## Development
-
-Clone the repository and install dependencies:
-
-```bash
-git clone https://github.com/josephabrahams/django-display-ids.git
-cd django-display-ids
-uv sync
-```
-
-Run tests:
-
-```bash
-uv run pytest
-```
-
-Run tests with coverage:
-
-```bash
-uv run pytest --cov=src/django_display_ids
-```
-
-Run tests across Python and Django versions:
-
-```bash
-uvx nox
-```
-
-Lint and format:
-
-```bash
-uvx pre-commit run --all-files
-```
-
-## Related Projects
-
-If you need ID generation and storage (custom model fields), consider these alternatives:
-
-- **[django-prefix-id](https://github.com/jaddison/django-prefix-id)** — PrefixIDField that generates and stores base62-encoded UUIDs
-- **[django-spicy-id](https://github.com/mik3y/django-spicy-id)** — Drop-in AutoField replacement that displays numeric IDs as prefixed strings
-- **[django-charid-field](https://github.com/yunojuno/django-charid-field)** — CharField wrapper supporting cuid, ksuid, ulid, and other generators
-
-**django-display-ids** takes a different approach: it works with your existing UUID fields and handles resolution only. No migrations, no schema changes — just add the mixin to your views.
-
-## License
-
-ISC