pico-sqlalchemy 0.1.0__py3-none-any.whl

pico_sqlalchemy/__init__.py

@@ -0,0 +1,20 @@
+from .config import DatabaseSettings, DatabaseConfigurer
+from .decorators import transactional, repository
+from .session import SessionManager, get_session
+from .interceptor import TransactionalInterceptor
+from .factory import SqlAlchemyFactory
+from .base import AppBase, Mapped, mapped_column
+
+__all__ = [
+    "DatabaseSettings",
+    "DatabaseConfigurer",
+    "transactional",
+    "repository",
+    "SessionManager",
+    "get_session",
+    "TransactionalInterceptor",
+    "SqlAlchemyFactory",
+    "AppBase",
+    "Mapped",
+    "mapped_column",
+]

pico_sqlalchemy/_version.py

@@ -0,0 +1 @@
+__version__ = '0.1.0'

pico_sqlalchemy/base.py

@@ -0,0 +1,10 @@
+from sqlalchemy.orm import DeclarativeBase, Mapped, mapped_column
+from pico_ioc import component
+
+
+@component(scope="singleton")
+class AppBase(DeclarativeBase):
+    pass
+
+
+__all__ = ["AppBase", "Mapped", "mapped_column"]

pico_sqlalchemy/config.py

@@ -0,0 +1,23 @@
+from dataclasses import dataclass
+from typing import Protocol, runtime_checkable
+from pico_ioc import configured
+
+
+@runtime_checkable
+class DatabaseConfigurer(Protocol):
+    @property
+    def priority(self) -> int:
+        return 0
+
+    def configure(self, engine) -> None:
+        raise NotImplementedError
+
+
+@configured(target="self", prefix="database", mapping="tree")
+@dataclass
+class DatabaseSettings:
+    url: str = "sqlite:///./app.db"
+    echo: bool = False
+    pool_size: int = 5
+    pool_pre_ping: bool = True
+    pool_recycle: int = 3600

pico_sqlalchemy/decorators.py

@@ -0,0 +1,89 @@
+from typing import Any, Callable, Optional, ParamSpec, TypeVar, Set
+from pico_ioc import component
+import inspect
+
+from .session import get_default_session_manager
+
+P = ParamSpec("P")
+R = TypeVar("R")
+
+TRANSACTIONAL_META = "_pico_sqlalchemy_transactional_meta"
+REPOSITORY_META = "_pico_sqlalchemy_repository_meta"
+REPOSITORIES: Set[type] = set()
+
+
+def transactional(
+    *,
+    propagation: str = "REQUIRED",
+    read_only: bool = False,
+    isolation_level: Optional[str] = None,
+    rollback_for: tuple[type[BaseException], ...] = (Exception,),
+    no_rollback_for: tuple[type[BaseException], ...] = (),
+) -> Callable[[Callable[P, R]], Callable[P, R]]:
+    valid = {
+        "REQUIRED",
+        "REQUIRES_NEW",
+        "SUPPORTS",
+        "MANDATORY",
+        "NOT_SUPPORTED",
+        "NEVER",
+    }
+    if propagation not in valid:
+        raise ValueError(f"Invalid propagation: {propagation}")
+
+    metadata = {
+        "propagation": propagation,
+        "read_only": read_only,
+        "isolation_level": isolation_level,
+        "rollback_for": rollback_for,
+        "no_rollback_for": no_rollback_for,
+    }
+
+    def decorator(func: Callable[P, R]) -> Callable[P, R]:
+        setattr(func, TRANSACTIONAL_META, metadata)
+
+        if inspect.iscoroutinefunction(func):
+
+            async def async_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+                manager = get_default_session_manager()
+                if manager is None:
+                    return await func(*args, **kwargs)
+                async with manager.transaction(
+                    propagation=propagation,
+                    read_only=read_only,
+                    isolation_level=isolation_level,
+                    rollback_for=rollback_for,
+                    no_rollback_for=no_rollback_for,
+                ):
+                    return await func(*args, **kwargs)
+
+            setattr(async_wrapper, TRANSACTIONAL_META, metadata)
+            return async_wrapper
+
+        def sync_wrapper(*args: P.args, **kwargs: P.kwargs) -> R:
+            raise TypeError(
+                f"Cannot apply @transactional to sync function '{func.__name__}' "
+                "when using an async SessionManager."
+            )
+
+        setattr(sync_wrapper, TRANSACTIONAL_META, metadata)
+        return sync_wrapper
+
+    return decorator
+
+
+def repository(
+    cls: Optional[type[Any]] = None,
+    *,
+    scope: str = "singleton",
+    **kwargs: Any,
+) -> Callable[[type[Any]], type[Any]] | type[Any]:
+    def decorate(c: type[Any]) -> type[Any]:
+        setattr(c, REPOSITORY_META, kwargs)
+        REPOSITORIES.add(c)
+        return component(c, scope=scope, **kwargs)
+
+    if cls is not None:
+        return decorate(cls)
+
+    return decorate

