pico-sqlalchemy 0.3.0__tar.gz → 0.4.0__tar.gz

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/.github/workflows/publish-to-pypi.yml

@@ -27,6 +27,18 @@ jobs:
     - name: Build package
       run: python -m build
 
+    - name: Reject non-clean versions (.dev / .post)
+      run: |
+        python - <<'PY'
+        import glob, sys
+        whl = sorted(glob.glob('dist/*.whl'))[0]
+        ver = whl.split('-')[1]
+        print(f"Built version: {ver}")
+        if 'dev' in ver or 'post' in ver:
+            sys.exit(f"::error::Refusing to publish non-clean version '{ver}'. "
+                     "Create the GitHub Release from an exact version tag (e.g. v0.4.0).")
+        PY
+
     - name: Publish to PyPI
       uses: pypa/gh-action-pypi-publish@release/v1
       with:

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/AGENTS.md

@@ -35,9 +35,10 @@ src/pico_sqlalchemy/
 - **Propagation modes**: REQUIRED, REQUIRES_NEW, MANDATORY, NEVER, NOT_SUPPORTED, SUPPORTS
 - **Priority chain**: `@transactional` > `@query` (read-only) > `@repository` (read-write)
 - **`SessionManager`**: Created by `SqlAlchemyFactory` (not `@component`). Manages engine, sessions, transactions
-- **`_tx_context` ContextVar**: Holds `TransactionContext` for session propagation. Separate from pico-ioc's "transaction" scope (which is for DI caching)
+- **`_tx_context` ContextVar**: Holds `TransactionContext` (the session) for propagation across nested calls — the *session* side of a transaction
+- **`"transaction"` DI scope**: `TransactionalInterceptor` activates pico-ioc's `"transaction"` scope (with `cleanup=True`) whenever a *new* transaction starts (REQUIRES_NEW, or REQUIRED with no enclosing tx). So a `scope="transaction"` component is one instance per transaction (Unit-of-Work / identity-map), released with its `@cleanup` hooks when the tx ends. The session ContextVar and the DI scope are two facets of one boundary
 - **`get_session(manager)`**: Returns current session from active transaction context
-- **Non-transactional paths** (NEVER, NOT_SUPPORTED, SUPPORTS without tx): Still set `TransactionContext` so `get_session()` works
+- **Non-transactional paths** (NEVER, NOT_SUPPORTED, SUPPORTS without tx): Still set `TransactionContext` so `get_session()` works, but open no DI `"transaction"` scope (resolving a `scope="transaction"` component there raises `ScopeError`)
 
 ## Code Style
 
@@ -59,4 +60,4 @@ src/pico_sqlalchemy/
 
 - Do not modify `_version.py`
 - Do not add `@component` to `SessionManager` (factory creates it)
-- `_tx_context` ContextVar is intentional and separate from pico-ioc scope system
+- `_tx_context` (session propagation) and the pico-ioc `"transaction"` DI scope are bound to one boundary by `TransactionalInterceptor` — keep them coordinated; do not reintroduce a second, independent transaction concept

{pico_sqlalchemy-0.3.0/docs → pico_sqlalchemy-0.4.0}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.h
 
 ---
 
+## [0.4.0] - 2026-06-07
+
+### Added
+- **Transaction-scoped DI**: `TransactionalInterceptor` now binds pico-ioc's `"transaction"` DI scope to the database transaction boundary. When a *new* transaction starts (`REQUIRES_NEW`, or `REQUIRED` with no enclosing transaction) it activates a fresh `"transaction"` scope (via `container.scope(..., cleanup=True)`) for the duration of the call, so components registered with `scope="transaction"` live exactly one transaction and run their `@cleanup` hooks when it ends. Joins reuse the enclosing scope. Requires **pico-ioc >= 2.2.6**.
+- `tests/test_transaction_scope.py`: covers one-instance-per-transaction, sharing within a transaction, `REQUIRES_NEW` scope push/restore, fail-fast resolution outside a transaction, and `@cleanup` on transaction end.
+
+### Changed
+- Bumped `pico-ioc` dependency to `>= 2.2.6`.
+
+---
+
 ## [0.3.0] - 2026-02-20
 
 ### Changed

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/CLAUDE.md

