django-display-ids 0.3.2__py3-none-any.whl → 0.4.1__py3-none-any.whl

django_display_ids/__init__.py

@@ -9,7 +9,7 @@ Example:
         encode_display_id,
         decode_display_id,
         resolve_object,
-        DisplayIDObjectMixin,
+        DisplayIDMixin,
     )
 
     # Encode a UUID to a display ID
@@ -17,15 +17,18 @@ Example:
     # -> "inv_2aUyqjCzEIiEcYMKj7TZtw"
 
     # Use in Django views
-    class InvoiceDetailView(DisplayIDObjectMixin, DetailView):
+    class InvoiceDetailView(DisplayIDMixin, DetailView):
         model = Invoice
         lookup_param = "id"
         display_id_prefix = "inv"
 """
 
+from importlib.metadata import version
 from typing import Any
 
-from .admin import DisplayIDSearchMixin
+from .admin import DisplayIDAdminSearchMixin
+
+__version__ = version("django-display-ids")
 from .converters import (
     DisplayIDConverter,
     DisplayIDOrSlugConverter,
@@ -48,8 +51,8 @@ from .examples import (
 )
 from .exceptions import (
     AmbiguousIdentifierError,
+    DisplayIDLookupError,
     InvalidIdentifierError,
-    LookupError,
     MissingPrefixError,
     ObjectNotFoundError,
     UnknownPrefixError,
@@ -57,15 +60,15 @@ from .exceptions import (
 from .managers import DisplayIDManager, DisplayIDQuerySet
 from .resolver import resolve_object
 from .typing import DEFAULT_STRATEGIES, StrategyName
-from .views import DisplayIDObjectMixin
+from .views import DisplayIDMixin
 
 
 def __getattr__(name: str) -> Any:
     """Lazy import for model-related items to avoid app registry issues."""
-    if name == "DisplayIDMixin":
-        from .models import DisplayIDMixin
+    if name == "DisplayIDModel":
+        from .models import DisplayIDModel
 
-        return DisplayIDMixin
+        return DisplayIDModel
     if name == "get_model_for_prefix":
         from .models import get_model_for_prefix
 
@@ -74,57 +77,43 @@ def __getattr__(name: str) -> Any:
 
 
 __all__ = [  # noqa: RUF022 - keep categorized order for readability
+    # Model integration
+    "DisplayIDModel",
+    "DisplayIDManager",
+    "DisplayIDQuerySet",
+    "get_model_for_prefix",
+    # View mixins
+    "DisplayIDMixin",
+    "DisplayIDAdminSearchMixin",
+    # Encoding/decoding
+    "encode_display_id",
+    "decode_display_id",
+    "encode_uuid",
+    "decode_uuid",
     # URL converters
     "DisplayIDConverter",
-    "DisplayIDOrSlugConverter",
     "DisplayIDOrUUIDConverter",
+    "DisplayIDOrSlugConverter",
     "DisplayIDOrUUIDOrSlugConverter",
     "make_display_id_or_slug_converter",
     "make_display_id_or_uuid_or_slug_converter",
-    # Encoding
-    "encode_uuid",
-    "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
-    "LookupError",
+    # Exceptions
+    "DisplayIDLookupError",
     "InvalidIdentifierError",
     "UnknownPrefixError",
     "MissingPrefixError",
     "ObjectNotFoundError",
     "AmbiguousIdentifierError",
-    # Django mixins
-    "DisplayIDObjectMixin",
-    # Admin mixins
-    "DisplayIDSearchMixin",
-    # Model mixin
-    "DisplayIDMixin",
-    "get_model_for_prefix",
-    # Managers
-    "DisplayIDManager",
-    "DisplayIDQuerySet",
+    # Examples (for OpenAPI)
+    "example_display_id",
+    "example_uuid",
+    "example_display_id_for_prefix",  # alias
+    "example_uuid_for_prefix",  # alias
     # Types
     "StrategyName",
     "DEFAULT_STRATEGIES",
+    # Version
+    "__version__",
 ]
-
-
-def get_drf_mixin() -> type:
-    """Lazily import the DRF mixin to avoid hard dependency.
-
-    Returns:
-        DisplayIDLookupMixin class.
-
-    Raises:
-        ImportError: If Django REST Framework is not installed.
-    """
-    from .contrib.rest_framework import DisplayIDLookupMixin
-
-    return DisplayIDLookupMixin

django_display_ids/admin.py

@@ -3,7 +3,6 @@
 from __future__ import annotations
 
 import contextlib
-import uuid
 from typing import TYPE_CHECKING, Any
 
 from .encoding import decode_display_id
@@ -12,30 +11,33 @@ if TYPE_CHECKING:
     from django.db.models import Model, QuerySet
     from django.http import HttpRequest
 
-__all__ = ["DisplayIDSearchMixin"]
+__all__ = ["DisplayIDAdminSearchMixin"]
 
 
-class DisplayIDSearchMixin:
-    """Mixin to enable searching by display_id or UUID in Django admin.
+class DisplayIDAdminSearchMixin:
+    """Mixin to enable searching by display ID in Django admin.
 
     Add this mixin to your ModelAdmin to allow searching by display ID
-    (e.g., "inv_2aUyqjCzEIiEcYMKj7TZtw") or raw UUID
-    (e.g., "550e8400-e29b-41d4-a716-446655440000") in the admin search box.
+    (e.g., "inv_2aUyqjCzEIiEcYMKj7TZtw") in the admin search box.
 
-    The mixin decodes the identifier and searches by the UUID field.
+    The mixin decodes the display ID and searches by the UUID field.
+
+    For raw UUID search, add the UUID field to ``search_fields`` instead::
+
+        search_fields = ["name", "id"]  # "id" enables raw UUID search
 
     Example:
         from django.contrib import admin
-        from django_display_ids.admin import DisplayIDSearchMixin
+        from django_display_ids import DisplayIDAdminSearchMixin
 
         @admin.register(Invoice)
-        class InvoiceAdmin(DisplayIDSearchMixin, admin.ModelAdmin):
+        class InvoiceAdmin(DisplayIDAdminSearchMixin, admin.ModelAdmin):
             list_display = ["id", "display_id", "name"]
-            search_fields = ["name"]  # display_id/UUID search is automatic
+            search_fields = ["name"]  # display ID search is automatic
 
     Attributes:
         uuid_field: Name of the UUID field to search. Defaults to model's
-            uuid_field if using DisplayIDMixin, otherwise "id".
+            uuid_field if using DisplayIDModel, otherwise "id".
     """
 
     uuid_field: str | None = None
