yaddd-sqlalchemy 0.1.0__tar.gz

yaddd_sqlalchemy-0.1.0/.gitignore

@@ -0,0 +1,165 @@
+# Byte-compiled / optimized / DLL files
+__pycache__/
+*.py[cod]
+*$py.class
+
+# C extensions
+*.so
+
+# Distribution / packaging
+.Python
+build/
+develop-eggs/
+dist/
+downloads/
+eggs/
+.eggs/
+lib/
+lib64/
+parts/
+sdist/
+var/
+wheels/
+share/python-wheels/
+*.egg-info/
+.installed.cfg
+*.egg
+MANIFEST
+
+# PyInstaller
+#  Usually these files are written by a python script from a template
+#  before PyInstaller builds the exe, so as to inject date/other infos into it.
+*.manifest
+*.spec
+
+# Installer logs
+pip-log.txt
+pip-delete-this-directory.txt
+
+# Unit test / coverage reports
+htmlcov/
+.tox/
+.nox/
+.coverage
+.coverage.*
+.cache
+nosetests.xml
+coverage.xml
+*.cover
+*.py,cover
+.hypothesis/
+.pytest_cache/
+cover/
+
+# Translations
+*.mo
+*.pot
+
+# Django stuff:
+*.log
+local_settings.py
+db.sqlite3
+db.sqlite3-journal
+
+# Flask stuff:
+instance/
+.webassets-cache
+
+# Scrapy stuff:
+.scrapy
+
+# Sphinx documentation
+docs/_build/
+
+# PyBuilder
+.pybuilder/
+target/
+
+# Jupyter Notebook
+.ipynb_checkpoints
+
+# IPython
+profile_default/
+ipython_config.py
+
+# pyenv
+#   For a library or package, you might want to ignore these files since the code is
+#   intended to run in multiple environments; otherwise, check them in:
+# .python-version
+
+# pipenv
+#   According to pypa/pipenv#598, it is recommended to include Pipfile.lock in version control.
+#   However, in case of collaboration, if having platform-specific dependencies or dependencies
+#   having no cross-platform support, pipenv may install dependencies that don't work, or not
+#   install all needed dependencies.
+#Pipfile.lock
+
+# poetry
+#   Similar to Pipfile.lock, it is generally recommended to include poetry.lock in version control.
+#   This is especially recommended for binary packages to ensure reproducibility, and is more
+#   commonly ignored for libraries.
+#   https://python-poetry.org/docs/basic-usage/#commit-your-poetrylock-file-to-version-control
+#poetry.lock
+
+# pdm
+#   Similar to Pipfile.lock, it is generally recommended to include pdm.lock in version control.
+#pdm.lock
+#   pdm stores project-wide configurations in .pdm.toml, but it is recommended to not include it
+#   in version control.
+#   https://pdm.fming.dev/latest/usage/project/#working-with-version-control
+.pdm.toml
+.pdm-python
+.pdm-build/
+
+# PEP 582; used by e.g. github.com/David-OConnor/pyflow and github.com/pdm-project/pdm
+__pypackages__/
+
+# Celery stuff
+celerybeat-schedule
+celerybeat.pid
+
+# SageMath parsed files
+*.sage.py
+
+# Environments
+.env
+.venv
+env/
+venv/
+ENV/
+env.bak/
+venv.bak/
+
+# Spyder project settings
+.spyderproject
+.spyproject
+
+# Rope project settings
+.ropeproject
+
+# mkdocs documentation
+/site
+
+# mypy
+.mypy_cache/
+.dmypy.json
+dmypy.json
+
+# Pyre type checker
+.pyre/
+
+# pytype static type analyzer
+.pytype/
+
+# Cython debug symbols
+cython_debug/
+
+# IDE
+.idea
+.vscode/!launch.json
+.vscode/!tasks.json
+
+# OS
+.DS_Store
+
+*_old/

yaddd_sqlalchemy-0.1.0/PKG-INFO