pico_sqlalchemy/factory.py

@@ -0,0 +1,46 @@
+from typing import List
+from pico_ioc import configure, factory, provides, component
+from .config import DatabaseConfigurer, DatabaseSettings
+from .session import SessionManager, set_default_session_manager
+
+
+def _priority_of(obj):
+    try:
+        return int(getattr(obj, "priority", 0))
+    except Exception:
+        return 0
+
+
+@component
+class PicoSqlAlchemyLifecycle:
+    @configure
+    def setup_database(
+        self,
+        session_manager: SessionManager,
+        configurers: List[DatabaseConfigurer],
+    ) -> None:
+        valid = [
+            c
+            for c in configurers
+            if isinstance(c, DatabaseConfigurer)
+            and callable(getattr(c, "configure", None))
+        ]
+        ordered = sorted(valid, key=_priority_of)
+        for cfg in ordered:
+            cfg.configure(session_manager.engine)
+
+
+@factory
+class SqlAlchemyFactory:
+    @provides(SessionManager, scope="singleton")
+    def create_session_manager(self, settings: DatabaseSettings) -> SessionManager:
+        manager = SessionManager(
+            url=settings.url,
+            echo=settings.echo,
+            pool_size=settings.pool_size,
+            pool_pre_ping=settings.pool_pre_ping,
+            pool_recycle=settings.pool_recycle,
+        )
+        set_default_session_manager(manager)
+        return manager
+

pico_sqlalchemy/interceptor.py

@@ -0,0 +1,39 @@
+import inspect
+from typing import Any, Callable
+from pico_ioc import MethodCtx, MethodInterceptor, component
+from .decorators import TRANSACTIONAL_META
+from .session import SessionManager
+
+
+@component
+class TransactionalInterceptor(MethodInterceptor):
+    def __init__(self, session_manager: SessionManager):
+        self.sm = session_manager
+
+    async def invoke(self, ctx: MethodCtx, call_next: Callable[[MethodCtx], Any]) -> Any:
+        func = getattr(ctx.cls, ctx.name, None)
+        meta = getattr(func, TRANSACTIONAL_META, None)
+
+        if not meta:
+            result = call_next(ctx)
+            if inspect.isawaitable(result):
+                return await result
+            return result
+
+        propagation = meta["propagation"]
+        read_only = meta["read_only"]
+        isolation = meta["isolation_level"]
+        rollback_for = meta["rollback_for"]
+        no_rollback_for = meta["no_rollback_for"]
+
+        async with self.sm.transaction(
+            propagation=propagation,
+            read_only=read_only,
+            isolation_level=isolation,
+            rollback_for=rollback_for,
+            no_rollback_for=no_rollback_for,
+        ):
+            result = call_next(ctx)
+            if inspect.isawaitable(result):
+                result = await result
+            return result

pico_sqlalchemy/session.py