@@ -49,43 +51,26 @@ class DisplayIDSearchMixin:
         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."""
-        try:
-            return uuid.UUID(value)
-        except (ValueError, TypeError):
-            return None
-
     def get_search_results(
         self,
         request: HttpRequest,
         queryset: QuerySet[Any],
         search_term: str,
     ) -> tuple[QuerySet[Any], bool]:
-        """Extend search to handle display IDs and raw UUIDs.
+        """Extend search to handle display IDs.
 
-        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
+        Tries to decode the search term as a display ID (prefix_base62uuid)
+        if it contains an underscore.
         """
         queryset, use_distinct = super().get_search_results(  # type: ignore[misc]
             request, queryset, search_term
         )
 
-        uuid_field = self._get_uuid_field()
-        uuid_val = None
-
         # Try to decode as display_id if it contains an underscore
         if "_" in search_term:
+            uuid_field = self._get_uuid_field()
             with contextlib.suppress(ValueError, TypeError):
                 _prefix, uuid_val = decode_display_id(search_term)
-
-        # Try to parse as raw UUID if not already matched
-        if uuid_val is None:
-            uuid_val = self._try_parse_uuid(search_term)
-
-        # Add matching objects to queryset if we found a UUID
-        if uuid_val is not None:
-            queryset |= self.model._default_manager.filter(**{uuid_field: uuid_val})
+                queryset |= self.model._default_manager.filter(**{uuid_field: uuid_val})
 
         return queryset, use_distinct

django_display_ids/conf.py

@@ -11,7 +11,7 @@ Settings can be configured in Django settings under the DISPLAY_IDS namespace:
 
 from __future__ import annotations
 
-from typing import TYPE_CHECKING
+from typing import TYPE_CHECKING, Any
 
 from django.conf import settings
 from django.urls.converters import SlugConverter
@@ -21,10 +21,16 @@ if TYPE_CHECKING:
 
 __all__ = [
     "DEFAULTS",
+    "NOT_SET",
     "SLUG_REGEX",
     "get_setting",
+    "get_slug_field",
+    "get_uuid_field",
 ]
 
+# Sentinel for distinguishing "not set" from None
+NOT_SET: Any = object()
+
 # Django's default slug regex pattern
 SLUG_REGEX: str = SlugConverter.regex
 
@@ -56,3 +62,31 @@ def get_setting(name: str) -> str | tuple[StrategyName, ...]:
     )
     result = user_settings.get(name, DEFAULTS[name])
     return result  # type: ignore[return-value]
+
+
+def get_uuid_field(override: str | None) -> str:
+    """Get the UUID field name, with optional override.
+
+    Args:
+        override: Explicit field name, or None to use settings default.
+
+    Returns:
+        The UUID field name.
+    """
+    if override is not None:
+        return override
+    return str(get_setting("UUID_FIELD"))
+
+
+def get_slug_field(override: str | None) -> str:
+    """Get the slug field name, with optional override.
+
+    Args:
+        override: Explicit field name, or None to use settings default.
+
+    Returns:
+        The slug field name.
+    """
+    if override is not None:
+        return override
+    return str(get_setting("SLUG_FIELD"))

django_display_ids/contrib/drf_spectacular/__init__.py

@@ -1,13 +1,62 @@
-"""drf-spectacular extension for DisplayIDField.
+"""drf-spectacular integration for django-display-ids.
 
