spakky-data 4.0.0__tar.gz

spakky_data-4.0.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.3
+Name: spakky-data
+Version: 4.0.0
+Summary: Data access layer for Spakky Framework (Repository implementations, ORM integration)
+Author: Spakky
+Author-email: Spakky <sejong418@icloud.com>
+Requires-Dist: spakky-domain>=4.0.0
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+
+# Spakky Data
+
+Data access layer abstractions for [Spakky Framework](https://github.com/E5presso/spakky-framework).
+
+## Installation
+
+```bash
+pip install spakky-data
+```
+
+## Features
+
+- **Repository Pattern**: Generic repository interfaces for aggregate persistence
+- **Transaction Management**: Abstract transaction classes with autocommit support
+- **External Proxy**: Proxy pattern for external service data access
+
+## Quick Start
+
+### Repository Pattern
+
+Define repository interfaces for your domain aggregates:
+
+```python
+from abc import abstractmethod
+from uuid import UUID
+
+from spakky.data.persistency.repository import IAsyncGenericRepository
+from spakky.domain.models.aggregate_root import AbstractAggregateRoot
+
+
+class User(AbstractAggregateRoot[UUID]):
+    name: str
+    email: str
+
+
+class IUserRepository(IAsyncGenericRepository[User, UUID]):
+    @abstractmethod
+    async def find_by_email(self, email: str) -> User | None: ...
+```
+
+### Transaction Management
+
+Use abstract transactions for database operations:
+
+```python
+from spakky.data.persistency.transaction import AbstractAsyncTransaction
+
+
+class SQLAlchemyTransaction(AbstractAsyncTransaction):
+    def __init__(self, session_factory, autocommit: bool = True) -> None:
+        super().__init__(autocommit)
+        self.session_factory = session_factory
+        self.session = None
+
+    async def initialize(self) -> None:
+        self.session = self.session_factory()
+
+    async def dispose(self) -> None:
+        await self.session.close()
+
+    async def commit(self) -> None:
+        await self.session.commit()
+
+    async def rollback(self) -> None:
+        await self.session.rollback()
+```
+
+Usage with context manager:
+
+```python
+async with transaction:
+    user = await repository.get(user_id)
+    user.name = "New Name"
+    await repository.save(user)
+    # Automatically commits on success, rollbacks on exception
+```
+
+### External Proxy Pattern
+
+Access external service data with proxy interfaces:
+
+```python
+from spakky.data.external.proxy import ProxyModel, IAsyncGenericProxy
+
+
+class ExternalUser(ProxyModel[int]):
+    name: str
+    email: str
+
+
+class IExternalUserProxy(IAsyncGenericProxy[ExternalUser, int]):
+    pass
+```
+
+## API Reference
+
+### Persistency
+
+| Class | Description |
+|-------|-------------|
+| `IGenericRepository` | Sync generic repository interface |
+| `IAsyncGenericRepository` | Async generic repository interface |
+| `AbstractTransaction` | Sync transaction with context manager |
+| `AbstractAsyncTransaction` | Async transaction with context manager |
+| `EntityNotFoundError` | Raised when entity not found |
+
+### External
+
+| Class | Description |
+|-------|-------------|
+| `ProxyModel` | Base class for external service data models |
+| `IGenericProxy` | Sync proxy interface |
+| `IAsyncGenericProxy` | Async proxy interface |
+
+### Errors
+
+| Class | Description |
+|-------|-------------|
+| `AbstractSpakkyPersistencyError` | Base error for persistency operations |
+| `AbstractSpakkyExternalError` | Base error for external service operations |
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| `spakky-domain` | DDD building blocks (Entity, AggregateRoot, ValueObject) |
+| `spakky-event` | Event publisher/consumer interfaces |
+
+## License
+
+MIT License

spakky_data-4.0.0/README.md

@@ -0,0 +1,131 @@
+# Spakky Data
+
+Data access layer abstractions for [Spakky Framework](https://github.com/E5presso/spakky-framework).
+
+## Installation
+
+```bash
+pip install spakky-data
+```
+
+## Features
+
+- **Repository Pattern**: Generic repository interfaces for aggregate persistence
+- **Transaction Management**: Abstract transaction classes with autocommit support
+- **External Proxy**: Proxy pattern for external service data access
+
+## Quick Start
+
+### Repository Pattern
+
+Define repository interfaces for your domain aggregates:
+
+```python
+from abc import abstractmethod
+from uuid import UUID
+
+from spakky.data.persistency.repository import IAsyncGenericRepository
+from spakky.domain.models.aggregate_root import AbstractAggregateRoot
+
+
+class User(AbstractAggregateRoot[UUID]):
+    name: str
+    email: str
+
+
+class IUserRepository(IAsyncGenericRepository[User, UUID]):
+    @abstractmethod
+    async def find_by_email(self, email: str) -> User | None: ...
+```
+
+### Transaction Management
+
+Use abstract transactions for database operations:
+
+```python
+from spakky.data.persistency.transaction import AbstractAsyncTransaction
+
+
+class SQLAlchemyTransaction(AbstractAsyncTransaction):
+    def __init__(self, session_factory, autocommit: bool = True) -> None:
+        super().__init__(autocommit)
+        self.session_factory = session_factory
+        self.session = None
+
+    async def initialize(self) -> None:
+        self.session = self.session_factory()
+
+    async def dispose(self) -> None:
+        await self.session.close()
+
+    async def commit(self) -> None:
+        await self.session.commit()
+
+    async def rollback(self) -> None:
+        await self.session.rollback()
+```
+
+Usage with context manager:
+
+```python
+async with transaction:
+    user = await repository.get(user_id)
+    user.name = "New Name"
+    await repository.save(user)
+    # Automatically commits on success, rollbacks on exception
+```
+
+### External Proxy Pattern
+
+Access external service data with proxy interfaces:
+
+```python
+from spakky.data.external.proxy import ProxyModel, IAsyncGenericProxy
+
+
+class ExternalUser(ProxyModel[int]):
+    name: str
+    email: str
+
+
+class IExternalUserProxy(IAsyncGenericProxy[ExternalUser, int]):
+    pass
+```
+
+## API Reference
+
+### Persistency
+
+| Class | Description |
+|-------|-------------|
+| `IGenericRepository` | Sync generic repository interface |
+| `IAsyncGenericRepository` | Async generic repository interface |
+| `AbstractTransaction` | Sync transaction with context manager |
+| `AbstractAsyncTransaction` | Async transaction with context manager |
+| `EntityNotFoundError` | Raised when entity not found |
+
+### External
+
+| Class | Description |
+|-------|-------------|
+| `ProxyModel` | Base class for external service data models |
+| `IGenericProxy` | Sync proxy interface |
+| `IAsyncGenericProxy` | Async proxy interface |
+
+### Errors
+
+| Class | Description |
+|-------|-------------|
+| `AbstractSpakkyPersistencyError` | Base error for persistency operations |
+| `AbstractSpakkyExternalError` | Base error for external service operations |
+
+## Related Packages
+
+| Package | Description |
+|---------|-------------|
+| `spakky-domain` | DDD building blocks (Entity, AggregateRoot, ValueObject) |
+| `spakky-event` | Event publisher/consumer interfaces |
+
+## License
+
+MIT License

spakky_data-4.0.0/pyproject.toml

@@ -0,0 +1,63 @@
+[project]
+name = "spakky-data"
+version = "4.0.0"
+description = "Data access layer for Spakky Framework (Repository implementations, ORM integration)"
+readme = "README.md"
+authors = [{ name = "Spakky", email = "sejong418@icloud.com" }]
+requires-python = ">=3.11"
+dependencies = ["spakky-domain>=4.0.0"]
+
+[build-system]
+requires = ["uv_build>=0.9.5,<0.10.0"]
+build-backend = "uv_build"
+
+[tool.uv.build-backend]
+module-root = "src"
+module-name = "spakky.data"
+
+[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/data"
+testpaths = "tests"
+python_files = ["test_*.py"]
+asyncio_mode = "auto"
+addopts = """
+    --cov
+    --cov-report=term
+    --cov-report=xml
+    --no-cov-on-fail
+    --strict-markers
+    --dist=load
+    -p no:warnings
+    -n auto
+    -vv
+"""
+
+[tool.coverage.run]
+include = ["src/spakky/data/*"]
+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",
+]
+
+[tool.uv.sources]
+spakky-domain = { workspace = true }

spakky_data-4.0.0/src/spakky/data/__init__.py

@@ -0,0 +1,40 @@
+"""Spakky Data package - Data access abstractions.
+
+This package provides:
+- Repository pattern for aggregate persistence
+- Transaction management
+- External service proxy pattern
+
+Usage:
+    from spakky.data import IGenericRepository, AbstractTransaction
+    from spakky.data import IGenericProxy, IAsyncGenericProxy
+"""
+
+# Persistency
+# External
+from spakky.data.external.error import AbstractSpakkyExternalError
+from spakky.data.external.proxy import IAsyncGenericProxy, IGenericProxy
+from spakky.data.persistency.error import AbstractSpakkyPersistencyError
+from spakky.data.persistency.repository import (
+    EntityNotFoundError,
+    IGenericRepository,
+)
+from spakky.data.persistency.transaction import (
+    AbstractAsyncTransaction,
+    AbstractTransaction,
+)
+
+__all__ = [
+    # Repository
+    "EntityNotFoundError",
+    "IGenericRepository",
+    # Transaction
+    "AbstractAsyncTransaction",
+    "AbstractTransaction",
+    # Proxy
+    "IAsyncGenericProxy",
+    "IGenericProxy",
+    # Errors
+    "AbstractSpakkyExternalError",
+    "AbstractSpakkyPersistencyError",
+]

spakky_data-4.0.0/src/spakky/data/external/__init__.py

@@ -0,0 +1,17 @@
+"""External service abstractions.
+
+This module provides:
+- Proxy pattern for external services
+- External service errors
+"""
+
+from spakky.data.external.error import AbstractSpakkyExternalError
+from spakky.data.external.proxy import IAsyncGenericProxy, IGenericProxy
+
+__all__ = [
+    # Proxy
+    "IAsyncGenericProxy",
+    "IGenericProxy",
+    # Errors
+    "AbstractSpakkyExternalError",
+]

spakky_data-4.0.0/src/spakky/data/external/error.py

@@ -0,0 +1,6 @@
+from abc import ABC
+
+from spakky.core.common.error import AbstractSpakkyFrameworkError
+
+
+class AbstractSpakkyExternalError(AbstractSpakkyFrameworkError, ABC): ...

spakky_data-4.0.0/src/spakky/data/external/proxy.py

@@ -0,0 +1,55 @@
+from abc import ABC, abstractmethod
+from typing import Any, Generic, Sequence, TypeVar
+
+from spakky.core.common.interfaces.equatable import IEquatable
+from spakky.core.common.mutability import immutable
+
+ProxyIdT_contra = TypeVar("ProxyIdT_contra", bound=IEquatable, contravariant=True)
+
+
+@immutable
+class ProxyModel(IEquatable, Generic[ProxyIdT_contra]):
+    id: ProxyIdT_contra
+
+    def __eq__(self, other: object) -> bool:
+        if not isinstance(other, type(self)):
+            return False
+        return self.id == other.id
+
+    def __hash__(self) -> int:
+        return hash(self.id)
+
+
+ProxyModelT_co = TypeVar("ProxyModelT_co", bound=ProxyModel[Any], covariant=True)
+
+
+class IGenericProxy(ABC, Generic[ProxyModelT_co, ProxyIdT_contra]):
+    @abstractmethod
+    def get(self, proxy_id: ProxyIdT_contra) -> ProxyModelT_co: ...
+
+    @abstractmethod
+    def get_or_none(self, proxy_id: ProxyIdT_contra) -> ProxyModelT_co | None: ...
+
+    @abstractmethod
+    def contains(self, proxy_id: ProxyIdT_contra) -> bool: ...
+
+    @abstractmethod
+    def range(
+        self, proxy_ids: Sequence[ProxyIdT_contra]
+    ) -> Sequence[ProxyModelT_co]: ...
+
+
+class IAsyncGenericProxy(ABC, Generic[ProxyModelT_co, ProxyIdT_contra]):
+    @abstractmethod
+    async def get(self, proxy_id: ProxyIdT_contra) -> ProxyModelT_co: ...
+
+    @abstractmethod
+    async def get_or_none(self, proxy_id: ProxyIdT_contra) -> ProxyModelT_co | None: ...
+
+    @abstractmethod
+    async def contains(self, proxy_id: ProxyIdT_contra) -> bool: ...
+
+    @abstractmethod
+    async def range(
+        self, proxy_ids: Sequence[ProxyIdT_contra]
+    ) -> Sequence[ProxyModelT_co]: ...

spakky_data-4.0.0/src/spakky/data/persistency/__init__.py

@@ -0,0 +1,28 @@
+"""Data persistence abstractions.
+
+This module provides:
+- Repository pattern interfaces
+- Transaction management
+- Persistence-related errors
+"""
+
+from spakky.data.persistency.error import AbstractSpakkyPersistencyError
+from spakky.data.persistency.repository import (
+    EntityNotFoundError,
+    IGenericRepository,
+)
+from spakky.data.persistency.transaction import (
+    AbstractAsyncTransaction,
+    AbstractTransaction,
+)
+
+__all__ = [
+    # Repository
+    "EntityNotFoundError",
+    "IGenericRepository",
+    # Transaction
+    "AbstractAsyncTransaction",
+    "AbstractTransaction",
+    # Errors
+    "AbstractSpakkyPersistencyError",
+]

spakky_data-4.0.0/src/spakky/data/persistency/error.py

@@ -0,0 +1,6 @@
+from abc import ABC
+
+from spakky.core.common.error import AbstractSpakkyFrameworkError
+
+
+class AbstractSpakkyPersistencyError(AbstractSpakkyFrameworkError, ABC): ...

spakky_data-4.0.0/src/spakky/data/persistency/repository.py

@@ -0,0 +1,83 @@
+from abc import ABC, abstractmethod
+from typing import Generic, Sequence, TypeVar
+
+from spakky.core.common.interfaces.equatable import IEquatable
+
+from spakky.domain.error import AbstractSpakkyDomainError
+from spakky.domain.models.aggregate_root import AggregateRootT
+
+AggregateIdT_contra = TypeVar(
+    "AggregateIdT_contra", bound=IEquatable, contravariant=True
+)
+
+
+class EntityNotFoundError(AbstractSpakkyDomainError):
+    message = "Entity not found by given id"
+
+
+class IGenericRepository(ABC, Generic[AggregateRootT, AggregateIdT_contra]):
+    @abstractmethod
+    def get(self, aggregate_id: AggregateIdT_contra) -> AggregateRootT: ...
+
+    @abstractmethod
+    def get_or_none(
+        self, aggregate_id: AggregateIdT_contra
+    ) -> AggregateRootT | None: ...
+
+    @abstractmethod
+    def contains(self, aggregate_id: AggregateIdT_contra) -> bool: ...
+
+    @abstractmethod
+    def range(
+        self, aggregate_ids: Sequence[AggregateIdT_contra]
+    ) -> Sequence[AggregateRootT]: ...
+
+    @abstractmethod
+    def save(self, aggregate: AggregateRootT) -> AggregateRootT: ...
+
+    @abstractmethod
+    def save_all(
+        self, aggregates: Sequence[AggregateRootT]
+    ) -> Sequence[AggregateRootT]: ...
+
+    @abstractmethod
+    def delete(self, aggregate: AggregateRootT) -> AggregateRootT: ...
+
+    @abstractmethod
+    def delete_all(
+        self, aggregates: Sequence[AggregateRootT]
+    ) -> Sequence[AggregateRootT]: ...
+
+
+class IAsyncGenericRepository(ABC, Generic[AggregateRootT, AggregateIdT_contra]):
+    @abstractmethod
+    async def get(self, aggregate_id: AggregateIdT_contra) -> AggregateRootT: ...
+
+    @abstractmethod
+    async def get_or_none(
+        self, aggregate_id: AggregateIdT_contra
+    ) -> AggregateRootT | None: ...
+
+    @abstractmethod
+    async def contains(self, aggregate_id: AggregateIdT_contra) -> bool: ...
+
+    @abstractmethod
+    async def range(
+        self, aggregate_ids: Sequence[AggregateIdT_contra]
+    ) -> Sequence[AggregateRootT]: ...
+
+    @abstractmethod
+    async def save(self, aggregate: AggregateRootT) -> AggregateRootT: ...
+
+    @abstractmethod
+    async def save_all(
+        self, aggregates: Sequence[AggregateRootT]
+    ) -> Sequence[AggregateRootT]: ...
+
+    @abstractmethod
+    async def delete(self, aggregate: AggregateRootT) -> AggregateRootT: ...
+
+    @abstractmethod
+    async def delete_all(
+        self, aggregates: Sequence[AggregateRootT]
+    ) -> Sequence[AggregateRootT]: ...

spakky_data-4.0.0/src/spakky/data/persistency/transaction.py

@@ -0,0 +1,93 @@
+from abc import ABC, abstractmethod
+from types import TracebackType
+from typing import Self, final
+
+from spakky.core.common.interfaces.disposable import IAsyncDisposable, IDisposable
+
+
+class AbstractTransaction(IDisposable, ABC):
+    autocommit_enabled: bool
+
+    def __init__(self, autocommit: bool = True) -> None:
+        self.autocommit_enabled = autocommit
+
+    @final
+    def __enter__(self) -> Self:
+        self.initialize()
+        return self
+
+    @final
+    def __exit__(
+        self,
+        __exc_type: type[BaseException] | None,
+        __exc_value: BaseException | None,
+        __traceback: TracebackType | None,
+    ) -> bool | None:
+        if __exc_value is not None:
+            self.rollback()
+            self.dispose()
+            return
+        try:
+            if self.autocommit_enabled:
+                self.commit()
+        except:
+            self.rollback()
+            raise
+        finally:
+            self.dispose()
+
+    @abstractmethod
+    def initialize(self) -> None: ...
+
+    @abstractmethod
+    def dispose(self) -> None: ...
+
+    @abstractmethod
+    def commit(self) -> None: ...
+
+    @abstractmethod
+    def rollback(self) -> None: ...
+
+
+class AbstractAsyncTransaction(IAsyncDisposable, ABC):
+    autocommit_enabled: bool
+
+    def __init__(self, autocommit: bool = True) -> None:
+        self.autocommit_enabled = autocommit
+
+    @final
+    async def __aenter__(self) -> Self:
+        await self.initialize()
+        return self
+
+    @final
+    async def __aexit__(
+        self,
+        __exc_type: type[BaseException] | None,
+        __exc_value: BaseException | None,
+        __traceback: TracebackType | None,
+    ) -> bool | None:
+        if __exc_value is not None:
+            await self.rollback()
+            await self.dispose()
+            return
+        try:
+            if self.autocommit_enabled:
+                await self.commit()
+        except:
+            await self.rollback()
+            raise
+        finally:
+            await self.dispose()
+
+    @abstractmethod
+    async def initialize(self) -> None: ...
+
+    @abstractmethod
+    async def dispose(self) -> None: ...
+
+    @abstractmethod
+    async def commit(self) -> None: ...
+
+    @abstractmethod
+    async def rollback(self) -> None: ...

spakky_data-4.0.0/src/spakky/data/stereotype/repository.py

@@ -0,0 +1,20 @@
+"""Repository stereotype for data access layer.
+
+This module provides @Repository stereotype for organizing classes
+that handle data persistence and retrieval.
+"""
+
+from dataclasses import dataclass
+
+from spakky.core.pod.annotations.pod import Pod
+
+
+@dataclass(eq=False)
+class Repository(Pod):
+    """Stereotype for repository classes handling data access.
+
+    Repositories provide an abstraction over data sources,
+    implementing data access patterns and queries.
+    """
+
+    ...