pico-sqlalchemy 0.2.1.dev0__tar.gz → 0.4.0__tar.gz

pico_sqlalchemy-0.4.0/.github/ISSUE_TEMPLATE/bug_report.yml

@@ -0,0 +1,32 @@
+name: Bug Report
+description: Report a bug in pico-sqlalchemy
+labels: ["bug"]
+body:
+  - type: textarea
+    id: description
+    attributes:
+      label: Description
+      description: What happened?
+    validations:
+      required: true
+  - type: textarea
+    id: reproduction
+    attributes:
+      label: Steps to Reproduce
+      description: Minimal code or steps to reproduce the issue.
+    validations:
+      required: true
+  - type: input
+    id: version
+    attributes:
+      label: pico-sqlalchemy version
+      placeholder: "0.2.0"
+    validations:
+      required: true
+  - type: input
+    id: python-version
+    attributes:
+      label: Python version
+      placeholder: "3.11"
+    validations:
+      required: true

pico_sqlalchemy-0.4.0/.github/ISSUE_TEMPLATE/feature_request.yml

@@ -0,0 +1,18 @@
+name: Feature Request
+description: Suggest an enhancement for pico-sqlalchemy
+labels: ["enhancement"]
+body:
+  - type: textarea
+    id: problem
+    attributes:
+      label: Problem
+      description: What problem does this solve?
+    validations:
+      required: true
+  - type: textarea
+    id: solution
+    attributes:
+      label: Proposed Solution
+      description: How should it work?
+    validations:
+      required: true

pico_sqlalchemy-0.4.0/.github/PULL_REQUEST_TEMPLATE.md

@@ -0,0 +1,10 @@
+## Summary
+
+<!-- Brief description of the changes -->
+
+## Checklist
+
+- [ ] Tests pass (`pytest tests/ -v`)
+- [ ] Code formatted (`ruff format src/ tests/`)
+- [ ] Lint clean (`ruff check src/ tests/`)
+- [ ] CHANGELOG.md updated (if user-facing change)

pico_sqlalchemy-0.4.0/.github/dependabot.yml

@@ -0,0 +1,11 @@
+version: 2
+updates:
+  - package-ecosystem: "github-actions"
+    directory: "/"
+    schedule:
+      interval: "weekly"
+
+  - package-ecosystem: "pip"
+    directory: "/"
+    schedule:
+      interval: "weekly"

{pico_sqlalchemy-0.2.1.dev0 → pico_sqlalchemy-0.4.0}/.github/workflows/ci.yml

@@ -3,8 +3,23 @@ name: CI & Coverage
 on:
   push:
     branches: [ main ]
+  pull_request:
+    branches: [ main ]
 
 jobs:
+  lint:
+    name: Lint & Format
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - uses: actions/setup-python@v6
+        with:
+          python-version: '3.11'
+          cache: pip
+      - run: pip install ruff
+      - run: ruff check src/ tests/
+      - run: ruff format --check src/ tests/
+
   tests:
     name: Tests (Python ${{ matrix.python-version }})
     runs-on: ubuntu-latest
@@ -15,12 +30,12 @@ jobs:
 
     steps:
       - name: Checkout
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v5
+        uses: actions/setup-python@v6
         with:
           python-version: ${{ matrix.python-version }}
           cache: pip
@@ -30,6 +45,12 @@ jobs:
           python -m pip install --upgrade pip
           pip install tox
 
+      - name: Cache tox environments
+        uses: actions/cache@v5
+        with:
+          path: .tox
+          key: tox-${{ matrix.python-version }}-${{ hashFiles('pyproject.toml', 'tox.ini') }}
+
       - name: Install build dependencies
         run: |
           sudo apt-get update
@@ -58,7 +79,7 @@ jobs:
     needs: tests
     steps:
       - name: Checkout (for repo context)
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Download all coverage artifacts
         uses: actions/download-artifact@v4

pico_sqlalchemy-0.4.0/.github/workflows/codeql.yml