@@ -0,0 +1,205 @@
+import contextvars
+from contextlib import asynccontextmanager
+from typing import Generator, Optional, Dict, Any
+
+from sqlalchemy import Engine
+from sqlalchemy.ext.asyncio import create_async_engine, AsyncEngine, AsyncSession
+from sqlalchemy.orm import Session, sessionmaker
+from pico_ioc import component
+
+_tx_context: contextvars.ContextVar["TransactionContext | None"] = contextvars.ContextVar(
+    "pico_sqlalchemy_tx_context", default=None
+)
+_default_manager: Optional["SessionManager"] = None
+
+
+def set_default_session_manager(manager: "SessionManager") -> None:
+    global _default_manager
+    _default_manager = manager
+
+
+def get_default_session_manager() -> Optional["SessionManager"]:
+    return _default_manager
+
+
+class TransactionContext:
+    __slots__ = ("session",)
+
+    def __init__(self, session: AsyncSession):
+        self.session = session
+
+
+@component(scope="singleton")
+class SessionManager:
+    def __init__(
+        self,
+        url: str,
+        echo: bool = False,
+        pool_size: int = 5,
+        pool_pre_ping: bool = True,
+        pool_recycle: int = 3600,
+    ):
+        engine_kwargs: Dict[str, Any] = {"echo": echo}
+
+        is_memory_sqlite = "sqlite" in url and ":memory:" in url
+
+        if not is_memory_sqlite:
+            engine_kwargs["pool_size"] = pool_size
+            engine_kwargs["pool_pre_ping"] = pool_pre_ping
+            engine_kwargs["pool_recycle"] = pool_recycle
+
+        self._engine: AsyncEngine = create_async_engine(
+            url, **engine_kwargs
+        )
+        self._session_factory = sessionmaker(
+            bind=self._engine,
+            class_=AsyncSession,
+            autoflush=False,
+            autocommit=False,
+            expire_on_commit=False,
+        )
+        set_default_session_manager(self)
+
+    @property
+    def engine(self) -> AsyncEngine:
+        return self._engine
+
+    def create_session(self) -> AsyncSession:
+        return self._session_factory()
+
+    def get_current_session(self) -> Optional[AsyncSession]:
+        ctx = _tx_context.get()
+        return ctx.session if ctx is not None else None
+
+    @asynccontextmanager
+    async def transaction(
+        self,
+        propagation: str = "REQUIRED",
+        read_only: bool = False,
+        isolation_level: Optional[str] = None,
+        rollback_for: tuple[type[BaseException], ...] = (Exception,),
+        no_rollback_for: tuple[type[BaseException], ...] = (),
+    ) -> Generator[AsyncSession, None, None]:
+        current = _tx_context.get()
+
+        if propagation == "MANDATORY":
+            if current is None:
+                raise RuntimeError("MANDATORY propagation requires active transaction")
+            yield current.session
+            return
+
+        if propagation == "NEVER":
+            if current is not None:
+                raise RuntimeError("NEVER propagation forbids active transaction")
+            session = self.create_session()
+            try:
+                yield session
+            finally:
+                await session.close()
+            return
+
+        if propagation == "NOT_SUPPORTED":
+            if current is not None:
+                token = _tx_context.set(None)
+                try:
+                    session = self.create_session()
+                    try:
+                        yield session
+                    finally:
+                        await session.close()
+                finally:
+                    _tx_context.reset(token)
+            else:
+                session = self.create_session()
+                try:
+                    yield session
+                finally:
+                    await session.close()
+            return
+
+        if propagation == "SUPPORTS":
+            if current is not None:
+                yield current.session
+                return
+            session = self.create_session()
+            try:
+                yield session
+            finally:
+                await session.close()
+            return
+
+        if propagation == "REQUIRES_NEW":
+            if current is not None:
+                parent_token = _tx_context.set(None)
+                try:
+                    async with self._start_transaction(
+                        read_only=read_only,
+                        isolation_level=isolation_level,
+                        rollback_for=rollback_for,
+                        no_rollback_for=no_rollback_for,
+                    ) as session:
+                        yield session
+                finally:
+                    _tx_context.reset(parent_token)
+            else:
+                async with self._start_transaction(
+                    read_only=read_only,
+                    isolation_level=isolation_level,
+                    rollback_for=rollback_for,
+                    no_rollback_for=no_rollback_for,
+                ) as session:
+                    yield session
+            return
+
+        if propagation == "REQUIRED":
+            if current is not None:
+                yield current.session
+                return
+            async with self._start_transaction(
+                read_only=read_only,
+                isolation_level=isolation_level,
+                rollback_for=rollback_for,
+                no_rollback_for=no_rollback_for,
+            ) as session:
+                yield session
+            return
+
+        raise ValueError(f"Unknown propagation: {propagation}")
+
+    @asynccontextmanager
+    async def _start_transaction(
+        self,
+        read_only: bool,
+        isolation_level: Optional[str],
+        rollback_for: tuple[type[BaseException], ...],
+        no_rollback_for: tuple[type[BaseException], ...],
+    ) -> Generator[AsyncSession, None, None]:
+        session = self.create_session()
+        if isolation_level:
+            await session.connection(
+                execution_options={"isolation_level": isolation_level}
+            )
+
+        ctx = TransactionContext(session)
+        token = _tx_context.set(ctx)
+        try:
+            yield session
+            if not read_only:
+                await session.commit()
+        except BaseException as e:
+            should_rollback = isinstance(e, rollback_for) and not isinstance(
+                e, no_rollback_for
+            )
+            if should_rollback:
+                await session.rollback()
+            raise
+        finally:
+            _tx_context.reset(token)
+            await session.close()
+
+
+def get_session(manager: SessionManager) -> AsyncSession:
+    session = manager.get_current_session()
+    if session is None:
+        raise RuntimeError("No active transaction")
+    return session