-This extension auto-registers when drf-spectacular is installed, providing
-proper OpenAPI schema generation for DisplayIDField.
+This module provides:
+- OpenAPI schema extension for DisplayIDField (auto-registers when imported)
+- Helper functions for documenting URL path parameters
 """
 
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
+# OpenAPI parameter description helpers
+# These work regardless of whether drf-spectacular is installed
+
+
+def id_param_description(
+    prefix: str, *, with_uuid: bool = True, with_slug: bool = False
+) -> str:
+    """Generate ID parameter description with the actual prefix.
+
+    Args:
+        prefix: The display_id prefix (e.g., "user", "app").
+        with_uuid: Include UUID as an identifier option.
+        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("user", with_uuid=False)
+        'Identifier: display_id (user_xxx)'
+
+        >>> id_param_description("app", with_slug=True)
+        'Identifier: display_id (app_xxx), UUID, or slug'
+
+        >>> id_param_description("app", with_uuid=False, with_slug=True)
+        'Identifier: display_id (app_xxx) or slug'
+    """
+    parts = [f"display_id ({prefix}_xxx)"]
+    if with_uuid:
+        parts.append("UUID")
+    if with_slug:
+        parts.append("slug")
+
+    if len(parts) == 1:
+        return f"Identifier: {parts[0]}"
+    elif len(parts) == 2:
+        return f"Identifier: {parts[0]} or {parts[1]}"
+    else:
+        return f"Identifier: {', '.join(parts[:-1])}, or {parts[-1]}"
+
+
+__all__ = [
+    "id_param_description",
+]
+
 try:
     from drf_spectacular.extensions import OpenApiSerializerFieldExtension
 except ImportError:

django_display_ids/contrib/rest_framework/__init__.py

@@ -1,48 +1,9 @@
 """Django REST Framework integration for django-display-ids."""
 
-import contextlib
-
 from .serializers import DisplayIDField
-from .views import DisplayIDLookupMixin
-
-# 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"
-
+from .views import DisplayIDMixin
 
-__all__ = [  # noqa: RUF022 - keep logical order for readability
+__all__ = [
     "DisplayIDField",
-    "DisplayIDLookupMixin",
-    "ID_PARAM_DESCRIPTION",
-    "ID_PARAM_DESCRIPTION_WITH_SLUG",
-    "id_param_description",
+    "DisplayIDMixin",
 ]

django_display_ids/contrib/rest_framework/views.py

@@ -4,11 +4,16 @@ from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
 
-from django_display_ids.conf import get_setting
+from django_display_ids.conf import (
+    NOT_SET,
+    get_setting,
+    get_slug_field,
+    get_uuid_field,
+)
 from django_display_ids.encoding import PREFIX_PATTERN
 from django_display_ids.exceptions import (
+    DisplayIDLookupError,
     InvalidIdentifierError,
-    LookupError,
     ObjectNotFoundError,
     UnknownPrefixError,
 )
@@ -19,11 +24,9 @@ if TYPE_CHECKING:
     from django.db import models
 
 __all__ = [
-    "DisplayIDLookupMixin",
+    "DisplayIDMixin",
 ]
 
-_NOT_SET: Any = object()
-
 
 def _get_drf_exceptions() -> tuple[type[Exception], type[Exception]]:
     """Lazily import DRF exceptions to avoid hard dependency."""
@@ -33,12 +36,12 @@ def _get_drf_exceptions() -> tuple[type[Exception], type[Exception]]:
         return NotFound, ParseError
     except ImportError:
         raise ImportError(
-            "Django REST Framework is required for DisplayIDLookupMixin. "
+            "Django REST Framework is required for DisplayIDMixin. "
             "Install it with: pip install djangorestframework"
         ) from None
 
 
-class DisplayIDLookupMixin:
+class DisplayIDMixin:
     """Mixin for DRF views that resolves objects by display ID, UUID, or slug.
 
     Works with APIView, GenericAPIView, and ViewSets. Does not require
@@ -52,7 +55,7 @@ class DisplayIDLookupMixin:
         slug_field: Name of the slug field on the model.
 
     Example:
-        class InvoiceView(DisplayIDLookupMixin, APIView):
+        class InvoiceView(DisplayIDMixin, APIView):
             lookup_url_kwarg = "id"
             lookup_strategies = ("display_id", "uuid")
             display_id_prefix = "inv"
@@ -62,7 +65,7 @@ class DisplayIDLookupMixin:
                 return Response({"id": str(invoice.id)})
 
     Example with ViewSet:
-        class InvoiceViewSet(DisplayIDLookupMixin, ModelViewSet):
+        class InvoiceViewSet(DisplayIDMixin, ModelViewSet):
             queryset = Invoice.objects.all()
             serializer_class = InvoiceSerializer
             lookup_url_kwarg = "pk"
@@ -71,7 +74,7 @@ class DisplayIDLookupMixin:
 
     lookup_url_kwarg: str = "pk"
     lookup_strategies: tuple[StrategyName, ...] | None = None
