uuid-backport 0.1.0.post1

Backport of Python 3.14 UUID module (RFC 9562) for Python 3.9+

uuid-backport

Backport of Python 3.14's UUID module (RFC 9562) for Python 3.9+

Features

• UUID v6: Reordered timestamp UUID for improved database locality
• UUID v7: Timestamp-based UUID with millisecond precision and monotonicity
• UUID v8: Custom 3-block UUID for application-specific use cases
• NIL/MAX UUID: Special UUID constants defined in RFC 9562

Installation

pip install uuid-backport

Or with uv:

uv add uuid-backport

Usage

UUID v6 - Improved Database Locality

from uuid_backport import uuid6

# Similar to UUID v1 but with reordered timestamp fields
id = uuid6()
print(id)  # Example: 1ef4a7c8-9b2c-6000-8000-0242ac120002

# Maintains time-based ordering
ids = [uuid6() for _ in range(5)]
assert ids == sorted(ids)

UUID v7 - Timestamp + Monotonicity

from uuid_backport import uuid7

# Millisecond-precision timestamp with guaranteed monotonicity
id1 = uuid7()
id2 = uuid7()
assert id1 < id2  # Always true, even within the same millisecond

# Ideal for distributed systems
ids = [uuid7() for _ in range(1000)]
assert ids == sorted(ids)

UUID v8 - Custom UUID

from uuid_backport import uuid8

# Create UUID with custom 3-block structure
# a: 48-bit, b: 12-bit, c: 62-bit
custom_id = uuid8(
    a=0x123456789ABC,      # Application prefix
    b=0xDEF,                # Type identifier
    c=0x123456789ABCDEF0    # Sequence number
)

# Generate random UUID v8
random_id = uuid8()

NIL/MAX UUID

from uuid_backport import NIL, MAX

print(NIL)  # 00000000-0000-0000-0000-000000000000
print(MAX)  # ffffffff-ffff-ffff-ffff-ffffffffffff

# Useful for validation
def is_valid_uuid(uuid):
    return NIL < uuid < MAX

Compatibility with Standard Library

import uuid
from uuid_backport import uuid6, uuid7, uuid8, NIL, MAX

# Use standard library for v1-v5
v1 = uuid.uuid1()
v4 = uuid.uuid4()
v5 = uuid.uuid5(uuid.NAMESPACE_DNS, 'example.com')

# Use backport for v6-v8
v6 = uuid6()
v7 = uuid7()
v8 = uuid8()

# All are instances of uuid.UUID
assert isinstance(v6, uuid.UUID)
assert isinstance(v7, uuid.UUID)

UUID Version Selection Guide

• UUID v1/v6: MAC address + timestamp based

  • v1: Legacy, poor database locality
  • v6: Improved v1, optimized for database indexes

• UUID v4: Fully random

  • Most widely used
  • No inherent ordering
  • Extremely low collision probability

• UUID v7: Timestamp + random + monotonic

  • Recommended for most new projects
  • Time-ordered and sortable
  • Ideal for distributed systems
  • Efficient database indexing

• UUID v8: Custom structure

  • For specialized requirements only
  • Application-specific optimizations

Development

Setup

git clone https://github.com/line1029/uuid-backport.git
cd uuid-backport

# Install test dependencies
uv sync --group test

# Install lint tools
uv sync --group lint

Testing

# Test with current Python version
uv run pytest tests/ -v

# Test with all Python versions (3.9-3.13) + lint + typing
tox

# Test specific environment
tox -e py311          # Python 3.11 only
tox -e lint           # Linting only
tox -e typing         # Type checking only

Code Quality

# Run linting and format checking
tox -e lint

# Run type checking
tox -e typing

# Or run directly
uv run ruff check .
uv run ruff format --check .
uv run mypy .

Formatting

uv run ruff format .

License

MIT License - Based on Python 3.14's uuid module

References

• RFC 9562 - Universally Unique IDentifiers (UUID)
• Python 3.14 What's New
• Python uuid Module Documentation