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

wexample_orm-2.0.1/PKG-INFO

@@ -0,0 +1,117 @@
+Metadata-Version: 2.1
+Name: wexample-orm
+Version: 2.0.1
+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
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Project-URL: homepage, https://github.com/wexample/python-orm
+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.6.0
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-cov; extra == "dev"
+Description-Content-Type: text/markdown
+
+# orm
+
+Version: 2.0.1
+
+Provides SQLAlchemy ORM abstractions — base entity, repository, session factory, and repository manager — with PostgreSQL-first defaults via psycopg
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Install](#install)
+- [Tests](#tests)
+- [Roadmap](#roadmap)
+- [Status Compatibility](#status-compatibility)
+- [Useful Links](#useful-links)
+
+Python Doctrine inspired ORM
+
+## Installation
+
+```bash
+pip install wexample-orm
+```
+
+Requires Python >=3.10.
+
+## Tests
+
+This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
+
+### Installation
+
+First, install the required testing dependencies:
+```bash
+.venv/bin/python -m pip install pytest pytest-cov
+```
+
+### Basic Usage
+
+Run all tests with coverage:
+```bash
+.venv/bin/python -m pytest --cov --cov-report=html
+```
+
+### Common Commands
+```bash
+# Run tests with coverage for a specific module
+.venv/bin/python -m pytest --cov=your_module
+
+# Show which lines are not covered
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
+
+# Generate an HTML coverage report
+.venv/bin/python -m pytest --cov=your_module --cov-report=html
+
+# Combine terminal and HTML reports
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
+
+# Run specific test file with coverage
+.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
+```
+
+### Viewing HTML Reports
+
+After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
+
+### Coverage Threshold
+
+To enforce a minimum coverage percentage:
+```bash
+.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
+```
+
+This will cause the test suite to fail if coverage drops below 80%.
+
+## Known Limitations & Roadmap
+
+Current limitations and planned features are tracked in the GitHub issues.
+
+See the [project roadmap](https://github.com/wexample/python-orm/issues) for upcoming features and improvements.
+
+## Status & Compatibility
+
+**Maturity**: Production-ready
+
+**Python Support**: >=3.10
+
+**OS Support**: Linux, macOS, Windows
+
+**Status**: Actively maintained
+
+## Useful Links
+
+- **Homepage**: https://github.com/wexample/python-orm
+- **Issue Tracker**: https://github.com/wexample/python-orm/issues
+- **Discussions**: https://github.com/wexample/python-orm/discussions
+- **PyPI**: [pypi.org/project/wexample-orm](https://pypi.org/project/wexample-orm/)

wexample_orm-2.0.1/README.md

@@ -0,0 +1,96 @@
+# orm
+
+Version: 2.0.1
+
+Provides SQLAlchemy ORM abstractions — base entity, repository, session factory, and repository manager — with PostgreSQL-first defaults via psycopg
+
+## Table of Contents
+
+- [Introduction](#introduction)
+- [Install](#install)
+- [Tests](#tests)
+- [Roadmap](#roadmap)
+- [Status Compatibility](#status-compatibility)
+- [Useful Links](#useful-links)
+
+Python Doctrine inspired ORM
+
+## Installation
+
+```bash
+pip install wexample-orm
+```
+
+Requires Python >=3.10.
+
+## Tests
+
+This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
+
+### Installation
+
+First, install the required testing dependencies:
+```bash
+.venv/bin/python -m pip install pytest pytest-cov
+```
+
+### Basic Usage
+
+Run all tests with coverage:
+```bash
+.venv/bin/python -m pytest --cov --cov-report=html
+```
+
+### Common Commands
+```bash
+# Run tests with coverage for a specific module
+.venv/bin/python -m pytest --cov=your_module
+
+# Show which lines are not covered
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
+
+# Generate an HTML coverage report
+.venv/bin/python -m pytest --cov=your_module --cov-report=html
+
+# Combine terminal and HTML reports
+.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
+
+# Run specific test file with coverage
+.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
+```
+
+### Viewing HTML Reports
+
+After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
+
+### Coverage Threshold
+
+To enforce a minimum coverage percentage:
+```bash
+.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
+```
+
+This will cause the test suite to fail if coverage drops below 80%.
+
+## Known Limitations & Roadmap
+
+Current limitations and planned features are tracked in the GitHub issues.
+
+See the [project roadmap](https://github.com/wexample/python-orm/issues) for upcoming features and improvements.
+
+## Status & Compatibility
+
+**Maturity**: Production-ready
+
+**Python Support**: >=3.10
+
+**OS Support**: Linux, macOS, Windows
+
+**Status**: Actively maintained
+
+## Useful Links
+
+- **Homepage**: https://github.com/wexample/python-orm
+- **Issue Tracker**: https://github.com/wexample/python-orm/issues
+- **Discussions**: https://github.com/wexample/python-orm/discussions
+- **PyPI**: [pypi.org/project/wexample-orm](https://pypi.org/project/wexample-orm/)

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

@@ -6,7 +6,7 @@ build-backend = "pdm.backend"
 
 [project]
 name = "wexample-orm"
-version = "1.4.5"
+version = "2.0.1"
 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,7 +21,8 @@ dependencies = [
     "attrs>=23.1.0",
     "psycopg[binary]>=3.2",
     "sqlalchemy>=2,<3",
-    "wexample-helpers>=20.5.0",
+    "uuid-utils>=0.11",
+    "wexample-helpers>=20.6.0",
 ]
 
 [project.readme]

wexample_orm-2.0.1/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.1}/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.1}/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.1}/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.1}/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.1}/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.1}/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/PKG-INFO

@@ -1,347 +0,0 @@
-Metadata-Version: 2.1
-Name: wexample-orm
-Version: 1.4.5
-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
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Project-URL: homepage, https://github.com/wexample/python-orm
-Requires-Python: >=3.10
-Requires-Dist: attrs>=23.1.0
-Requires-Dist: psycopg[binary]>=3.2
-Requires-Dist: sqlalchemy<3,>=2
-Requires-Dist: wexample-helpers>=20.5.0
-Provides-Extra: dev
-Requires-Dist: pytest; extra == "dev"
-Requires-Dist: pytest-cov; extra == "dev"
-Description-Content-Type: text/markdown
-
-# orm
-
-Version: 1.4.5
-
-`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.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quickstart](#quickstart)
-- [Tests](#tests)
-- [Architecture](#architecture)
-- [Integration in the Suite](#integration-in-the-suite)
-- [Dependencies](#dependencies)
-- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
-- [License](#license)
-- [About us](#about-us)
-- [Known Limitations & Roadmap](#known-limitations--roadmap)
-- [Status & Compatibility](#status--compatibility)
-- [Useful Links](#useful-links)
-- [Migration Notes](#migration-notes)
-
-## Installation
-
-```bash
-pip install wexample-orm
-```
-
-Requires Python >=3.10.
-
-## Quickstart
-
-Install from PyPI:
-
-```bash
-pip install wexample-orm
-```
-
-### Define an entity and a repository
-
-Subclass `AbstractEntity` to get a BIGINT primary key and a table name derived automatically from the class name (`User` → `user`). Subclass `AbstractRepository` and declare which entity it covers:
-
-```python
-from sqlalchemy.orm import Mapped, mapped_column
-from wexample_orm.entity.abstract_entity import AbstractEntity
-from wexample_orm.repository.abstract_repository import AbstractRepository
-
-class User(AbstractEntity):
-    name: Mapped[str] = mapped_column()
-
-class UserRepository(AbstractRepository):
-    @classmethod
-    def get_entity_type(cls) -> type[AbstractEntity]:
-        return User
-```
-
-### Connect and persist (PostgreSQL)
-
-`AbstractSessionFactory` wraps `create_engine` and `sessionmaker`. Pass a SQLAlchemy URL and call `create_session()`:
-
-```python
-from wexample_orm.session.abstract_session_factory import AbstractSessionFactory
-
-factory = AbstractSessionFactory(dsn="postgresql+psycopg://user:password@localhost/mydb")
-User.metadata.create_all(factory.get_engine())
-
-session = factory.create_session()
-repo = UserRepository(session=session)
-
-user = repo.save(User(name="alice"))
-print(user.id)    # 1 — assigned by the database
-
-found = repo.find(user.id)
-print(found.name) # alice
-```
-
-`save()` calls `session.commit()` by default. Pass `flush=False` to add the row without committing, or `refresh=True` to reload the instance from the database after commit.
-
-### In-memory session for local development and tests
-
-`wexample_orm.testing.in_memory_session` creates a disposable SQLite engine — no PostgreSQL required. It creates all tables on entry and disposes the engine on exit:
-
-```python
-from wexample_orm.testing import in_memory_session
-
-with in_memory_session(AbstractEntity) as session:
-    repo = UserRepository(session=session)
-    repo.save(User(name="alice"))
-
-    found = repo.find(1)
-    print(found.name)  # alice
-```
-
-## Tests
-
-This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
-
-### Installation
-
-First, install the required testing dependencies:
-```bash
-.venv/bin/python -m pip install pytest pytest-cov
-```
-
-### Basic Usage
-
-Run all tests with coverage:
-```bash
-.venv/bin/python -m pytest --cov --cov-report=html
-```
-
-### Common Commands
-```bash
-# Run tests with coverage for a specific module
-.venv/bin/python -m pytest --cov=your_module
-
-# Show which lines are not covered
-.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
-
-# Generate an HTML coverage report
-.venv/bin/python -m pytest --cov=your_module --cov-report=html
-
-# Combine terminal and HTML reports
-.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
-
-# Run specific test file with coverage
-.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
-```
-
-### Viewing HTML Reports
-
-After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
-
-### Coverage Threshold
-
-To enforce a minimum coverage percentage:
-```bash
-.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
-```
-
-This will cause the test suite to fail if coverage drops below 80%.
-
-## Architecture
-
-The package (`wexample-orm`) is a thin layer on top of SQLAlchemy 2.x. It defines four abstract base classes that projects subclass, two domain exceptions, and a test helper. Nothing is concrete out of the box: the library ships patterns, not implementations.
-
-### Entity
-
-src/wexample_orm/entity/abstract_entity.py
-
-`AbstractEntity` is the SQLAlchemy declarative base for the whole stack. It is decorated with `@as_declarative()`, so every subclass automatically participates in the same `MetaData` registry.
-
-Two conventions are fixed here and nowhere else:
-
-- **Table name** — `__tablename__` is set by `get_entity_name()`, which calls `string_to_snake_case(cls.__name__)`. A class named `UserAccount` maps to the table `user_account` with no annotation needed.
-- **Primary key** — `id` is a `BigInteger` with `autoincrement=True`. A `with_variant(Integer(), "sqlite")` is bolted on so that the same declaration works in the in-memory SQLite sessions used during testing (SQLite only auto-increments a column typed `INTEGER PRIMARY KEY`, not `BIGINT`).
-
-### Repository
-
-src/wexample_orm/repository/abstract_repository.py
-
-`AbstractRepository` is the data-access object. It holds one `session` field (default `None`) and exposes:
-
-- `get_entity_type()` — abstract classmethod every concrete repository must implement; returns the `AbstractEntity` subclass it owns.
-- `find(id)` — delegates to `session.get(EntityType, id)`; returns `None` when no session is set.
-- `find_one_by(filter_clause)` — `query().filter(clause).first()`.
-- `query()` — returns a raw `session.query(EntityType)`; calls `_require_session()` first.
-- `save(entity, flush=True, refresh=False)` — `session.add` then `session.commit`; optionally refreshes from DB.
-- `_require_session()` — raises `RepositorySessionMissingException` when `session` is `None`; called by any method that cannot function without it.
-
-A repository can be constructed standalone (session-less `find` returns `None`, everything else raises) or injected with a session directly.
-
-### Session factory
-
-src/wexample_orm/session/abstract_session_factory.py
-
-`AbstractSessionFactory` builds and caches a SQLAlchemy engine and sessionmaker from a DSN string. The engine is created on first call to `get_engine()` and reused thereafter; the sessionmaker is created on first call to `create_session()`.
-
-Public API:
-
-- `dsn` — SQLAlchemy URL, e.g. `postgresql+psycopg://user:pwd@host/db` or `sqlite:///:memory:`.
-- `engine_options` / `session_options` — dicts forwarded verbatim to `create_engine()` and `sessionmaker()`.
-- `create_session()` — returns a fresh `Session` from the cached maker.
-- `get_engine()` — returns the cached engine (creates it on first call).
-- `dispose()` — calls `engine.dispose()` and resets both caches; intended for test teardown.
-- `_engine_kwargs()` / `_session_kwargs()` — overridable hooks; by default they just copy the option dicts.
-
-The session factory is decoupled from the rest: nothing in the repository or manager imports it. Callers create a session through it and pass it in manually.
-
-### Repositories manager
-
-src/wexample_orm/common/abstract_repositories_manager.py
-
-`AbstractRepositoriesManager` is a registry that maps entity types to repository instances. It is the single entry point when a project has multiple repositories and wants to avoid constructing them by hand.
-
-Fields:
-
-- `repository_classes` — the list of repository classes the manager may instantiate.
-- `session` — the SQLAlchemy session shared across every repository the manager creates.
-- `_instances` — private cache (`entity_type → repository instance`); a repository is built once and reused.
-
-Methods:
-
-- `get(entity_type)` — looks up the cache; on miss, walks `repository_classes` looking for the class whose `get_entity_type()` matches, instantiates it with `session=self.session`, stores it, and returns it. Raises `UnknownRepositoryException` if nothing matches.
-- `get_by_table_name(table_name)` — same lookup but keyed on `entity_type.get_entity_name()` (the snake-case table name).
-- `get_classes()` — returns a copy of `repository_classes`.
-
-### Call path
-
-A typical read goes: caller asks the manager for a repository (`manager.get(User)`) → manager instantiates `UserRepository(session=session)` if not cached → caller calls `repo.find(42)` → repository calls `session.get(User, 42)` → SQLAlchemy issues the SQL against the engine that the session factory built.
-
-A write follows the same path through `repo.save(entity)`, which calls `session.add` then `session.commit`.
-
-### Exceptions
-
-src/wexample_orm/exception/unknown_repository_exception.py
-
-`UnknownRepositoryException` (error code `ORM_UNKNOWN_REPOSITORY`) is raised by the manager when `get()` receives an entity type for which no repository class is registered.
-
-src/wexample_orm/exception/repository_session_missing_exception.py
-
-`RepositorySessionMissingException` (error code `ORM_REPOSITORY_SESSION_MISSING`) is raised by `AbstractRepository._require_session()` when a session-dependent method is called on a repository that has `session=None`.
-
-Both extend `UndefinedException` from `wexample-helpers` and carry a structured `data` dict alongside the human-readable message.
-
-### Testing helper
-
-src/wexample_orm/testing/sqlite.py
-
-`in_memory_session(declarative_base)` is a context manager that creates a fresh SQLite in-memory engine, runs `metadata.create_all()` on it, yields a session, then closes the session and disposes the engine. The `declarative_base` argument must be the `@as_declarative()`-decorated class whose `MetaData` holds the tables to create — in practice `AbstractEntity` or a project subclass of it.
-
-```python
-from wexample_orm.testing import in_memory_session
-from wexample_orm.entity.abstract_entity import AbstractEntity
-
-with in_memory_session(AbstractEntity) as session:
-    repo = UserRepository(session=session)
-    repo.save(User(name="alice"))
-    assert repo.find(1).name == "alice"
-```
-
-The helper is excluded from the published wheel (`tool.setuptools.packages.find` omits `wexample_orm.testing*`) and is only available in a development install.
-
-### Source layout
-
-```
-src/wexample_orm/
-    __init__.py                        # re-exports the three main abstractions
-    entity/abstract_entity.py          # declarative base + PK convention
-    repository/abstract_repository.py  # data-access object
-    session/abstract_session_factory.py# engine + sessionmaker cache
-    common/abstract_repositories_manager.py  # repository registry
-    exception/
-        unknown_repository_exception.py
-        repository_session_missing_exception.py
-    testing/sqlite.py                  # in-memory SQLite helper
-```
-
-## Integration in the Suite
-
-This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
-
-### Related Packages
-
-The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
-
-## Dependencies
-
-- attrs: >=23.1.0
-- psycopg: >=3.2
-- sqlalchemy: <3,>=2
-- wexample-helpers: >=20.5.0
-
-## Versioning & Compatibility Policy
-
-Wexample packages follow **Semantic Versioning** (SemVer):
-
-- **MAJOR**: Breaking changes
-- **MINOR**: New features, backward compatible
-- **PATCH**: Bug fixes, backward compatible
-
-We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-Free to use in both personal and commercial projects.
-
-## About us
-
-[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
-
-This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.
-
-Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
-
-Built and maintained by [Romain Weeger](https://weeger.io).
-
-## Known Limitations & Roadmap
-
-Current limitations and planned features are tracked in the GitHub issues.
-
-See the [project roadmap](https://github.com/wexample/python-orm/issues) for upcoming features and improvements.
-
-## Status & Compatibility
-
-**Maturity**: Production-ready
-
-**Python Support**: >=3.10
-
-**OS Support**: Linux, macOS, Windows
-
-**Status**: Actively maintained
-
-## Useful Links
-
-- **Homepage**: https://github.com/wexample/python-orm
-- **Issue Tracker**: https://github.com/wexample/python-orm/issues
-- **Discussions**: https://github.com/wexample/python-orm/discussions
-- **PyPI**: [pypi.org/project/wexample-orm](https://pypi.org/project/wexample-orm/)
-
-## Migration Notes
-
-When upgrading between major versions, refer to the migration guides in the documentation.
-
-Breaking changes are clearly documented with upgrade paths and examples.

wexample_orm-1.4.5/README.md

@@ -1,327 +0,0 @@
-# orm
-
-Version: 1.4.5
-
-`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.
-
-## Table of Contents
-
-- [Installation](#installation)
-- [Quickstart](#quickstart)
-- [Tests](#tests)
-- [Architecture](#architecture)
-- [Integration in the Suite](#integration-in-the-suite)
-- [Dependencies](#dependencies)
-- [Versioning & Compatibility Policy](#versioning--compatibility-policy)
-- [License](#license)
-- [About us](#about-us)
-- [Known Limitations & Roadmap](#known-limitations--roadmap)
-- [Status & Compatibility](#status--compatibility)
-- [Useful Links](#useful-links)
-- [Migration Notes](#migration-notes)
-
-## Installation
-
-```bash
-pip install wexample-orm
-```
-
-Requires Python >=3.10.
-
-## Quickstart
-
-Install from PyPI:
-
-```bash
-pip install wexample-orm
-```
-
-### Define an entity and a repository
-
-Subclass `AbstractEntity` to get a BIGINT primary key and a table name derived automatically from the class name (`User` → `user`). Subclass `AbstractRepository` and declare which entity it covers:
-
-```python
-from sqlalchemy.orm import Mapped, mapped_column
-from wexample_orm.entity.abstract_entity import AbstractEntity
-from wexample_orm.repository.abstract_repository import AbstractRepository
-
-class User(AbstractEntity):
-    name: Mapped[str] = mapped_column()
-
-class UserRepository(AbstractRepository):
-    @classmethod
-    def get_entity_type(cls) -> type[AbstractEntity]:
-        return User
-```
-
-### Connect and persist (PostgreSQL)
-
-`AbstractSessionFactory` wraps `create_engine` and `sessionmaker`. Pass a SQLAlchemy URL and call `create_session()`:
-
-```python
-from wexample_orm.session.abstract_session_factory import AbstractSessionFactory
-
-factory = AbstractSessionFactory(dsn="postgresql+psycopg://user:password@localhost/mydb")
-User.metadata.create_all(factory.get_engine())
-
-session = factory.create_session()
-repo = UserRepository(session=session)
-
-user = repo.save(User(name="alice"))
-print(user.id)    # 1 — assigned by the database
-
-found = repo.find(user.id)
-print(found.name) # alice
-```
-
-`save()` calls `session.commit()` by default. Pass `flush=False` to add the row without committing, or `refresh=True` to reload the instance from the database after commit.
-
-### In-memory session for local development and tests
-
-`wexample_orm.testing.in_memory_session` creates a disposable SQLite engine — no PostgreSQL required. It creates all tables on entry and disposes the engine on exit:
-
-```python
-from wexample_orm.testing import in_memory_session
-
-with in_memory_session(AbstractEntity) as session:
-    repo = UserRepository(session=session)
-    repo.save(User(name="alice"))
-
-    found = repo.find(1)
-    print(found.name)  # alice
-```
-
-## Tests
-
-This project uses `pytest` for testing and `pytest-cov` for code coverage analysis.
-
-### Installation
-
-First, install the required testing dependencies:
-```bash
-.venv/bin/python -m pip install pytest pytest-cov
-```
-
-### Basic Usage
-
-Run all tests with coverage:
-```bash
-.venv/bin/python -m pytest --cov --cov-report=html
-```
-
-### Common Commands
-```bash
-# Run tests with coverage for a specific module
-.venv/bin/python -m pytest --cov=your_module
-
-# Show which lines are not covered
-.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing
-
-# Generate an HTML coverage report
-.venv/bin/python -m pytest --cov=your_module --cov-report=html
-
-# Combine terminal and HTML reports
-.venv/bin/python -m pytest --cov=your_module --cov-report=term-missing --cov-report=html
-
-# Run specific test file with coverage
-.venv/bin/python -m pytest tests/test_file.py --cov=your_module --cov-report=term-missing
-```
-
-### Viewing HTML Reports
-
-After generating an HTML report, open `htmlcov/index.html` in your browser to view detailed line-by-line coverage information.
-
-### Coverage Threshold
-
-To enforce a minimum coverage percentage:
-```bash
-.venv/bin/python -m pytest --cov=your_module --cov-fail-under=80
-```
-
-This will cause the test suite to fail if coverage drops below 80%.
-
-## Architecture
-
-The package (`wexample-orm`) is a thin layer on top of SQLAlchemy 2.x. It defines four abstract base classes that projects subclass, two domain exceptions, and a test helper. Nothing is concrete out of the box: the library ships patterns, not implementations.
-
-### Entity
-
-src/wexample_orm/entity/abstract_entity.py
-
-`AbstractEntity` is the SQLAlchemy declarative base for the whole stack. It is decorated with `@as_declarative()`, so every subclass automatically participates in the same `MetaData` registry.
-
-Two conventions are fixed here and nowhere else:
-
-- **Table name** — `__tablename__` is set by `get_entity_name()`, which calls `string_to_snake_case(cls.__name__)`. A class named `UserAccount` maps to the table `user_account` with no annotation needed.
-- **Primary key** — `id` is a `BigInteger` with `autoincrement=True`. A `with_variant(Integer(), "sqlite")` is bolted on so that the same declaration works in the in-memory SQLite sessions used during testing (SQLite only auto-increments a column typed `INTEGER PRIMARY KEY`, not `BIGINT`).
-
-### Repository
-
-src/wexample_orm/repository/abstract_repository.py
-
-`AbstractRepository` is the data-access object. It holds one `session` field (default `None`) and exposes:
-
-- `get_entity_type()` — abstract classmethod every concrete repository must implement; returns the `AbstractEntity` subclass it owns.
-- `find(id)` — delegates to `session.get(EntityType, id)`; returns `None` when no session is set.
-- `find_one_by(filter_clause)` — `query().filter(clause).first()`.
-- `query()` — returns a raw `session.query(EntityType)`; calls `_require_session()` first.
-- `save(entity, flush=True, refresh=False)` — `session.add` then `session.commit`; optionally refreshes from DB.
-- `_require_session()` — raises `RepositorySessionMissingException` when `session` is `None`; called by any method that cannot function without it.
-
-A repository can be constructed standalone (session-less `find` returns `None`, everything else raises) or injected with a session directly.
-
-### Session factory
-
-src/wexample_orm/session/abstract_session_factory.py
-
-`AbstractSessionFactory` builds and caches a SQLAlchemy engine and sessionmaker from a DSN string. The engine is created on first call to `get_engine()` and reused thereafter; the sessionmaker is created on first call to `create_session()`.
-
-Public API:
-
-- `dsn` — SQLAlchemy URL, e.g. `postgresql+psycopg://user:pwd@host/db` or `sqlite:///:memory:`.
-- `engine_options` / `session_options` — dicts forwarded verbatim to `create_engine()` and `sessionmaker()`.
-- `create_session()` — returns a fresh `Session` from the cached maker.
-- `get_engine()` — returns the cached engine (creates it on first call).
-- `dispose()` — calls `engine.dispose()` and resets both caches; intended for test teardown.
-- `_engine_kwargs()` / `_session_kwargs()` — overridable hooks; by default they just copy the option dicts.
-
-The session factory is decoupled from the rest: nothing in the repository or manager imports it. Callers create a session through it and pass it in manually.
-
-### Repositories manager
-
-src/wexample_orm/common/abstract_repositories_manager.py
-
-`AbstractRepositoriesManager` is a registry that maps entity types to repository instances. It is the single entry point when a project has multiple repositories and wants to avoid constructing them by hand.
-
-Fields:
-
-- `repository_classes` — the list of repository classes the manager may instantiate.
-- `session` — the SQLAlchemy session shared across every repository the manager creates.
-- `_instances` — private cache (`entity_type → repository instance`); a repository is built once and reused.
-
-Methods:
-
-- `get(entity_type)` — looks up the cache; on miss, walks `repository_classes` looking for the class whose `get_entity_type()` matches, instantiates it with `session=self.session`, stores it, and returns it. Raises `UnknownRepositoryException` if nothing matches.
-- `get_by_table_name(table_name)` — same lookup but keyed on `entity_type.get_entity_name()` (the snake-case table name).
-- `get_classes()` — returns a copy of `repository_classes`.
-
-### Call path
-
-A typical read goes: caller asks the manager for a repository (`manager.get(User)`) → manager instantiates `UserRepository(session=session)` if not cached → caller calls `repo.find(42)` → repository calls `session.get(User, 42)` → SQLAlchemy issues the SQL against the engine that the session factory built.
-
-A write follows the same path through `repo.save(entity)`, which calls `session.add` then `session.commit`.
-
-### Exceptions
-
-src/wexample_orm/exception/unknown_repository_exception.py
-
-`UnknownRepositoryException` (error code `ORM_UNKNOWN_REPOSITORY`) is raised by the manager when `get()` receives an entity type for which no repository class is registered.
-
-src/wexample_orm/exception/repository_session_missing_exception.py
-
-`RepositorySessionMissingException` (error code `ORM_REPOSITORY_SESSION_MISSING`) is raised by `AbstractRepository._require_session()` when a session-dependent method is called on a repository that has `session=None`.
-
-Both extend `UndefinedException` from `wexample-helpers` and carry a structured `data` dict alongside the human-readable message.
-
-### Testing helper
-
-src/wexample_orm/testing/sqlite.py
-
-`in_memory_session(declarative_base)` is a context manager that creates a fresh SQLite in-memory engine, runs `metadata.create_all()` on it, yields a session, then closes the session and disposes the engine. The `declarative_base` argument must be the `@as_declarative()`-decorated class whose `MetaData` holds the tables to create — in practice `AbstractEntity` or a project subclass of it.
-
-```python
-from wexample_orm.testing import in_memory_session
-from wexample_orm.entity.abstract_entity import AbstractEntity
-
-with in_memory_session(AbstractEntity) as session:
-    repo = UserRepository(session=session)
-    repo.save(User(name="alice"))
-    assert repo.find(1).name == "alice"
-```
-
-The helper is excluded from the published wheel (`tool.setuptools.packages.find` omits `wexample_orm.testing*`) and is only available in a development install.
-
-### Source layout
-
-```
-src/wexample_orm/
-    __init__.py                        # re-exports the three main abstractions
-    entity/abstract_entity.py          # declarative base + PK convention
-    repository/abstract_repository.py  # data-access object
-    session/abstract_session_factory.py# engine + sessionmaker cache
-    common/abstract_repositories_manager.py  # repository registry
-    exception/
-        unknown_repository_exception.py
-        repository_session_missing_exception.py
-    testing/sqlite.py                  # in-memory SQLite helper
-```
-
-## Integration in the Suite
-
-This package is part of the Wexample Suite — a collection of high-quality, modular tools designed to work seamlessly together across multiple languages and environments.
-
-### Related Packages
-
-The suite includes packages for configuration management, file handling, prompts, and more. Each package can be used independently or as part of the integrated suite.
-
-## Dependencies
-
-- attrs: >=23.1.0
-- psycopg: >=3.2
-- sqlalchemy: <3,>=2
-- wexample-helpers: >=20.5.0
-
-## Versioning & Compatibility Policy
-
-Wexample packages follow **Semantic Versioning** (SemVer):
-
-- **MAJOR**: Breaking changes
-- **MINOR**: New features, backward compatible
-- **PATCH**: Bug fixes, backward compatible
-
-We maintain backward compatibility within major versions and provide clear migration guides for breaking changes.
-
-## License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-Free to use in both personal and commercial projects.
-
-## About us
-
-[Wexample](https://wexample.com) stands as a cornerstone of the digital ecosystem — a collective of seasoned engineers, researchers, and creators driven by a relentless pursuit of technological excellence. More than a media platform, it has grown into a vibrant community where innovation meets craftsmanship, and where every line of code reflects a commitment to clarity, durability, and shared intelligence.
-
-This packages suite embodies this spirit. Trusted by professionals and enthusiasts alike, it delivers a consistent, high-quality foundation for modern development — open, elegant, and battle-tested. Its reputation is built on years of collaboration, refinement, and rigorous attention to detail, making it a natural choice for those who demand both robustness and beauty in their tools.
-
-Wexample cultivates a culture of mastery. Each package, each contribution carries the mark of a community that values precision, ethics, and innovation — a community proud to shape the future of digital craftsmanship.
-
-Built and maintained by [Romain Weeger](https://weeger.io).
-
-## Known Limitations & Roadmap
-
-Current limitations and planned features are tracked in the GitHub issues.
-
-See the [project roadmap](https://github.com/wexample/python-orm/issues) for upcoming features and improvements.
-
-## Status & Compatibility
-
-**Maturity**: Production-ready
-
-**Python Support**: >=3.10
-
-**OS Support**: Linux, macOS, Windows
-
-**Status**: Actively maintained
-
-## Useful Links
-
-- **Homepage**: https://github.com/wexample/python-orm
-- **Issue Tracker**: https://github.com/wexample/python-orm/issues
-- **Discussions**: https://github.com/wexample/python-orm/discussions
-- **PyPI**: [pypi.org/project/wexample-orm](https://pypi.org/project/wexample-orm/)
-
-## Migration Notes
-
-When upgrading between major versions, refer to the migration guides in the documentation.
-
-Breaking changes are clearly documented with upgrade paths and examples.

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,
-        )