-    display_id_prefix: str | None = _NOT_SET
+    display_id_prefix: str | None = NOT_SET
     uuid_field: str | None = None
     slug_field: str | None = None
 
@@ -80,14 +83,10 @@ class DisplayIDLookupMixin:
     request: Any
 
     def _get_uuid_field(self) -> str:
-        if self.uuid_field is not None:
-            return self.uuid_field
-        return str(get_setting("UUID_FIELD"))
+        return get_uuid_field(self.uuid_field)
 
     def _get_slug_field(self) -> str:
-        if self.slug_field is not None:
-            return self.slug_field
-        return str(get_setting("SLUG_FIELD"))
+        return get_slug_field(self.slug_field)
 
     def _get_strategies(self) -> tuple[StrategyName, ...]:
         if self.lookup_strategies is not None:
@@ -101,7 +100,7 @@ class DisplayIDLookupMixin:
         explicitly disable), otherwise falls back to the model's
         display_id_prefix attribute.
         """
-        if self.display_id_prefix is not _NOT_SET:
+        if self.display_id_prefix is not NOT_SET:
             if self.display_id_prefix is not None and not PREFIX_PATTERN.match(
                 self.display_id_prefix
             ):
@@ -168,7 +167,7 @@ class DisplayIDLookupMixin:
             raise NotFound(str(e)) from e
         except (InvalidIdentifierError, UnknownPrefixError) as e:
             raise ParseError(str(e)) from e
-        except LookupError as e:
+        except DisplayIDLookupError as e:
             raise ParseError(str(e)) from e
 
         # Check object-level permissions

django_display_ids/converters.py

@@ -2,7 +2,7 @@
 
 from __future__ import annotations
 
-from .conf import SLUG_REGEX
+from .conf import SLUG_REGEX, get_setting
 
 __all__ = [
     "DISPLAY_ID_REGEX",
@@ -19,6 +19,9 @@ __all__ = [
 DISPLAY_ID_REGEX = r"[a-z]{1,16}_[0-9A-Za-z]{22}"
 UUID_REGEX = r"[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}"
 
+# Slug regex from settings (respects DISPLAY_IDS["SLUG_REGEX"] Django setting)
+_SLUG_REGEX: str = str(get_setting("SLUG_REGEX"))
+
 
 class BaseConverter:
     """Base class for URL path converters with pass-through conversion."""
@@ -78,7 +81,7 @@ class DisplayIDOrSlugConverter(BaseConverter):
 
     Matches either format:
     - Display ID: {prefix}_{base62}
-    - Slug: Django's default slug pattern [-a-zA-Z0-9_]+
+    - Slug: matches DISPLAY_IDS["SLUG_REGEX"] setting (default: [-a-zA-Z0-9_]+)
 
     Example:
         from django.urls import path, register_converter
@@ -91,7 +94,7 @@ class DisplayIDOrSlugConverter(BaseConverter):
         ]
     """
 
-    regex = rf"(?:{DISPLAY_ID_REGEX}|{SLUG_REGEX})"
+    regex = rf"(?:{DISPLAY_ID_REGEX}|{_SLUG_REGEX})"
 
 
 class DisplayIDOrUUIDOrSlugConverter(BaseConverter):
@@ -100,7 +103,7 @@ class DisplayIDOrUUIDOrSlugConverter(BaseConverter):
     Matches any of:
     - Display ID: {prefix}_{base62}
     - UUID: hyphenated (e.g., 550e8400-e29b-41d4-a716-446655440000)
-    - Slug: Django's default slug pattern [-a-zA-Z0-9_]+
+    - Slug: matches DISPLAY_IDS["SLUG_REGEX"] setting (default: [-a-zA-Z0-9_]+)
 
     Example:
         from django.urls import path, register_converter
@@ -113,7 +116,7 @@ class DisplayIDOrUUIDOrSlugConverter(BaseConverter):
         ]
     """
 
-    regex = rf"(?:{DISPLAY_ID_REGEX}|{UUID_REGEX}|{SLUG_REGEX})"
+    regex = rf"(?:{DISPLAY_ID_REGEX}|{UUID_REGEX}|{_SLUG_REGEX})"
 
 
 def make_display_id_or_slug_converter(
@@ -140,8 +143,6 @@ def make_display_id_or_slug_converter(
             path("products/<display_id_or_slug:id>/", ProductDetailView.as_view()),
         ]
     """
-    from .conf import get_setting
-
     pattern = slug_regex if slug_regex is not None else get_setting("SLUG_REGEX")
 
     class CustomDisplayIDOrSlugConverter(DisplayIDOrSlugConverter):