pico_sqlalchemy-0.1.0.dist-info/METADATA

@@ -0,0 +1,357 @@
+Metadata-Version: 2.4
+Name: pico-sqlalchemy
+Version: 0.1.0
+Summary: Pico-ioc integration for SQLAlchemy. Adds Spring-style transactional support, configuration, and helpers.
+Author-email: David Perez Cabrera <dperezcabrera@gmail.com>
+License: MIT License
+        
+        Copyright (c) 2025 David Perez
+        
+        Permission is hereby granted, free of charge, to any person obtaining a copy
+        of this software and associated documentation files (the "Software"), to deal
+        in the Software without restriction, including without limitation the rights
+        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+        copies of the Software, and to permit persons to whom the Software is
+        furnished to do so, subject to the following conditions:
+        
+        The above copyright notice and this permission notice shall be included in all
+        copies or substantial portions of the Software.
+        
+        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+        SOFTWARE.
+        
+Project-URL: Homepage, https://github.com/dperezcabrera/pico-sqlalchemy
+Project-URL: Repository, https://github.com/dperezcabrera/pico-sqlalchemy
+Project-URL: Issue Tracker, https://github.com/dperezcabrera/pico-sqlalchemy/issues
+Keywords: ioc,di,dependency injection,sqlalchemy,transaction,orm,inversion of control,asyncio
+Classifier: Development Status :: 4 - Beta
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Database
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: pico-ioc>=2.0
+Requires-Dist: sqlalchemy>=2.0
+Provides-Extra: async
+Requires-Dist: asyncpg>=0.29.0; extra == "async"
+Provides-Extra: test
+Requires-Dist: pytest>=8; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.5; extra == "test"
+Requires-Dist: pytest-cov>=5; extra == "test"
+Dynamic: license-file
+
+# 📦 pico-sqlalchemy
+
+[![PyPI](https://img.shields.io/pypi/v/pico-sqlalchemy.svg)](https://pypi.org/project/pico-sqlalchemy/)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/dperezcabrera/pico-sqlalchemy)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
+![CI (tox matrix)](https://github.com/dperezcabrera/pico-sqlalchemy/actions/workflows/ci.yml/badge.svg)
+[![codecov](https://codecov.io/gh/dperezcabrera/pico-sqlalchemy/branch/main/graph/badge.svg)](https://codecov.io/gh/dperezcabrera/pico-sqlalchemy)
+[![Quality Gate Status](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-sqlalchemy\&metric=alert_status)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-sqlalchemy)
+[![Duplicated Lines (%)](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-sqlalchemy\&metric=duplicated_lines_density)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-sqlalchemy)
+[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=dperezcabrera_pico-sqlalchemy\&metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=dperezcabrera_pico-sqlalchemy)
+
+# Pico-SQLAlchemy
+
+**Pico-SQLAlchemy** integrates **[Pico-IoC](https://github.com/dperezcabrera/pico-ioc)** with **SQLAlchemy**, providing real inversion of control for your persistence layer, with declarative repositories, transactional boundaries, and clean architectural isolation.
+
+It brings constructor-based dependency injection, transparent transaction management, and a repository pattern inspired by the elegance of Spring Data — but using pure Python, Pico-IoC, and SQLAlchemy’s ORM.
+
+> 🐍 Requires Python 3.10+
+> 🚀 **Async-Native:** Built entirely on SQLAlchemy's async ORM (`AsyncSession`, `create_async_engine`).
+> 🧩 Works with SQLAlchemy 2.0+ ORM
+> 🔄 Automatic async transaction management
+> 🧪 Fully testable without a running DB
+
+With Pico-SQLAlchemy you get the expressive power of SQLAlchemy with proper IoC, clean layering, and annotation-driven transactions.
+
+---
+
+## 🎯 Why pico-sqlalchemy
+
+SQLAlchemy is powerful, but most applications end up with raw session handling, manual transaction scopes, or ad-hoc repository patterns.
+
+Pico-SQLAlchemy provides:
+
+* Constructor-injected repositories and services
+* Declarative `@transactional` boundaries
+* `REQUIRES_NEW`, `READ_ONLY`, `MANDATORY`, and all familiar propagation modes
+* `SessionManager` that centralizes engine/session lifecycle
+* Clean decoupling from frameworks (FastAPI, Flask, CLI, workers)
+
+| Concern | SQLAlchemy Default | pico-sqlalchemy |
+| :--- | :--- | :--- |
+| Managing sessions | Manual `AsyncSession()` | Automatic |
+| Transactions | Explicit `await commit()` / `await rollback()` | Declarative `@transactional` |
+| Repository pattern | DIY, inconsistent | First-class `@repository` |
+| Dependency injection | None | IoC-driven constructor injection |
+| Testability | Manual setup | Container-managed + overrides |
+
+---
+
+## 🧱 Core Features
+
+* Repository classes with `@repository`
+* Declarative transactions via `@transactional`
+* Full propagation semantics (`REQUIRED`, `REQUIRES_NEW`, `MANDATORY`, etc.)
+* Automatic `AsyncSession` lifecycle
+* Centralized `AsyncEngine` + session factory via `SessionManager`
+* Transaction-aware `get_session()` for repository methods
+* Plug-and-play integration with any Pico-IoC app (FastAPI, CLI tools, workers, event handlers)
+
+---
+
+## 📦 Installation
+
+```bash
+pip install pico-sqlalchemy
+```
+
+Also install `pico-ioc`, `sqlalchemy`, and an **async driver**:
+
+```bash
+pip install pico-ioc sqlalchemy
+pip install aiosqlite  # For SQLite
+# pip install asyncpg    # For PostgreSQL
+```
+
+-----
+
+## 🚀 Quick Example
+
+### Define your model:
+
+```python
+from sqlalchemy import Integer, String
+from pico_sqlalchemy import AppBase, Mapped, mapped_column
+
+class User(AppBase):
+    __tablename__ = "users"
+    id: Mapped[int] = mapped_column(Integer, primary_key=True)
+    username: Mapped[str] = mapped_column(String(50))
+```
+
+### Define a repository:
+
+```python
+from sqlalchemy.future import select
+from pico_sqlalchemy import repository, transactional, get_session, SessionManager
+
+@repository
+class UserRepository:
+    def __init__(self, manager: SessionManager):
+        self.manager = manager
+
+    @transactional
+    async def save(self, user: User) -> User:
+        session = get_session(self.manager)
+        session.add(user)
+        return user
+
+    @transactional(read_only=True)
+    async def find_all(self) -> list[User]:
+        session = get_session(self.manager)
+        stmt = select(User).order_by(User.username)
+        result = await session.scalars(stmt)
+        return list(result.all())
+```
+
+### Define a service:
+
+```python
+from pico_ioc import component
+
+@component
+class UserService:
+    def __init__(self, repo: UserRepository):
+        self.repo = repo
+
+    @transactional
+    async def create(self, name: str) -> User:
+        user = User(username=name)
+        user = await self.repo.save(user)
+        
+        session = get_session(self.repo.manager)
+        await session.flush()
+        await session.refresh(user)
+        return user
+```
+
+### Initialize Pico-IoC and run:
+
+```python
+import asyncio
+from pico_ioc import init, configuration, DictSource
+
+config = configuration(DictSource({
+    "database": {
+        "url": "sqlite+aiosqlite:///:memory:", # Async URL
+        "echo": False
+    }
+}))
+
+container = init(
+    modules=["services", "repositories", "pico_sqlalchemy"],
+    config=config,
+)
+
+async def main():
+    # Use await container.aget() for async resolution
+    service = await container.aget(UserService)
+    
+    # Await the async service method
+    user = await service.create("alice")
+    print(f"Created user: {user.id}")
+
+    # Clean up async resources
+    await container.cleanup_all_async()
+
+if __name__ == "__main__":
+    asyncio.run(main())
+```
+
+-----
+
+## 🔄 Transaction Propagation Modes
+
+Pico-SQLAlchemy supports the core Spring-inspired semantics:
+
+| Mode | Behavior |
+| :--- | :--- |
+| `REQUIRED` | Join existing tx or create new |
+| `REQUIRES_NEW` | Suspend parent and start new tx |
+| `SUPPORTS` | Join if exists, else run without tx |
+| `MANDATORY` | Requires existing tx |
+| `NOT_SUPPORTED`| Run without tx, suspending parent |
+| `NEVER` | Fail if a tx exists |
+
+Example:
+
+```python
+@transactional(propagation="REQUIRES_NEW")
+async def write_audit(self, entry: AuditEntry):
+    ...
+```
+
+-----
+
+## 🧪 Testing with Pico-IoC
+
+You can override repositories, engines, or services easily:
+
+```python
+import pytest
+import pytest_asyncio
+from pico_ioc import init, configuration, DictSource
+from pico_sqlalchemy import SessionManager, AppBase
+
+# In conftest.py
+@pytest_asyncio.fixture
+async def container():
+    cfg = configuration(DictSource({"database": {"url": "sqlite+aiosqlite:///:memory:"}}))
+    c = init(modules=["pico_sqlalchemy", "myapp"], config=cfg)
+    
+    # Setup the in-memory database
+    sm = await c.aget(SessionManager)
+    async with sm.engine.begin() as conn:
+        await conn.run_sync(AppBase.metadata.create_all)
+
+    yield c
+    
+    # Clean up all async components
+    await c.cleanup_all_async()
+
+# In your test
+@pytest.mark.asyncio
+async def test_my_service(container):
+    service = await container.aget(UserService)
+    user = await service.create("test")
+    assert user.id is not None
+```
+
+-----
+
+## 🧬 Example: Custom Database Configurer
+
+```python
+from pico_sqlalchemy import DatabaseConfigurer, AppBase
+from pico_ioc import component
+import asyncio
+
+@component
+class TableCreationConfigurer(DatabaseConfigurer):
+    priority = 10
+    def __init__(self, base: AppBase):
+        self.base = base
+        
+    def configure(self, engine):
+        # This configure method is called by the factory.
+        # We need to run the async setup.
+        async def setup():
+            async with engine.begin() as conn:
+                await conn.run_sync(self.base.metadata.create_all)
+        
+        asyncio.run(setup())
+```
+
+Pico-SQLAlchemy will detect it and call `configure` during initialization.
+
+-----
+
+## ⚙️ How It Works
+
+  * `SessionManager` is created by Pico-IoC (`SqlAlchemyFactory`)
+  * A global session context is established via `contextvars`
+  * `@transactional` automatically opens/closes async transactions
+  * `@repository` registers a class as a singleton component
+  * All dependencies (repositories, services, configurers) are resolved by Pico-IoC
+
+No globals. No implicit singletons. No framework coupling.
+
+-----
+
+## 💡 Architecture Overview
+
+```
+                 ┌─────────────────────────────┐
+                 │         Your App            │
+                 └──────────────┬──────────────┘
+                                │
+                      Constructor Injection
+                                │
+                 ┌──────────────▼───────────────┐
+                 │          Pico-IoC            │
+                 └──────────────┬───────────────┘
+                                │
+                 SessionManager / SqlAlchemyFactory
+                                │
+                 ┌──────────────▼───────────────┐
+                 │       pico-sqlalchemy        │
+                 │ Transactional Decorators     │
+                 │ Repository Metadata          │
+                 └──────────────┬───────────────┘
+                                │
+                             SQLAlchemy
+                           (Async ORM)
+```
+
+-----
+
+## 📝 License
+
+MIT
+

pico_sqlalchemy-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pico_sqlalchemy/__init__.py,sha256=xQ4q2D_-qjDUBwu5D5xIIk7cTa9oqrnAtCRWTmbS9Bg,546
+pico_sqlalchemy/_version.py,sha256=IMjkMO3twhQzluVTo8Z6rE7Eg-9U79_LGKMcsWLKBkY,22
+pico_sqlalchemy/base.py,sha256=YvwsUQiOdm7aKioV3Rpgkif_iBnQafz8cT20JUPSePI,221
+pico_sqlalchemy/config.py,sha256=nqZjWnPQIJqecydENcZSyaBwGRrqMNiyco7hmjDIPis,549
+pico_sqlalchemy/decorators.py,sha256=928rtYkhsCsrZk6zC77x38GglbD7k0N9YRvBERXkuE4,2724
+pico_sqlalchemy/factory.py,sha256=dGE5n5P8n96-6Q2jONsN7-pw4isM0YSaFmqc6C6EDiI,1320
+pico_sqlalchemy/interceptor.py,sha256=4f2FoWJk4XJFon3hdUC2UwrFRlVnQHvCX9X9baIykaw,1309
+pico_sqlalchemy/session.py,sha256=UOW7saISQ9OLMQbqSxnOZZrqD39zmhPo1D4WbKUddwo,6582
+pico_sqlalchemy-0.1.0.dist-info/licenses/LICENSE,sha256=j86ePhARUMlHapXj0uGGdmnRTholb6VMoORCv8jkGdU,1068
+pico_sqlalchemy-0.1.0.dist-info/METADATA,sha256=OHjl9p3SAxwMakZNUIWTtXRMd7prPFd5wsFKeEF1CYo,12786
+pico_sqlalchemy-0.1.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+pico_sqlalchemy-0.1.0.dist-info/top_level.txt,sha256=NYXrmd16JCyVKtyNLqsxfeoirlnos4dlPjSLgHuwHG4,16
+pico_sqlalchemy-0.1.0.dist-info/RECORD,,

pico_sqlalchemy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (80.9.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pico_sqlalchemy-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 David Perez
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pico_sqlalchemy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pico_sqlalchemy