URL Path Converters

Django path converters for validating identifier formats in URL patterns.

DisplayIDConverter

class django_display_ids.converters.DisplayIDConverter

Path converter for display IDs.

Matches the format {prefix}_{base62} where:

• prefix is 1-16 lowercase letters

• base62 is exactly 22 alphanumeric characters

Regex: [a-z]{1,16}_[0-9A-Za-z]{22}

Example matches:

• inv_2aUyqjCzEIiEcYMKj7TZtw

• prod_0000000000000000000000

Does not match:

• INV_2aUyqjCzEIiEcYMKj7TZtw (uppercase prefix)

• 550e8400-e29b-41d4-a716-446655440000 (UUID)

DisplayIDOrUUIDConverter

class django_display_ids.converters.DisplayIDOrUUIDConverter

Path converter for display IDs or UUIDs.

Matches either format:

• Display ID: {prefix}_{base62}

• UUID: hyphenated (550e8400-e29b-41d4-a716-446655440000)

Consistent with Django’s built-in <uuid:id> converter, only hyphenated UUIDs are accepted.

Example matches:

• inv_2aUyqjCzEIiEcYMKj7TZtw (display ID)

• 550e8400-e29b-41d4-a716-446655440000 (UUID)

DisplayIDOrSlugConverter

class django_display_ids.converters.DisplayIDOrSlugConverter

Path converter for display IDs or slugs.

Matches either format:

• Display ID: {prefix}_{base62}

• Slug: Django’s default slug pattern ([-a-zA-Z0-9_]+)

Example matches:

• inv_2aUyqjCzEIiEcYMKj7TZtw (display ID)

• my-product-slug (slug)

• product_123 (slug)

DisplayIDOrUUIDOrSlugConverter

class django_display_ids.converters.DisplayIDOrUUIDOrSlugConverter

Path converter for display IDs, UUIDs, or slugs.

Matches any of:

• Display ID: {prefix}_{base62}

• UUID: hyphenated (550e8400-e29b-41d4-a716-446655440000)

• Slug: Django’s default slug pattern ([-a-zA-Z0-9_]+)

This is the most permissive converter, useful when you want to accept any identifier format.

Example matches:

• inv_2aUyqjCzEIiEcYMKj7TZtw (display ID)

• 550e8400-e29b-41d4-a716-446655440000 (UUID)

• my-product-slug (slug)

Factory Functions

For custom slug patterns, use the factory functions:

django_display_ids.converters.make_display_id_or_slug_converter(slug_regex=None)

Create a DisplayIDOrSlugConverter with a custom slug regex.

Parameters:

slug_regex – Custom slug regex pattern. If None, uses the DISPLAY_IDS["SLUG_REGEX"] setting.

Returns:

A DisplayIDOrSlugConverter subclass with the custom regex.

from django_display_ids.converters import make_display_id_or_slug_converter

# Lowercase slugs only
LowercaseConverter = make_display_id_or_slug_converter(r"[a-z0-9-]+")
register_converter(LowercaseConverter, "lowercase_id")

django_display_ids.converters.make_display_id_or_uuid_or_slug_converter(slug_regex=None)

Create a DisplayIDOrUUIDOrSlugConverter with a custom slug regex.

Parameters:

slug_regex – Custom slug regex pattern. If None, uses the DISPLAY_IDS["SLUG_REGEX"] setting.

Returns:

A DisplayIDOrUUIDOrSlugConverter subclass with the custom regex.

from django_display_ids.converters import make_display_id_or_uuid_or_slug_converter

# Lowercase slugs only
Converter = make_display_id_or_uuid_or_slug_converter(r"[a-z0-9-]+")
register_converter(Converter, "identifier")

Converter Summary

Converter	display_id	uuid	slug
DisplayIDConverter	✓
DisplayIDOrUUIDConverter	✓	✓
DisplayIDOrSlugConverter	✓		✓
DisplayIDOrUUIDOrSlugConverter	✓	✓	✓

Note

For standalone UUID matching, use Django’s built-in <uuid:param> converter.

Usage

Register converters in your URL configuration:

from django.urls import path, register_converter
from django_display_ids.converters import (
    DisplayIDConverter,
    DisplayIDOrUUIDConverter,
    DisplayIDOrSlugConverter,
    DisplayIDOrUUIDOrSlugConverter,
)

register_converter(DisplayIDConverter, "display_id")
register_converter(DisplayIDOrUUIDConverter, "display_id_or_uuid")
register_converter(DisplayIDOrSlugConverter, "display_id_or_slug")
register_converter(DisplayIDOrUUIDOrSlugConverter, "identifier")

urlpatterns = [
    # Display ID only
    path("invoices/<display_id:id>/", InvoiceDetailView.as_view()),

    # Display ID or UUID
    path("items/<display_id_or_uuid:id>/", ItemView.as_view()),

    # Display ID or slug
    path("products/<display_id_or_slug:id>/", ProductView.as_view()),

    # Any identifier format
    path("resources/<identifier:id>/", ResourceView.as_view()),
]

Regex Constants

The following regex constants are available for use in custom converters:

django_display_ids.converters.DISPLAY_ID_REGEX

Regex pattern for display IDs: [a-z]{1,16}_[0-9A-Za-z]{22}

django_display_ids.converters.SLUG_REGEX

Django’s default slug regex pattern: [-a-zA-Z0-9_]+

This is imported from Django’s SlugConverter and can be overridden via the DISPLAY_IDS["SLUG_REGEX"] setting.