@@ -176,8 +177,6 @@ def make_display_id_or_uuid_or_slug_converter(
             path("products/<identifier:id>/", ProductDetailView.as_view()),
         ]
     """
-    from .conf import get_setting
-
     pattern = slug_regex if slug_regex is not None else get_setting("SLUG_REGEX")
 
     class CustomDisplayIDOrUUIDOrSlugConverter(DisplayIDOrUUIDOrSlugConverter):

django_display_ids/exceptions.py

@@ -4,21 +4,21 @@ from __future__ import annotations
 
 __all__ = [
     "AmbiguousIdentifierError",
+    "DisplayIDLookupError",
     "InvalidIdentifierError",
-    "LookupError",
     "MissingPrefixError",
     "ObjectNotFoundError",
     "UnknownPrefixError",
 ]
 
 
-class LookupError(Exception):
+class DisplayIDLookupError(Exception):
     """Base exception for all lookup errors."""
 
     pass
 
 
-class InvalidIdentifierError(LookupError):
+class InvalidIdentifierError(DisplayIDLookupError):
     """Raised when an identifier has an invalid format.
 
     This indicates the identifier string cannot be parsed as any
@@ -31,7 +31,7 @@ class InvalidIdentifierError(LookupError):
         super().__init__(self.message)
 
 
-class UnknownPrefixError(LookupError):
+class UnknownPrefixError(DisplayIDLookupError):
     """Raised when a display ID has an unexpected prefix.
 
     This occurs when prefix enforcement is enabled and the
@@ -49,7 +49,7 @@ class UnknownPrefixError(LookupError):
         super().__init__(message)
 
 
-class MissingPrefixError(LookupError):
+class MissingPrefixError(DisplayIDLookupError):
     """Raised when a display ID lookup is attempted without a prefix.
 
     This occurs when calling get_by_display_id() on a model that
@@ -68,7 +68,7 @@ class MissingPrefixError(LookupError):
         super().__init__(message)
 
 
-class ObjectNotFoundError(LookupError):
+class ObjectNotFoundError(DisplayIDLookupError):
     """Raised when no object matches the identifier.
 
     This indicates the identifier was valid but no matching
@@ -85,7 +85,7 @@ class ObjectNotFoundError(LookupError):
         super().__init__(message)
 
 
-class AmbiguousIdentifierError(LookupError):
+class AmbiguousIdentifierError(DisplayIDLookupError):
     """Raised when an identifier matches multiple objects.
 
     This can occur with slug lookups if slugs are not unique,

django_display_ids/managers.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import uuid
 from typing import TYPE_CHECKING, Any, TypeVar
 
 from django.db import models
@@ -51,14 +52,15 @@ class DisplayIDQuerySet(models.QuerySet[M]):
 
     def get_by_display_id(
         self,
-        value: str,
+        value: str | uuid.UUID,
         *,
         prefix: str | None = None,
     ) -> M:
         """Get an object by its display ID.
 
         Args:
-            value: The display ID string (e.g., "inv_1a2B3c4D5e6F7g8H").
+            value: The display ID string (e.g., "inv_1a2B3c4D5e6F7g8H"),
+                or a UUID instance for direct UUID lookup.
             prefix: Expected prefix for validation. If None, uses model's prefix.
 
         Returns:
@@ -70,9 +72,19 @@ class DisplayIDQuerySet(models.QuerySet[M]):
             UnknownPrefixError: If the prefix doesn't match expected.
             ObjectNotFoundError: If no matching object exists.
         """
-        # Get model config
         model = self.model
         uuid_field = self._get_uuid_field()
+
+        # UUID objects skip display ID parsing entirely
+        if isinstance(value, uuid.UUID):
+            try:
+                return self.get(**{uuid_field: value})
+            except model.DoesNotExist:  # type: ignore[attr-defined]
+                raise ObjectNotFoundError(
+                    str(value), model_name=model.__name__
+                ) from None
+
+        # Get model config
         expected_prefix = prefix or self._get_model_prefix()
 
         # Require a prefix for display ID lookups
