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.5

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.5
File Size Uploaded Provenance Actions
fraiseql_uuid-0.1.5.tar.gz 54.2 kB With provenance Details for fraiseql_uuid-0.1.5.tar.gz

Built distribution (wheel)

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

Total release size: 64.8 kB

Release files / fraiseql_uuid-0.1.5.tar.gz

Download URL fraiseql_uuid-0.1.5.tar.gz
Size 54.2 kB
Tags Source
SHA-256 checksum
How to use checksums
e9b2be796fecc563276d824ee594e8bf3b09e6af018a200e69d9d855b9016202
BLAKE2b-256 checksum
How to use checksums
0858c683efece0528db39523a0532b4d35e0cde6e900d2b1a560abaa58ecf439
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 7, 2026.

Transparency log

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

Download URL fraiseql_uuid-0.1.5-py3-none-any.whl
Size 10.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3c88e3f60bb65ab977e9e91a1bb034af2f63d960bc0563ccbb9b23043df49dcc
BLAKE2b-256 checksum
How to use checksums
a721960f7a608194aa24c5854e8e05646f06c4f977b410c462cc25756b66f3bf
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 7, 2026.

Transparency log

Security for fraiseql-uuid 0.1.5

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.5.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 7, 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