sqlacache 0.1.0__tar.gz

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

@@ -0,0 +1,26 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+    branches: ["main"]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - run: uv sync --extra redis --group dev
+      - run: uv run ruff check src/ tests/
+      - run: uv run ruff format --check src/ tests/
+      - run: uv run mypy src/
+      - run: uv run ty src/ || true
+      - run: uv run pytest -m "not integration"

sqlacache-0.1.0/.github/workflows/integration.yml

@@ -0,0 +1,18 @@
+name: Integration
+
+on:
+  workflow_dispatch:
+  schedule:
+    - cron: "0 6 * * 1"
+
+jobs:
+  integration:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.12"
+      - run: docker compose up -d
+      - run: uv sync --extra redis --group dev
+      - run: uv run pytest -m integration

sqlacache-0.1.0/.github/workflows/release.yml

@@ -0,0 +1,21 @@
+name: Release
+
+on:
+  push:
+    tags:
+      - "v*"
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+      contents: read
+
+    steps:
+      - uses: actions/checkout@v4
+      - uses: astral-sh/setup-uv@v5
+        with:
+          python-version: "3.10"
+      - run: uv build
+      - uses: pypa/gh-action-pypi-publish@release/v1

sqlacache-0.1.0/.gitignore

@@ -0,0 +1,49 @@
+# Python
+.venv/
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+
+# Type checkers / linters
+.mypy_cache/
+.ruff_cache/
+.ty_cache/
+
+# Test / coverage
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Package managers
+.uv-cache/
+uv.lock.bak
+
+# OS
+.DS_Store
+Thumbs.db
+
+# IDE
+.idea/
+.vscode/
+
+# AI assistant tool directories (not project source)
+.claude/
+CLAUDE.md
+.codex/
+.gemini/
+.opencode/
+.github/prompts/
+.github/skills/
+
+# prek hook runner logs and scratch
+.prek/prek.log
+.prek/scratch/
+
+# Scratch / research notes not part of the project
+research.md
+landscape-research.md
+
+# Examples (not part of the library itself)
+examples/

sqlacache-0.1.0/.pre-commit-config.yaml

@@ -0,0 +1,32 @@
+repos:
+  - repo: https://github.com/pre-commit/pre-commit-hooks
+    rev: v5.0.0
+    hooks:
+      - id: trailing-whitespace
+      - id: end-of-file-fixer
+      - id: check-yaml
+      - id: check-toml
+      - id: check-added-large-files
+
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: uv run ruff check --fix src/ tests/
+        language: system
+        pass_filenames: false
+      - id: ruff-format
+        name: ruff format
+        entry: uv run ruff format src/ tests/
+        language: system
+        pass_filenames: false
+      - id: mypy
+        name: mypy
+        entry: uv run mypy src/
+        language: system
+        pass_filenames: false
+      - id: ty
+        name: ty
+        entry: uv run ty check src/
+        language: system
+        pass_filenames: false

sqlacache-0.1.0/.prek/README

@@ -0,0 +1,2 @@
+This directory is maintained by the prek project.
+Learn more: https://github.com/j178/prek

sqlacache-0.1.0/CHANGELOG.md

@@ -0,0 +1,13 @@
+# Changelog
+
+## 0.1.0
+
+- Initial alpha MVP release.
+- Added package scaffolding, linting, typing, tests, CI, and build metadata.
+- Added validated configuration and cache manager APIs via `configure(...)`.
+- Added `cashews` transport integration for `mem://` and `redis://` backends.
+- Added automatic async ORM caching for configured reads, including `AsyncSession.get(...)`.
+- Added row-level invalidation for ORM inserts, updates, deletes, and bulk mutations.
+- Added Redis pub/sub support for cross-process invalidation.
+- Added unit tests, Redis integration coverage, and an external wheel-install smoke test workflow.
+- Sync session support remains deferred.

