pUUID - Prefixed UUIDs for Python with Pydantic & SQLAlchemy support.

pUUID - Prefixed UUIDs for Python

Raw UUIDs like 019b9a2e-9856-... are annoying to work with. They provide no context in logs, traces or bug reports and offer no safe guards against accidental ID swapping in code. pUUID provides prefixed UUIDs for python with minimal overhead and strong type guarantees.

Features

• Human-Friendly: Immediate context with prefixed UUIDs (e.g. user_019b9a2e...).
• Strong type guarantees: Prevent passing of a CustomerID into a payment_id field.
• Standard Compliant: Supports all UUID versions from RFC 9562.
• Pydantic support. (Read more)
• FastAPI support (just use Pydantic as you want)
• SQLAlchemy support. (Read more)

Installation

# NOTE: pUUID requires python 3.14+
pip install pUUID

# For Pydantic support:
pip install 'pUUID[pydantic]'

# For SQLAlchemy support:
pip install 'pUUID[sqlalchemy]'

Usage

Define a domain-specific ID by inheriting from a versioned base:

from typing import Literal
from puuid import PUUIDv7

class UserUUID(PUUIDv7[Literal["user"]]): ...

# Generation
uid = UserUUID.factory()
print(uid) # user_019b956e-ed25-70db-9d0a-0f30fb9047c2

# Deserialization
uid2 = UserUUID.from_string("user_019b956e-ed25-70db-9d0a-0f30fb9047c2")

Resources

• Online documentation
• API Reference
• Changelog
• Coverage Report
• How to contribute

Alternatives

If you only need lexicographically sortable IDs and want to build the SQLAlchemy support yourself, these two projects might be for you:

• TypeID - pUUID supports all UUID versions because it uses Python’s standard uuid library for UUID generation, while TypeID uses a custom generator that comes with performance improvements but only supports UUIDv7. TypeID does not support SQLAlchemy out of the box.
• UPID - UPID implements a modified version of the ULID standard, which was designed before UUIDv7 was available. UPID does not support SQLAlchemy out of the box.

Sponsor

Digon.IO provides dev & data end-to-end consulting for SMEs and software companies. (Website) (Technical Blog)

The sponsor logo is the property of Digon.IO GmbH. Standard trademark and copyright restrictions apply to any use outside this repository.

License

• Library source code: Licensed under LGPLv3.