spakky-sqlalchemy 5.0.1__tar.gz

spakky_sqlalchemy-5.0.1/PKG-INFO

@@ -0,0 +1,255 @@
+Metadata-Version: 2.3
+Name: spakky-sqlalchemy
+Version: 5.0.1
+Summary: SQLAlchemy plugin for Spakky framework
+Author: Spakky
+Author-email: Spakky <sejong418@icloud.com>
+License: MIT
+Requires-Dist: spakky-data>=5.0.1
+Requires-Dist: sqlalchemy>=2.0.45
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Spakky SQLAlchemy
+
+SQLAlchemy integration plugin for [Spakky Framework](https://github.com/E5presso/spakky-framework).
+
+## Installation
+
+```bash
+pip install spakky-sqlalchemy
+```
+
+Or install via Spakky extras:
+
+```bash
+pip install spakky[sqlalchemy]
+```
+
+## Configuration
+
+Set environment variables with the `SPAKKY_SQLALCHEMY__` prefix:
+
+```bash
+# Required
+export SPAKKY_SQLALCHEMY__CONNECTION_STRING="postgresql+psycopg://user:pass@localhost/db"
+
+# Engine options (optional)
+export SPAKKY_SQLALCHEMY__ECHO="false"
+export SPAKKY_SQLALCHEMY__ECHO_POOL="false"
+
+# Connection pool options (optional)
+export SPAKKY_SQLALCHEMY__POOL_SIZE="5"
+export SPAKKY_SQLALCHEMY__POOL_MAX_OVERFLOW="10"
+export SPAKKY_SQLALCHEMY__POOL_TIMEOUT="30.0"
+export SPAKKY_SQLALCHEMY__POOL_RECYCLE="-1"
+export SPAKKY_SQLALCHEMY__POOL_PRE_PING="false"
+
+# Session options (optional)
+export SPAKKY_SQLALCHEMY__SESSION_AUTOFLUSH="true"
+export SPAKKY_SQLALCHEMY__SESSION_EXPIRE_ON_COMMIT="true"
+
+# Transaction options (optional)
+export SPAKKY_SQLALCHEMY__AUTOCOMMIT="true"
+
+# Async support (optional)
+export SPAKKY_SQLALCHEMY__SUPPORT_ASYNC_MODE="true"
+```
+
+## Usage
+
+### Defining Tables with Domain Mapping
+
+Use `@Table` decorator and inherit from `AbstractTable` to define ORM tables with domain model mapping:
+
+```python
+from uuid import UUID
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+from spakky.plugins.sqlalchemy.orm.table import AbstractTable, Table
+from spakky.domain.models.aggregate_root import AbstractAggregateRoot
+
+# Domain model
+class User(AbstractAggregateRoot[UUID]):
+    id: UUID
+    name: str
+    email: str
+
+# Table definition with domain mapping
+@Table()
+class UserTable(AbstractMappableTable[User]):
+    __tablename__ = "users"
+
+    id: Mapped[UUID] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(255))
+    email: Mapped[str] = mapped_column(String(255))
+
+    @classmethod
+    def from_domain(cls, domain: User) -> "UserTable":
+        return cls(id=domain.id, name=domain.name, email=domain.email)
+
+    def to_domain(self) -> User:
+        return User(id=self.id, name=self.name, email=self.email)
+```
+
+### Repository Implementation
+
+Extend `AbstractGenericRepository` or `AbstractAsyncGenericRepository`:
+
+```python
+from uuid import UUID
+from spakky.data.stereotype.repository import Repository
+from spakky.plugins.sqlalchemy.persistency.repository import (
+    AbstractGenericRepository,
+    AbstractAsyncGenericRepository,
+)
+
+# Synchronous repository
+@Repository()
+class UserRepository(AbstractGenericRepository[User, UUID]):
+    pass  # CRUD methods inherited
+
+# Asynchronous repository
+@Repository()
+class AsyncUserRepository(AbstractAsyncGenericRepository[User, UUID]):
+    pass  # Async CRUD methods inherited
+```
+
+### Using Transactions
+
+Use the `@Transactional` decorator from `spakky-data`:
+
+```python
+from spakky.core.stereotype.usecase import UseCase
+from spakky.data.aspects.transactional import Transactional
+
+@UseCase()
+class CreateUserUseCase:
+    def __init__(self, user_repo: UserRepository) -> None:
+        self._user_repo = user_repo
+
+    @Transactional()
+    def execute(self, name: str, email: str) -> User:
+        user = User.create(name, email)
+        return self._user_repo.save(user)
+```
+
+### Async Transactions
+
+The same `@Transactional()` decorator works for both sync and async methods.
+The framework automatically selects the correct aspect based on whether the method is a coroutine.
+
+```python
+from spakky.data.aspects.transactional import Transactional
+
+@UseCase()
+class AsyncCreateUserUseCase:
+    def __init__(self, user_repo: AsyncUserRepository) -> None:
+        self._user_repo = user_repo
+
+    @Transactional()
+    async def execute(self, name: str, email: str) -> User:
+        user = User.create(name, email)
+        return await self._user_repo.save(user)
+```
+
+### Accessing Session Directly
+
+For complex queries, access the SQLAlchemy session directly in **QueryUseCase**.
+Following CQRS principles, queries should be implemented directly rather than
+adding query methods to repositories.
+
+```python
+from spakky.core.common.mutability import immutable
+from spakky.core.stereotype.usecase import UseCase
+from spakky.domain.application.query import AbstractQuery, IAsyncQueryUseCase
+from spakky.plugins.sqlalchemy.persistency.session_manager import AsyncSessionManager
+
+
+@immutable
+class FindUserByEmailQuery(AbstractQuery):
+    email: str
+
+
+@immutable
+class UserDTO:
+    id: UUID
+    name: str
+    email: str
+
+
+@UseCase()
+class FindUserByEmailUseCase(IAsyncQueryUseCase[FindUserByEmailQuery, UserDTO | None]):
+    def __init__(self, session_manager: AsyncSessionManager) -> None:
+        self._session_manager = session_manager
+
+    async def run(self, query: FindUserByEmailQuery) -> UserDTO | None:
+        result = await self._session_manager.session.execute(
+            select(UserTable).where(UserTable.email == query.email)
+        )
+        table = result.scalar_one_or_none()
+        if table is None:
+            return None
+        return UserDTO(id=table.id, name=table.name, email=table.email)
+```
+
+### Schema Registry
+
+Access `SchemaRegistry` to get table metadata for migrations:
+
+```python
+from spakky.plugins.sqlalchemy.orm.schema_registry import SchemaRegistry
+
+@Pod()
+class MigrationService:
+    def __init__(self, schema_registry: SchemaRegistry) -> None:
+        self._schema_registry = schema_registry
+
+    def get_metadata(self) -> MetaData:
+        return self._schema_registry.metadata
+```
+
+## Features
+
+- **Domain-Table mapping**: Bidirectional conversion between domain models and ORM tables
+- **Generic repositories**: Pre-built CRUD operations with composite PK support
+- **Sync and Async support**: Full support for both synchronous and asynchronous operations
+- **Scoped sessions**: Thread/context-safe session management
+- **Optimistic locking**: Built-in `VersionConflictError` for concurrent updates
+- **Schema registry**: Centralized table metadata management
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `@Table` | Decorator for registering ORM tables with domain mapping |
+| `AbstractTable` | Base class for ORM tables with `from_domain`/`to_domain` |
+| `AbstractGenericRepository` | Sync repository with CRUD operations |
+| `AbstractAsyncGenericRepository` | Async repository with CRUD operations |
+| `SchemaRegistry` | Central registry for table-domain mappings |
+| `SessionManager` | Sync scoped session management |
+| `AsyncSessionManager` | Async scoped session management |
+| `Transaction` | Sync transaction implementation |
+| `AsyncTransaction` | Async transaction implementation |
+| `ConnectionManager` | Sync SQLAlchemy engine lifecycle |
+| `AsyncConnectionManager` | Async SQLAlchemy engine lifecycle |
+| `SQLAlchemyConnectionConfig` | Configuration via environment variables |
+
+## Repository Methods
+
+Both sync and async repositories provide:
+
+| Method | Description |
+|--------|-------------|
+| `get(id)` | Get aggregate by ID, raises `EntityNotFoundError` if not found |
+| `get_or_none(id)` | Get aggregate by ID, returns `None` if not found |
+| `contains(id)` | Check if aggregate exists |
+| `range(ids)` | Get multiple aggregates by ID list |
+| `save(aggregate)` | Save (insert or update) an aggregate |
+| `save_all(aggregates)` | Save multiple aggregates |
+| `delete(aggregate)` | Delete an aggregate |
+| `delete_all(aggregates)` | Delete multiple aggregates |
+
+## License
+
+MIT License

spakky_sqlalchemy-5.0.1/README.md

@@ -0,0 +1,243 @@
+# Spakky SQLAlchemy
+
+SQLAlchemy integration plugin for [Spakky Framework](https://github.com/E5presso/spakky-framework).
+
+## Installation
+
+```bash
+pip install spakky-sqlalchemy
+```
+
+Or install via Spakky extras:
+
+```bash
+pip install spakky[sqlalchemy]
+```
+
+## Configuration
+
+Set environment variables with the `SPAKKY_SQLALCHEMY__` prefix:
+
+```bash
+# Required
+export SPAKKY_SQLALCHEMY__CONNECTION_STRING="postgresql+psycopg://user:pass@localhost/db"
+
+# Engine options (optional)
+export SPAKKY_SQLALCHEMY__ECHO="false"
+export SPAKKY_SQLALCHEMY__ECHO_POOL="false"
+
+# Connection pool options (optional)
+export SPAKKY_SQLALCHEMY__POOL_SIZE="5"
+export SPAKKY_SQLALCHEMY__POOL_MAX_OVERFLOW="10"
+export SPAKKY_SQLALCHEMY__POOL_TIMEOUT="30.0"
+export SPAKKY_SQLALCHEMY__POOL_RECYCLE="-1"
+export SPAKKY_SQLALCHEMY__POOL_PRE_PING="false"
+
+# Session options (optional)
+export SPAKKY_SQLALCHEMY__SESSION_AUTOFLUSH="true"
+export SPAKKY_SQLALCHEMY__SESSION_EXPIRE_ON_COMMIT="true"
+
+# Transaction options (optional)
+export SPAKKY_SQLALCHEMY__AUTOCOMMIT="true"
+
+# Async support (optional)
+export SPAKKY_SQLALCHEMY__SUPPORT_ASYNC_MODE="true"
+```
+
+## Usage
+
+### Defining Tables with Domain Mapping
+
+Use `@Table` decorator and inherit from `AbstractTable` to define ORM tables with domain model mapping:
+
+```python
+from uuid import UUID
+from sqlalchemy import String
+from sqlalchemy.orm import Mapped, mapped_column
+from spakky.plugins.sqlalchemy.orm.table import AbstractTable, Table
+from spakky.domain.models.aggregate_root import AbstractAggregateRoot
+
+# Domain model
+class User(AbstractAggregateRoot[UUID]):
+    id: UUID
+    name: str
+    email: str
+
+# Table definition with domain mapping
+@Table()
+class UserTable(AbstractMappableTable[User]):
+    __tablename__ = "users"
+
+    id: Mapped[UUID] = mapped_column(primary_key=True)
+    name: Mapped[str] = mapped_column(String(255))
+    email: Mapped[str] = mapped_column(String(255))
+
+    @classmethod
+    def from_domain(cls, domain: User) -> "UserTable":
+        return cls(id=domain.id, name=domain.name, email=domain.email)
+
+    def to_domain(self) -> User:
+        return User(id=self.id, name=self.name, email=self.email)
+```
+
+### Repository Implementation
+
+Extend `AbstractGenericRepository` or `AbstractAsyncGenericRepository`:
+
+```python
+from uuid import UUID
+from spakky.data.stereotype.repository import Repository
+from spakky.plugins.sqlalchemy.persistency.repository import (
+    AbstractGenericRepository,
+    AbstractAsyncGenericRepository,
+)
+
+# Synchronous repository
+@Repository()
+class UserRepository(AbstractGenericRepository[User, UUID]):
+    pass  # CRUD methods inherited
+
+# Asynchronous repository
+@Repository()
+class AsyncUserRepository(AbstractAsyncGenericRepository[User, UUID]):
+    pass  # Async CRUD methods inherited
+```
+
+### Using Transactions
+
+Use the `@Transactional` decorator from `spakky-data`:
+
+```python
+from spakky.core.stereotype.usecase import UseCase
+from spakky.data.aspects.transactional import Transactional
+
+@UseCase()
+class CreateUserUseCase:
+    def __init__(self, user_repo: UserRepository) -> None:
+        self._user_repo = user_repo
+
+    @Transactional()
+    def execute(self, name: str, email: str) -> User:
+        user = User.create(name, email)
+        return self._user_repo.save(user)
+```
+
+### Async Transactions
+
+The same `@Transactional()` decorator works for both sync and async methods.
+The framework automatically selects the correct aspect based on whether the method is a coroutine.
+
+```python
+from spakky.data.aspects.transactional import Transactional
+
+@UseCase()
+class AsyncCreateUserUseCase:
+    def __init__(self, user_repo: AsyncUserRepository) -> None:
+        self._user_repo = user_repo
+
+    @Transactional()
+    async def execute(self, name: str, email: str) -> User:
+        user = User.create(name, email)
+        return await self._user_repo.save(user)
+```
+
+### Accessing Session Directly
+
+For complex queries, access the SQLAlchemy session directly in **QueryUseCase**.
+Following CQRS principles, queries should be implemented directly rather than
+adding query methods to repositories.
+
+```python
+from spakky.core.common.mutability import immutable
+from spakky.core.stereotype.usecase import UseCase
+from spakky.domain.application.query import AbstractQuery, IAsyncQueryUseCase
+from spakky.plugins.sqlalchemy.persistency.session_manager import AsyncSessionManager
+
+
+@immutable
+class FindUserByEmailQuery(AbstractQuery):
+    email: str
+
+
+@immutable
+class UserDTO:
+    id: UUID
+    name: str
+    email: str
+
+
+@UseCase()
+class FindUserByEmailUseCase(IAsyncQueryUseCase[FindUserByEmailQuery, UserDTO | None]):
+    def __init__(self, session_manager: AsyncSessionManager) -> None:
+        self._session_manager = session_manager
+
+    async def run(self, query: FindUserByEmailQuery) -> UserDTO | None:
+        result = await self._session_manager.session.execute(
+            select(UserTable).where(UserTable.email == query.email)
+        )
+        table = result.scalar_one_or_none()
+        if table is None:
+            return None
+        return UserDTO(id=table.id, name=table.name, email=table.email)
+```
+
+### Schema Registry
+
+Access `SchemaRegistry` to get table metadata for migrations:
+
+```python
+from spakky.plugins.sqlalchemy.orm.schema_registry import SchemaRegistry
+
+@Pod()
+class MigrationService:
+    def __init__(self, schema_registry: SchemaRegistry) -> None:
+        self._schema_registry = schema_registry
+
+    def get_metadata(self) -> MetaData:
+        return self._schema_registry.metadata
+```
+
+## Features
+
+- **Domain-Table mapping**: Bidirectional conversion between domain models and ORM tables
+- **Generic repositories**: Pre-built CRUD operations with composite PK support
+- **Sync and Async support**: Full support for both synchronous and asynchronous operations
+- **Scoped sessions**: Thread/context-safe session management
+- **Optimistic locking**: Built-in `VersionConflictError` for concurrent updates
+- **Schema registry**: Centralized table metadata management
+
+## Components
+
+| Component | Description |
+|-----------|-------------|
+| `@Table` | Decorator for registering ORM tables with domain mapping |
+| `AbstractTable` | Base class for ORM tables with `from_domain`/`to_domain` |
+| `AbstractGenericRepository` | Sync repository with CRUD operations |
+| `AbstractAsyncGenericRepository` | Async repository with CRUD operations |
+| `SchemaRegistry` | Central registry for table-domain mappings |
+| `SessionManager` | Sync scoped session management |
+| `AsyncSessionManager` | Async scoped session management |
+| `Transaction` | Sync transaction implementation |
+| `AsyncTransaction` | Async transaction implementation |
+| `ConnectionManager` | Sync SQLAlchemy engine lifecycle |
+| `AsyncConnectionManager` | Async SQLAlchemy engine lifecycle |
+| `SQLAlchemyConnectionConfig` | Configuration via environment variables |
+
+## Repository Methods
+
+Both sync and async repositories provide:
+
+| Method | Description |
+|--------|-------------|
+| `get(id)` | Get aggregate by ID, raises `EntityNotFoundError` if not found |
+| `get_or_none(id)` | Get aggregate by ID, returns `None` if not found |
+| `contains(id)` | Check if aggregate exists |
+| `range(ids)` | Get multiple aggregates by ID list |
+| `save(aggregate)` | Save (insert or update) an aggregate |
+| `save_all(aggregates)` | Save multiple aggregates |
+| `delete(aggregate)` | Delete an aggregate |
+| `delete_all(aggregates)` | Delete multiple aggregates |
+
+## License
+
+MIT License

spakky_sqlalchemy-5.0.1/pyproject.toml

@@ -0,0 +1,80 @@
+[project]
+name = "spakky-sqlalchemy"
+version = "5.0.1"
+description = "SQLAlchemy plugin for Spakky framework"
+readme = "README.md"
+requires-python = ">=3.11"
+license = { text = "MIT" }
+authors = [{ name = "Spakky", email = "sejong418@icloud.com" }]
+dependencies = [
+    "spakky-data>=5.0.1",
+    "sqlalchemy>=2.0.45",
+]
+
+[dependency-groups]
+dev = [
+    "testcontainers[postgres]>=4.13.3",
+    "psycopg[binary]>=3.2.6",
+    "greenlet>=3.1.0",
+]
+
+[project.entry-points."spakky.plugins"]
+spakky-sqlalchemy = "spakky.plugins.sqlalchemy.main:initialize"
+
+[build-system]
+requires = ["uv_build>=0.9.13,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "spakky.plugins.sqlalchemy"
+
+[tool.pyrefly]
+python-version = "3.14"
+search_path = ["src", "."]
+project_excludes = ["**/__pycache__", "**/*.pyc"]
+
+[tool.ruff]
+builtins = ["_"]
+cache-dir = "~/.cache/ruff"
+
+[tool.pytest.ini_options]
+pythonpath = "src/spakky/plugins/sqlalchemy"
+testpaths = "tests"
+python_files = ["test_*.py"]
+asyncio_mode = "auto"
+addopts = """
+    --cov
+    --cov-report=term
+    --cov-report=xml
+    --no-cov-on-fail
+    --strict-markers
+    --dist=loadfile
+    -p no:warnings
+    -n auto
+    --spec
+"""
+spec_test_format = "{result} {docstring_summary}"
+
+[tool.coverage.run]
+include = ["src/spakky/plugins/sqlalchemy/*"]
+branch = true
+
+[tool.coverage.report]
+show_missing = true
+precision = 2
+fail_under = 90
+skip_empty = true
+exclude_lines = [
+    "pragma: no cover",
+    "def __repr__",
+    "raise AssertionError",
+    "raise NotImplementedError",
+    "@(abc\\.)?abstractmethod",
+    "@(typing\\.)?overload",
+    "\\.\\.\\.\\.",
+    "pass",
+]
+
+[tool.uv.sources]
+spakky-data = { workspace = true }

spakky_sqlalchemy-5.0.1/src/spakky/plugins/sqlalchemy/__init__.py

@@ -0,0 +1,4 @@
+from spakky.core.application.plugin import Plugin
+
+PLUGIN_NAME = Plugin(name="spakky-sqlalchemy")
+"""Plugin identifier for the SQLAlchemy integration."""

spakky_sqlalchemy-5.0.1/src/spakky/plugins/sqlalchemy/common/config.py

@@ -0,0 +1,71 @@
+from typing import ClassVar
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+from spakky.core.stereotype.configuration import Configuration
+
+from spakky.plugins.sqlalchemy.common.constants import (
+    SPAKKY_SQLALCHEMY_CONFIG_ENV_PREFIX,
+)
+
+
+@Configuration()
+class SQLAlchemyConnectionConfig(BaseSettings):
+    model_config: ClassVar[SettingsConfigDict] = SettingsConfigDict(
+        env_prefix=SPAKKY_SQLALCHEMY_CONFIG_ENV_PREFIX,
+        env_file_encoding="utf-8",
+        env_nested_delimiter="__",
+    )
+
+    # --- Connection ---
+    connection_string: str
+    """SQLAlchemy database connection URL (e.g. postgresql+psycopg://user:pass@host/db)."""
+
+    # --- Engine ---
+    echo: bool = False
+    """If True, the engine logs all SQL statements to the default logger."""
+    echo_pool: bool = False
+    """If True, the connection pool logs all checkout/checkin events."""
+
+    # --- Connection Pool (QueuePool) Defaults ---
+    DEFAULT_POOL_SIZE: ClassVar[int] = 5
+    """Default number of connections in the pool."""
+    DEFAULT_POOL_MAX_OVERFLOW: ClassVar[int] = 10
+    """Default maximum overflow connections."""
+    DEFAULT_POOL_TIMEOUT: ClassVar[float] = 30.0
+    """Default seconds to wait when pool is exhausted."""
+    DEFAULT_POOL_RECYCLE: ClassVar[int] = -1
+    """Default connection recycle time (-1 = disabled)."""
+    DEFAULT_POOL_PRE_PING: ClassVar[bool] = False
+    """Default pre-ping setting."""
+
+    # --- Connection Pool (QueuePool) ---
+    pool_size: int = DEFAULT_POOL_SIZE
+    """Number of connections to maintain persistently in the pool."""
+    pool_max_overflow: int = DEFAULT_POOL_MAX_OVERFLOW
+    """Maximum number of connections that can be opened beyond pool_size."""
+    pool_timeout: float = DEFAULT_POOL_TIMEOUT
+    """Seconds to wait before raising an error when the pool is exhausted."""
+    pool_recycle: int = DEFAULT_POOL_RECYCLE
+    """Recycle connections after this many seconds to prevent stale connections.
+    Recommended when connecting through a proxy or firewall with idle timeouts."""
+    pool_pre_ping: bool = DEFAULT_POOL_PRE_PING
+    """If True, tests each connection for liveness before returning it from the pool.
+    Prevents errors caused by connections dropped by the database server."""
+
+    # --- Session ---
+    session_autoflush: bool = True
+    """If True, the session automatically flushes pending changes before queries."""
+    session_expire_on_commit: bool = True
+    """If True, ORM objects are expired after each commit, forcing a reload on next access."""
+
+    # --- Transaction ---
+    autocommit: bool = True
+    """If True, transactions are automatically committed after with statements. If False, transactions must be manually committed or rolled back."""
+
+    # --- Async Mode ---
+    support_async_mode: bool = True
+    """If True, registers async Pods (AsyncSessionManager, AsyncTransaction).
+    Set to False when using database drivers that don't support async operations."""
+
+    def __init__(self) -> None:
+        super().__init__()

spakky_sqlalchemy-5.0.1/src/spakky/plugins/sqlalchemy/common/constants.py

@@ -0,0 +1 @@
+SPAKKY_SQLALCHEMY_CONFIG_ENV_PREFIX = "SPAKKY_SQLALCHEMY__"

spakky_sqlalchemy-5.0.1/src/spakky/plugins/sqlalchemy/error.py

@@ -0,0 +1,7 @@
+from abc import ABC
+
+from spakky.core.common.error import AbstractSpakkyFrameworkError
+
+
+class AbstractSpakkySqlAlchemyError(AbstractSpakkyFrameworkError, ABC):
+    """Base exception for Spakky SQLAlchemy errors."""