Skip to main content

fraiseql-uuid

UUID v4 compliant pattern with encoded metadata for the FraiseQL ecosystem.

Quality Gate codecov Python 3.12+ License: MIT

Status: ✅ v0.1.0 Production-Ready | 🔒 Type-Safe (ty strict) | 📋 SBOM Available

Installation

pip install fraiseql-uuid

Quick Start

from fraiseql_uuid import Pattern, UUIDGenerator

# Create pattern
pattern = Pattern()

# Generate UUID
gen = UUIDGenerator(pattern, table_code="012345")
uuid = gen.generate(instance=1)
print(uuid)  # → "01234521-0000-4000-8000-000000000001"

# Decode UUID
decoded = pattern.decode(uuid)
print(decoded["table_code"])  # → "012345"
print(decoded["instance"])  # → 1

UUID Format

Code notation: {table:6}{type:2}-{func:4}-4{scen:3}-8{scen:1}{test:2}-{inst:12} Docs notation: TTTTTTDD-FFFF-4SSS-8STT-IIIIIIIIIIII

Components

Symbol Component Length Default Description
T table_code 6 - Table/Entity code (required)
D seed_dir 2 21 Seed directory (21=general, 22=mutation, 23=query)
F function 4 0 Function code
4 version 1 4 UUID v4 version bit (fixed)
S scenario 4 0 Test scenario (split 3+1 for v4 compliance)
8 variant 1 8 UUID variant bit (fixed)
T test_case 2 0 Test case number
I instance 12 - Instance number (required)

Example

01234521-0042-4100-8015-000000000001
│      │ │  │ │  │ │  │ └─ instance: 1
│      │ │  │ │  │ └─── test_case: 15
│      │ │  │ │  └───── scenario: 1000 (split as 100 + 0)
│      │ │  │ └──────── variant: 8
│      │ │  └─────────── version: 4
│      │ └────────────── function: 42
│      └──────────────── table: 012345
└─────────────────────── seed_dir: 21

Usage Examples

Basic Generation

from fraiseql_uuid import Pattern

pattern = Pattern()

# Minimal - uses defaults
uuid = pattern.generate(table_code="012345", instance=1)
# → "01234521-0000-4000-8000-000000000001"

# Full parameters
uuid = pattern.generate(
    table_code="123456",
    seed_dir=22,  # mutation tests
    function=42,
    scenario=1000,
    test_case=5,
    instance=999,
)
# → "12345622-0042-4100-8005-000000000999"

Batch Generation

from fraiseql_uuid import Pattern, UUIDGenerator

pattern = Pattern()
gen = UUIDGenerator(pattern, table_code="012345", scenario=1000)

# Generate batch
uuids = gen.generate_batch(count=5)
# → ["01234521-0000-4100-8000-000000000001",
#    "01234521-0000-4100-8000-000000000002",
#    ...]

Decoding

from fraiseql_uuid import Pattern

pattern = Pattern()
decoded = pattern.decode("01234521-0042-4100-8015-000000000001")

print(decoded["table_code"])  # → "012345"
print(decoded["seed_dir"])  # → 21
print(decoded["function"])  # → 42
print(decoded["scenario"])  # → 1000
print(decoded["test_case"])  # → 15
print(decoded["instance"])  # → 1

Validation

from fraiseql_uuid import Pattern, UUIDValidator

pattern = Pattern()
validator = UUIDValidator(pattern)

result = validator.validate("01234521-0000-4000-8000-000000000001")
print(result.valid)  # → True

result = validator.validate("not-a-uuid")
print(result.valid)  # → False
print(result.error)  # → "Invalid UUID format: not-a-uuid"

Caching

from fraiseql_uuid import UUIDCache

cache = UUIDCache()

# Store generated UUIDs
cache.set("users", instance=1, uuid="01234521-0000-4000-8000-000000000001")
cache.set("users", instance=2, uuid="01234521-0000-4000-8000-000000000002")

# Retrieve from cache
uuid = cache.get("users", instance=1)
print(uuid)  # → "01234521-0000-4000-8000-000000000001"

CLI Usage

# Generate UUID
fraiseql-uuid generate --table 012345 --instance 1

# Generate batch
fraiseql-uuid generate --table 012345 --count 10

# Decode UUID
fraiseql-uuid decode 01234521-0000-4000-8000-000000000001

# Validate UUID
fraiseql-uuid validate 01234521-0000-4000-8000-000000000001

UUID v4 Compliance

All generated UUIDs are UUID v4 compliant:

  • Version bit 4 in the correct position
  • Variant bit 8 in the correct position
  • Can be used anywhere standard UUIDs are expected
  • Compatible with database UUID columns
  • Parseable by standard UUID libraries
import uuid

# Works with standard UUID library
generated = pattern.generate(table_code="012345", instance=1)
parsed = uuid.UUID(generated)
print(parsed.version)  # → 4
print(parsed.variant)  # → uuid.RFC_4122

Development

# Install for development
git clone https://github.com/fraiseql/fraiseql-seed
cd fraiseql-seed
uv sync

# Run tests
uv run pytest packages/fraiseql-uuid/tests -v

# Type check
uv run ty check packages/fraiseql-uuid/src

License

MIT

Metadata

Release files for fraiseql-uuid 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for fraiseql-uuid 0.1.4
File Size Uploaded Provenance Actions
fraiseql_uuid-0.1.4.tar.gz 54.0 kB With provenance Details for fraiseql_uuid-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for fraiseql-uuid 0.1.4
File Interpreter ABI Platform Actions
fraiseql_uuid-0.1.4-py3-none-any.whl Python 3 none any Details for fraiseql_uuid-0.1.4-py3-none-any.whl

Total release size: 64.6 kB

Release files / fraiseql_uuid-0.1.4.tar.gz

Download URL fraiseql_uuid-0.1.4.tar.gz
Size 54.0 kB
Tags Source
SHA-256 checksum
How to use checksums
2bb0a3dcfb2c3cebe647bdac32c3f17b2d0ff9ff76951d5974d23c6a3f30ca69
BLAKE2b-256 checksum
How to use checksums
157bbf0f2f31bc032f486656b56243ba2652ed0ed65afaade6a9b873c298cc07
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Release files / fraiseql_uuid-0.1.4-py3-none-any.whl

Download URL fraiseql_uuid-0.1.4-py3-none-any.whl
Size 10.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
0ae94979959dc8157ab956ca0b7372ab73874ae48b3d49c9aef46a7dc75e18b3
BLAKE2b-256 checksum
How to use checksums
e853b22bd6d7715d58d8a8a6a1115862a08d258fb0883f5472dd8b7635dcf8f1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.14

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

Security for fraiseql-uuid 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for fraiseql_uuid-0.1.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 5, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page