@@ -10,10 +10,10 @@ pico-sqlalchemy provides SQLAlchemy integration for pico-ioc. It uses:
 
 ## Key Reminders
 
-- pico-ioc dependency: `>= 2.2.0`
+- pico-ioc dependency: `>= 2.2.6` (needs `container.scope(..., cleanup=True)`)
 - **NEVER change `version_scheme`** in pyproject.toml. It MUST remain `"post-release"`. Changing it to `"guess-next-dev"` causes `.dev0` versions to leak to PyPI. This was already fixed once — do not revert it.
 - requires-python >= 3.11
 - Commit messages: one line only
 - `@transactional` works both with and without parentheses (like `@repository`)
 - `SessionManager` has NO `@component` decorator - it's created by the factory
-- `_tx_context` ContextVar is for session propagation, NOT the same as pico-ioc's "transaction" scope
+- `_tx_context` ContextVar is the *session* side of a transaction (propagation across nested calls). `TransactionalInterceptor` binds pico-ioc's `"transaction"` DI scope to the *same* boundary: when a new transaction starts (REQUIRES_NEW, or REQUIRED with no enclosing tx) it activates a fresh `"transaction"` scope (with `cleanup=True`) for the call, so `scope="transaction"` components live exactly one transaction. They are two facets of one boundary, not separate mechanisms.

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-sqlalchemy
-Version: 0.3.0
+Version: 0.4.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
@@ -47,7 +47,7 @@ Classifier: Typing :: Typed
 Requires-Python: >=3.11
 Description-Content-Type: text/markdown
 License-File: LICENSE
-Requires-Dist: pico-ioc>=2.2.0
+Requires-Dist: pico-ioc>=2.2.6
 Requires-Dist: sqlalchemy>=2.0
 Provides-Extra: async
 Requires-Dist: asyncpg>=0.29.0; extra == "async"
@@ -57,7 +57,7 @@ Requires-Dist: pytest-asyncio>=0.23.5; extra == "test"
 Requires-Dist: pytest-cov>=5; extra == "test"
 Dynamic: license-file
 