sqlacache-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,49 @@
+# Contributing
+
+## Environment
+
+```bash
+uv sync --extra redis --group dev
+prek install
+```
+
+## Common Commands
+
+```bash
+make lint
+make format
+make typecheck
+make test
+```
+
+## Current Scope
+
+- The implemented runtime is async SQLAlchemy
+- Redis integration is supported and tested
+- Sync session support is not implemented yet
+- The architecture document includes planned work beyond the current MVP
+
+## Release Smoke Test
+
+To verify the built package outside the repo, run:
+
+```bash
+.venv/bin/python -m build
+.venv/bin/python -m twine check dist/*
+python -m venv /tmp/sqlacache-release-venv
+UV_CACHE_DIR=.uv-cache uv pip install --python /tmp/sqlacache-release-venv/bin/python dist/*.whl
+UV_CACHE_DIR=.uv-cache uv pip install --python /tmp/sqlacache-release-venv/bin/python redis aiosqlite
+```
+
+Then run a standalone script from `/tmp` that imports `sqlacache` from that external environment and validates:
+
+- automatic `session.get(...)` caching
+- Redis keys appearing after cache population
+- invalidation after an update
+- recache with fresh data after invalidation
+
+## Workflow
+
+- Keep changes focused and aligned with the active OpenSpec change.
+- Run the relevant local checks before opening a pull request.
+- CI should pass before merging.

sqlacache-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Hamidreza Samsami
+
+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.

sqlacache-0.1.0/Makefile