@@ -0,0 +1,28 @@
+name: CodeQL
+
+on:
+  push:
+    branches: [ main ]
+  pull_request:
+    branches: [ main ]
+  schedule:
+    - cron: '0 6 * * 1'
+
+jobs:
+  analyze:
+    name: Analyze (Python)
+    runs-on: ubuntu-latest
+    permissions:
+      security-events: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Initialize CodeQL
+        uses: github/codeql-action/init@v4
+        with:
+          languages: python
+
+      - name: Perform CodeQL Analysis
+        uses: github/codeql-action/analyze@v4

{pico_sqlalchemy-0.2.1.dev0 → pico_sqlalchemy-0.4.0}/.github/workflows/docs.yml

@@ -29,11 +29,11 @@ jobs:
     if: github.event_name == 'pull_request'
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.11'
           cache: 'pip'
@@ -51,7 +51,7 @@ jobs:
           pip install linkchecker
           python -m http.server --directory site 8000 &
           sleep 3
-          linkchecker http://127.0.0.1:8000 --check-extern || true
+          linkchecker http://127.0.0.1:8000 --check-extern
 
   deploy:
     if: github.event_name != 'pull_request'
@@ -61,11 +61,11 @@ jobs:
       url: ${{ steps.deployment.outputs.page_url }}
 
     steps:
-      - uses: actions/checkout@v4
+      - uses: actions/checkout@v6
         with:
           fetch-depth: 0
 
-      - uses: actions/setup-python@v5
+      - uses: actions/setup-python@v6
         with:
           python-version: '3.11'
           cache: 'pip'

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

@@ -12,12 +12,12 @@ jobs:
       contents: read
 
     steps:
-    - uses: actions/checkout@v4
+    - uses: actions/checkout@v6
       with:
         fetch-depth: 0
 
     - name: Set up Python
-      uses: actions/setup-python@v5
+      uses: actions/setup-python@v6
       with:
         python-version: '3.x'
 
@@ -27,10 +27,22 @@ 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:
         skip-existing: true
         verify-metadata: true
-        attestations: false
+        attestations: true
 

{pico_sqlalchemy-0.2.1.dev0 → pico_sqlalchemy-0.4.0}/.github/workflows/sync-keywords.yml

@@ -18,10 +18,10 @@ jobs:
 
     steps:
       - name: Checkout Repository
-        uses: actions/checkout@v4
+        uses: actions/checkout@v6
 
       - name: Set up Python
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v6
         with:
           python-version: '3.11'
 

{pico_sqlalchemy-0.2.1.dev0 → 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.2.1.dev0/docs → pico_sqlalchemy-0.4.0}/CHANGELOG.md

@@ -7,6 +7,24 @@ 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
+- **Breaking:** Renamed `DatabaseConfigurer.configure(engine)` to `configure_database(engine)` to avoid protocol collision with `FastApiConfigurer.configure(app)` in structural typing.
+
+---
+
 ## [0.2.0] - 2026-02-06
 
 ### Added

pico_sqlalchemy-0.4.0/CLAUDE.md

@@ -0,0 +1,19 @@
+Read and follow ./AGENTS.md for project conventions.
+
+## Pico Ecosystem Context
+
+pico-sqlalchemy provides SQLAlchemy integration for pico-ioc. It uses:
+- `@factory` + `@provides` for SessionManager creation
+- `@configured` for DatabaseSettings
+- `MethodInterceptor` for both `TransactionalInterceptor` and `RepositoryQueryInterceptor`
+- Auto-discovered via `pico_boot.modules` entry point
+
+## Key Reminders
+
+- 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 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.4.0/CODE_OF_CONDUCT.md

