wexample-orm 1.4.5__tar.gz → 2.0.0__tar.gz

{wexample_orm-1.4.5 → wexample_orm-2.0.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: wexample-orm
-Version: 1.4.5
+Version: 2.0.0
 Summary: Provides SQLAlchemy ORM abstractions — base entity, repository, session factory, and repository manager — with PostgreSQL-first defaults via psycopg
 Author-Email: weeger <contact@wexample.com>
 License: MIT
@@ -12,6 +12,7 @@ Requires-Python: >=3.10
 Requires-Dist: attrs>=23.1.0
 Requires-Dist: psycopg[binary]>=3.2
 Requires-Dist: sqlalchemy<3,>=2
+Requires-Dist: uuid-utils>=0.11
 Requires-Dist: wexample-helpers>=20.5.0
 Provides-Extra: dev
 Requires-Dist: pytest; extra == "dev"
@@ -20,7 +21,7 @@ Description-Content-Type: text/markdown
 
 # orm
 
-Version: 1.4.5
+Version: 2.0.0
 
 `wexample-orm` provides four SQLAlchemy base classes — `AbstractEntity`, `AbstractRepository`, `AbstractSessionFactory`, and `AbstractRepositoriesManager` — that impose a Doctrine-style repository pattern on top of SQLAlchemy 2. It targets Python developers in the Wexample stack who connect to PostgreSQL via psycopg and want a consistent, opinionated foundation without rewriting engine, session, and repository boilerplate for every project.
 
@@ -289,6 +290,7 @@ The suite includes packages for configuration management, file handling, prompts
 - attrs: >=23.1.0
 - psycopg: >=3.2
 - sqlalchemy: <3,>=2
+- uuid-utils: >=0.11
 - wexample-helpers: >=20.5.0
 
 ## Versioning & Compatibility Policy

{wexample_orm-1.4.5 → wexample_orm-2.0.0}/README.md

@@ -1,6 +1,6 @@
 # orm
 
-Version: 1.4.5
+Version: 2.0.0
 
 `wexample-orm` provides four SQLAlchemy base classes — `AbstractEntity`, `AbstractRepository`, `AbstractSessionFactory`, and `AbstractRepositoriesManager` — that impose a Doctrine-style repository pattern on top of SQLAlchemy 2. It targets Python developers in the Wexample stack who connect to PostgreSQL via psycopg and want a consistent, opinionated foundation without rewriting engine, session, and repository boilerplate for every project.
 
@@ -269,6 +269,7 @@ The suite includes packages for configuration management, file handling, prompts
 - attrs: >=23.1.0
 - psycopg: >=3.2
 - sqlalchemy: <3,>=2
+- uuid-utils: >=0.11
 - wexample-helpers: >=20.5.0
 
 ## Versioning & Compatibility Policy

{wexample_orm-1.4.5 → wexample_orm-2.0.0}/pyproject.toml

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-orm"
-version = "1.4.5"
+version = "2.0.0"
 description = "Provides SQLAlchemy ORM abstractions — base entity, repository, session factory, and repository manager — with PostgreSQL-first defaults via psycopg"
 authors = [
     { name = "weeger", email = "contact@wexample.com" },
@@ -21,6 +21,7 @@ dependencies = [
     "attrs>=23.1.0",
     "psycopg[binary]>=3.2",
     "sqlalchemy>=2,<3",
+    "uuid-utils>=0.11",
     "wexample-helpers>=20.5.0",
 ]
 

wexample_orm-2.0.0/src/wexample_orm/entity/abstract_entity.py

@@ -0,0 +1,40 @@
+from __future__ import annotations
+
+from uuid import UUID
+
+from sqlalchemy import Uuid
+from sqlalchemy.orm import Mapped, as_declarative, declared_attr, mapped_column
+from wexample_helpers.helper.string import string_to_snake_case
+
+
+@as_declarative()
+class AbstractEntity:
+    """Common ancestor for every wex-managed SQLAlchemy entity.
+
+    Imposes a single convention for the primary key across all projects: a
+    UUIDv7, as the PHP side gives every entity (symfony-helpers
+    ``AbstractEntity``), so the same table is read and written from PHP and
+    Python alike.
+
+    The id is generated here, not by the database: an entity written from
+    Python has its id before the flush, and its timestamp prefix keeps the
+    creation order. ``Uuid`` is a native ``UUID`` on PostgreSQL and a
+    ``CHAR(32)`` on SQLite, so in-memory sessions used by
+    ``wexample_orm.testing.in_memory_session`` keep working as they are.
+    """
+
+    __abstract__ = True
+
+    @declared_attr
+    def __tablename__(cls) -> str:
+        return cls.get_entity_name()
+
+    @classmethod
+    def get_entity_name(cls) -> str:
+        return string_to_snake_case(cls.__name__)
+
+    @declared_attr
+    def id(cls) -> Mapped[UUID]:
+        from uuid_utils.compat import uuid7
+
+        return mapped_column(Uuid, primary_key=True, default=uuid7)

{wexample_orm-1.4.5 → wexample_orm-2.0.0}/src/wexample_orm/generator/entity_generator.py

@@ -124,10 +124,11 @@ class EntityGenerator(BaseClass):
                     self._attribute(
                         foreign_key,
                         "object",
-                        f"mapped_column(Integer, {constraint}nullable={nullable})",
+                        f"mapped_column(Uuid, {constraint}nullable={nullable})",
                     )
                 )
-                imports.add("Integer")
+                # Every id is a UUID (AbstractEntity), whatever entity it points to.
+                imports.add("Uuid")
                 field_names.add(foreign_key)
 
             if target is not None:

{wexample_orm-1.4.5 → wexample_orm-2.0.0}/src/wexample_orm/helper/doctrine.py

@@ -21,6 +21,8 @@ def doctrine_type_to_sqlalchemy(orm: dict[str, Any]) -> tuple[str, set[str]]:
     the names it needs imported from `sqlalchemy`."""
     doctrine_type = str(orm.get("type") or "string").lower()
 
+    if doctrine_type == "uuid":
+        return "Uuid", {"Uuid"}
     if doctrine_type in {"integer", "int", "smallint", "bigint"}:
         return "Integer", {"Integer"}
     if doctrine_type in {"string", "guid"}:

{wexample_orm-1.4.5 → wexample_orm-2.0.0}/src/wexample_orm/import_export/entity_importer.py

@@ -35,7 +35,7 @@ class EntityImporter(BaseClass):
     """
 
     assign_ids: bool = public_field(
-        description="Give every entity a sequential id, for graphs that never reach a database.",
+        description="Give every entity its UUID at once, for graphs that never reach a database.",
         default=False,
     )
     entity_types: list[type[AbstractEntity]] = public_field(
@@ -159,7 +159,9 @@ class EntityImporter(BaseClass):
         entity = entity_type()
         self._entities.append(entity)
         if self.assign_ids:
-            entity.id = len(self._entities)
+            from uuid_utils.compat import uuid7
+
+            entity.id = uuid7()
         return entity
 
     def _find_column_attribute(self, mapper: Mapper, name: str) -> str | None:

{wexample_orm-1.4.5 → wexample_orm-2.0.0}/src/wexample_orm/repository/abstract_repository.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 from typing import TYPE_CHECKING, Any
+from uuid import UUID
 
 from wexample_helpers.classes.base_class import BaseClass
 from wexample_helpers.classes.field import public_field
@@ -23,9 +24,13 @@ class AbstractRepository(BaseClass):
     def get_entity_type(cls) -> type[AbstractEntity]:
         cls._raise_not_implemented_error()
 
-    def find(self, entity_id: int) -> AbstractEntity | None:
+    def find(self, entity_id: UUID | str) -> AbstractEntity | None:
         if self.session is None:
             return None
+        # Ids arrive as text as often as not (message bodies, command lines,
+        # API payloads); the Uuid column only binds UUID objects.
+        if not isinstance(entity_id, UUID):
+            entity_id = UUID(str(entity_id))
         return self.session.get(self.get_entity_type(), entity_id)
 
     def find_one_by(self, filter_clause: Any) -> AbstractEntity | None:

{wexample_orm-1.4.5 → wexample_orm-2.0.0}/tests/test_abstract.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+from uuid import UUID
+
 import pytest
-from sqlalchemy import BigInteger
+from sqlalchemy import Uuid
 from sqlalchemy.orm import Mapped, mapped_column
 
 from wexample_orm.common.abstract_repositories_manager import (
@@ -28,18 +30,20 @@ def test_entity_name_is_snake_case_of_class_name() -> None:
 # ---------------------------------------------------------------------------
 
 
-def test_id_is_bigint_identity_style() -> None:
-    """Every entity gets a BIGINT autoincrement PK with no Sequence.
-
-    Production schema (PG) uses ``GENERATED BY DEFAULT AS IDENTITY`` — the
-    DB owns id allocation, SQLAlchemy doesn't carry a Sequence default.
-    """
+def test_id_is_a_uuid_v7_given_by_python() -> None:
+    """Every entity gets a UUID primary key, generated on the Python side: the
+    same identity the PHP entities have, available before the flush."""
     id_col = User.__table__.c.id
-    assert isinstance(id_col.type, BigInteger)
-    assert id_col.default is None  # no SQLAlchemy-managed Sequence
-    assert id_col.autoincrement is True
+    assert isinstance(id_col.type, Uuid)
     assert id_col.primary_key is True
 
+    with in_memory_session(AbstractEntity) as session:
+        user = User(name="alice")
+        session.add(user)
+        session.flush()
+        assert isinstance(user.id, UUID)
+        assert user.id.version == 7
+
 
 def test_manager_caches_repository_instances() -> None:
     with in_memory_session(AbstractEntity) as session:
@@ -86,12 +90,15 @@ def test_repository_without_session_raises_on_query() -> None:
 def test_save_and_find_roundtrip() -> None:
     with in_memory_session(AbstractEntity) as session:
         repo = UserRepository(session=session)
-        repo.save(User(name="alice"))
+        alice = User(name="alice")
+        repo.save(alice)
         repo.save(User(name="bob"))
 
-        first = repo.find(1)
+        first = repo.find(alice.id)
         assert first is not None
         assert first.name == "alice"
+        # The text form, as ids come from messages and payloads.
+        assert repo.find(str(alice.id)) is first
 
 
 class User(AbstractEntity):

{wexample_orm-1.4.5 → wexample_orm-2.0.0}/tests/test_entity_importer.py

@@ -1,7 +1,9 @@
 from __future__ import annotations
 
+from uuid import UUID
+
 import pytest
-from sqlalchemy import JSON, DateTime, ForeignKey, Integer, String
+from sqlalchemy import JSON, DateTime, ForeignKey, String, Uuid
 from sqlalchemy.orm import Mapped, mapped_column, relationship
 
 from wexample_orm.entity.abstract_entity import AbstractEntity
@@ -157,9 +159,9 @@ class ImpFolder(AbstractEntity):
         "ImpFile", foreign_keys="ImpFile.folder_id", back_populates="folder"
     )
     owner = relationship("ImpOwner", foreign_keys="ImpFolder.owner_id")
-    owner_id: Mapped[int] = mapped_column(Integer, ForeignKey("imp_owner.id"), nullable=True)
+    owner_id: Mapped[UUID] = mapped_column(Uuid, ForeignKey("imp_owner.id"), nullable=True)
     pinned = relationship("ImpFile", foreign_keys="ImpFolder.pinned_id")
-    pinned_id: Mapped[int] = mapped_column(Integer, ForeignKey("imp_file.id"), nullable=True)
+    pinned_id: Mapped[UUID] = mapped_column(Uuid, ForeignKey("imp_file.id"), nullable=True)
     title: Mapped[str] = mapped_column(String(64), nullable=True)
 
 
@@ -169,9 +171,9 @@ class ImpFile(AbstractEntity):
     folder = relationship(
         "ImpFolder", foreign_keys="ImpFile.folder_id", back_populates="files"
     )
-    folder_id: Mapped[int] = mapped_column(Integer, ForeignKey("imp_folder.id"), nullable=True)
+    folder_id: Mapped[UUID] = mapped_column(Uuid, ForeignKey("imp_folder.id"), nullable=True)
     name: Mapped[str] = mapped_column(String(64), nullable=True)
-    target: Mapped[int] = mapped_column(Integer, nullable=True)
+    target: Mapped[UUID] = mapped_column(Uuid, nullable=True)
 
 
 class ImpTag(AbstractEntity):
@@ -180,9 +182,9 @@ class ImpTag(AbstractEntity):
 
 class ImpFolderTag(AbstractEntity):
     folder = relationship("ImpFolder", foreign_keys="ImpFolderTag.folder_id")
-    folder_id: Mapped[int] = mapped_column(Integer, ForeignKey("imp_folder.id"), nullable=True)
+    folder_id: Mapped[UUID] = mapped_column(Uuid, ForeignKey("imp_folder.id"), nullable=True)
     tag = relationship("ImpTag", foreign_keys="ImpFolderTag.tag_id")
-    tag_id: Mapped[int] = mapped_column(Integer, ForeignKey("imp_tag.id"), nullable=True)
+    tag_id: Mapped[UUID] = mapped_column(Uuid, ForeignKey("imp_tag.id"), nullable=True)
 
 
 ENTITY_TYPES = [ImpOwner, ImpFolder, ImpFile, ImpTag, ImpFolderTag]

wexample_orm-1.4.5/src/wexample_orm/entity/abstract_entity.py

@@ -1,41 +0,0 @@
-from __future__ import annotations
-
-from sqlalchemy import BigInteger, Integer
-from sqlalchemy.orm import Mapped, as_declarative, declared_attr, mapped_column
-from wexample_helpers.helper.string import string_to_snake_case
-
-
-@as_declarative()
-class AbstractEntity:
-    """Common ancestor for every wex-managed SQLAlchemy entity.
-
-    Imposes a single convention for the primary key across all projects:
-
-      ``id BIGINT GENERATED BY DEFAULT AS IDENTITY`` on PostgreSQL — modern
-      SQL standard (PG ≥ 10) and Doctrine's default when it owns the
-      schema, so the same table works seamlessly from PHP and Python.
-
-    A ``with_variant(Integer, "sqlite")`` is bolted on for tests: SQLite
-    only auto-increments a column declared as ``INTEGER PRIMARY KEY``
-    (ROWID alias), not ``BIGINT``. Production stays BIGINT, in-memory
-    sessions used by ``wexample_orm.testing.in_memory_session`` keep
-    working without per-project gymnastics.
-    """
-
-    __abstract__ = True
-
-    @declared_attr
-    def __tablename__(cls) -> str:
-        return cls.get_entity_name()
-
-    @classmethod
-    def get_entity_name(cls) -> str:
-        return string_to_snake_case(cls.__name__)
-
-    @declared_attr
-    def id(cls) -> Mapped[int]:
-        return mapped_column(
-            BigInteger().with_variant(Integer(), "sqlite"),
-            primary_key=True,
-            autoincrement=True,
-        )