-# 📦 pico-sqlalchemy
+# 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)
@@ -68,6 +68,7 @@ Dynamic: license-file
 [![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)
 [![Docs](https://img.shields.io/badge/Docs-pico--sqlalchemy-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-sqlalchemy/)
+[![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/pico-learn/)
 
 # Pico-SQLAlchemy
 
@@ -75,14 +76,14 @@ Dynamic: license-file
 
 It brings constructor-based dependency injection, **implicit transaction management**, and powerful **declarative queries** using pure Python and SQLAlchemy’s Async ORM.
 
-> 🐍 **Requires Python 3.11+**
-> 🚀 **Async-Native:** Built entirely on `AsyncSession` and `create_async_engine`.
-> ✨ **Zero-Boilerplate:** Repositories are transactional by default.
-> 🔍 **Declarative Queries:** Define SQL or expressions in decorators; the library executes them for you.
+> **Requires Python 3.11+**
+> **Async-Native:** Built entirely on `AsyncSession` and `create_async_engine`.
+> **Zero-Boilerplate:** Repositories are transactional by default.
+> **Declarative Queries:** Define SQL or expressions in decorators; the library executes them for you.
 
 ---
 
-## 🎯 Why pico-sqlalchemy?
+## Why pico-sqlalchemy?
 
 Most Python apps suffer from manual session handling (`async with session...`), scattered transaction logic, and verbose repository patterns.
 
@@ -98,7 +99,7 @@ Most Python apps suffer from manual session handling (`async with session...`),
 
 ---
 
-## 🧱 Core Features
+## Core Features
 
 * **Implicit Transactions:** Methods inside `@repository` are automatically **Read-Write** transactional.
 * **Declarative Queries:** Use `@query` to run SQL or Expressions automatically (defaults to **Read-Only**).
@@ -108,7 +109,7 @@ Most Python apps suffer from manual session handling (`async with session...`),
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 pip install pico-sqlalchemy
@@ -123,7 +124,7 @@ pip install asyncpg     # for PostgreSQL
 
 -----
 
-## 🚀 Quick Example
+## Quick Example
 
 ### 1\. Define Model
 
@@ -218,7 +219,7 @@ if __name__ == "__main__":
 
 -----
 
-## ⚡ Transaction Hierarchy & Rules
+## Transaction Hierarchy & Rules
 
 Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction configuration. The priority order (highest wins) is:
 
@@ -236,7 +237,7 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def update_user(self): ...
     ```
 
-    👉 **Result:** Active Read-Write Transaction (Implicit from `@repository`).
+    **Result:** Active Read-Write Transaction (Implicit from `@repository`).
 
 2.  **Query Method:**
 
@@ -245,7 +246,7 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def get_data(self): ...
     ```
 
-    👉 **Result:** Active Read-Only Transaction (Implicit from `@query`).
+    **Result:** Active Read-Only Transaction (Implicit from `@query`).
 
 3.  **Manual Override:**
 
@@ -254,11 +255,29 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def complex_report(self): ...
     ```
 
-    👉 **Result:** Active Read-Only Transaction (Explicit override).
+    **Result:** Active Read-Only Transaction (Explicit override).
+
+### Transaction-scoped components *(v0.4.0+)*
+
+Beyond managing the SQLAlchemy session, the interceptor binds pico-ioc's **`"transaction"` DI scope** to the same boundary. A component registered with `scope="transaction"` is instantiated **once per database transaction** and torn down (running its `@cleanup` hooks) when that transaction ends:
+
+```python
+@component(scope="transaction")
+class UnitOfWorkAudit:
+    def __init__(self):
+        self.events: list[str] = []
+
+    @cleanup
+    def flush(self):
+        # runs exactly when the enclosing transaction ends
+        ...
+```
+
+A **new** transaction (`REQUIRES_NEW`, or `REQUIRED` with no enclosing transaction) opens a fresh scope; **joins reuse** the enclosing one — so the session boundary and the DI lifetime are two facets of a single transaction. Requires **pico-ioc ≥ 2.2.6**.
 
 -----
 
-## 🔍 Declarative Queries in Depth
+## Declarative Queries in Depth
 
 The `@query` decorator eliminates boilerplate for common fetches.
 
@@ -293,7 +312,7 @@ async def find_active(self, page: PageRequest) -> Page[User]: ...
 
 -----
 
-## 🧪 Testing
+## Testing
 
 Testing is simple because you can override the configuration or the components easily using Pico-IoC.
 
@@ -311,7 +330,7 @@ async def test_service():
 
 -----
 
-## 💡 Architecture Overview
+## Architecture Overview
 
 ```
                  ┌─────────────────────────────┐
@@ -349,7 +368,7 @@ curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/instal
 |---------|-------------|
 | `/add-repository` | Add SQLAlchemy entities and repositories with transactions |
 | `/add-component` | Add components, factories, interceptors, settings |
-| `/add-tests` | Generate tests for pico-framework components |
+| `/add-tests` | Generate tests for pico components |
 
 All skills: `curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash`
 
@@ -357,6 +376,6 @@ See [pico-skills](https://github.com/dperezcabrera/pico-skills) for details.
 
 ---
 
-## 📝 License
+## License
 
 MIT

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/README.md

@@ -1,4 +1,4 @@
-# 📦 pico-sqlalchemy
+# 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)
@@ -9,6 +9,7 @@
 [![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)
 [![Docs](https://img.shields.io/badge/Docs-pico--sqlalchemy-blue?style=flat&logo=readthedocs&logoColor=white)](https://dperezcabrera.github.io/pico-sqlalchemy/)
+[![Interactive Lab](https://img.shields.io/badge/Learn-online-green?style=flat&logo=python&logoColor=white)](https://dperezcabrera.github.io/pico-learn/)
 
 # Pico-SQLAlchemy
 
@@ -16,14 +17,14 @@
 
 It brings constructor-based dependency injection, **implicit transaction management**, and powerful **declarative queries** using pure Python and SQLAlchemy’s Async ORM.
 
-> 🐍 **Requires Python 3.11+**
-> 🚀 **Async-Native:** Built entirely on `AsyncSession` and `create_async_engine`.
-> ✨ **Zero-Boilerplate:** Repositories are transactional by default.
-> 🔍 **Declarative Queries:** Define SQL or expressions in decorators; the library executes them for you.
+> **Requires Python 3.11+**
+> **Async-Native:** Built entirely on `AsyncSession` and `create_async_engine`.
+> **Zero-Boilerplate:** Repositories are transactional by default.
+> **Declarative Queries:** Define SQL or expressions in decorators; the library executes them for you.
 
 ---
 
-## 🎯 Why pico-sqlalchemy?
+## Why pico-sqlalchemy?
 
 Most Python apps suffer from manual session handling (`async with session...`), scattered transaction logic, and verbose repository patterns.
 
@@ -39,7 +40,7 @@ Most Python apps suffer from manual session handling (`async with session...`),
 
 ---
 
-## 🧱 Core Features
+## Core Features
 
 * **Implicit Transactions:** Methods inside `@repository` are automatically **Read-Write** transactional.
 * **Declarative Queries:** Use `@query` to run SQL or Expressions automatically (defaults to **Read-Only**).
@@ -49,7 +50,7 @@ Most Python apps suffer from manual session handling (`async with session...`),
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 pip install pico-sqlalchemy
@@ -64,7 +65,7 @@ pip install asyncpg     # for PostgreSQL
 
 -----
 
-## 🚀 Quick Example
+## Quick Example
 
 ### 1\. Define Model
 
@@ -159,7 +160,7 @@ if __name__ == "__main__":
 
 -----
 
-## ⚡ Transaction Hierarchy & Rules
+## Transaction Hierarchy & Rules
 
 Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction configuration. The priority order (highest wins) is:
 
@@ -177,7 +178,7 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def update_user(self): ...
     ```
 
-    👉 **Result:** Active Read-Write Transaction (Implicit from `@repository`).
+    **Result:** Active Read-Write Transaction (Implicit from `@repository`).
 
 2.  **Query Method:**
 
@@ -186,7 +187,7 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def get_data(self): ...
     ```
 
-    👉 **Result:** Active Read-Only Transaction (Implicit from `@query`).
+    **Result:** Active Read-Only Transaction (Implicit from `@query`).
 
 3.  **Manual Override:**
 
@@ -195,11 +196,29 @@ Pico-SQLAlchemy applies a "Best Effort" strategy to determine transaction config
     async def complex_report(self): ...
     ```
 
-    👉 **Result:** Active Read-Only Transaction (Explicit override).
+    **Result:** Active Read-Only Transaction (Explicit override).
+
+### Transaction-scoped components *(v0.4.0+)*
+
+Beyond managing the SQLAlchemy session, the interceptor binds pico-ioc's **`"transaction"` DI scope** to the same boundary. A component registered with `scope="transaction"` is instantiated **once per database transaction** and torn down (running its `@cleanup` hooks) when that transaction ends:
+
+```python
+@component(scope="transaction")
+class UnitOfWorkAudit:
+    def __init__(self):
+        self.events: list[str] = []
+
+    @cleanup
+    def flush(self):
+        # runs exactly when the enclosing transaction ends
+        ...
+```
+
+A **new** transaction (`REQUIRES_NEW`, or `REQUIRED` with no enclosing transaction) opens a fresh scope; **joins reuse** the enclosing one — so the session boundary and the DI lifetime are two facets of a single transaction. Requires **pico-ioc ≥ 2.2.6**.
 
 -----
 
-## 🔍 Declarative Queries in Depth
+## Declarative Queries in Depth
 
 The `@query` decorator eliminates boilerplate for common fetches.
 
@@ -234,7 +253,7 @@ async def find_active(self, page: PageRequest) -> Page[User]: ...
 
 -----
 
-## 🧪 Testing
+## Testing
 
 Testing is simple because you can override the configuration or the components easily using Pico-IoC.
 
@@ -252,7 +271,7 @@ async def test_service():
 
 -----
 
-## 💡 Architecture Overview
+## Architecture Overview
 
 ```
                  ┌─────────────────────────────┐
@@ -290,7 +309,7 @@ curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/instal
 |---------|-------------|
 | `/add-repository` | Add SQLAlchemy entities and repositories with transactions |
 | `/add-component` | Add components, factories, interceptors, settings |
-| `/add-tests` | Generate tests for pico-framework components |
+| `/add-tests` | Generate tests for pico components |
 
 All skills: `curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash`
 
@@ -298,6 +317,6 @@ See [pico-skills](https://github.com/dperezcabrera/pico-skills) for details.
 
 ---
 
-## 📝 License
+## License
 
 MIT

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0/docs}/CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.h
 
 ---
 
+## [0.4.0] - 2026-06-07
+
+### Added
+- **Transaction-scoped DI**: `TransactionalInterceptor` now binds pico-ioc's `"transaction"` DI scope to the database transaction boundary. When a *new* transaction starts (`REQUIRES_NEW`, or `REQUIRED` with no enclosing transaction) it activates a fresh `"transaction"` scope (via `container.scope(..., cleanup=True)`) for the duration of the call, so components registered with `scope="transaction"` live exactly one transaction and run their `@cleanup` hooks when it ends. Joins reuse the enclosing scope. Requires **pico-ioc >= 2.2.6**.
+- `tests/test_transaction_scope.py`: covers one-instance-per-transaction, sharing within a transaction, `REQUIRES_NEW` scope push/restore, fail-fast resolution outside a transaction, and `@cleanup` on transaction end.
+
+### Changed
+- Bumped `pico-ioc` dependency to `>= 2.2.6`.
+
+---
+
 ## [0.3.0] - 2026-02-20
 
 ### Changed

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/docs/architecture.md

@@ -118,7 +118,7 @@ pico-sqlalchemy uses a `ContextVar` to propagate the active session across async
 _tx_context: ContextVar[TransactionContext | None]
 ```
 
-This is **separate from pico-ioc's scope system**. It is a lightweight, per-async-task variable that stores the currently active `AsyncSession` wrapped in a `TransactionContext`.
+This is the **session** side of a transaction: a lightweight, per-async-task variable that stores the currently active `AsyncSession` wrapped in a `TransactionContext`. It is paired with the pico-ioc `"transaction"` DI scope (the **component** side — see below), bound to the same boundary by `TransactionalInterceptor`.
 
 **How it works:**
 
@@ -140,7 +140,31 @@ Service.create_user()                     ← @transactional
    _tx_context = None
 ```
 
-**Why not pico-ioc scopes?** The `_tx_context` ContextVar provides transaction propagation semantics (REQUIRED, REQUIRES_NEW, etc.) that don't map to pico-ioc's scope lifecycle. A transaction may be suspended and restored (REQUIRES_NEW, NOT_SUPPORTED), which requires explicit save/restore of the context — something ContextVar handles naturally.
+**Why a ContextVar for the session?** Transaction propagation (REQUIRED, REQUIRES_NEW, etc.) needs to suspend and restore the active session (REQUIRES_NEW, NOT_SUPPORTED) — something a `ContextVar` handles naturally, save/restore via tokens.
+
+### The paired `"transaction"` DI scope
+
+`TransactionalInterceptor` also binds pico-ioc's `"transaction"` **DI scope** to the same boundary. Whenever a *new* transaction is born — `REQUIRES_NEW`, or `REQUIRED` with no enclosing transaction — it activates a fresh `"transaction"` scope (with `cleanup=True`) around the call:
+
+```text
+Service.create_user()                     ← @transactional REQUIRED (new tx)
+│  activate "transaction" scope  (id = T1)         _tx_context = session_A
+│
+├─ container.get(AuditLog)  → scope="transaction"  ← created once, id T1
+├─ container.get(AuditLog)  → same instance        ← joined: same T1
+│
+├─ Other.in_new_tx()                      ← @transactional REQUIRES_NEW
+│  │  activate "transaction" scope (id = T2)        _tx_context = session_B
+│  └─ container.get(AuditLog) → NEW instance        ← isolated in T2
+│     deactivate T2 (+ @cleanup), restore T1, session_A
+│
+└─ commit / rollback
+   deactivate T1 (runs @cleanup on T1's components), _tx_context = None
+```
+
+So a `scope="transaction"` component is **one instance per transaction** — a Unit-of-Work / identity-map that is released (running its `@cleanup` hooks) when the transaction ends. Joins reuse the enclosing instance; `REQUIRES_NEW` gets its own and restores the outer one afterwards. Non-transactional paths (`NEVER`, `NOT_SUPPORTED`, `SUPPORTS` without a tx) open no scope — resolving a `scope="transaction"` component there raises `ScopeError`.
+
+> The scope is bound at the interceptor (which wraps the call directly), not deep inside `SessionManager`: a `ContextVar` set inside the transaction async-generator does not reliably reach the method body across nesting. As with any AOP, **self-invocation bypasses it** — `REQUIRES_NEW` only opens a new transaction/scope when the method is called on another injected component, not via `self.method()`.
 
 ---
 

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/docs/skills.md

@@ -8,7 +8,7 @@
 curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash -s -- sqlalchemy
 ```
 
-Or install all pico-framework skills:
+Or install all pico skills:
 
 ```bash
 curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash
@@ -47,7 +47,7 @@ Creates a new pico-ioc component with dependency injection. Use when adding serv
 
 ### `/add-tests`
 
-Generates tests for existing pico-framework components. Creates integration tests with in-memory database for repositories and unit tests for services.
+Generates tests for existing pico components. Creates integration tests with in-memory database for repositories and unit tests for services.
 
 ```
 /add-tests ProductRepository --integration

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/examples/crud-async/app/main.py

@@ -1,7 +1,7 @@
 import asyncio
 
 from pico_boot import init
-from pico_ioc import configuration, YamlTreeSource
+from pico_ioc import YamlTreeSource, configuration
 
 from .services import UserService
 
@@ -9,14 +9,8 @@ from .services import UserService
 async def main():
     config = configuration(YamlTreeSource("config.yml"))
 
-    container = init(
-        modules=[
-            "app.models",
-            "app.repositories",
-            "app.services",
-        ],
-        config=config,
-    )
+    # pico-boot scans "app" recursively and auto-discovers pico-sqlalchemy
+    container = init(modules=["app"], config=config)
 
     service = await container.aget(UserService)
 

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/examples/crud-async/app/repositories.py

@@ -1,5 +1,6 @@
 from pico_ioc import component
-from pico_sqlalchemy import transactional, repository
+
+from pico_sqlalchemy import repository, transactional
 
 from .models import User
 

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/pyproject.toml

@@ -37,7 +37,7 @@ classifiers = [
 ]
 
 dependencies = [
-    "pico-ioc >= 2.2.0",
+    "pico-ioc >= 2.2.6",
     "sqlalchemy >= 2.0",
 ]
 

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/src/pico_sqlalchemy/__init__.py

@@ -18,7 +18,8 @@ Typical usage::
     config = configuration(DictSource({
         "database": {"url": "sqlite+aiosqlite:///:memory:"}
     }))
-    container = init(modules=["pico_sqlalchemy", "my_app"], config=config)
+    # pico-boot auto-discovers pico-sqlalchemy — just list your app module
+    container = init(modules=["my_app"], config=config)
 """
 
 from .base import AppBase, Mapped, mapped_column

pico_sqlalchemy-0.4.0/src/pico_sqlalchemy/_version.py

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

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/src/pico_sqlalchemy/factory.py

@@ -53,7 +53,9 @@ class PicoSqlAlchemyLifecycle:
                 discovered by the container (injected as a list).
         """
         valid = [
-            c for c in configurers if isinstance(c, DatabaseConfigurer) and callable(getattr(c, "configure_database", None))
+            c
+            for c in configurers
+            if isinstance(c, DatabaseConfigurer) and callable(getattr(c, "configure_database", None))
         ]
         ordered = sorted(valid, key=_priority_of)
         for cfg in ordered:

{pico_sqlalchemy-0.3.0 → pico_sqlalchemy-0.4.0}/src/pico_sqlalchemy/interceptor.py

@@ -14,9 +14,11 @@ Priority resolution order (highest wins):
 """
 
 import inspect
+from contextlib import nullcontext
 from typing import Any, Callable
+from uuid import uuid4
 
-from pico_ioc import MethodCtx, MethodInterceptor, component
+from pico_ioc import MethodCtx, MethodInterceptor, PicoContainer, component
 
 from .decorators import QUERY_META, REPOSITORY_META, TRANSACTIONAL_META
 from .session import SessionManager
@@ -41,13 +43,26 @@ class TransactionalInterceptor(MethodInterceptor):
     If none of these markers are present, the method is invoked directly
     without opening a transaction.
 
+    In addition to the SQLAlchemy transaction, this interceptor binds
+    pico-ioc's ``"transaction"`` DI scope to the same boundary: whenever a
+    *new* transaction is started (``REQUIRES_NEW``, or ``REQUIRED`` with no
+    enclosing transaction) it activates a fresh ``"transaction"`` scope for
+    the duration of the call, so ``scope="transaction"`` components live
+    exactly one transaction and are released (running their ``@cleanup``
+    hooks) when it ends. Joins reuse the enclosing scope.
+
     Args:
         session_manager: The ``SessionManager`` singleton used to open
             or join transactions.
+        container: The pico-ioc container, used to activate the
+            ``"transaction"`` DI scope around new transactions. Required —
+            auto-injected by pico-ioc; directly-constructed interceptors
+            (e.g. in a unit test) must pass a real container.
     """
 
-    def __init__(self, session_manager: SessionManager):
+    def __init__(self, session_manager: SessionManager, container: PicoContainer):
         self.sm = session_manager
+        self.container = container
 
     async def invoke(self, ctx: MethodCtx, call_next: Callable[[MethodCtx], Any]) -> Any:
         """Intercept the method call and wrap it in a transaction if needed.
@@ -98,6 +113,20 @@ class TransactionalInterceptor(MethodInterceptor):
         rollback_for = meta["rollback_for"]
         no_rollback_for = meta["no_rollback_for"]
 
+        # A *new* transaction is born when REQUIRES_NEW is requested, or
+        # when REQUIRED finds no enclosing transaction. Those are exactly
+        # the cases that should push a fresh DI "transaction" scope; every
+        # other mode (joins, MANDATORY, SUPPORTS-with-tx) reuses the
+        # enclosing scope, and the non-transactional modes open none. We
+        # bind the scope here, at the interceptor, rather than inside
+        # SessionManager: a ContextVar set deep in the transaction
+        # async-generator does not reliably reach the method body across
+        # nesting, whereas this frame wraps ``call_next`` directly.
+        opens_new_tx = propagation == "REQUIRES_NEW" or (
+            propagation == "REQUIRED" and self.sm.get_current_session() is None
+        )
+        scope_cm = self.container.scope("transaction", uuid4().hex, cleanup=True) if opens_new_tx else nullcontext()
+
         async with self.sm.transaction(
             propagation=propagation,
             read_only=read_only,
@@ -105,7 +134,8 @@ class TransactionalInterceptor(MethodInterceptor):
             rollback_for=rollback_for,
             no_rollback_for=no_rollback_for,
         ):
-            result = call_next(ctx)
-            if inspect.isawaitable(result):
-                result = await result
-            return result
+            with scope_cm:
+                result = call_next(ctx)
+                if inspect.isawaitable(result):
+                    result = await result
+                return result