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

django_display_ids/__init__.py

@@ -23,7 +23,10 @@ Example:
         display_id_prefix = "inv"
 """
 
+from typing import Any
+
 from .admin import DisplayIDSearchMixin
+from .converters import DisplayIDConverter, DisplayIDOrUUIDConverter, UUIDConverter
 from .encoding import (
     decode_display_id,
     decode_uuid,
@@ -45,12 +48,29 @@ from .exceptions import (
     UnknownPrefixError,
 )
 from .managers import DisplayIDManager, DisplayIDQuerySet
-from .models import DisplayIDMixin, get_model_for_prefix
 from .resolver import resolve_object
 from .typing import DEFAULT_STRATEGIES, StrategyName
 from .views import DisplayIDObjectMixin
 
+
+def __getattr__(name: str) -> Any:
+    """Lazy import for model-related items to avoid app registry issues."""
+    if name == "DisplayIDMixin":
+        from .models import DisplayIDMixin
+
+        return DisplayIDMixin
+    if name == "get_model_for_prefix":
+        from .models import get_model_for_prefix
+
+        return get_model_for_prefix
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
+
+
 __all__ = [  # noqa: RUF022 - keep categorized order for readability
+    # URL converters
+    "DisplayIDConverter",
+    "UUIDConverter",
+    "DisplayIDOrUUIDConverter",
     # Encoding
     "encode_uuid",
     "decode_uuid",
@@ -85,10 +105,8 @@ __all__ = [  # noqa: RUF022 - keep categorized order for readability
     "DEFAULT_STRATEGIES",
 ]
 
-__version__ = "0.1.1"
-
 
-def get_drf_mixin():
+def get_drf_mixin() -> type:
     """Lazily import the DRF mixin to avoid hard dependency.
 
     Returns:

django_display_ids/admin.py

@@ -4,12 +4,12 @@ from __future__ import annotations
 
 import contextlib
 import uuid
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from .encoding import decode_display_id
 
 if TYPE_CHECKING:
-    from django.db.models import QuerySet
+    from django.db.models import Model, QuerySet
     from django.http import HttpRequest
 
 __all__ = ["DisplayIDSearchMixin"]
@@ -39,13 +39,15 @@ class DisplayIDSearchMixin:
     """
 
     uuid_field: str | None = None
+    model: type[Model]
 
     def _get_uuid_field(self) -> str:
         """Get the UUID field name to search."""
         if self.uuid_field is not None:
             return self.uuid_field
         # Try to get from model's uuid_field attribute
-        return getattr(self.model, "uuid_field", None) or "id"
+        uuid_field: str | None = getattr(self.model, "uuid_field", None)
+        return uuid_field or "id"
 
     def _try_parse_uuid(self, value: str) -> uuid.UUID | None:
         """Try to parse a string as a UUID."""
@@ -57,16 +59,16 @@ class DisplayIDSearchMixin:
     def get_search_results(
         self,
         request: HttpRequest,
-        queryset: QuerySet,
+        queryset: QuerySet[Any],
         search_term: str,
-    ) -> tuple[QuerySet, bool]:
+    ) -> tuple[QuerySet[Any], bool]:
         """Extend search to handle display IDs and raw UUIDs.
 
         Tries to match the search term as:
         1. A display ID (prefix_base62uuid) if it contains an underscore
         2. A raw UUID if it looks like a UUID format
         """
-        queryset, use_distinct = super().get_search_results(
+        queryset, use_distinct = super().get_search_results(  # type: ignore[misc]
             request, queryset, search_term
         )
 

django_display_ids/apps.py

@@ -0,0 +1,11 @@
+"""Django app configuration for django-display-ids."""
+
+from django.apps import AppConfig
+
+
+class DjangoDisplayIdsConfig(AppConfig):
+    """App configuration for django-display-ids."""
+
+    name = "django_display_ids"
+    verbose_name = "Django Display IDs"
+    default_auto_field = "django.db.models.BigAutoField"

django_display_ids/conf.py

@@ -45,5 +45,8 @@ def get_setting(name: str) -> str | tuple[StrategyName, ...]:
     if name not in DEFAULTS:
         raise KeyError(f"Unknown setting: {name}")
 
-    user_settings = getattr(settings, "DISPLAY_IDS", {})
-    return user_settings.get(name, DEFAULTS[name])
+    user_settings: dict[str, str | tuple[str, ...]] = getattr(
+        settings, "DISPLAY_IDS", {}
+    )
+    result = user_settings.get(name, DEFAULTS[name])
+    return result  # type: ignore[return-value]

django_display_ids/contrib/drf_spectacular/__init__.py

@@ -6,16 +6,21 @@ proper OpenAPI schema generation for DisplayIDField.
 
 from __future__ import annotations
 
+from typing import TYPE_CHECKING, Any
+
 try:
     from drf_spectacular.extensions import OpenApiSerializerFieldExtension
 except ImportError:
     # drf-spectacular not installed, skip extension registration
     pass
 else:
+    if TYPE_CHECKING:
+        from drf_spectacular.openapi import AutoSchema
+
     from django_display_ids.encoding import ENCODED_UUID_LENGTH, encode_uuid
     from django_display_ids.examples import example_uuid_for_prefix
 
-    class DisplayIDFieldExtension(OpenApiSerializerFieldExtension):
+    class DisplayIDFieldExtension(OpenApiSerializerFieldExtension):  # type: ignore[no-untyped-call]
         """OpenAPI schema extension for DisplayIDField.
 
         Generates schema with correct prefix example based on the field's
