django-display-ids 0.2.0__py3-none-any.whl → 0.3.1__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)
 
@@ -125,13 +125,16 @@ class DisplayIDMixin(models.Model):
         """Generate the display ID for this instance.
 
         Returns:
-            Display ID in format {prefix}_{base62(uuid)}, or None if no prefix.
+            Display ID in format {prefix}_{base62(uuid)}, or None if no prefix
+            or if the UUID field is None (e.g., unsaved instance).
         """
         prefix = self.get_display_id_prefix()
         if prefix is None:
             return None
         uuid_value = getattr(self, self._get_uuid_field())
+        if uuid_value is None:
+            return None
         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

@@ -51,12 +51,21 @@ def resolve_object(
         UnknownPrefixError: If display ID prefix doesn't match expected.
         ObjectNotFoundError: If no matching object exists.
         AmbiguousIdentifierError: If multiple objects match (slug lookup).
+        TypeError: If queryset is not for the specified model.
     """
     # Parse the identifier to determine type
     result = parse_identifier(value, strategies, expected_prefix=prefix)
 
     # Get the base queryset
-    qs: QuerySet[M] = queryset if queryset is not None else model._default_manager.all()
+    if queryset is not None:
+        if queryset.model is not model:
+            raise TypeError(
+                f"queryset must be for {model.__name__}, "
+                f"got queryset for {queryset.model.__name__}"
+            )
+        qs: QuerySet[M] = queryset
+    else:
+        qs = model._default_manager.all()
 
     # Build the lookup based on strategy
     lookup: dict[str, Any]
@@ -70,8 +79,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.2.0.dist-info → django_display_ids-0.3.1.dist-info}/METADATA

@@ -1,15 +1,15 @@
 Metadata-Version: 2.3
 Name: django-display-ids
-Version: 0.2.0
+Version: 0.3.1
 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
+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 :: ISC License (ISCL)
+Classifier: License :: OSI Approved :: MIT License
 Classifier: Programming Language :: Python :: 3
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: 3.13
@@ -26,10 +26,24 @@ Description-Content-Type: text/markdown
 [![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.
 
-**Documentation**: [django-display-ids.readthedocs.io](https://django-display-ids.readthedocs.io/)
+## 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
 
@@ -37,10 +51,19 @@ Stripe-like prefixed IDs for Django. Works with existing UUIDs — no schema cha
 pip install django-display-ids
 ```
 
-No `INSTALLED_APPS` entry required.
+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
@@ -48,53 +71,53 @@ from django_display_ids import DisplayIDObjectMixin
 class InvoiceDetailView(DisplayIDObjectMixin, DetailView):
     model = Invoice
     lookup_param = "id"
-    lookup_strategies = ("display_id", "uuid")
+    lookup_strategies = ("display_id", "uuid", "slug")
     display_id_prefix = "inv"
 ```
 
+**Django REST Framework:**
+
 ```python
-# urls.py
-urlpatterns = [
-    path("invoices/<str:id>/", InvoiceDetailView.as_view()),
-]
+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 view accepts:
+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
 
-## Development
-
-```bash
-git clone https://github.com/josephabrahams/django-display-ids.git
-cd django-display-ids
-uv sync
-```
+## Documentation
 
-Run tests:
+Full documentation at [django-display-ids.readthedocs.io](https://django-display-ids.readthedocs.io/).
 
-```bash
-uv run pytest
-```
+## Contributing
 
-Run tests across Python and Django versions:
-
-```bash
-uvx nox
-```
-
-Lint and format:
-
-```bash
-uvx pre-commit run --all-files
-```
+See the [contributing guide](https://django-display-ids.readthedocs.io/en/latest/contributing/).
 
 ## Related Projects
 
@@ -105,7 +128,3 @@ If you need ID generation and storage (custom model fields), consider:
 - **[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.3.1.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=XI73N4bvxy1Pr2oHeTaJP3uq3huyCX67CFZ2T8mefsA,4317
+django_display_ids/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_display_ids/resolver.py,sha256=ZlDVoxX0PmVf0MSwPyiNNwQVzdqJGDGE8fm2iyV7QjE,2848
+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.1.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
+django_display_ids-0.3.1.dist-info/METADATA,sha256=eKOjG80Rb_fK-_FQtUYR67fyWGZlN5SzgZuhjD4RGDA,5295
+django_display_ids-0.3.1.dist-info/RECORD,,

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

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

django_display_ids-0.2.0.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.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,,