@@ -0,0 +1,31 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+
+Examples of unacceptable behavior:
+
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information without explicit permission
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to **dperezcabrera@gmail.com**. All complaints will be reviewed
+and investigated promptly and fairly.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant](https://www.contributor-covenant.org/), version 2.1.

pico_sqlalchemy-0.4.0/CONTRIBUTING.md

@@ -0,0 +1,34 @@
+# Contributing to Pico-SQLAlchemy
+
+## Development Setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install -e ".[test]"
+pip install ruff
+```
+
+## Running Tests
+
+```bash
+pytest tests/ -v                # Run tests
+tox                             # Full matrix (3.11-3.14)
+```
+
+## Code Style
+
+- Python 3.11+
+- Format with `ruff format src/ tests/`
+- Lint with `ruff check src/ tests/`
+
+## Pull Requests
+
+1. Fork the repository
+2. Create a feature branch
+3. Ensure tests pass and code is formatted
+4. Submit a PR with a clear description
+
+## Reporting Issues
+
+Use [GitHub Issues](https://github.com/dperezcabrera/pico-sqlalchemy/issues) for bugs and feature requests.

{pico_sqlalchemy-0.2.1.dev0 → pico_sqlalchemy-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: pico-sqlalchemy
-Version: 0.2.1.dev0
+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
@@ -28,6 +28,8 @@ License: MIT License
 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
+Project-URL: Documentation, https://dperezcabrera.github.io/pico-sqlalchemy/
+Project-URL: Changelog, https://github.com/dperezcabrera/pico-sqlalchemy/blob/main/CHANGELOG.md
 Keywords: ioc,di,dependency injection,sqlalchemy,transaction,orm,inversion of control,asyncio
 Classifier: Development Status :: 4 - Beta
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
@@ -38,12 +40,14 @@ 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: Intended Audience :: Developers
 Classifier: License :: OSI Approved :: MIT License
 Classifier: Operating System :: OS Independent
+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"
@@ -53,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)
@@ -64,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
 
@@ -71,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.
 
@@ -94,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**).
@@ -104,7 +109,7 @@ Most Python apps suffer from manual session handling (`async with session...`),
 
 ---
 
-## 📦 Installation
+## Installation
 
 ```bash
 pip install pico-sqlalchemy
@@ -119,7 +124,7 @@ pip install asyncpg     # for PostgreSQL
 
 -----
 
-## 🚀 Quick Example
+## Quick Example
 
 ### 1\. Define Model
 
@@ -214,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:
 
@@ -232,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:**
 
@@ -241,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:**
 
@@ -250,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.
 
@@ -289,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.
 
@@ -307,7 +330,7 @@ async def test_service():
 
 -----
 
-## 💡 Architecture Overview
+## Architecture Overview
 
 ```
                  ┌─────────────────────────────┐
@@ -333,19 +356,26 @@ async def test_service():
 
 -----
 
-## 🤖 Claude Code Skills
+## AI Coding Skills
+
+Install [Claude Code](https://code.claude.com) or [OpenAI Codex](https://openai.com/index/introducing-codex/) skills for AI-assisted development with pico-sqlalchemy:
+
+```bash
+curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash -s -- sqlalchemy
+```
 
-This project includes pre-designed skills for [Claude Code](https://claude.ai/claude-code), enabling AI-assisted development with pico-sqlalchemy patterns.
+| Command | Description |
+|---------|-------------|
+| `/add-repository` | Add SQLAlchemy entities and repositories with transactions |
+| `/add-component` | Add components, factories, interceptors, settings |
+| `/add-tests` | Generate tests for pico components |
 
-| Skill | Command | Description |
-|-------|---------|-------------|
-| **Pico SQLAlchemy Repository** | `/pico-sqlalchemy` | Creates models, repositories and services with DI |
-| **Pico Test Generator** | `/pico-tests` | Generates tests for pico-framework components |
+All skills: `curl -sL https://raw.githubusercontent.com/dperezcabrera/pico-skills/main/install.sh | bash`
 
-See [Skills documentation](docs/skills.md) for full details and installation instructions.
+See [pico-skills](https://github.com/dperezcabrera/pico-skills) for details.
 
 ---
 
-## 📝 License
+## License
 
 MIT