django-display-ids 0.4.1__tar.gz → 0.5.1__tar.gz

{django_display_ids-0.4.1 → django_display_ids-0.5.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.3
 Name: django-display-ids
-Version: 0.4.1
+Version: 0.5.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
@@ -72,7 +72,6 @@ from django_display_ids import DisplayIDMixin
 class InvoiceDetailView(DisplayIDMixin, DetailView):
     model = Invoice
     lookup_param = "id"
-    lookup_strategies = ("display_id", "uuid", "slug")
     display_id_prefix = "inv"
 ```
 
@@ -86,7 +85,6 @@ class InvoiceViewSet(DisplayIDMixin, ModelViewSet):
     queryset = Invoice.objects.all()
     serializer_class = InvoiceSerializer
     lookup_url_kwarg = "id"
-    lookup_strategies = ("display_id", "uuid", "slug")
     display_id_prefix = "inv"
 ```
 

{django_display_ids-0.4.1 → django_display_ids-0.5.1}/README.md

@@ -48,7 +48,6 @@ from django_display_ids import DisplayIDMixin
 class InvoiceDetailView(DisplayIDMixin, DetailView):
     model = Invoice
     lookup_param = "id"
-    lookup_strategies = ("display_id", "uuid", "slug")
     display_id_prefix = "inv"
 ```
 
@@ -62,7 +61,6 @@ class InvoiceViewSet(DisplayIDMixin, ModelViewSet):
     queryset = Invoice.objects.all()
     serializer_class = InvoiceSerializer
     lookup_url_kwarg = "id"
-    lookup_strategies = ("display_id", "uuid", "slug")
     display_id_prefix = "inv"
 ```
 

{django_display_ids-0.4.1 → django_display_ids-0.5.1}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "django-display-ids"
-version = "0.4.1"
+version = "0.5.1"
 description = "Stripe-like prefixed IDs for Django. Works with existing UUIDs — no schema changes."
 readme = "README.md"
 requires-python = ">=3.12"

{django_display_ids-0.4.1 → django_display_ids-0.5.1}/src/django_display_ids/conf.py

@@ -5,7 +5,7 @@ Settings can be configured in Django settings under the DISPLAY_IDS namespace:
     DISPLAY_IDS = {
         "UUID_FIELD": "uid",
         "SLUG_FIELD": "slug",
-        "STRATEGIES": ("display_id", "uuid"),
+        "STRATEGIES": ("display_id", "uuid", "slug"),
     }
 """
 
@@ -37,7 +37,7 @@ SLUG_REGEX: str = SlugConverter.regex
 DEFAULTS: dict[str, str | tuple[str, ...]] = {
     "UUID_FIELD": "id",
     "SLUG_FIELD": "slug",
-    "STRATEGIES": ("display_id", "uuid"),
+    "STRATEGIES": ("display_id", "uuid", "slug"),
     "SLUG_REGEX": SLUG_REGEX,
 }
 

{django_display_ids-0.4.1 → django_display_ids-0.5.1}/src/django_display_ids/contrib/rest_framework/views.py

@@ -13,9 +13,7 @@ from django_display_ids.conf import (
 from django_display_ids.encoding import PREFIX_PATTERN
 from django_display_ids.exceptions import (
     DisplayIDLookupError,
-    InvalidIdentifierError,
     ObjectNotFoundError,
-    UnknownPrefixError,
 )
 from django_display_ids.resolver import resolve_object
 from django_display_ids.typing import StrategyName  # noqa: TC001 - used at runtime
@@ -57,7 +55,6 @@ class DisplayIDMixin:
     Example:
         class InvoiceView(DisplayIDMixin, APIView):
             lookup_url_kwarg = "id"
-            lookup_strategies = ("display_id", "uuid")
             display_id_prefix = "inv"
 
             def get(self, request, *args, **kwargs):
@@ -69,7 +66,6 @@ class DisplayIDMixin:
             queryset = Invoice.objects.all()
             serializer_class = InvoiceSerializer
             lookup_url_kwarg = "pk"
-            lookup_strategies = ("display_id", "uuid")
     """
 
     lookup_url_kwarg: str = "pk"
@@ -165,8 +161,6 @@ class DisplayIDMixin:
             )
         except ObjectNotFoundError as e:
             raise NotFound(str(e)) from e