@@ -0,0 +1,37 @@
+.PHONY: help install lint format typecheck test testcov integration clean
+
+help:
+	@printf "Available targets:\n"
+	@printf "  install      Install project dependencies with uv\n"
+	@printf "  lint         Run ruff checks\n"
+	@printf "  format       Format code with ruff\n"
+	@printf "  typecheck    Run mypy and ty\n"
+	@printf "  test         Run unit tests\n"
+	@printf "  testcov      Run unit tests with coverage\n"
+	@printf "  integration  Run integration tests\n"
+	@printf "  clean        Remove caches, build artifacts, and virtualenv\n"
+
+install:
+	uv sync --extra redis --group dev
+
+lint:
+	uv run ruff check src/ tests/
+
+format:
+	uv run ruff format src/ tests/
+
+typecheck:
+	uv run mypy src/
+	uv run ty check src/ || true
+
+test:
+	uv run pytest -x -m "not integration"
+
+testcov:
+	uv run pytest --cov=sqlacache --cov-report=term-missing -m "not integration"
+
+integration:
+	uv run pytest -m integration
+
+clean:
+	rm -rf .venv .mypy_cache .pytest_cache .ruff_cache dist build src/*.egg-info .coverage htmlcov

sqlacache-0.1.0/PKG-INFO

@@ -0,0 +1,298 @@
+Metadata-Version: 2.4
+Name: sqlacache
+Version: 0.1.0
+Summary: Django-cacheops-style declarative caching with automatic row-level invalidation for SQLAlchemy
+Project-URL: Homepage, https://github.com/persix/sqlacache
+Project-URL: Repository, https://github.com/persix/sqlacache
+Project-URL: Documentation, https://github.com/persix/sqlacache/blob/main/README.md
+Project-URL: Issues, https://github.com/persix/sqlacache/issues
+Author-email: Hamidreza Samsami <hamidreza.samsami@gmail.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: asyncio,cache,orm,redis,sqlalchemy
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python
+Classifier: Programming Language :: Python :: 3
+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 :: Implementation :: CPython
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: cashews<8.0,>=7.0
+Requires-Dist: sqlalchemy>=1.4
+Provides-Extra: all
+Requires-Dist: asyncpg>=0.30.0; extra == 'all'
+Requires-Dist: cashews[dill,diskcache,redis,speedup]<8.0,>=7.0; extra == 'all'
+Provides-Extra: dill
+Requires-Dist: cashews[dill]<8.0,>=7.0; extra == 'dill'
+Provides-Extra: diskcache
+Requires-Dist: cashews[diskcache]<8.0,>=7.0; extra == 'diskcache'
+Provides-Extra: postgresql
+Requires-Dist: asyncpg>=0.30.0; extra == 'postgresql'
+Provides-Extra: redis
+Requires-Dist: cashews[redis]<8.0,>=7.0; extra == 'redis'
+Provides-Extra: speedup
+Requires-Dist: cashews[speedup]<8.0,>=7.0; extra == 'speedup'
+Description-Content-Type: text/markdown
+
+# sqlacache
+
+A slick library that adds automatic queryset caching and row-level invalidation to SQLAlchemy async sessions.
+
+[![Tests](https://github.com/hr-samsami/sqlacache/actions/workflows/ci.yml/badge.svg)](https://github.com/hr-samsami/sqlacache/actions/workflows/ci.yml)
+[![PyPI version](https://img.shields.io/pypi/v/sqlacache)](https://pypi.org/project/sqlacache/)
+[![Python](https://img.shields.io/pypi/pyversions/sqlacache)](https://pypi.org/project/sqlacache/)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+---
+
+`session.get(User, 42)` is cached. `session.commit()` invalidates it. That's the whole idea.
+
+Built on top of [`cashews`](https://github.com/Krukov/cashews) for storage and tag-based dependency tracking.
+
+- Zero changes to your session usage — reads are intercepted automatically
+- Row-level invalidation — only the rows that changed are evicted, not the whole table
+- Cross-process invalidation via Redis pub/sub — all workers stay in sync
+- Declarative config — map models to ops and TTLs in one place, with wildcard fallback
+- Two backends: `redis://` for production, `mem://` for dev and testing
+
+---
+
+## Requirements
+
+- Python 3.10+
+- SQLAlchemy >= 1.4
+- cashews >= 7.0
+- Redis (for production; not needed for `mem://`)
+
+---
+
+## Installation
+
+```bash
+pip install sqlacache
+pip install "sqlacache[redis]"   # with Redis support
+```
+
+Using `uv`:
+
+```bash
+uv add "sqlacache[redis]"
+```
+
+---
+
+## Setup
+
+Call `configure()` once at startup — alongside your engine setup.
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlacache import configure
+
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+
+sqlacache = configure(
+    backend="redis://localhost:6379/1",
+    models={
+        "app.models.User":    {"ops": {"get", "fetch"}, "timeout": 900},
+        "app.models.Product": {"ops": "all",            "timeout": 3600},
+        "*":                  {"timeout": 3600},
+    },
+)
+await sqlacache.bind(engine)
+```
+
+That's all the wiring needed. From here, your sessions work as normal.
+
+---
+
+## Usage
+
+### Reads are cached automatically
+
+```python
+async with AsyncSession(engine) as session:
+    user = await session.get(User, 42)           # cache miss → fetches from DB, stores result
+    user = await session.get(User, 42)           # cache hit → returned instantly
+
+    result = await session.execute(select(User).where(User.active == True))
+    users = result.scalars().all()               # multi-row fetch, also cached
+```
+
+### Writes invalidate the cache automatically
+
+```python
+async with AsyncSession(engine) as session:
+    user = await session.get(User, 42)
+    user.name = "Alice"
+    await session.commit()     # evicts all cached reads that touched User id=42
+```
+
+No decorators. No manual cache keys. No changes to how you write queries.
+
+---
+
+## FastAPI Example
+
+```python
+from contextlib import asynccontextmanager
+from fastapi import FastAPI, Depends
+from sqlalchemy.ext.asyncio import AsyncSession, async_sessionmaker, create_async_engine
+from sqlacache import configure
+
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+session_maker = async_sessionmaker(engine, expire_on_commit=False)
+
+sqlacache = configure(
+    backend="redis://localhost:6379/1",
+    models={"app.models.User": {"ops": "all", "timeout": 300}},
+)
+
+
+@asynccontextmanager
+async def lifespan(app: FastAPI):
+    await sqlacache.bind(engine)
+    yield
+    await sqlacache.disconnect()
+
+
+app = FastAPI(lifespan=lifespan)
+
+
+async def get_session():
+    async with session_maker() as session:
+        yield session
+
+
+@app.get("/users/{user_id}")
+async def get_user(user_id: int, session: AsyncSession = Depends(get_session)):
+    return await session.get(User, user_id)   # cached after the first request
+```
+
+---
+
+## Configuration Reference
+
+### `configure()`
+
+```python
+sqlacache = configure(
+    backend="redis://localhost:6379/1",   # or "mem://" for in-memory
+    models={...},
+    prefix="sqlacache",       # key prefix (default: "sqlacache")
+    default_timeout=3600,     # TTL when not specified per model (default: 3600)
+    serializer="sqlalchemy",  # cashews serializer (default: "sqlalchemy")
+)
+await sqlacache.bind(engine)
+```
+
+### Model config
+
+```python
+models={
+    "app.models.User": {
+        "ops": {"get", "fetch"},   # operations to cache
+        "timeout": 900,            # TTL in seconds
+    },
+    "app.models.Product": {"ops": "all", "timeout": 3600},
+    "*": {"timeout": 3600},        # wildcard fallback
+}
+```
+
+**Ops:**
+
+| Op | What it covers |
+| --- | --- |
+| `"get"` | `session.get(Model, pk)` |
+| `"fetch"` | `session.execute(select(Model))` |
+| `"count"` | `select(func.count())` queries |
+| `"exists"` | `select(exists(...))` queries |
+| `"all"` | All four above |
+
+### Backends
+
+| Backend | URL | Notes |
+| --- | --- | --- |
+| Redis | `redis://host:port/db` | Production; enables cross-process invalidation |
+| In-memory | `mem://` | Dev and testing; no infrastructure needed |
+
+---
+
+## Manual Control
+
+You rarely need these — sqlacache handles everything through the session automatically. They're available for edge cases:
+
+```python
+# Cache a statement explicitly
+result = await sqlacache.execute(session, select(User).where(User.active == True), timeout=300)
+
+# Invalidate specific rows
+await sqlacache.invalidate(User, pks=[42, 99])
+
+# Invalidate all cached reads for a model
+await sqlacache.invalidate(User)
+
+# Flush everything
+await sqlacache.invalidate_all()
+```
+
+---
+
+## How It Works
+
+```text
+session.get(User, 42)
+    │
+    ├── cache HIT  → return immediately
+    └── cache MISS → execute SQL → tag result as "users:42" → return
+
+session.commit()  [User id=42 changed]
+    │
+    └── after_flush event → delete tag "users:42" → all reads that touched that row are evicted
+          └── (Redis) → pub/sub → other workers evict their copies too
+```
+
+- Cache keys are a hash of the compiled SQL + bound parameters + a per-table version counter.
+- Tags (`"{tablename}:{pk}"`) let cashews atomically evict all keys that depended on a row.
+- Bulk `UPDATE ... WHERE ...` bumps a table-level version so all cached queries for that model go stale.
+
+---
+
+## Caveats
+
+- **Async only.** Sync `Session` is not supported yet (planned for v0.2.0).
+- **Bulk writes use table-level invalidation.** `session.execute(update(Model).where(...))` evicts all cached reads for that model, not just the affected rows.
+- **Eager-loaded relationships are not tracked.** If a related row changes, queries that joined or selectin-loaded it won't be invalidated.
+- **Raw SQL is not intercepted.** `text(...)` and `engine.execute()` bypass sqlacache entirely.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/hr-samsami/sqlacache
+cd sqlacache
+uv sync --extra redis --group dev
+
+make test          # unit tests (no infrastructure needed)
+make lint          # ruff
+make format        # ruff format
+make typecheck     # mypy
+
+docker-compose up -d
+make integration   # Redis + Postgres integration tests
+```
+
+---
+
+## License
+
+[MIT](LICENSE)