Skip to content

Logo: pUUID - Prefixed UUIDs for Python

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

repository mirror License: LGPLv3 pipeline status coverage report Code style: black Imports: isort

pkgversion versionsupport Downloads Week Downloads Total

pUUID - Prefixed UUIDs for Python

Features

  • Human-Friendly: user_550e8400... instead of just randomness.
  • Standard Compliant: Supports all UUID versions from RFC 9562.
  • Pydantic support. (Read more)
  • SQLAlchemy support. (Read more)
  • Strong type guarantees!

Motivation

Standard UUIDs like 019b9a2e-9856-737c-955e-c4e4523a2176 are great for machines but difficult for humans. pUUID implements prefixed identifiers (e.g., user_019b9a2e...) to provide:

  • Semantics & Context: Immediately identify the resource type in logs, URLs, and databases without additional lookups.
  • Error Prevention: Strong type guarantees prevent passing a customer_id into a payment_id field.
  • Improved UX: Identifiers are easier to discuss, double-click to select (thanks to the underscore separator), and debug.

Installation

pip install pUUID

# 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"]]):
    _prefix = "user"

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

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

Resources

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.

Digon.IO GmbH Logo

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.