python-ulid-django

ULID (Universally Unique Lexicographically Sortable Identifier) support for Django.

This package uses the ULID type implemented by python-ulid.

This package is heavily inspired by django-ulid. The reason I'm reinventing the wheel is that I want to use python-ulid's ULID implementation.

Requirements

Python 3.12+ and Django 5.2+.

Usage

Installation

pip install python-ulid-django

Model Field

You can then add ULIDField to your Django model just like other fields.

Example:

from django.contrib.auth.models import AbstractUser
from ulid import ULID
from ulid_django.models import ULIDField


class User(AbstractUser):
    id = ULIDField(primary_key=True, default=ULID, editable=False)

Form Field

ULIDField supplies a matching form field automatically, so a ModelForm needs no extra wiring. Use it directly when building a plain form:

from django import forms
from ulid_django.forms import ULIDField


class LookupForm(forms.Form):
    item_id = ULIDField()

It cleans to a ULID and accepts three input widths: the 26-character canonical representation, a 32-character hex string, and a 36-character UUID string.

URL Converter

A URL converter is also provided.

from django.urls import path, register_converter
from ulid import ULID
from ulid_django.converters import ULIDConverter


def user_detail_view(request, user_id):
    assert isinstance(user_id, ULID)
    ...


register_converter(ULIDConverter, "ulid")

urlpatterns = [
    path("user/<ulid:user_id>/", user_detail_view),
    ...,
]

Development

Prerequisite: uv and just

Environment setup: just dev-setup

Run linters: just lint

Test: just test

Test against every supported Python version: just test-all