-        except (InvalidIdentifierError, UnknownPrefixError) as e:
-            raise ParseError(str(e)) from e
         except DisplayIDLookupError as e:
             raise ParseError(str(e)) from e
 

{django_display_ids-0.4.1 → django_display_ids-0.5.1}/src/django_display_ids/exceptions.py

@@ -1,7 +1,26 @@
-"""Typed exceptions for identifier lookup errors."""
+"""Typed exceptions for identifier lookup errors.
+
+All exceptions inherit from both ``DisplayIDLookupError`` and a standard
+Django/Python exception, so they integrate naturally with existing error
+handling patterns::
+
+    # Catch with library-specific base
+    except DisplayIDLookupError: ...
+
+    # Or catch with standard Django/Python exceptions
+    except ObjectDoesNotExist: ...   # catches ObjectNotFoundError
+    except ValueError: ...           # catches InvalidIdentifierError, UnknownPrefixError
+    except ImproperlyConfigured: ... # catches MissingPrefixError
+"""
 
 from __future__ import annotations
 
+from django.core.exceptions import (
+    ImproperlyConfigured,
+    MultipleObjectsReturned,
+    ObjectDoesNotExist,
+)
+
 __all__ = [
     "AmbiguousIdentifierError",
     "DisplayIDLookupError",
@@ -18,11 +37,14 @@ class DisplayIDLookupError(Exception):
     pass
 
 
-class InvalidIdentifierError(DisplayIDLookupError):
+class InvalidIdentifierError(DisplayIDLookupError, ValueError):
     """Raised when an identifier has an invalid format.
 
     This indicates the identifier string cannot be parsed as any
     of the supported formats (UUID, display ID, or slug).
+
+    Inherits from ``ValueError`` because it represents bad input — the
+    caller provided a value that isn't a valid identifier.
     """
 
     def __init__(self, value: str, message: str | None = None) -> None:
@@ -31,11 +53,14 @@ class InvalidIdentifierError(DisplayIDLookupError):
         super().__init__(self.message)
 
 
-class UnknownPrefixError(DisplayIDLookupError):
+class UnknownPrefixError(DisplayIDLookupError, ValueError):
     """Raised when a display ID has an unexpected prefix.
 
     This occurs when prefix enforcement is enabled and the
     display ID's prefix doesn't match the expected value.
+
+    Inherits from ``ValueError`` because it represents bad input — the
+    caller provided a display ID with the wrong prefix.
     """
 
     def __init__(self, value: str, actual: str, expected: str | None = None) -> None:
@@ -49,11 +74,14 @@ class UnknownPrefixError(DisplayIDLookupError):
         super().__init__(message)
 
 
-class MissingPrefixError(DisplayIDLookupError):
+class MissingPrefixError(DisplayIDLookupError, ImproperlyConfigured):
     """Raised when a display ID lookup is attempted without a prefix.
 
     This occurs when calling get_by_display_id() on a model that
     doesn't have display_id_prefix configured.
+
+    Inherits from ``ImproperlyConfigured`` because it represents a
+    configuration problem — the model is missing a required setting.
     """
 
     def __init__(self, model_name: str | None = None) -> None:
@@ -68,11 +96,14 @@ class MissingPrefixError(DisplayIDLookupError):
         super().__init__(message)
 
 
-class ObjectNotFoundError(DisplayIDLookupError):
+class ObjectNotFoundError(DisplayIDLookupError, ObjectDoesNotExist):
     """Raised when no object matches the identifier.
 
     This indicates the identifier was valid but no matching
     database record exists.
+
+    Inherits from ``ObjectDoesNotExist`` so it integrates with Django's
+    built-in error handling (e.g., ``get_object_or_404``).
     """
 
     def __init__(self, value: str, model_name: str | None = None) -> None:
@@ -85,11 +116,14 @@ class ObjectNotFoundError(DisplayIDLookupError):
         super().__init__(message)
 
 
-class AmbiguousIdentifierError(DisplayIDLookupError):
+class AmbiguousIdentifierError(DisplayIDLookupError, MultipleObjectsReturned):
     """Raised when an identifier matches multiple objects.
 
     This can occur with slug lookups if slugs are not unique,
     or in edge cases with identifier collisions.
+
+    Inherits from ``MultipleObjectsReturned`` because the semantics
+    are identical — a lookup that expected one result found many.
     """
 
     def __init__(self, value: str, count: int) -> None:

{django_display_ids-0.4.1 → django_display_ids-0.5.1}/src/django_display_ids/managers.py

@@ -3,19 +3,17 @@
 from __future__ import annotations
 
 import uuid
-from typing import TYPE_CHECKING, Any, TypeVar
+from typing import TYPE_CHECKING, Any, Self, TypeVar
 
+from django.core.exceptions import FieldDoesNotExist
 from django.db import models
 from django.db.models import Q
 
 from .conf import get_setting
 from .encoding import decode_display_id
 from .exceptions import (
-    AmbiguousIdentifierError,
-    InvalidIdentifierError,
+    DisplayIDLookupError,
     MissingPrefixError,
-    ObjectNotFoundError,
-    UnknownPrefixError,
 )
 from .strategies import parse_identifier
 
@@ -50,6 +48,33 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         invoice = Invoice.objects.get_by_display_id("inv_1a2B3c4D5e6F7g8H")
     """
 
+    # Re-annotate inherited QuerySet methods with -> Self so that
+    # display ID methods remain visible to type checkers after chaining
+    # (e.g. Invoice.objects.filter(...).get_by_identifier(...)).
+    def filter(self, *args: Any, **kwargs: Any) -> Self:
+        return super().filter(*args, **kwargs)
+
+    def exclude(self, *args: Any, **kwargs: Any) -> Self:
+        return super().exclude(*args, **kwargs)
+
+    def select_related(self, *fields: Any) -> Self:
+        return super().select_related(*fields)
+
+    def prefetch_related(self, *lookups: Any) -> Self:
+        return super().prefetch_related(*lookups)
+
+    def order_by(self, *fields: Any) -> Self:
+        return super().order_by(*fields)
+
+    def distinct(self, *fields: Any) -> Self:
+        return super().distinct(*fields)
+
+    def all(self) -> Self:
+        return super().all()
+
+    def none(self) -> Self:
+        return super().none()
+
     def get_by_display_id(
         self,
         value: str | uuid.UUID,
@@ -67,22 +92,16 @@ class DisplayIDQuerySet(models.QuerySet[M]):
             The matching model instance.
 
         Raises:
+            Model.DoesNotExist: If no matching object exists, if the display ID
+                format is invalid, or if the prefix doesn't match.
             MissingPrefixError: If no prefix is configured on the model.
-            InvalidIdentifierError: If the display ID format is invalid.
-            UnknownPrefixError: If the prefix doesn't match expected.
-            ObjectNotFoundError: If no matching object exists.
         """
         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
+            return self.get(**{uuid_field: value})
 
         # Get model config
         expected_prefix = prefix or self._get_model_prefix()
@@ -91,23 +110,22 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         if expected_prefix is None:
             raise MissingPrefixError(model_name=model.__name__)
 
-        # Decode the display ID
+        # Decode the display ID and validate prefix
         try:
             decoded_prefix, uuid_value = decode_display_id(value)
         except ValueError as e:
-            raise InvalidIdentifierError(value, str(e)) from e
+            raise model.DoesNotExist(  # type: ignore[attr-defined]
+                f"{model.__name__}: invalid display ID: {value!r}"
+            ) from e
 
-        # Validate prefix
         if decoded_prefix != expected_prefix:
-            raise UnknownPrefixError(
-                value, actual=decoded_prefix, expected=expected_prefix
+            raise model.DoesNotExist(  # type: ignore[attr-defined]
+                f"{model.__name__}: unknown prefix {decoded_prefix!r} "
+                f"in {value!r}, expected {expected_prefix!r}"
             )
 
         # Query the database
-        try:
-            return self.get(**{uuid_field: uuid_value})
-        except model.DoesNotExist:  # type: ignore[attr-defined]
-            raise ObjectNotFoundError(value, model_name=model.__name__) from None
+        return self.get(**{uuid_field: uuid_value})
 
     def get_by_identifier(
         self,
@@ -130,31 +148,34 @@ class DisplayIDQuerySet(models.QuerySet[M]):
             The matching model instance.
 
         Raises:
-            InvalidIdentifierError: If no strategy can parse the identifier.
-            UnknownPrefixError: If display ID prefix doesn't match expected.
-            ObjectNotFoundError: If no matching object exists.
-            AmbiguousIdentifierError: If multiple objects match (slug).
+            Model.DoesNotExist: If the identifier cannot be parsed or
+                no matching object exists.
+            Model.MultipleObjectsReturned: If multiple objects match (slug).
         """
         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
+            return self.get(**{uuid_field: value})
 
         slug_field = self._get_slug_field()
         expected_prefix = prefix or self._get_model_prefix()
         lookup_strategies = strategies or self._get_strategies()
 
+        # Skip slug strategy if the model has no slug field
+        if not self._has_slug_field(slug_field):
+            lookup_strategies = tuple(s for s in lookup_strategies if s != "slug")
+
         # Parse the identifier
-        result = parse_identifier(
-            value, lookup_strategies, expected_prefix=expected_prefix
-        )
+        try:
+            result = parse_identifier(
+                value, lookup_strategies, expected_prefix=expected_prefix
+            )
+        except DisplayIDLookupError as e:
+            raise model.DoesNotExist(  # type: ignore[attr-defined]
+                f"{model.__name__}: {e}"
+            ) from e
 
         # Build the lookup
         lookup: dict[str, Any]
@@ -164,13 +185,70 @@ class DisplayIDQuerySet(models.QuerySet[M]):
             lookup = {slug_field: result.slug}
 
         # Execute the query
+        return self.get(**lookup)
+
+    def resolve_identifier(
+        self,
+        value: str | uuid.UUID,
+        *,
+        strategies: tuple[StrategyName, ...] | None = None,
+        prefix: str | None = None,
+    ) -> uuid.UUID:
+        """Resolve an identifier to a UUID without fetching the object.
+
+        For UUID and display_id identifiers, the UUID is extracted by parsing
+        alone — no database query is needed. Only slug identifiers require a
+        database lookup.
+
+        This is useful for cursor-based pagination where you need the UUID
+        value to build a WHERE clause but don't need the full model instance.
+
+        Args:
+            value: The identifier string (display ID, UUID, or slug),
+                or a UUID instance (returned as-is).
+            strategies: Strategies to try. Defaults to settings.
+            prefix: Expected display ID prefix for validation.
+
+        Returns:
+            The resolved UUID value.
+
+        Raises:
+            Model.DoesNotExist: If the identifier cannot be parsed or
+                no matching object exists (slug lookup).
+            Model.MultipleObjectsReturned: If multiple objects match (slug).
+        """
+        model = self.model
+        uuid_field = self._get_uuid_field()
+
+        # UUID objects are returned as-is
+        if isinstance(value, uuid.UUID):
+            return value
+
+        slug_field = self._get_slug_field()
+        expected_prefix = prefix or self._get_model_prefix()
+        lookup_strategies = strategies or self._get_strategies()
+
+        # Skip slug strategy if the model has no slug field
+        if not self._has_slug_field(slug_field):
+            lookup_strategies = tuple(s for s in lookup_strategies if s != "slug")
+
+        # Parse the identifier
         try:
-            return self.get(**lookup)
-        except model.DoesNotExist:  # type: ignore[attr-defined]
-            raise ObjectNotFoundError(str(value), model_name=model.__name__) from None
-        except model.MultipleObjectsReturned:  # type: ignore[attr-defined]
-            count = self.filter(**lookup).count()
-            raise AmbiguousIdentifierError(str(value), count) from None
+            result = parse_identifier(
+                value, lookup_strategies, expected_prefix=expected_prefix
+            )
+        except DisplayIDLookupError as e:
+            raise model.DoesNotExist(  # type: ignore[attr-defined]
+                f"{model.__name__}: {e}"
+            ) from e
+
+        # UUID and display_id strategies yield a UUID directly — no DB query
+        if result.strategy in ("uuid", "display_id"):
+            return result.uuid  # type: ignore[return-value]
+
+        # Slug strategy requires a DB lookup
+        obj = self.get(**{slug_field: result.slug})
+        return getattr(obj, uuid_field)  # type: ignore[no-any-return]
 
     def get_by_identifiers(
         self,
@@ -213,6 +291,10 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         expected_prefix = prefix or self._get_model_prefix()
         lookup_strategies = strategies or self._get_strategies()
 
+        # Skip slug strategy if the model has no slug field
+        if not self._has_slug_field(slug_field):
+            lookup_strategies = tuple(s for s in lookup_strategies if s != "slug")
+
         # Collect UUIDs and slugs separately
         uuids: list[Any] = []
         slugs: list[str] = []
@@ -258,6 +340,14 @@ class DisplayIDQuerySet(models.QuerySet[M]):
         """Get the default strategies."""
         return get_setting("STRATEGIES")  # type: ignore[return-value]
 
+    def _has_slug_field(self, slug_field: str) -> bool:
+        """Check whether the model has the configured slug field."""
+        try:
+            self.model._meta.get_field(slug_field)
+            return True
+        except FieldDoesNotExist:
+            return False
+
     def _get_model_prefix(self) -> str | None:
         """Get the display ID prefix from the model, if defined."""
         if hasattr(self.model, "get_display_id_prefix"):
@@ -308,6 +398,21 @@ class DisplayIDManager(models.Manager[M]):
             value, strategies=strategies, prefix=prefix
         )
 
+    def resolve_identifier(
+        self,
+        value: str | uuid.UUID,
+        *,
+        strategies: tuple[StrategyName, ...] | None = None,
+        prefix: str | None = None,
+    ) -> uuid.UUID:
+        """Resolve an identifier to a UUID without fetching the object.
+
+        See DisplayIDQuerySet.resolve_identifier for details.
+        """
+        return self.get_queryset().resolve_identifier(
+            value, strategies=strategies, prefix=prefix
+        )
+
     def get_by_identifiers(
         self,
         values: Sequence[str | uuid.UUID],

{django_display_ids-0.4.1 → django_display_ids-0.5.1}/src/django_display_ids/resolver.py

@@ -5,6 +5,7 @@ from __future__ import annotations
 import uuid
 from typing import TYPE_CHECKING, Any, TypeVar
 
+from django.core.exceptions import FieldDoesNotExist
 from django.db import models
 
 from .exceptions import AmbiguousIdentifierError, ObjectNotFoundError
@@ -73,6 +74,12 @@ def resolve_object(
         except model.DoesNotExist:  # type: ignore[attr-defined]
             raise ObjectNotFoundError(str(value), model_name=model.__name__) from None
 
+    # Skip slug strategy if the model has no slug field
+    try:
+        model._meta.get_field(slug_field)
+    except FieldDoesNotExist:
+        strategies = tuple(s for s in strategies if s != "slug")
+
     # Parse the identifier to determine type
     result = parse_identifier(value, strategies, expected_prefix=prefix)
 

{django_display_ids-0.4.1 → django_display_ids-0.5.1}/src/django_display_ids/typing.py

@@ -12,6 +12,7 @@ __all__ = [
 # Supported lookup strategy names
 StrategyName = Literal["uuid", "display_id", "slug"]
 
-# Default strategy order: display_id first (most specific), then uuid
-# Slug is excluded by default since it's a catch-all that matches any string
-DEFAULT_STRATEGIES: tuple[StrategyName, ...] = ("display_id", "uuid")
+# Default strategy order: display_id first (most specific), then uuid, then slug
+# Slug is a catch-all — it's safe to include by default because the manager
+# and resolver automatically skip it for models without a slug field.
+DEFAULT_STRATEGIES: tuple[StrategyName, ...] = ("display_id", "uuid", "slug")

{django_display_ids-0.4.1 → django_display_ids-0.5.1}/src/django_display_ids/views.py

@@ -8,12 +8,7 @@ from django.http import Http404
 
 from .conf import NOT_SET, get_setting, get_slug_field, get_uuid_field
 from .encoding import PREFIX_PATTERN
-from .exceptions import (
-    DisplayIDLookupError,
-    InvalidIdentifierError,
-    ObjectNotFoundError,
-    UnknownPrefixError,
-)
+from .exceptions import DisplayIDLookupError
 from .resolver import resolve_object
 from .typing import StrategyName  # noqa: TC001 - used at runtime in type hints
 
@@ -43,7 +38,6 @@ class DisplayIDMixin:
         class InvoiceDetailView(DisplayIDMixin, DetailView):
             model = Invoice
             lookup_param = "id"
-            lookup_strategies = ("display_id", "uuid")
             display_id_prefix = "inv"
     """
 
@@ -136,9 +130,5 @@ class DisplayIDMixin:
                 slug_field=self._get_slug_field(),
                 queryset=qs,
             )
-        except ObjectNotFoundError as e:
-            raise Http404(str(e)) from e
-        except (InvalidIdentifierError, UnknownPrefixError) as e:
-            raise Http404(str(e)) from e
         except DisplayIDLookupError as e:
             raise Http404(str(e)) from e