tigrbl-orm 0.4.5.dev4__py3-none-any.whl → 0.4.5.dev6__py3-none-any.whl

tigrbl_orm/orm/mixins/__init__.py

@@ -16,7 +16,15 @@ from .utils import (
     CRUD_IO,
     RO_IO,
 )
-from .principals import GUIDPk, TenantColumn, UserColumn, OrgColumn, Principal
+from .principals import (
+    GUIDPk,
+    UUID7Pk,
+    ULIDPk,
+    TenantColumn,
+    UserColumn,
+    OrgColumn,
+    Principal,
+)
 from .bound import OwnerBound, UserBound
 from .lifecycle import (
     Created,
@@ -59,6 +67,8 @@ __all__ = [
     "CRUD_IO",
     "RO_IO",
     "GUIDPk",
+    "UUID7Pk",
+    "ULIDPk",
     "TenantColumn",
     "UserColumn",
     "OrgColumn",

tigrbl_orm/orm/mixins/principals.py

@@ -1,12 +1,78 @@
 from __future__ import annotations
 
+import re
+from secrets import randbits
+from time import time_ns
+
+from pydantic import UUID7
+from sqlalchemy import String, TypeDecorator
+
 from tigrbl.specs import ColumnSpec, F, S, acol
 from tigrbl._spec.storage_spec import ForeignKeySpec
 from tigrbl.types import PgUUID, UUID, declarative_mixin, declared_attr, uuid4, Mapped
+from tigrbl_core._spec.datatypes import DataTypeSpec
 
 from .utils import _infer_schema, uuid_example, CRUD_IO, RO_IO
 
 
+_ULID_ALPHABET = "0123456789ABCDEFGHJKMNPQRSTVWXYZ"
+_ULID_PATTERN = rf"^[0-7][{_ULID_ALPHABET}]{{25}}$"
+
+
+def _new_ulid() -> str:
+    timestamp_ms = time_ns() // 1_000_000
+    value = (timestamp_ms << 80) | randbits(80)
+    return "".join(
+        _ULID_ALPHABET[(value >> shift) & 31] for shift in range(125, -1, -5)
+    )
+
+
+def _new_uuid7() -> UUID:
+    timestamp_ms = time_ns() // 1_000_000
+    # RFC 9562 §5.7: 48-bit time, version, 12 random bits, variant, 62 random bits.
+    return UUID(
+        int=(timestamp_ms << 80)
+        | (7 << 76)
+        | (randbits(12) << 64)
+        | (2 << 62)
+        | randbits(62)
+    )
+
+
+class _UUID7Type(TypeDecorator[UUID]):
+    impl = PgUUID
+    cache_ok = True
+
+    @property
+    def python_type(self) -> type[UUID]:
+        return UUID
+
+    def process_bind_param(self, value: UUID | str | None, dialect) -> UUID | None:
+        if value is None:
+            return None
+        if isinstance(value, str):
+            value = UUID(value)
+        if not isinstance(value, UUID) or value.version != 7:
+            raise ValueError("Expected an RFC 9562 UUID version 7")
+        return value
+
+
+class _ULIDString(TypeDecorator[str]):
+    impl = String(26)
+    cache_ok = True
+
+    @property
+    def python_type(self) -> type[str]:
+        return str
+
+    def process_bind_param(self, value: str | None, dialect) -> str | None:
+        if value is not None and (
+            not isinstance(value, str) or re.fullmatch(_ULID_PATTERN, value) is None
+        ):
+            raise ValueError("Expected a canonical 26-character uppercase ULID")
+        return value
+
+
 @declarative_mixin
 class GUIDPk:
     """Universal surrogate primary key."""
@@ -24,6 +90,54 @@ class GUIDPk:
     )
 
 
+@declarative_mixin
+class UUID7Pk:
+    """Add a UUIDv7 primary key generated on insert."""
+
+    id: Mapped[UUID] = acol(
+        spec=ColumnSpec(
+            storage=S(
+                type_=_UUID7Type(),
+                primary_key=True,
+                nullable=False,
+                default=_new_uuid7,
+            ),
+            field=F(
+                py_type=UUID7,
+                constraints={"examples": ["017f22e2-79b0-7cc3-98c4-dc0c0c07398f"]},
+            ),
+            io=RO_IO,
+            datatype=DataTypeSpec(logical_name="uuid"),
+        )
+    )
+
+
+@declarative_mixin
+class ULIDPk:
+    """Add a canonical ULID string primary key, generated on insert."""
+
+    id: Mapped[str] = acol(
+        spec=ColumnSpec(
+            storage=S(
+                type_=_ULIDString(),
+                primary_key=True,
+                nullable=False,
+                default=_new_ulid,
+            ),
+            field=F(
+                py_type=str,
+                constraints={
+                    "min_length": 26,
+                    "max_length": 26,
+                    "pattern": _ULID_PATTERN,
+                },
+            ),
+            io=RO_IO,
+            datatype=DataTypeSpec(logical_name="ulid"),
+        )
+    )
+
+
 @declarative_mixin
 class TenantColumn:
     """Adds ``tenant_id`` with a schema-qualified FK to ``<schema>.tenants.id``."""
@@ -91,6 +205,8 @@ class Principal:
 
 __all__ = [
     "GUIDPk",
+    "UUID7Pk",
+    "ULIDPk",
     "TenantColumn",
     "UserColumn",
     "OrgColumn",

tigrbl_orm/orm/mixins/utils.py

@@ -1,19 +1,7 @@
 from __future__ import annotations
 
-import datetime as dt
-
 from tigrbl.specs import IO
-from tigrbl.types import UUID
-
-
-def tzutcnow() -> dt.datetime:
-    """Return an aware UTC ``datetime``."""
-    return dt.datetime.now(dt.timezone.utc)
-
-
-def tzutcnow_plus_day() -> dt.datetime:
-    """Return an aware UTC ``datetime`` one day in the future."""
-    return tzutcnow() + dt.timedelta(days=1)
+from tigrbl.types import UUID, tzutcnow, tzutcnow_plus_day
 
 
 def _infer_schema(cls, default: str = "public") -> str:

{tigrbl_orm-0.4.5.dev4.dist-info → tigrbl_orm-0.4.5.dev6.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: tigrbl-orm
-Version: 0.4.5.dev4
+Version: 0.4.5.dev6
 Summary: SQLAlchemy ORM tables, mixins, columns, model helpers, and persistence primitives for Tigrbl applications.
 License: Apache License
                                     Version 2.0, January 2004
@@ -230,7 +230,7 @@ Project-URL: Discord, https://discord.gg/K4YTAPapjR
 Project-URL: Homepage, https://github.com/tigrbl/tigrbl
 Project-URL: Issues, https://github.com/tigrbl/tigrbl/issues
 Project-URL: Organization, https://github.com/tigrbl
-Project-URL: Repository, https://github.com/tigrbl/tigrbl/tree/master/pkgs/core/tigrbl_orm
+Project-URL: Repository, https://github.com/tigrbl/tigrbl/tree/master/pkgs/30_orm/tigrbl_orm
 Description-Content-Type: text/markdown
 
 <div align="center">
@@ -240,7 +240,7 @@ Description-Content-Type: text/markdown
 <a href="https://pypi.org/project/tigrbl-orm/"><img src="https://img.shields.io/pypi/v/tigrbl-orm?label=PyPI" alt="PyPI version for tigrbl-orm"/></a>
 <a href="https://pypi.org/project/tigrbl-orm/"><img src="https://static.pepy.tech/badge/tigrbl-orm" alt="Downloads for tigrbl-orm"/></a>
 <a href="https://discord.gg/K4YTAPapjR"><img src="https://img.shields.io/badge/Discord-Join%20chat-5865F2?logo=discord&logoColor=white" alt="Discord community for tigrbl-orm"/></a>
-<a href="https://github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_orm/README.md"><img src="https://hits.sh/github.com/tigrbl/tigrbl/blob/master/pkgs/core/tigrbl_orm/README.md.svg?label=hits" alt="Repository hits for tigrbl-orm README"/></a>
+<a href="https://github.com/tigrbl/tigrbl/blob/master/pkgs/30_orm/tigrbl_orm/README.md"><img src="https://hits.sh/github.com/tigrbl/tigrbl/blob/master/pkgs/30_orm/tigrbl_orm/README.md.svg?label=hits" alt="Repository hits for tigrbl-orm README"/></a>
 <a href="LICENSE"><img src="https://img.shields.io/badge/license-Apache%202.0-525252" alt="Apache 2.0 license"/></a>
 <a href="pyproject.toml"><img src="https://img.shields.io/badge/python-3.10%20%7C%203.11%20%7C%203.12%20%7C%203.13%20%7C%203.14-3776ab" alt="Python versions 3.10 | 3.11 | 3.12 | 3.13 | 3.14 for tigrbl-orm"/></a>
 <a href="https://github.com/tigrbl/tigrbl/blob/master/docs/README.md"><img src="https://img.shields.io/badge/workspace-core-1f6feb" alt="Workspace group for tigrbl-orm"/></a>
@@ -264,7 +264,7 @@ Framework maintainers, extension authors, and advanced users composing Tigrbl fr
 
 ## Where does tigrbl-orm fit?
 
-`tigrbl-orm` lives at `pkgs/core/tigrbl_orm` and serves a focused layer in the split Tigrbl framework.
+`tigrbl-orm` lives at `pkgs/30_orm/tigrbl_orm` and serves a focused layer in the split Tigrbl framework.
 
 ## How does tigrbl-orm work?
 
@@ -286,7 +286,7 @@ pip install tigrbl-orm
 | Surface | Value |
 |---|---|
 | PyPI package | [`tigrbl-orm`](https://pypi.org/project/tigrbl-orm/) |
-| Repository path | [`pkgs/core/tigrbl_orm`](https://github.com/tigrbl/tigrbl/tree/master/pkgs/core/tigrbl_orm) |
+| Repository path | [`pkgs/30_orm/tigrbl_orm`](https://github.com/tigrbl/tigrbl/tree/master/pkgs/30_orm/tigrbl_orm) |
 | Python import root | `tigrbl_orm` |
 | Console scripts | none declared |
 | Entry points | none declared |
@@ -395,7 +395,6 @@ Choose `tigrbl-orm` when the quick-answer table matches your use case. Choose [`
 - [Package catalog](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/PACKAGE_CATALOG.md)
 - [Package layout](https://github.com/tigrbl/tigrbl/blob/master/docs/developer/PACKAGE_LAYOUT.md)
 - [Current target](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/CURRENT_TARGET.md)
-- [Current state](https://github.com/tigrbl/tigrbl/blob/master/docs/conformance/CURRENT_STATE.md)
 - [SSOT registry](https://github.com/tigrbl/tigrbl/blob/master/.ssot/registry.json)
 - [Release workflow](https://github.com/tigrbl/tigrbl/actions/workflows/publish.yml)
 
@@ -403,7 +402,7 @@ Choose `tigrbl-orm` when the quick-answer table matches your use case. Choose [`
 
 - Community: [Discord](https://discord.gg/K4YTAPapjR).
 - Issues: [GitHub Issues](https://github.com/tigrbl/tigrbl/issues).
-- Repository: [pkgs/core/tigrbl_orm](https://github.com/tigrbl/tigrbl/tree/master/pkgs/core/tigrbl_orm).
+- Repository: [pkgs/30_orm/tigrbl_orm](https://github.com/tigrbl/tigrbl/tree/master/pkgs/30_orm/tigrbl_orm).
 
 ## Package-local Boundary
 
@@ -414,7 +413,7 @@ This README is the package-local distribution entry point for `tigrbl-orm`. It a
 - Package status: governed package in the `tigrbl/tigrbl` workspace.
 - Governance source: [SSOT registry](https://github.com/tigrbl/tigrbl/blob/master/.ssot/registry.json).
 - Release evidence: [publish workflow](https://github.com/tigrbl/tigrbl/actions/workflows/publish.yml) validates package builds, tests, GitHub release assets, and PyPI publication for managed packages.
-- Local certification guard: `pkgs/core/tigrbl_tests/tests/unit/test_package_badges_and_notices.py` verifies every package README keeps the Discord badge, Apache 2.0 badge, explicit Python-version badge, `LICENSE`, and `NOTICE`.
+- Local certification guard: `pkgs/97_tests/tigrbl_tests/tests/unit/test_package_badges_and_notices.py` verifies every package README keeps the Discord badge, Apache 2.0 badge, explicit Python-version badge, `LICENSE`, and `NOTICE`.
 - Scope note: this README documents the package boundary. Runtime feature support remains governed by `.ssot/` entities and the conformance docs linked below.
 
 ## License

{tigrbl_orm-0.4.5.dev4.dist-info → tigrbl_orm-0.4.5.dev6.dist-info}/RECORD

@@ -1,6 +1,6 @@
 tigrbl_orm/orm/__init__.py,sha256=oQVk8swfAop9oNNC-WVf0_OdAmXRf7EjqIQfW7w_fLA,61
 tigrbl_orm/orm/mixins/_RowBound.py,sha256=ORIMeEzD5zPRuI3QY010cMlvkDUIyiEIkBcqpaa8aKU,3058
-tigrbl_orm/orm/mixins/__init__.py,sha256=X1qWzDcr_wSNNOo7JJ_hpHGR_tO1HsqDF7vHh6N-xNs,1914
+tigrbl_orm/orm/mixins/__init__.py,sha256=wmSv9phPIegc337t_v4bMFCv6b9uY8VYH6RIPhnAh1Q,1993
 tigrbl_orm/orm/mixins/bootstrappable.py,sha256=4lWg5n1j4TV7u-J_aMQj3ZIFqILMS2eU-DpcgkFjOJI,3881
 tigrbl_orm/orm/mixins/bound.py,sha256=VcNM8r4Gr1MpK1SMdHnWKEoKpBX--HBZOv4wSIrhnDM,1348
 tigrbl_orm/orm/mixins/edges.py,sha256=7D0hK5slbvs6r4kLB5ZvBqWjDTBcDS7yYnM9gj4KBlc,862
@@ -12,10 +12,10 @@ tigrbl_orm/orm/mixins/locks.py,sha256=Z4k5WuE-wiyV6CxPuczfOT84vqgZzYc0vieUUX7Bxs
 tigrbl_orm/orm/mixins/markers.py,sha256=EVeAPXw6h6m9HtMrtrkCz_uxug5cdP7za_AFSmKOWnc,214
 tigrbl_orm/orm/mixins/operations.py,sha256=8pYhuiLtkrb81WREzp6VzXYq7KwEP4FXrtBKt4zNJtA,1843
 tigrbl_orm/orm/mixins/ownable.py,sha256=4enszRMvgpWwzEJSPVhDpQIfQ06kXY6CJG2mgQ9Iwfg,11328
-tigrbl_orm/orm/mixins/principals.py,sha256=JdX6s0HtVLoN87XBln4ML2qLjKc9T2a-637A4U6jrvk,2758
+tigrbl_orm/orm/mixins/principals.py,sha256=FGsVJHtZuCZFaHEcIJ9D0fLvKVhH0l0dLrptCF-Yh8A,5819
 tigrbl_orm/orm/mixins/tenant_bound.py,sha256=2i0Da-wD07-ELcaXl68pv-e4JLV-CvHik_tnrDbF-uk,10119
 tigrbl_orm/orm/mixins/upsertable.py,sha256=_fj006p2d5Qz6-8T88Yq3SQJiRYFSC0W_m0XN9FmMjc,4010
-tigrbl_orm/orm/mixins/utils.py,sha256=B8ZvAh55ng8B6fz72XyC3oBbBDkynyt8jnWyXzchiw4,1265
+tigrbl_orm/orm/mixins/utils.py,sha256=c3eaICdGYIKdFCc2Qjxu-7jb8NThiOg2036EDVgKguI,997
 tigrbl_orm/orm/tables/__init__.py,sha256=OtKDm6V5je8DJ6M-9Xq_rZUSBm0l5fpFo9JKO6a1Boo,1972
 tigrbl_orm/orm/tables/_base.py,sha256=tYNTG35sQ-4HQBJXfCm98ZSNL9BDTU-Cu8iYvSau5wM,163
 tigrbl_orm/orm/tables/audit.py,sha256=5hVeFUQQ7pw0NzZcf5Mz1yzZKNdAf5xYVfr0sq1CAQo,1434
@@ -26,8 +26,8 @@ tigrbl_orm/orm/tables/rbac.py,sha256=zv8XBC2vrQLqxjN3ilA7TyCNJnnBp6jlQs1yqylw0qs
 tigrbl_orm/orm/tables/status.py,sha256=eYY_13BJScrZN2VK6s_QG0Jlk0vrysKbINVR28GfklE,3596
 tigrbl_orm/orm/tables/tenant.py,sha256=yTDrGktHqp7EE3dtE959SAqKOY6guNUbt-H__FQvmIM,460
 tigrbl_orm/orm/tables/user.py,sha256=ROdfbnF4Nta96pY__sir-2CpSoGJp_YappmyDYJ_Nso,807
-tigrbl_orm-0.4.5.dev4.dist-info/METADATA,sha256=BuV4tDvK7qAbtjRu-JeFV0zVBq7OpTxmJmVjpjpH5xg,23959
-tigrbl_orm-0.4.5.dev4.dist-info/WHEEL,sha256=eY7nduwzv-ldUxpzbRlxwvC693Hg6PX8bWDjEHjZ_dk,88
-tigrbl_orm-0.4.5.dev4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-tigrbl_orm-0.4.5.dev4.dist-info/licenses/NOTICE,sha256=EvJMTshzsWz43LiK-DeN2ZuLtrP49cxvlrFlJ8F_buc,221
-tigrbl_orm-0.4.5.dev4.dist-info/RECORD,,
+tigrbl_orm-0.4.5.dev6.dist-info/METADATA,sha256=3xn9i8y6lYzdsahpFawlCT-YO4wx09fkCB_Zp5YAoH8,23881
+tigrbl_orm-0.4.5.dev6.dist-info/WHEEL,sha256=L-WvLdSBvJWHXv5zrQxDvNRnIgoBzLUpcbuiw19KCuQ,88
+tigrbl_orm-0.4.5.dev6.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+tigrbl_orm-0.4.5.dev6.dist-info/licenses/NOTICE,sha256=EvJMTshzsWz43LiK-DeN2ZuLtrP49cxvlrFlJ8F_buc,221
+tigrbl_orm-0.4.5.dev6.dist-info/RECORD,,

{tigrbl_orm-0.4.5.dev4.dist-info → tigrbl_orm-0.4.5.dev6.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: poetry-core 2.4.1
+Generator: poetry-core 2.5.0
 Root-Is-Purelib: true
 Tag: py3-none-any