@@ -99,7 +111,7 @@ class DisplayIDQuerySet(models.QuerySet[M]):
 
     def get_by_identifier(
         self,
-        value: str,
+        value: str | uuid.UUID,
         *,
         strategies: tuple[StrategyName, ...] | None = None,
         prefix: str | None = None,
@@ -109,7 +121,8 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         Tries each strategy in order and returns the first match.
 
         Args:
-            value: The identifier string (display ID, UUID, or slug).
+            value: The identifier string (display ID, UUID, or slug),
+                or a UUID instance for direct UUID lookup.
             strategies: Strategies to try. Defaults to settings.
             prefix: Expected display ID prefix for validation.
 
@@ -124,6 +137,16 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         """
         model = self.model
         uuid_field = self._get_uuid_field()
+
+        # UUID objects skip strategy parsing entirely
+        if isinstance(value, uuid.UUID):
+            try:
+                return self.get(**{uuid_field: value})
+            except model.DoesNotExist:  # type: ignore[attr-defined]
+                raise ObjectNotFoundError(
+                    str(value), model_name=model.__name__
+                ) from None
+
         slug_field = self._get_slug_field()
         expected_prefix = prefix or self._get_model_prefix()
         lookup_strategies = strategies or self._get_strategies()
@@ -144,14 +167,14 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         try:
             return self.get(**lookup)
         except model.DoesNotExist:  # type: ignore[attr-defined]
-            raise ObjectNotFoundError(value, model_name=model.__name__) from None
+            raise ObjectNotFoundError(str(value), model_name=model.__name__) from None
         except model.MultipleObjectsReturned:  # type: ignore[attr-defined]
             count = self.filter(**lookup).count()
-            raise AmbiguousIdentifierError(value, count) from None
+            raise AmbiguousIdentifierError(str(value), count) from None
 
     def get_by_identifiers(
         self,
-        values: Sequence[str],
+        values: Sequence[str | uuid.UUID],
         *,
         strategies: tuple[StrategyName, ...] | None = None,
         prefix: str | None = None,
@@ -162,7 +185,8 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         then executes a single database query using `__in` lookups.
 
         Args:
-            values: A sequence of identifier strings (display IDs, UUIDs, or slugs).
+            values: A sequence of identifier strings (display IDs, UUIDs, or slugs)
+                or UUID instances. UUID instances skip strategy parsing.
             strategies: Strategies to try. Defaults to settings.
             prefix: Expected display ID prefix for validation.
 
@@ -178,6 +202,7 @@ class DisplayIDQuerySet(models.QuerySet[M]):
                 'inv_2aUyqjCzEIiEcYMKj7TZtw',
                 'inv_7kN3xPqRmLwYvTzJ5HfUaB',
                 '550e8400-e29b-41d4-a716-446655440000',
+                uuid.UUID('550e8400-e29b-41d4-a716-446655440000'),
             ])
         """
         if not values:
@@ -193,6 +218,11 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         slugs: list[str] = []
 
         for value in values:
+            # UUID objects skip strategy parsing entirely
+            if isinstance(value, uuid.UUID):
+                uuids.append(value)
+                continue
+
             result = parse_identifier(
                 value, lookup_strategies, expected_prefix=expected_prefix
             )
@@ -253,7 +283,7 @@ class DisplayIDManager(models.Manager[M]):
 
     def get_by_display_id(
         self,
-        value: str,
+        value: str | uuid.UUID,
         *,
         prefix: str | None = None,
     ) -> M:
@@ -265,7 +295,7 @@ class DisplayIDManager(models.Manager[M]):
 
     def get_by_identifier(
         self,
-        value: str,
+        value: str | uuid.UUID,
         *,
         strategies: tuple[StrategyName, ...] | None = None,
         prefix: str | None = None,
@@ -280,7 +310,7 @@ class DisplayIDManager(models.Manager[M]):
 
     def get_by_identifiers(
         self,
-        values: Sequence[str],
+        values: Sequence[str | uuid.UUID],
         *,
         strategies: tuple[StrategyName, ...] | None = None,
         prefix: str | None = None,

django_display_ids/models.py

@@ -10,7 +10,7 @@ from .conf import get_setting
 from .encoding import PREFIX_PATTERN, encode_display_id
 
 __all__ = [
-    "DisplayIDMixin",
+    "DisplayIDModel",
     "get_model_for_prefix",
 ]
 
@@ -50,14 +50,14 @@ def _register_prefix(prefix: str, model_name: str) -> None:
     _prefix_registry[prefix] = model_name
 
 
-class DisplayIDMixin(models.Model):
-    """Mixin that adds display_id support to a Django model.
+class DisplayIDModel(models.Model):
+    """Abstract base model that adds display_id support.
 
     Subclasses must define `display_id_prefix` as a class attribute.
     Optionally override `uuid_field` or `slug_field` if using non-default field names.
 
     Example:
-        class Invoice(DisplayIDMixin):
+        class Invoice(DisplayIDModel):
             display_id_prefix = "inv"
 
             id = models.UUIDField(primary_key=True, default=uuid.uuid4)
@@ -67,7 +67,7 @@ class DisplayIDMixin(models.Model):
         invoice.display_id  # -> "inv_2aUyqjCzEIiEcYMKj7TZtw"
 
     Example with custom field names:
-        class Product(DisplayIDMixin):
+        class Product(DisplayIDModel):
             display_id_prefix = "prod"
             uuid_field = "uid"
             slug_field = "handle"

django_display_ids/resolver.py

@@ -2,6 +2,7 @@
 
 from __future__ import annotations
 
+import uuid
 from typing import TYPE_CHECKING, Any, TypeVar
 
 from django.db import models
@@ -23,7 +24,7 @@ M = TypeVar("M", bound=models.Model)
 def resolve_object(
     *,
     model: type[M],
-    value: str,
+    value: str | uuid.UUID,
     strategies: tuple[StrategyName, ...] = DEFAULT_STRATEGIES,
     prefix: str | None = None,
     uuid_field: str = "id",
@@ -36,7 +37,8 @@ def resolve_object(
 
     Args:
         model: The Django model class.
-        value: The identifier string (UUID, display ID, or slug).
+        value: The identifier string (UUID, display ID, or slug),
+            or a UUID instance for direct UUID lookup.
         strategies: Tuple of strategy names to try in order.
         prefix: Expected display ID prefix (for validation).
         uuid_field: Name of the UUID field on the model.
@@ -53,9 +55,6 @@ def resolve_object(
         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
     if queryset is not None:
         if queryset.model is not model:
@@ -67,6 +66,16 @@ def resolve_object(
     else:
         qs = model._default_manager.all()
 
+    # UUID objects skip strategy parsing entirely
+    if isinstance(value, uuid.UUID):
+        try:
+            return qs.get(**{uuid_field: value})
+        except model.DoesNotExist:  # type: ignore[attr-defined]
+            raise ObjectNotFoundError(str(value), model_name=model.__name__) from None
+
+    # Parse the identifier to determine type
+    result = parse_identifier(value, strategies, expected_prefix=prefix)
+
     # Build the lookup based on strategy
     lookup: dict[str, Any]
     if result.strategy in ("uuid", "display_id"):

django_display_ids/views.py

@@ -6,11 +6,11 @@ from typing import TYPE_CHECKING, Any
 
 from django.http import Http404
 
-from .conf import get_setting
+from .conf import NOT_SET, get_setting, get_slug_field, get_uuid_field
 from .encoding import PREFIX_PATTERN
 from .exceptions import (
+    DisplayIDLookupError,
     InvalidIdentifierError,
-    LookupError,
     ObjectNotFoundError,
     UnknownPrefixError,
 )
@@ -21,13 +21,11 @@ if TYPE_CHECKING:
     from django.db import models
 
 __all__ = [
-    "DisplayIDObjectMixin",
+    "DisplayIDMixin",
 ]
 
-_NOT_SET: Any = object()
 
-
-class DisplayIDObjectMixin:
+class DisplayIDMixin:
     """Mixin for Django CBVs that resolves objects by display ID, UUID, or slug.
 
     Drop-in replacement for SingleObjectMixin's get_object() method.
@@ -42,7 +40,7 @@ class DisplayIDObjectMixin:
         slug_field: Name of the slug field on the model.
 
     Example:
-        class InvoiceDetailView(DisplayIDObjectMixin, DetailView):
+        class InvoiceDetailView(DisplayIDMixin, DetailView):
             model = Invoice
             lookup_param = "id"
             lookup_strategies = ("display_id", "uuid")
@@ -52,19 +50,15 @@ class DisplayIDObjectMixin:
     model: type[models.Model] | None = None
     lookup_param: str = "pk"
     lookup_strategies: tuple[StrategyName, ...] | None = None
-    display_id_prefix: str | None = _NOT_SET
+    display_id_prefix: str | None = NOT_SET
     uuid_field: str | None = None
     slug_field: str | None = None
 
     def _get_uuid_field(self) -> str:
-        if self.uuid_field is not None:
-            return self.uuid_field
-        return str(get_setting("UUID_FIELD"))
+        return get_uuid_field(self.uuid_field)
 
     def _get_slug_field(self) -> str:
-        if self.slug_field is not None:
-            return self.slug_field
-        return str(get_setting("SLUG_FIELD"))
+        return get_slug_field(self.slug_field)
 
     def _get_strategies(self) -> tuple[StrategyName, ...]:
         if self.lookup_strategies is not None:
@@ -78,7 +72,7 @@ class DisplayIDObjectMixin:
         explicitly disable), otherwise falls back to the model's
         display_id_prefix attribute.
         """
-        if self.display_id_prefix is not _NOT_SET:
+        if self.display_id_prefix is not NOT_SET:
             if self.display_id_prefix is not None and not PREFIX_PATTERN.match(
                 self.display_id_prefix
             ):
@@ -146,5 +140,5 @@ class DisplayIDObjectMixin:
             raise Http404(str(e)) from e
         except (InvalidIdentifierError, UnknownPrefixError) as e:
             raise Http404(str(e)) from e
-        except LookupError as e:
+        except DisplayIDLookupError as e:
             raise Http404(str(e)) from e

{django_display_ids-0.3.2.dist-info → django_display_ids-0.4.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-display-ids
-Version: 0.3.2
+Version: 0.4.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: MIT
@@ -19,6 +19,7 @@ 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
+Project-URL: Changelog, https://github.com/josephabrahams/django-display-ids/blob/main/CHANGELOG.md
 Description-Content-Type: text/markdown
 
 # django-display-ids
@@ -66,9 +67,9 @@ INSTALLED_APPS = [
 
 ```python
 from django.views.generic import DetailView
-from django_display_ids import DisplayIDObjectMixin
+from django_display_ids import DisplayIDMixin
 
-class InvoiceDetailView(DisplayIDObjectMixin, DetailView):
+class InvoiceDetailView(DisplayIDMixin, DetailView):
     model = Invoice
     lookup_param = "id"
     lookup_strategies = ("display_id", "uuid", "slug")
@@ -79,9 +80,9 @@ class InvoiceDetailView(DisplayIDObjectMixin, DetailView):
 
 ```python
 from rest_framework.viewsets import ModelViewSet
-from django_display_ids.contrib.rest_framework import DisplayIDLookupMixin
+from django_display_ids.contrib.rest_framework import DisplayIDMixin
 
-class InvoiceViewSet(DisplayIDLookupMixin, ModelViewSet):
+class InvoiceViewSet(DisplayIDMixin, ModelViewSet):
     queryset = Invoice.objects.all()
     serializer_class = InvoiceSerializer
     lookup_url_kwarg = "id"

django_display_ids-0.4.1.dist-info/RECORD

@@ -0,0 +1,25 @@
+django_display_ids/__init__.py,sha256=zFd0XNNOeVgpIImWBe_b-HD59svbVwkDVYq8X6lsLug,3256
+django_display_ids/admin.py,sha256=UPmU-kGsZ5x_-r9n99P17La5lr-3BLvB9qTfWJgklt8,2569
+django_display_ids/apps.py,sha256=UqblGiYNONOIEH-giEAuKp1YDgxl2yf0jS0ELMj1iig,315
+django_display_ids/conf.py,sha256=RXcWGyRfLS9J5fyUaoM5ASq2rwOFSxX22tvSX-TB2ig,2215
+django_display_ids/contrib/__init__.py,sha256=sxGJK8Whb6cL7RqACqGRYrIZvaMwP3l6dYk3mIYWzDY,62
+django_display_ids/contrib/drf_spectacular/__init__.py,sha256=9swSJge_dQldC4AZMkYI3M04LzU20eJ_2oz3XABviFA,5427
+django_display_ids/contrib/rest_framework/__init__.py,sha256=pKV6BVB7k0dJm29C7XMr0M-wK2lXPUgW8Hf4BZHHwuE,198
+django_display_ids/contrib/rest_framework/serializers.py,sha256=Jp-z7qHafxkGNYv30YC9rrqLt936SrhONJv3rqfQaC0,4049
+django_display_ids/contrib/rest_framework/views.py,sha256=I6jpsdpM1sRKrPBVyrjypsKgFyUdu6WljGcffHXDiCw,5961
+django_display_ids/converters.py,sha256=KGD5FYWkuXztO-6TvTtPwMP7xbnAXAaYuk9LvIpxkBM,5918
+django_display_ids/encoding.py,sha256=csIwUZaQKSOLwRU6-DWGTNGvSxmroyK0Yt7TBCo0AFE,2945
+django_display_ids/examples.py,sha256=gap5NNPTmE7B5uxiYKoMoK8G-OEtL1Ek0W039l6oJ9I,2689
+django_display_ids/exceptions.py,sha256=ATIW6SLM9zQ0s-26c3qdQfnPDbuiMpMZK6fxdyQN0tA,3085
+django_display_ids/managers.py,sha256=I7qY1V64lDPplhE56ueARICFOHEQqCJhme6LQfBWo_o,11031
+django_display_ids/models.py,sha256=_hmgAR4HC3I-5wU2DND6uNLjEllu1Y9eaXeBQ9dWMNI,4313
+django_display_ids/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+django_display_ids/resolver.py,sha256=YhgfkBEVKFsAA9UB66cbyND46sWYWBHPqOJy-yQWstA,3229
+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=uAXQJryWQNnTSHIjTLhisrYnNiaTo1pLzkUdvYyOLRs,4992
+django_display_ids-0.4.1.dist-info/WHEEL,sha256=iHtWm8nRfs0VRdCYVXocAWFW8ppjHL-uTJkAdZJKOBM,80
+django_display_ids-0.4.1.dist-info/METADATA,sha256=irrOfygrirWeDRa2mCNHvsnKpb6VJRd_8Ty1orTkRGg,5359
+django_display_ids-0.4.1.dist-info/RECORD,,

{django_display_ids-0.3.2.dist-info → django_display_ids-0.4.1.dist-info}/WHEEL

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

django_display_ids-0.3.2.dist-info/RECORD

@@ -1,25 +0,0 @@
-django_display_ids/__init__.py,sha256=wwFvtGjdQia56uY893Jz5iSwaqyH4KXbgvd3nxdzGss,3496
-django_display_ids/admin.py,sha256=_voqWbr8AwPRC_uCTJWTcEhAhc7RZUgvs7DyVsutDuw,3046
-django_display_ids/apps.py,sha256=UqblGiYNONOIEH-giEAuKp1YDgxl2yf0jS0ELMj1iig,315
-django_display_ids/conf.py,sha256=6bHdUwDkuroYEPmOlPiAc49EcxlOG_QO0aHHawckOe8,1404
-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=ElwrfA7DXiadSZ-Sjvl6ZALgH7tfEZ-tLI7UdE6MsAs,5797
-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.2.dist-info/WHEEL,sha256=fAguSjoiATBe7TNBkJwOjyL1Tt4wwiaQGtNtjRPNMQA,80
-django_display_ids-0.3.2.dist-info/METADATA,sha256=qlsCntznDOhR1wMFyPhU2AAnWyodabq1nMHtQm2HczA,5283
-django_display_ids-0.3.2.dist-info/RECORD,,