fraiseql-uuid 0.1.1__tar.gz

fraiseql_uuid-0.1.1/.gitignore

@@ -0,0 +1,67 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# Virtual environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# IDEs
+.vscode/
+.idea/
+*.swp
+*.swo
+*~
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.tox/
+.nox/
+
+# Type checking
+.mypy_cache/
+.dmypy.json
+dmypy.json
+.pyre/
+.pytype/
+.ty_cache/
+
+# Linting
+.ruff_cache/
+
+# uv
+# uv.lock is committed for reproducible installs
+
+# Development planning
+.phases/
+
+# OS
+.DS_Store
+Thumbs.db
+node_modules/

fraiseql_uuid-0.1.1/PKG-INFO

@@ -0,0 +1,235 @@
+Metadata-Version: 2.4
+Name: fraiseql-uuid
+Version: 0.1.1
+Summary: Structured UUID pattern library with encode/decode support
+Project-URL: Homepage, https://github.com/fraiseql/fraiseql-seed
+Project-URL: Documentation, https://fraiseql-seed.readthedocs.io
+Project-URL: Repository, https://github.com/fraiseql/fraiseql-seed
+Project-URL: Bug Tracker, https://github.com/fraiseql/fraiseql-seed/issues
+Author-email: Lionel Hamayon <lionel.hamayon@evolution-digitale.fr>
+License: MIT
+Keywords: database,encoding,pattern,testing,uuid
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.11
+Requires-Dist: pydantic>=2.5.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: cli
+Requires-Dist: click>=8.1.0; extra == 'cli'
+Requires-Dist: rich>=13.7.0; extra == 'cli'
+Description-Content-Type: text/markdown
+
+# fraiseql-uuid
+
+UUID v4 compliant pattern with encoded metadata for the FraiseQL ecosystem.
+
+[![Quality Gate](https://github.com/fraiseql/fraiseql-seed/actions/workflows/quality-gate.yml/badge.svg)](https://github.com/fraiseql/fraiseql-seed/actions/workflows/quality-gate.yml)
+[![codecov](https://codecov.io/gh/fraiseql/fraiseql-seed/branch/main/graph/badge.svg?flag=fraiseql-uuid)](https://codecov.io/gh/fraiseql/fraiseql-seed?flag=fraiseql-uuid)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Status**: ✅ v0.1.0 Production-Ready | 🔒 Type-Safe (ty strict) | 📋 SBOM Available
+
+## Installation
+
+```bash
+pip install fraiseql-uuid
+```
+
+## Quick Start
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```bash
+# 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
+
+```python
+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
+
+```bash
+# 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

fraiseql_uuid-0.1.1/README.md

@@ -0,0 +1,209 @@
+# fraiseql-uuid
+
+UUID v4 compliant pattern with encoded metadata for the FraiseQL ecosystem.
+
+[![Quality Gate](https://github.com/fraiseql/fraiseql-seed/actions/workflows/quality-gate.yml/badge.svg)](https://github.com/fraiseql/fraiseql-seed/actions/workflows/quality-gate.yml)
+[![codecov](https://codecov.io/gh/fraiseql/fraiseql-seed/branch/main/graph/badge.svg?flag=fraiseql-uuid)](https://codecov.io/gh/fraiseql/fraiseql-seed?flag=fraiseql-uuid)
+[![Python 3.12+](https://img.shields.io/badge/python-3.12%20%7C%203.13-blue.svg)](https://www.python.org/downloads/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+**Status**: ✅ v0.1.0 Production-Ready | 🔒 Type-Safe (ty strict) | 📋 SBOM Available
+
+## Installation
+
+```bash
+pip install fraiseql-uuid
+```
+
+## Quick Start
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```python
+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
+
+```bash
+# 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
+
+```python
+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
+
+```bash
+# 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

fraiseql_uuid-0.1.1/pyproject.toml

@@ -0,0 +1,50 @@
+# fraiseql-uuid - Structured UUID Pattern Library
+
+[project]
+name = "fraiseql-uuid"
+version = "0.1.1"
+description = "Structured UUID pattern library with encode/decode support"
+authors = [
+    {name = "Lionel Hamayon", email = "lionel.hamayon@evolution-digitale.fr"}
+]
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.11"
+keywords = ["uuid", "pattern", "encoding", "database", "testing"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Python Modules",
+    "Topic :: Database",
+]
+
+# Package dependencies
+dependencies = [
+    "pyyaml>=6.0",
+    "pydantic>=2.5.0",
+]
+
+[project.optional-dependencies]
+cli = [
+    "click>=8.1.0",
+    "rich>=13.7.0",
+]
+
+[project.urls]
+Homepage = "https://github.com/fraiseql/fraiseql-seed"
+Documentation = "https://fraiseql-seed.readthedocs.io"
+Repository = "https://github.com/fraiseql/fraiseql-seed"
+"Bug Tracker" = "https://github.com/fraiseql/fraiseql-seed/issues"
+
+[project.scripts]
+fraiseql-uuid = "fraiseql_uuid.cli.main:cli [cli]"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/fraiseql_uuid"]

fraiseql_uuid-0.1.1/src/fraiseql_uuid/__init__.py

@@ -0,0 +1,22 @@
+"""
+fraiseql-uuid - Structured UUID Pattern Library
+
+UUID v4 compliant pattern encoding/decoding for FraiseQL ecosystem.
+"""
+
+from fraiseql_uuid.cache import UUIDCache
+from fraiseql_uuid.decoder import UUIDDecoder
+from fraiseql_uuid.generator import UUIDGenerator
+from fraiseql_uuid.patterns import Pattern
+from fraiseql_uuid.validator import UUIDValidator, ValidationResult
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Pattern",
+    "UUIDCache",
+    "UUIDDecoder",
+    "UUIDGenerator",
+    "UUIDValidator",
+    "ValidationResult",
+]

fraiseql_uuid-0.1.1/src/fraiseql_uuid/cache.py

@@ -0,0 +1,37 @@
+"""UUID generation cache for performance."""
+
+
+class UUIDCache:
+    """Cache for generated UUIDs."""
+
+    def __init__(self) -> None:
+        """Initialize cache."""
+        self._cache: dict[str, dict[int, str]] = {}
+
+    def get(self, table: str, instance: int) -> str | None:
+        """Get cached UUID.
+
+        Args:
+            table: Table name
+            instance: Instance number
+
+        Returns:
+            Cached UUID or None
+        """
+        return self._cache.get(table, {}).get(instance)
+
+    def set(self, table: str, instance: int, uuid: str) -> None:
+        """Set cached UUID.
+
+        Args:
+            table: Table name
+            instance: Instance number
+            uuid: UUID to cache
+        """
+        if table not in self._cache:
+            self._cache[table] = {}
+        self._cache[table][instance] = uuid
+
+    def clear(self) -> None:
+        """Clear cache."""
+        self._cache.clear()

fraiseql_uuid-0.1.1/src/fraiseql_uuid/cli/__init__.py

@@ -0,0 +1 @@
+"""CLI package for fraiseql-uuid."""