@@ -0,0 +1,31 @@
+Metadata-Version: 2.5
+Name: yaddd-sqlalchemy
+Version: 0.1.0
+Summary: SQLAlchemy integration for yaddd: SqlCrudRepository, SqlUnitOfWork, VOTypeDecorator
+Project-URL: Homepage, https://github.com/netstuff/yaddd
+Author-email: Yuri Andreev <andreev.jr@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Internet
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.12
+Requires-Dist: sqlalchemy[asyncio]>=2.0
+Requires-Dist: yaddd>=0.1
+Description-Content-Type: text/markdown
+
+# yaddd-sqlalchemy
+SQLAlchemy integration for [yaddd](https://github.com/pyDDD/yaddd).
+
+- `SqlCrudRepository` — SQLAlchemy Core-based implementation of the `CrudRepository` port;
+- `SqlUnitOfWork` — `UnitOfWork` over `AsyncSession`;
+- `VOTypeDecorator` — `TypeDecorator` persisting `ValueObject` instances as raw values.
+
+Wiring is explicit: instantiate in your composition root, no auto-discovery.
+Port conformance is proven by the contract suites in `yaddd.testing`.

yaddd_sqlalchemy-0.1.0/README.md

@@ -0,0 +1,9 @@
+# yaddd-sqlalchemy
+SQLAlchemy integration for [yaddd](https://github.com/pyDDD/yaddd).
+
+- `SqlCrudRepository` — SQLAlchemy Core-based implementation of the `CrudRepository` port;
+- `SqlUnitOfWork` — `UnitOfWork` over `AsyncSession`;
+- `VOTypeDecorator` — `TypeDecorator` persisting `ValueObject` instances as raw values.
+
+Wiring is explicit: instantiate in your composition root, no auto-discovery.
+Port conformance is proven by the contract suites in `yaddd.testing`.

yaddd_sqlalchemy-0.1.0/pyproject.toml

@@ -0,0 +1,39 @@
+[project]
+name = "yaddd-sqlalchemy"
+description = "SQLAlchemy integration for yaddd: SqlCrudRepository, SqlUnitOfWork, VOTypeDecorator"
+authors = [
+    {name = "Yuri Andreev", email = "andreev.jr@gmail.com"},
+]
+license = 'MIT'
+license-files = ['LICENSE']
+classifiers = [
+    'Development Status :: 4 - Beta',
+    'Programming Language :: Python',
+    'Programming Language :: Python :: 3.12',
+    'Programming Language :: Python :: 3.13',
+    'Programming Language :: Python :: 3.14',
+    'Intended Audience :: Developers',
+    'Operating System :: OS Independent',
+    'Topic :: Software Development :: Libraries :: Python Modules',
+    'Topic :: Internet',
+]
+requires-python = '>=3.12'
+dependencies = [
+    "yaddd>=0.1",
+    "sqlalchemy[asyncio]>=2.0",
+]
+version = "0.1.0"
+readme = 'README.md'
+
+[project.urls]
+Homepage = 'https://github.com/netstuff/yaddd'
+
+[tool.uv.sources]
+yaddd = { workspace = true }
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/yaddd_sqlalchemy"]

yaddd_sqlalchemy-0.1.0/src/yaddd_sqlalchemy/__init__.py

@@ -0,0 +1,8 @@
+"""SQLAlchemy integration for yaddd."""
+
+from yaddd_sqlalchemy.repositories import SqlCrudRepository
+from yaddd_sqlalchemy.uow import SqlUnitOfWork
+from yaddd_sqlalchemy.value_objects import VOTypeDecorator
+
+
+__all__ = ["SqlCrudRepository", "SqlUnitOfWork", "VOTypeDecorator"]

yaddd_sqlalchemy-0.1.0/src/yaddd_sqlalchemy/repositories.py

@@ -0,0 +1,87 @@
+"""SQLAlchemy Core implementation of the ``CrudRepository`` port."""
+
+from abc import ABC, abstractmethod
+from typing import Any, ClassVar
+
+from sqlalchemy import Column, Table, delete, insert, select, update
+from sqlalchemy.engine import Row
+from sqlalchemy.ext.asyncio import AsyncSession
+from yaddd.domain.entities import AggregateRoot, PrimaryKey
+from yaddd.domain.repositories import CrudRepository
+from yaddd.exceptions import EntityNotFoundError
+
+
+__all__ = ["SqlCrudRepository"]
+
+
+class SqlCrudRepository[T: AggregateRoot](CrudRepository[T], ABC):
+    """SQLAlchemy Core-based repository for a single aggregate type.
+
+    No ORM declarative opinions: the subclass declares a Core ``table`` and
+    the mapping between rows and aggregates. The repository never commits —
+    transaction boundaries belong to ``SqlUnitOfWork``.
+
+    Primary keys must be single-column, and ``pk`` values must be natively
+    bindable by the primary-key column type (use a ``TypeDecorator`` column
+    or string/integer primary keys otherwise).
+
+    Example:
+        class OrderRepository(SqlCrudRepository[Order]):
+            table = orders_table
+
+            def to_domain(self, row: Row[Any]) -> Order:
+                return Order(id=row.id, status=row.status, total=row.total)
+
+            def to_row(self, instance: Order) -> dict[str, Any]:
+                return {"id": instance.pk, "status": instance.status, "total": instance.total}
+    """
+
+    table: ClassVar[Table]
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+
+    @abstractmethod
+    def to_domain(self, row: Row[Any]) -> T:
+        """Reconstitute the aggregate from a table row."""
+
+    @abstractmethod
+    def to_row(self, instance: T) -> dict[str, Any]:
+        """Map the aggregate to a dict of column values."""
+
+    @property
+    def _pk_column(self) -> Column[Any]:
+        columns = list(self.table.primary_key.columns)
+        if len(columns) != 1:
+            raise NotImplementedError("SqlCrudRepository supports single-column primary keys only")
+        return columns[0]
+
+    async def get(self, pk: PrimaryKey) -> T | None:
+        result = await self._session.execute(select(self.table).where(self._pk_column == pk))
+        row = result.first()
+        return None if row is None else self.to_domain(row)
+
+    async def read(self, filter: dict[str, Any] | None = None, *, slice: tuple[int, int] = (0, 0)) -> list[T]:
+        stmt = select(self.table)
+        for key, value in (filter or {}).items():
+            stmt = stmt.where(self.table.c[key] == value)
+        offset, limit = slice
+        stmt = stmt.offset(offset)
+        if limit:
+            stmt = stmt.limit(limit)
+        result = await self._session.execute(stmt)
+        return [self.to_domain(row) for row in result.all()]
+
+    async def create(self, instance: T) -> T:
+        await self._session.execute(insert(self.table).values(**self.to_row(instance)))
+        return instance
+
+    async def update(self, instance: T) -> T:
+        if await self.get(instance.pk) is None:
+            raise EntityNotFoundError(f"{type(instance).__name__}({instance.pk})")
+        stmt = update(self.table).where(self._pk_column == instance.pk).values(**self.to_row(instance))
+        await self._session.execute(stmt)
+        return instance
+
+    async def delete(self, pk: PrimaryKey) -> None:
+        await self._session.execute(delete(self.table).where(self._pk_column == pk))

yaddd_sqlalchemy-0.1.0/src/yaddd_sqlalchemy/uow.py

@@ -0,0 +1,47 @@
+"""``UnitOfWork`` implementation over a SQLAlchemy ``AsyncSession``."""
+
+from types import TracebackType
+from typing import Self
+
+from sqlalchemy.ext.asyncio import AsyncSession
+from yaddd.application.uow import UnitOfWork
+
+
+__all__ = ["SqlUnitOfWork"]
+
+
+class SqlUnitOfWork(UnitOfWork):
+    """Transactional boundary over a single ``AsyncSession``.
+
+    ``commit()`` flushes and commits the session. Leaving the context without
+    a commit — or with an exception — rolls back; the session is always
+    closed on exit.
+    """
+
+    def __init__(self, session: AsyncSession) -> None:
+        self._session = session
+        self._committed = False
+
+    async def __aenter__(self) -> Self:
+        return self
+
+    async def __aexit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc_value: BaseException | None,
+        traceback: TracebackType | None,
+    ) -> None:
+        try:
+            if exc_type is not None or not self._committed:
+                await self.rollback()
+        finally:
+            await self._session.close()
+
+    async def commit(self) -> None:
+        """Persist all changes made within the unit of work."""
+        await self._session.commit()
+        self._committed = True
+
+    async def rollback(self) -> None:
+        """Discard all changes made within the unit of work."""
+        await self._session.rollback()

yaddd_sqlalchemy-0.1.0/src/yaddd_sqlalchemy/value_objects.py

@@ -0,0 +1,33 @@
+"""SQLAlchemy type decorator persisting ``ValueObject`` instances."""
+
+from typing import Any, ClassVar
+
+from sqlalchemy.engine import Dialect
+from sqlalchemy.types import TypeDecorator
+from yaddd.domain.value_object import ValueObject
+
+
+__all__ = ["VOTypeDecorator"]
+
+
+class VOTypeDecorator(TypeDecorator[ValueObject[Any]]):
+    """Persist a ``ValueObject`` as its raw value and rebuild it on load.
+
+    Subclass, declare ``vo_class`` and pick the storage type via ``impl``::
+
+        class EmailType(VOTypeDecorator):
+            impl = String(255)
+            cache_ok = True
+            vo_class = Email
+
+    Binding unwraps ``value.value``; loading revalidates through
+    ``vo_class(value)``. ``None`` passes through untouched in both directions.
+    """
+
+    vo_class: ClassVar[type[ValueObject[Any]]]
+
+    def process_bind_param(self, value: ValueObject[Any] | None, dialect: Dialect) -> Any:
+        return None if value is None else value.value
+
+    def process_result_value(self, value: Any, dialect: Dialect) -> ValueObject[Any] | None:
+        return None if value is None else self.vo_class(value)

yaddd_sqlalchemy-0.1.0/tests/conftest.py

@@ -0,0 +1,54 @@
+from collections.abc import AsyncIterator
+from typing import Any
+from uuid import uuid4
+
+import pytest
+from sqlalchemy import Column, Integer, MetaData, String, Table
+from sqlalchemy.engine import Row
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+
+from yaddd.domain import AggregateRoot
+from yaddd_sqlalchemy import SqlCrudRepository
+
+
+metadata = MetaData()
+
+orders_table = Table(
+    "orders",
+    metadata,
+    Column("id", String(32), primary_key=True),
+    Column("status", String(16), nullable=False),
+    Column("total", Integer, nullable=False),
+)
+
+
+class Order(AggregateRoot):
+    id: str
+    status: str
+    total: int
+
+
+class OrderRepository(SqlCrudRepository[Order]):
+    table = orders_table
+
+    def to_domain(self, row: Row[Any]) -> Order:
+        return Order(id=str(row.id), status=str(row.status), total=int(row.total))
+
+    def to_row(self, instance: Order) -> dict[str, Any]:
+        return {"id": instance.pk, "status": instance.status, "total": instance.total}
+
+
+@pytest.fixture
+async def engine() -> AsyncIterator[AsyncEngine]:
+    engine = create_async_engine("sqlite+aiosqlite://")
+    async with engine.begin() as connection:
+        await connection.run_sync(metadata.create_all)
+    yield engine
+    await engine.dispose()
+
+
+@pytest.fixture
+async def session(engine: AsyncEngine) -> AsyncIterator[AsyncSession]:
+    session_factory = async_sessionmaker(engine, expire_on_commit=False)
+    async with session_factory() as session:
+        yield session

yaddd_sqlalchemy-0.1.0/tests/test_repository.py

@@ -0,0 +1,33 @@
+from collections.abc import Callable
+from typing import Any
+from uuid import uuid4
+
+import pytest
+from sqlalchemy.ext.asyncio import AsyncSession
+
+from yaddd.domain import AggregateRoot, CrudRepository
+from yaddd.testing import CrudRepositoryContract
+
+from conftest import Order, OrderRepository
+
+
+class TestSqlCrudRepository(CrudRepositoryContract):
+    """The contract suite proves port conformance against in-memory sqlite."""
+
+    @pytest.fixture
+    def repo(self, session: AsyncSession) -> CrudRepository[Order]:
+        return OrderRepository(session)
+
+    @pytest.fixture
+    def aggregate_factory(self) -> Callable[[], Order]:
+        def make() -> Order:
+            token = uuid4().hex
+            return Order(id=token, status=f"status-{token[:8]}", total=int(token[:6], 16) % 1000)
+
+        return make
+
+
+async def test_get_missing_returns_none_for_unknown_pk(session: AsyncSession):
+    repo: CrudRepository[Any] = OrderRepository(session)
+
+    assert await repo.get("no-such-id") is None

yaddd_sqlalchemy-0.1.0/tests/test_uow.py

@@ -0,0 +1,65 @@
+from collections.abc import Awaitable, Callable
+
+import pytest
+from sqlalchemy import select
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession
+
+from yaddd.application.uow import UnitOfWork
+from yaddd.testing import UnitOfWorkContract
+from yaddd_sqlalchemy import SqlUnitOfWork
+
+from conftest import Order, OrderRepository, orders_table
+
+
+class TestSqlUnitOfWork(UnitOfWorkContract):
+    @pytest.fixture
+    def uow(self, session: AsyncSession) -> UnitOfWork:
+        return SqlUnitOfWork(session)
+
+    @pytest.fixture
+    def assert_rolled_back(self, session: AsyncSession) -> Callable[[], Awaitable[None]]:
+        async def check() -> None:
+            assert not session.in_transaction()
+            assert not session.new and not session.dirty
+
+        return check
+
+
+async def test_commit_persists_changes(engine: AsyncEngine, session: AsyncSession):
+    async with SqlUnitOfWork(session) as uow:
+        await OrderRepository(session).create(Order(id="order-1", status="new", total=10))
+        await uow.commit()
+
+    async with AsyncSession(engine) as verify:
+        result = await verify.execute(select(orders_table).where(orders_table.c.id == "order-1"))
+        assert result.first() is not None
+
+
+async def test_exception_inside_context_rolls_back(engine: AsyncEngine, session: AsyncSession):
+    with pytest.raises(RuntimeError, match="boom"):
+        async with SqlUnitOfWork(session):
+            await OrderRepository(session).create(Order(id="order-2", status="new", total=10))
+            raise RuntimeError("boom")
+
+    async with AsyncSession(engine) as verify:
+        result = await verify.execute(select(orders_table).where(orders_table.c.id == "order-2"))
+        assert result.first() is None
+
+
+async def test_exit_without_commit_rolls_back(engine: AsyncEngine, session: AsyncSession):
+    async with SqlUnitOfWork(session):
+        await OrderRepository(session).create(Order(id="order-3", status="new", total=10))
+
+    async with AsyncSession(engine) as verify:
+        result = await verify.execute(select(orders_table).where(orders_table.c.id == "order-3"))
+        assert result.first() is None
+
+
+async def test_rollback_discards_pending_changes(engine: AsyncEngine, session: AsyncSession):
+    async with SqlUnitOfWork(session) as uow:
+        await OrderRepository(session).create(Order(id="order-4", status="new", total=10))
+        await uow.rollback()
+
+    async with AsyncSession(engine) as verify:
+        result = await verify.execute(select(orders_table).where(orders_table.c.id == "order-4"))
+        assert result.first() is None

yaddd_sqlalchemy-0.1.0/tests/test_value_objects.py

@@ -0,0 +1,61 @@
+import pytest
+from sqlalchemy import Column, MetaData, String, Table, insert, select
+from sqlalchemy.ext.asyncio import AsyncEngine, AsyncSession, async_sessionmaker, create_async_engine
+
+from yaddd.domain import ValueObject
+from yaddd.exceptions import ValidationError
+from yaddd_sqlalchemy import VOTypeDecorator
+
+
+class Email(ValueObject[str]):
+    @classmethod
+    def validate(cls, value: str) -> str:
+        if "@" not in value:
+            raise ValidationError(f"not an email: {value}")
+        return value.lower()
+
+
+class EmailType(VOTypeDecorator):
+    impl = String(255)
+    cache_ok = True
+    vo_class = Email
+
+
+contacts_metadata = MetaData()
+
+contacts_table = Table(
+    "contacts",
+    contacts_metadata,
+    Column("id", String(32), primary_key=True),
+    Column("email", EmailType, nullable=True),
+)
+
+
+@pytest.fixture
+async def session() -> AsyncSession:
+    engine = create_async_engine("sqlite+aiosqlite://")
+    async with engine.begin() as connection:
+        await connection.run_sync(contacts_metadata.create_all)
+    session_factory = async_sessionmaker(engine, expire_on_commit=False)
+    async with session_factory() as session:
+        yield session
+    await engine.dispose()
+
+
+async def test_value_object_round_trip(session: AsyncSession):
+    await session.execute(insert(contacts_table).values(id="c-1", email=Email("User@Example.com")))
+    await session.commit()
+
+    result = await session.execute(select(contacts_table.c.email).where(contacts_table.c.id == "c-1"))
+    loaded = result.scalar_one()
+
+    assert isinstance(loaded, Email)
+    assert loaded == Email("user@example.com")
+
+
+async def test_none_round_trip(session: AsyncSession):
+    await session.execute(insert(contacts_table).values(id="c-2", email=None))
+    await session.commit()
+
+    result = await session.execute(select(contacts_table.c.email).where(contacts_table.c.id == "c-2"))
+    assert result.scalar_one() is None