@@ -27,7 +32,7 @@ else:
         )
         match_subclasses = True
 
-        def _get_model_from_view(self, auto_schema):
+        def _get_model_from_view(self, auto_schema: AutoSchema | None) -> Any:
             """Try to get model from the view's queryset."""
             if auto_schema is None:
                 return None
@@ -48,7 +53,9 @@ else:
                 return queryset.model
             return None
 
-        def map_serializer_field(self, auto_schema, direction):
+        def map_serializer_field(
+            self, auto_schema: AutoSchema, direction: str
+        ) -> dict[str, Any]:
             """Generate OpenAPI schema for DisplayIDField."""
             # Get prefix from field override or try to get from model
             prefix = self.target._prefix_override

django_display_ids/contrib/rest_framework/serializers.py

@@ -95,9 +95,9 @@ class DisplayIDField(serializers.SerializerMethodField):
         # 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)
+            uuid_field_name: str | None = getattr(obj, "uuid_field", None)
             if uuid_field_name is None:
-                uuid_field_name = get_setting("UUID_FIELD")
+                uuid_field_name = str(get_setting("UUID_FIELD"))
             uuid_value = getattr(obj, uuid_field_name, None)
             if uuid_value is None:
                 raise ValueError(
@@ -108,7 +108,8 @@ class DisplayIDField(serializers.SerializerMethodField):
 
         # Use the model's display_id property
         if hasattr(obj, "display_id"):
-            return obj.display_id
+            display_id: str = obj.display_id
+            return display_id
 
         raise ValueError(
             f"Cannot generate display_id: {obj.__class__.__name__} "

django_display_ids/contrib/rest_framework/views.py

@@ -174,4 +174,4 @@ class DisplayIDLookupMixin:
         # Check object-level permissions
         self.check_object_permissions(self.request, obj)
 
-        return obj
+        return obj  # type: ignore[no-any-return]

django_display_ids/converters.py

@@ -0,0 +1,111 @@
+"""Django URL path converters for display IDs and UUIDs."""
+
+from __future__ import annotations
+
+__all__ = [
+    "DisplayIDConverter",
+    "DisplayIDOrUUIDConverter",
+    "UUIDConverter",
+]
+
+
+class DisplayIDConverter:
+    """Path converter for display IDs.
+
+    Matches the format: {prefix}_{base62} where prefix is 1-16 lowercase
+    letters and base62 is exactly 22 alphanumeric characters.
+
+    Example:
+        from django.urls import path, register_converter
+        from django_display_ids.converters import DisplayIDConverter
+
+        register_converter(DisplayIDConverter, "display_id")
+
+        urlpatterns = [
+            path("invoices/<display_id:id>/", InvoiceDetailView.as_view()),
+        ]
+    """
+
+    regex = r"[a-z]{1,16}_[0-9A-Za-z]{22}"
+
+    def to_python(self, value: str) -> str:
+        """Convert the URL value to a Python object."""
+        return value
+
+    def to_url(self, value: str) -> str:
+        """Convert a Python object to a URL string."""
+        return value
+
+
+class UUIDConverter:
+    """Path converter for UUIDs.
+
+    Matches UUIDs in both hyphenated and unhyphenated formats:
+    - 550e8400-e29b-41d4-a716-446655440000 (hyphenated)
+    - 550e8400e29b41d4a716446655440000 (unhyphenated)
+
+    Example:
+        from django.urls import path, register_converter
+        from django_display_ids.converters import UUIDConverter
+
+        register_converter(UUIDConverter, "uuid")
+
+        urlpatterns = [
+            path("invoices/<uuid:id>/", InvoiceDetailView.as_view()),
+        ]
+
+    Note:
+        Django's built-in UUIDConverter only accepts hyphenated UUIDs.
+        This converter is more permissive.
+    """
+
+    # Hyphenated: 8-4-4-4-12 hex chars with hyphens
+    # Unhyphenated: 32 hex chars
+    # Note: Parentheses group the alternatives so ^ and $ anchor correctly
+    regex = (
+        r"(?:[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}|[0-9a-f]{32})"
+    )
+
+    def to_python(self, value: str) -> str:
+        """Convert the URL value to a Python object."""
+        return value
+
+    def to_url(self, value: str) -> str:
+        """Convert a Python object to a URL string."""
+        return value
+
+
+class DisplayIDOrUUIDConverter:
+    """Path converter for display IDs or UUIDs.
+
+    Matches either format:
+    - Display ID: {prefix}_{base62}
+    - UUID: hyphenated or unhyphenated
+
+    Example:
+        from django.urls import path, register_converter
+        from django_display_ids.converters import DisplayIDOrUUIDConverter
+
+        register_converter(DisplayIDOrUUIDConverter, "display_id_or_uuid")
+
+        urlpatterns = [
+            path("invoices/<display_id_or_uuid:id>/", InvoiceDetailView.as_view()),
+        ]
+    """
+
+    # Note: Parentheses group the alternatives so ^ and $ anchor correctly
+    regex = (
+        r"(?:"
+        r"[a-z]{1,16}_[0-9A-Za-z]{22}"
+        r"|[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
+        r"|[0-9a-f]{32}"
+        r")"
+    )
+
+    def to_python(self, value: str) -> str:
+        """Convert the URL value to a Python object."""
+        return value
+
+    def to_url(self, value: str) -> str:
+        """Convert a Python object to a URL string."""
+        return value

django_display_ids/examples.py

@@ -26,7 +26,7 @@ def _get_prefix(prefix_or_model: str | type[Model]) -> str:
     if isinstance(prefix_or_model, str):
         return prefix_or_model
     # It's a model class
-    prefix = getattr(prefix_or_model, "display_id_prefix", None)
+    prefix: str | None = 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

django_display_ids/managers.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 from typing import TYPE_CHECKING, Any, TypeVar
 
 from django.db import models
+from django.db.models import Q
 
 from .conf import get_setting
 from .encoding import decode_display_id
@@ -18,6 +19,8 @@ from .exceptions import (
 from .strategies import parse_identifier
 
 if TYPE_CHECKING:
+    from collections.abc import Sequence
+
     from .typing import StrategyName
 
 __all__ = [
@@ -91,7 +94,7 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         # Query the database
         try:
             return self.get(**{uuid_field: uuid_value})
-        except model.DoesNotExist:
+        except model.DoesNotExist:  # type: ignore[attr-defined]
             raise ObjectNotFoundError(value, model_name=model.__name__) from None
 
     def get_by_identifier(
@@ -140,22 +143,85 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         # Execute the query
         try:
             return self.get(**lookup)
-        except model.DoesNotExist:
+        except model.DoesNotExist:  # type: ignore[attr-defined]
             raise ObjectNotFoundError(value, model_name=model.__name__) from None
-        except model.MultipleObjectsReturned:
+        except model.MultipleObjectsReturned:  # type: ignore[attr-defined]
             count = self.filter(**lookup).count()
             raise AmbiguousIdentifierError(value, count) from None
 
+    def get_by_identifiers(
+        self,
+        values: Sequence[str],
+        *,
+        strategies: tuple[StrategyName, ...] | None = None,
+        prefix: str | None = None,
+    ) -> DisplayIDQuerySet[M]:
+        """Get multiple objects by any supported identifier type in a single query.
+
+        Parses each identifier to determine its type (display ID, UUID, or slug),
+        then executes a single database query using `__in` lookups.
+
+        Args:
+            values: A sequence of identifier strings (display IDs, UUIDs, or slugs).
+            strategies: Strategies to try. Defaults to settings.
+            prefix: Expected display ID prefix for validation.
+
+        Returns:
+            A queryset containing matching objects. Order is not guaranteed
+            to match input order. Missing identifiers are silently excluded.
+
+        Raises:
+            InvalidIdentifierError: If any identifier cannot be parsed.
+
+        Example:
+            invoices = Invoice.objects.get_by_identifiers([
+                'inv_2aUyqjCzEIiEcYMKj7TZtw',
+                'inv_7kN3xPqRmLwYvTzJ5HfUaB',
+                '550e8400-e29b-41d4-a716-446655440000',
+            ])
+        """
+        if not values:
+            return self.none()
+
+        uuid_field = self._get_uuid_field()
+        slug_field = self._get_slug_field()
+        expected_prefix = prefix or self._get_model_prefix()
+        lookup_strategies = strategies or self._get_strategies()
+
+        # Collect UUIDs and slugs separately
+        uuids: list[Any] = []
+        slugs: list[str] = []
+
+        for value in values:
+            result = parse_identifier(
+                value, lookup_strategies, expected_prefix=expected_prefix
+            )
+            if result.strategy in ("uuid", "display_id"):
+                uuids.append(result.uuid)
+            else:
+                slugs.append(result.slug)  # type: ignore[arg-type]
+
+        # Build query with OR conditions
+        query = Q()
+        if uuids:
+            query |= Q(**{f"{uuid_field}__in": uuids})
+        if slugs:
+            query |= Q(**{f"{slug_field}__in": slugs})
+
+        return self.filter(query)
+
     def _get_uuid_field(self) -> str:
         """Get the UUID field name for this model."""
         if hasattr(self.model, "_get_uuid_field"):
-            return self.model._get_uuid_field()  # type: ignore[attr-defined]
+            result: str = self.model._get_uuid_field()  # type: ignore[attr-defined]
+            return result
         return str(get_setting("UUID_FIELD"))
 
     def _get_slug_field(self) -> str:
         """Get the slug field name for this model."""
         if hasattr(self.model, "_get_slug_field"):
-            return self.model._get_slug_field()  # type: ignore[attr-defined]
+            result: str = self.model._get_slug_field()  # type: ignore[attr-defined]
+            return result
         return str(get_setting("SLUG_FIELD"))
 
     def _get_strategies(self) -> tuple[StrategyName, ...]:
@@ -166,7 +232,8 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         """Get the display ID prefix from the model, if defined."""
         if hasattr(self.model, "get_display_id_prefix"):
             try:
-                return self.model.get_display_id_prefix()  # type: ignore[attr-defined]
+                result: str | None = self.model.get_display_id_prefix()  # type: ignore[attr-defined]
+                return result
             except NotImplementedError:
                 return None
         return None
@@ -210,3 +277,18 @@ class DisplayIDManager(models.Manager[M]):
         return self.get_queryset().get_by_identifier(
             value, strategies=strategies, prefix=prefix
         )
+
+    def get_by_identifiers(
+        self,
+        values: Sequence[str],
+        *,
+        strategies: tuple[StrategyName, ...] | None = None,
+        prefix: str | None = None,
+    ) -> DisplayIDQuerySet[M]:
+        """Get multiple objects by any supported identifier type.
+
+        See DisplayIDQuerySet.get_by_identifiers for details.
+        """
+        return self.get_queryset().get_by_identifiers(
+            values, strategies=strategies, prefix=prefix
+        )

django_display_ids/models.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from typing import ClassVar
+from typing import Any, ClassVar
 
 from django.db import models
 
@@ -84,7 +84,7 @@ class DisplayIDMixin(models.Model):
     class Meta:
         abstract = True
 
-    def __init_subclass__(cls, **kwargs) -> None:
+    def __init_subclass__(cls, **kwargs: Any) -> None:
         """Register prefix when subclass is created."""
         super().__init_subclass__(**kwargs)
 
@@ -134,4 +134,4 @@ class DisplayIDMixin(models.Model):
         return encode_display_id(prefix, uuid_value)
 
     # Django admin display configuration
-    display_id.fget.short_description = "Display ID"
+    display_id.fget.short_description = "Display ID"  # type: ignore[attr-defined]

django_display_ids/resolver.py

@@ -70,8 +70,8 @@ def resolve_object(
     # Execute the query
     try:
         return qs.get(**lookup)
-    except model.DoesNotExist:
+    except model.DoesNotExist:  # type: ignore[attr-defined]
         raise ObjectNotFoundError(value, model_name=model.__name__) from None
-    except model.MultipleObjectsReturned:
+    except model.MultipleObjectsReturned:  # type: ignore[attr-defined]
         count = qs.filter(**lookup).count()
         raise AmbiguousIdentifierError(value, count) from None

django_display_ids/templatetags/display_ids.py

@@ -0,0 +1,48 @@
+"""Template tags and filters for generating display IDs."""
+
+from __future__ import annotations
+
+import uuid
+
+from django import template
+
+from ..encoding import encode_display_id
+
+__all__ = [
+    "display_id",
+]
+
+register = template.Library()
+
+
+@register.filter(name="display_id")
+def display_id(value: uuid.UUID | None, prefix: str) -> str:
+    """Encode a UUID as a display ID.
+
+    Usage:
+        {{ some_uuid|display_id:"inv" }}
+        {{ invoice.customer_id|display_id:"cust" }}
+
+    Args:
+        value: UUID to encode.
+        prefix: Display ID prefix (1-16 lowercase letters).
+
+    Returns:
+        Display ID string like "inv_2aUyqjCzEIiEcYMKj7TZtw", or empty string
+        if value is None.
+
+    Raises:
+        TemplateSyntaxError: If prefix is invalid or value is not a UUID.
+    """
+    if value is None:
+        return ""
+
+    if not isinstance(value, uuid.UUID):
+        raise template.TemplateSyntaxError(
+            f"display_id filter requires a UUID, got {type(value).__name__}"
+        )
+
+    try:
+        return encode_display_id(prefix, value)
+    except ValueError as e:
+        raise template.TemplateSyntaxError(str(e)) from e

django_display_ids/views.py

@@ -133,7 +133,7 @@ class DisplayIDObjectMixin:
         qs = queryset if queryset is not None else self.get_queryset()
 
         try:
-            return resolve_object(
+            return resolve_object(  # type: ignore[no-any-return]
                 model=self.model,
                 value=str(value),
                 strategies=self._get_strategies(),

django_display_ids-0.3.0.dist-info/METADATA

@@ -0,0 +1,130 @@
+Metadata-Version: 2.3
+Name: django-display-ids
+Version: 0.3.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: MIT
+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 :: MIT License
+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/)
+[![CI](https://github.com/josephabrahams/django-display-ids/actions/workflows/ci.yml/badge.svg)](https://github.com/josephabrahams/django-display-ids/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/josephabrahams/django-display-ids/graph/badge.svg)](https://codecov.io/gh/josephabrahams/django-display-ids)
+[![Docs](https://readthedocs.org/projects/django-display-ids/badge/?version=stable)](https://django-display-ids.readthedocs.io/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://github.com/josephabrahams/django-display-ids/blob/main/LICENSE)
+
+Stripe-like prefixed IDs for Django. Works with existing UUIDs — no schema changes.
+
+## Why?
+
+UUIDv7 (native in Python 3.14+) offers excellent database performance with time-ordered indexing. But they lack context — seeing `550e8400-e29b-41d4-a716-446655440000` in a URL or log doesn't tell you what kind of object it refers to.
+
+Display IDs like `inv_2aUyqjCzEIiEcYMKj7TZtw` are more useful: the prefix identifies the object type at a glance, and they're compact and URL-safe. But storing display IDs in the database is far less efficient than native UUIDs.
+
+Different consumers have different needs:
+- **Humans** prefer slugs (`my-invoice`) or display IDs (`inv_xxx`)
+- **APIs and integrations** work well with UUIDs
+
+This library gives you the best of both worlds: accept any format in your URLs and API endpoints, then translate to an efficient UUID lookup in the database. Store UUIDs, expose whatever format your users need.
+
+## Installation
+
+```bash
+pip install django-display-ids
+```
+
+Add to `INSTALLED_APPS`:
+
+```python
+INSTALLED_APPS = [
+    # ...
+    "django_display_ids",
+]
+```
+
+## Quick Start
+
+**Django views:**
+
+```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", "slug")
+    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", "slug")
+    display_id_prefix = "inv"
+```
+
+Now your views accept:
+- `inv_2aUyqjCzEIiEcYMKj7TZtw` (display ID)
+- `550e8400-e29b-41d4-a716-446655440000` (UUID)
+- `my-invoice-slug` (slug)
+
+**Templates:**
+
+```django
+{% load display_ids %}
+
+{{ invoice.display_id }}                       {# inv_2aUyqjCzEIiEcYMKj7TZtw #}
+{{ order.customer_id|display_id:"cust" }}      {# encode any UUID #}
+```
+
+## Features
+
+- **Multiple identifier formats**: display ID (`prefix_base62uuid`), UUID (v4/v7), slug
+- **Framework support**: Django CBVs and Django REST Framework
+- **Template filter**: Encode UUIDs as display IDs in templates
+- **Zero model changes required**: Works with any existing UUID field
+- **OpenAPI integration**: Automatic schema generation with drf-spectacular
+
+## Documentation
+
+Full documentation at [django-display-ids.readthedocs.io](https://django-display-ids.readthedocs.io/).
+
+## Contributing
+
+See the [contributing guide](https://django-display-ids.readthedocs.io/en/latest/contributing.html).
+
+## 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.

django_display_ids-0.3.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+django_display_ids/__init__.py,sha256=2qX0YC7Jwpoom5rLOhvOewR3GQEIbUhu5ZYwjfEoklo,3207
+django_display_ids/admin.py,sha256=_voqWbr8AwPRC_uCTJWTcEhAhc7RZUgvs7DyVsutDuw,3046
+django_display_ids/apps.py,sha256=UqblGiYNONOIEH-giEAuKp1YDgxl2yf0jS0ELMj1iig,315
+django_display_ids/conf.py,sha256=Mg5ZIhTRSF5dzNO_iYndoF4_g5Umo-5oUw1vB76M7fw,1230
+django_display_ids/contrib/__init__.py,sha256=sxGJK8Whb6cL7RqACqGRYrIZvaMwP3l6dYk3mIYWzDY,62
+django_display_ids/contrib/drf_spectacular/__init__.py,sha256=21n56CH7tp2lKq4EGW99KVEgVB9fJ5GnfllUW_KrIe8,4003
+django_display_ids/contrib/rest_framework/__init__.py,sha256=Xun6zMhCZzQJZQ7ywvBYoKhTJIZEV84AntrbSWfBjYI,1567
+django_display_ids/contrib/rest_framework/serializers.py,sha256=Jp-z7qHafxkGNYv30YC9rrqLt936SrhONJv3rqfQaC0,4049
+django_display_ids/contrib/rest_framework/views.py,sha256=nDaze7MJwVqL0MrxQLOur3sPVrRXud_WT4ijGR02jDY,6087
+django_display_ids/converters.py,sha256=9xP3vKW1keN1glJvwmZun0BaBRLMKio0aD7Coc888ms,3197
+django_display_ids/encoding.py,sha256=csIwUZaQKSOLwRU6-DWGTNGvSxmroyK0Yt7TBCo0AFE,2945
+django_display_ids/examples.py,sha256=gap5NNPTmE7B5uxiYKoMoK8G-OEtL1Ek0W039l6oJ9I,2689
+django_display_ids/exceptions.py,sha256=nmyRfpsqVvz226Zcu_QANwr8MudbfoX09mAgOCwuPuQ,3022
+django_display_ids/managers.py,sha256=PymcK4BZL6UsUOtoloHP34MCRNmvNHSKEcOImhZxGag,9779
+django_display_ids/models.py,sha256=r2SGrP-6g2LeiZZ4yC1Zp8CcJQ5VvpXS8kQMXl2FBgU,4196
+django_display_ids/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_display_ids/resolver.py,sha256=TJub6nT6JFThanxETbH8kXVliScjFiksD2kGpu0OvXA,2554
+django_display_ids/strategies.py,sha256=Rq00-AW_FB8-K04u2oBK5J6kPiYgsE3TdYlLyK_zro0,4436
+django_display_ids/templatetags/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_display_ids/templatetags/display_ids.py,sha256=4KHE8r8mgSKb7LgIuXJaJB_3UGrzRZvTdLqSCYQtb5I,1157
+django_display_ids/typing.py,sha256=2O3kT7XKkiE7WI9A5KkILPM-Zi7-zCy5gVvXQL_J2mI,478
+django_display_ids/views.py,sha256=-y_Zwo4QLU0lPRPjABpijsze5vsG0CBvJtrVwVtuLwM,5127
+django_display_ids-0.3.0.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+django_display_ids-0.3.0.dist-info/METADATA,sha256=9QObcv7ll6Nt2c-WzRF-KCm3olO0RNheX-xKUfqzLEc,5299
+django_display_ids-0.3.0.dist-info/RECORD,,

{django_display_ids-0.1.4.dist-info → django_display_ids-0.3.0.dist-info}/WHEEL

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

django_display_ids-0.1.4.dist-info/METADATA

@@ -1,422 +0,0 @@
-Metadata-Version: 2.3
-Name: django-display-ids
-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
-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)})
-```
-
-#### 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:
-
-```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

django_display_ids-0.1.4.dist-info/RECORD

@@ -1,21 +0,0 @@
-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/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
-django_display_ids/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-django_display_ids/resolver.py,sha256=oCoA6jbGCFS8SMrkfD_oSSBQNrSxnxdooK5j933eA9Y,2494
-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.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,,