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

django_display_ids-0.2.0.dist-info/METADATA

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

{django_display_ids-0.1.4.dist-info → django_display_ids-0.2.0.dist-info}/RECORD

@@ -16,6 +16,6 @@ django_display_ids/resolver.py,sha256=oCoA6jbGCFS8SMrkfD_oSSBQNrSxnxdooK5j933eA9
 django_display_ids/strategies.py,sha256=Rq00-AW_FB8-K04u2oBK5J6kPiYgsE3TdYlLyK_zro0,4436
 django_display_ids/typing.py,sha256=2O3kT7XKkiE7WI9A5KkILPM-Zi7-zCy5gVvXQL_J2mI,478
 django_display_ids/views.py,sha256=sLsJm8Tpe3Qk1gOLcDzfpazxuaVqTCAdgVIXOONFnKQ,5096
-django_display_ids-0.1.4.dist-info/WHEEL,sha256=XV0cjMrO7zXhVAIyyc8aFf1VjZ33Fen4IiJk5zFlC3g,80
-django_display_ids-0.1.4.dist-info/METADATA,sha256=46ob0brsZSBW7QFrmISYvNkD7mQGu3NkIXRe3ueae6g,12356
-django_display_ids-0.1.4.dist-info/RECORD,,
+django_display_ids-0.2.0.dist-info/WHEEL,sha256=e_m4S054HL0hyR3CpOk-b7Q7fDX6BuFkgL5OjAExXas,80
+django_display_ids-0.2.0.dist-info/METADATA,sha256=cXxwTVjdSXtYv0ghEid7n-udEjrdZrZWhbEWSkvFr6M,3342
+django_display_ids-0.2.0.dist-info/RECORD,,

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

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

django_display_ids-0.1.4.dist-info/METADATA

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