pico-sqlalchemy 0.1.0__tar.gz

pico_sqlalchemy-0.1.0/.coveragerc

@@ -0,0 +1,17 @@
+[run]
+branch = True
+source =
+    pico_fastapi
+omit =
+    */_version.py
+
+[paths]
+pico_fastapi =
+    src/pico_fastapi
+    .tox/*/lib/*/site-packages/pico_fastapi
+    .tox/*/site-packages/pico_fastapi
+    */site-packages/pico_fastapi
+
+[report]
+show_missing = True
+

pico_sqlalchemy-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,106 @@
+name: CI & Coverage
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+
+jobs:
+  tests:
+    name: Tests (Python ${{ matrix.python-version }})
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: [ "3.10", "3.11", "3.12", "3.13", "3.14" ]
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install tox
+        run: |
+          python -m pip install --upgrade pip
+          pip install tox
+
+      - name: Install build dependencies
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y build-essential
+
+      - name: Run tests with coverage (writes to repo root)
+        shell: bash
+        run: |
+          set -euxo pipefail
+          tox -e cov
+          # Rename to per-version file for artifact + merge job
+          mv .coverage .coverage.${{ matrix.python-version }}
+          ls -la .coverage.${{ matrix.python-version }}
+
+      - name: Upload .coverage artifact
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-${{ matrix.python-version }}
+          path: .coverage.${{ matrix.python-version }}
+          include-hidden-files: true
+          if-no-files-found: error
+
+  coverage-merge:
+    name: Merge coverage
+    runs-on: ubuntu-latest
+    needs: tests
+    steps:
+      - name: Checkout (for repo context)
+        uses: actions/checkout@v4
+
+      - name: Download all coverage artifacts
+        uses: actions/download-artifact@v4
+        with:
+          path: coverage-reports
+
+      - name: Combine coverage and generate reports
+        shell: bash
+        run: |
+          set -euxo pipefail
+          python -m pip install coverage
+          files=$(find coverage-reports -type f -name ".coverage.*" -print)
+          if [ -z "$files" ]; then
+            echo "No coverage data files found"; exit 1
+          fi
+          coverage combine $files
+          coverage report -m --rcfile=.coveragerc
+          coverage xml -o coverage.xml --rcfile=.coveragerc
+          coverage html -d htmlcov --rcfile=.coveragerc
+
+      - name: Upload combined coverage XML
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-xml
+          path: coverage.xml
+          if-no-files-found: error
+
+      - name: Upload HTML coverage report
+        uses: actions/upload-artifact@v4
+        with:
+          name: coverage-html
+          path: htmlcov
+          if-no-files-found: error
+
+      - name: Upload to Codecov
+        if: always() && !cancelled()
+        uses: codecov/codecov-action@v5
+        continue-on-error: true
+        with:
+          files: coverage.xml
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}
+          slug: dperezcabrera/pico-sqlalchemy

pico_sqlalchemy-0.1.0/.github/workflows/publish-to-pypi.yml

@@ -0,0 +1,36 @@
+name: Publish Python Package to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  deploy:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+    - uses: actions/checkout@v4
+      with:
+        fetch-depth: 0
+
+    - name: Set up Python
+      uses: actions/setup-python@v5
+      with:
+        python-version: '3.x'
+
+    - name: Install build deps
+      run: python -m pip install --upgrade pip build
+
+    - name: Build package
+      run: python -m build
+
+    - name: Publish to PyPI
+      uses: pypa/gh-action-pypi-publish@release/v1
+      with:
+        skip-existing: true
+        verify-metadata: true
+        attestations: false
+

pico_sqlalchemy-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.html).
+
+---
+
+## [Unreleased]
+
+### Added
+
+* Initial public release of `pico-sqlalchemy`.
+* **Async-Native Core:** Built entirely on SQLAlchemy's async ORM (`AsyncSession`, `create_async_engine`).
+* **`@transactional`** decorator providing Spring-style, async-native transactional method boundaries with propagation modes:
+  `REQUIRED`, `REQUIRES_NEW`, `SUPPORTS`, `MANDATORY`, `NOT_SUPPORTED`, and `NEVER`.
+* **`SessionManager`** singleton responsible for:
+  * creating the SQLAlchemy `AsyncEngine`
+  * managing `AsyncSession` instances
+  * implementing async transaction semantics
+  * `await commit()` / `await rollback()` behavior
+* **`get_session()`** helper for retrieving the currently active `AsyncSession` inside transactional methods.
+* **`TransactionalInterceptor`** implementing AOP-based async transaction handling for methods decorated with `@transactional`.
+* **`DatabaseSettings`** dataclass for type-safe, IOC-managed configuration of SQLAlchemy (URL, pool options, echo).
+* **`DatabaseConfigurer`** protocol for extensible, ordered database initialization hooks (e.g., migrations, DDL, seeding).
+* **`SqlAlchemyFactory`** to register and wire the `SessionManager` and configuration into the IoC container.
+* **`AppBase`**, `Mapped`, and `mapped_column` declarative base components registered for SQLAlchemy models.
+* Async-native in-memory SQLite support (`aiosqlite`) out of the box (useful for testing).
+* Test suite validating async `SessionManager` commit/rollback behavior and transactional propagation.

pico_sqlalchemy-0.1.0/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/MANIFEST.in

@@ -0,0 +1,24 @@
+# Incluir ficheros importantes
+include README.md
+include LICENSE
+
+# Incluir todo el código fuente
+recursive-include src *.py
+
+# Incluir datos de tests si quieres que otros puedan correrlos desde el sdist
+# (opcional — puedes quitarlo si no quieres incluir tests en PyPI)
+recursive-include tests *.py
+
+# Excluir cosas innecesarias
+exclude .gitignore
+exclude Dockerfile*
+exclude docker-compose*.yml
+exclude Makefile
+
+# Excluir carpetas de build, virtualenvs, caches, etc.
+prune build
+prune dist
+prune .tox
+prune .pytest_cache
+prune __pycache__
+

pico_sqlalchemy-0.1.0/PKG-INFO

@@ -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
+