varco-sa 0.0.1__tar.gz

varco_sa-0.0.1/PKG-INFO

@@ -0,0 +1,191 @@
+Metadata-Version: 2.4
+Name: varco-sa
+Version: 0.0.1
+Summary: SQLAlchemy async backend for varco — runtime ORM generation, repository, schema guard, and Alembic helpers
+License: Apache-2.0
+Keywords: fastapi,sqlalchemy,async,domain-model,repository,alembic,orm,schema-guard
+Author: edoardo.scarpaci
+Author-email: edoardo.scarpaci@gmail.com
+Requires-Python: >=3.12
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: FastAPI
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: Apache Software License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Database
+Classifier: Topic :: Software Development :: Libraries :: Application Frameworks
+Classifier: Typing :: Typed
+Requires-Dist: sqlalchemy[asyncio] (>=2.0)
+Requires-Dist: varco-core (>=0.0.1)
+Project-URL: Documentation, https://github.com/edoardoscarpaci/varco#sqlalchemy-backend
+Project-URL: Homepage, https://github.com/edoardoscarpaci/varco
+Project-URL: Repository, https://github.com/edoardoscarpaci/varco
+Description-Content-Type: text/markdown
+
+# varco-sa
+
+[![PyPI version](https://img.shields.io/pypi/v/varco-sa)](https://pypi.org/project/varco-sa/)
+[![Python](https://img.shields.io/pypi/pyversions/varco-sa)](https://pypi.org/project/varco-sa/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/edoardoscarpaci/varco/blob/main/LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-edoardoscarpaci%2Fvarco-blue?logo=github)](https://github.com/edoardoscarpaci/varco)
+
+SQLAlchemy async backend for **varco**.
+
+Generates SQLAlchemy ORM classes at runtime from your `DomainModel` subclasses — no hand-written ORM models needed. Requires [`varco-core`](https://pypi.org/project/varco-core/).
+
+---
+
+## Install
+
+```bash
+pip install varco-sa
+
+# With PostgreSQL async driver:
+pip install "varco-sa[postgresql]"
+
+# With SQLite (tests / local dev):
+pip install "varco-sa[sqlite]"
+```
+
+---
+
+## Features
+
+- **Zero-boilerplate ORM** — `SAModelFactory` generates `DeclarativeBase` subclasses at runtime; no duplication between domain and ORM layers
+- **Full async repository** — `AsyncSQLAlchemyRepository` implements `AsyncRepository` (CRUD, `exists()`, `stream_by_query()` with server-side cursor)
+- **Unit of Work** — `SQLAlchemyUnitOfWork` manages `AsyncSession` lifecycle and atomic commits
+- **One-liner bootstrap** — `SAFastrestApp` + `SAConfig` wire engine, session factory, ORM generation, and table creation
+- **Alembic integration** — `get_target_metadata()` and `print_create_ddl()` helpers for migration scripts
+- **Schema Guard** — `SchemaGuard` detects drift between ORM metadata and the live database schema
+- **Query integration** — accepts `varco-core` `QueryParams` / `QueryBuilder` AST natively; translates to SQLAlchemy `where()` clauses
+
+---
+
+## What's in the package
+
+| Module | Purpose |
+|---|---|
+| `factory.py` | `SAModelFactory` — generates `DeclarativeBase` subclasses at runtime; `SAModelRegistry` — escape hatch |
+| `repository.py` | `AsyncSQLAlchemyRepository` — `AsyncSession`-backed CRUD + `exists()` + `stream_by_query()` |
+| `uow.py` | `SQLAlchemyUnitOfWork` — session lifecycle + atomic commits |
+| `provider.py` | `SQLAlchemyRepositoryProvider` — wires factory + repos + UoW |
+| `bootstrap.py` | `SAConfig`, `SAFastrestApp` — one-liner app setup |
+| `alembic_helpers.py` | `get_target_metadata`, `print_create_ddl` — Alembic integration |
+| `schema_guard.py` | `SchemaGuard` — drift detection between ORM metadata and live DB |
+
+---
+
+## Quick start
+
+### Bootstrap (one-liner)
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+from varco_sa import SAConfig, SAFastrestApp
+
+class Base(DeclarativeBase): pass
+
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+
+app = SAFastrestApp(SAConfig(
+    engine=engine,
+    base=Base,
+    entity_classes=(User, Post),
+))
+
+await app.create_all()              # CREATE TABLE IF NOT EXISTS ...
+uow_provider = app.uow_provider     # ready to inject as IUoWProvider
+```
+
+### Manual setup
+
+```python
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from varco_sa import SQLAlchemyRepositoryProvider
+
+sessions = async_sessionmaker(engine, expire_on_commit=False)
+provider = SQLAlchemyRepositoryProvider(engine=engine, session_factory=sessions)
+provider.register(User, Post)
+await provider.create_all()
+
+async with provider.make_uow() as uow:
+    user = await uow.users.save(User(name="Edo", email="edo@example.com"))
+    print(user.pk)
+```
+
+### Query integration
+
+```python
+from varco_core import QueryBuilder, QueryParams
+
+async with provider.make_uow() as uow:
+    # exists() — uses SA identity-map cache, no full ORM load when cached
+    if await uow.posts.exists(post_id):
+        ...
+
+    # stream_by_query() — server-side cursor, constant memory regardless of result size
+    params = QueryParams(node=QueryBuilder().eq("active", True).build())
+    async for post in uow.posts.stream_by_query(params):
+        await process(post)
+```
+
+### Alembic integration
+
+```python
+# alembic/env.py
+from varco_sa import get_target_metadata
+from myapp.models import User, Post
+
+target_metadata = get_target_metadata(User, Post)
+```
+
+Preview the DDL before running a migration:
+
+```python
+from varco_sa import print_create_ddl
+
+print(print_create_ddl(User, Post, dialect="postgresql"))
+```
+
+### Schema Guard — detect drift
+
+```python
+from varco_sa import SchemaGuard
+
+guard = SchemaGuard(engine, User, Post)
+differences = await guard.check()
+if differences:
+    print("Schema drift detected:", differences)
+```
+
+### Access the generated SA model (escape hatch)
+
+```python
+from varco_sa import SAModelRegistry
+from sqlalchemy.orm import relationship
+
+UserORM = SAModelRegistry.get(User)
+UserORM.posts = relationship("PostORM", back_populates="author")
+```
+
+---
+
+## Related packages
+
+| Package | Description |
+|---|---|
+| [`varco-core`](https://pypi.org/project/varco-core/) | Domain model, service layer, query AST, JWT — required dependency |
+| [`varco-beanie`](https://pypi.org/project/varco-beanie/) | Beanie / Motor MongoDB backend (alternative to this package) |
+
+---
+
+## Links
+
+- **Repository**: https://github.com/edoardoscarpaci/varco
+- **Full docs**: https://github.com/edoardoscarpaci/varco#sqlalchemy-backend
+- **Issue tracker**: https://github.com/edoardoscarpaci/varco/issues
+

varco_sa-0.0.1/README.md

@@ -0,0 +1,163 @@
+# varco-sa
+
+[![PyPI version](https://img.shields.io/pypi/v/varco-sa)](https://pypi.org/project/varco-sa/)
+[![Python](https://img.shields.io/pypi/pyversions/varco-sa)](https://pypi.org/project/varco-sa/)
+[![License: Apache 2.0](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/edoardoscarpaci/varco/blob/main/LICENSE)
+[![GitHub](https://img.shields.io/badge/GitHub-edoardoscarpaci%2Fvarco-blue?logo=github)](https://github.com/edoardoscarpaci/varco)
+
+SQLAlchemy async backend for **varco**.
+
+Generates SQLAlchemy ORM classes at runtime from your `DomainModel` subclasses — no hand-written ORM models needed. Requires [`varco-core`](https://pypi.org/project/varco-core/).
+
+---
+
+## Install
+
+```bash
+pip install varco-sa
+
+# With PostgreSQL async driver:
+pip install "varco-sa[postgresql]"
+
+# With SQLite (tests / local dev):
+pip install "varco-sa[sqlite]"
+```
+
+---
+
+## Features
+
+- **Zero-boilerplate ORM** — `SAModelFactory` generates `DeclarativeBase` subclasses at runtime; no duplication between domain and ORM layers
+- **Full async repository** — `AsyncSQLAlchemyRepository` implements `AsyncRepository` (CRUD, `exists()`, `stream_by_query()` with server-side cursor)
+- **Unit of Work** — `SQLAlchemyUnitOfWork` manages `AsyncSession` lifecycle and atomic commits
+- **One-liner bootstrap** — `SAFastrestApp` + `SAConfig` wire engine, session factory, ORM generation, and table creation
+- **Alembic integration** — `get_target_metadata()` and `print_create_ddl()` helpers for migration scripts
+- **Schema Guard** — `SchemaGuard` detects drift between ORM metadata and the live database schema
+- **Query integration** — accepts `varco-core` `QueryParams` / `QueryBuilder` AST natively; translates to SQLAlchemy `where()` clauses
+
+---
+
+## What's in the package
+
+| Module | Purpose |
+|---|---|
+| `factory.py` | `SAModelFactory` — generates `DeclarativeBase` subclasses at runtime; `SAModelRegistry` — escape hatch |
+| `repository.py` | `AsyncSQLAlchemyRepository` — `AsyncSession`-backed CRUD + `exists()` + `stream_by_query()` |
+| `uow.py` | `SQLAlchemyUnitOfWork` — session lifecycle + atomic commits |
+| `provider.py` | `SQLAlchemyRepositoryProvider` — wires factory + repos + UoW |
+| `bootstrap.py` | `SAConfig`, `SAFastrestApp` — one-liner app setup |
+| `alembic_helpers.py` | `get_target_metadata`, `print_create_ddl` — Alembic integration |
+| `schema_guard.py` | `SchemaGuard` — drift detection between ORM metadata and live DB |
+
+---
+
+## Quick start
+
+### Bootstrap (one-liner)
+
+```python
+from sqlalchemy.ext.asyncio import create_async_engine
+from sqlalchemy.orm import DeclarativeBase
+from varco_sa import SAConfig, SAFastrestApp
+
+class Base(DeclarativeBase): pass
+
+engine = create_async_engine("postgresql+asyncpg://user:pass@localhost/mydb")
+
+app = SAFastrestApp(SAConfig(
+    engine=engine,
+    base=Base,
+    entity_classes=(User, Post),
+))
+
+await app.create_all()              # CREATE TABLE IF NOT EXISTS ...
+uow_provider = app.uow_provider     # ready to inject as IUoWProvider
+```
+
+### Manual setup
+
+```python
+from sqlalchemy.ext.asyncio import async_sessionmaker
+from varco_sa import SQLAlchemyRepositoryProvider
+
+sessions = async_sessionmaker(engine, expire_on_commit=False)
+provider = SQLAlchemyRepositoryProvider(engine=engine, session_factory=sessions)
+provider.register(User, Post)
+await provider.create_all()
+
+async with provider.make_uow() as uow:
+    user = await uow.users.save(User(name="Edo", email="edo@example.com"))
+    print(user.pk)
+```
+
+### Query integration
+
+```python
+from varco_core import QueryBuilder, QueryParams
+
+async with provider.make_uow() as uow:
+    # exists() — uses SA identity-map cache, no full ORM load when cached
+    if await uow.posts.exists(post_id):
+        ...
+
+    # stream_by_query() — server-side cursor, constant memory regardless of result size
+    params = QueryParams(node=QueryBuilder().eq("active", True).build())
+    async for post in uow.posts.stream_by_query(params):
+        await process(post)
+```
+
+### Alembic integration
+
+```python
+# alembic/env.py
+from varco_sa import get_target_metadata
+from myapp.models import User, Post
+
+target_metadata = get_target_metadata(User, Post)
+```
+
+Preview the DDL before running a migration:
+
+```python
+from varco_sa import print_create_ddl
+
+print(print_create_ddl(User, Post, dialect="postgresql"))
+```
+
+### Schema Guard — detect drift
+
+```python
+from varco_sa import SchemaGuard
+
+guard = SchemaGuard(engine, User, Post)
+differences = await guard.check()
+if differences:
+    print("Schema drift detected:", differences)
+```
+
+### Access the generated SA model (escape hatch)
+
+```python
+from varco_sa import SAModelRegistry
+from sqlalchemy.orm import relationship
+
+UserORM = SAModelRegistry.get(User)
+UserORM.posts = relationship("PostORM", back_populates="author")
+```
+
+---
+
+## Related packages
+
+| Package | Description |
+|---|---|
+| [`varco-core`](https://pypi.org/project/varco-core/) | Domain model, service layer, query AST, JWT — required dependency |
+| [`varco-beanie`](https://pypi.org/project/varco-beanie/) | Beanie / Motor MongoDB backend (alternative to this package) |
+
+---
+
+## Links
+
+- **Repository**: https://github.com/edoardoscarpaci/varco
+- **Full docs**: https://github.com/edoardoscarpaci/varco#sqlalchemy-backend
+- **Issue tracker**: https://github.com/edoardoscarpaci/varco/issues

varco_sa-0.0.1/pyproject.toml

@@ -0,0 +1,49 @@
+[tool.poetry]
+name          = "varco-sa"
+version       = "0.0.1"
+description   = "SQLAlchemy async backend for varco — runtime ORM generation, repository, schema guard, and Alembic helpers"
+authors       = ["edoardo.scarpaci <edoardo.scarpaci@gmail.com>"]
+readme        = "README.md"
+license       = "Apache-2.0"
+homepage      = "https://github.com/edoardoscarpaci/varco"
+repository    = "https://github.com/edoardoscarpaci/varco"
+documentation = "https://github.com/edoardoscarpaci/varco#sqlalchemy-backend"
+keywords      = ["fastapi", "sqlalchemy", "async", "domain-model", "repository", "alembic", "orm", "schema-guard"]
+classifiers   = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: Apache Software License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Software Development :: Libraries :: Application Frameworks",
+    "Topic :: Database",
+    "Framework :: FastAPI",
+    "Typing :: Typed",
+]
+packages      = [{include = "varco_sa"}]
+
+[tool.poetry.dependencies]
+python        = ">=3.12"
+# Path dependency — installs varco_core in editable mode from the monorepo.
+# Changes to varco_core are immediately visible without reinstalling.
+varco-core = ">=0.0.1"
+sqlalchemy    = {version = ">=2.0", extras = ["asyncio"]}
+
+[tool.poetry.group.postgresql.dependencies]
+# Install with: poetry install --with postgresql
+asyncpg = ">=0.29"
+
+[tool.poetry.group.dev.dependencies]
+# aiosqlite is included here (not just sqlite group) so tests run without
+# needing a separate --with sqlite flag during local development.
+pytest         = ">=8.0"
+pytest-asyncio = ">=0.24"
+aiosqlite      = ">=0.20"
+
+[build-system]
+requires      = ["poetry-core>=2.0.0,<3.0.0", "poetry-monorepo-dependency-plugin"]
+build-backend = "poetry.core.masonry.api"
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+testpaths    = ["tests"]

varco_sa-0.0.1/varco_sa/__init__.py

@@ -0,0 +1,78 @@
+"""
+varco_sa
+============
+SQLAlchemy async backend for varco.
+
+All stable public symbols are importable directly from ``varco_sa``::
+
+    from varco_sa import SQLAlchemyRepositoryProvider, SAModelRegistry
+    from varco_sa import BaseDatabaseModel, IndexedDatabaseModel
+    from varco_sa import SQLAlchemyQueryApplicator
+
+    # Query usage
+    from varco_core import QueryBuilder, QueryParams
+    from varco_sa import SQLAlchemyRepositoryProvider
+
+    provider = SQLAlchemyRepositoryProvider(base=Base, session_factory=async_session)
+    provider.register(User, Post)
+
+    async with provider.make_uow() as uow:
+        active_users = await uow.users.find_by_query(
+            QueryParams(
+                node=QueryBuilder().eq("active", True).build(),
+                limit=20,
+            )
+        )
+
+Sub-package layout
+------------------
+    varco_sa/
+    ├── factory.py    — SAModelFactory (DomainModel → SA ORM class at runtime)
+    │                   SAModelRegistry (process-level ORM class registry)
+    ├── provider.py   — SQLAlchemyRepositoryProvider
+    ├── repository.py — AsyncSQLAlchemyRepository (CRUD + find_by_query + count)
+    ├── uow.py        — SQLAlchemyUnitOfWork
+    └── models.py     — BaseDatabaseModel
+"""
+
+from __future__ import annotations
+
+from varco_sa.alembic_helpers import get_target_metadata, print_create_ddl
+from varco_sa.bootstrap import SAConfig, SAFastrestApp
+from varco_sa.factory import SAModelFactory, SAModelRegistry
+from varco_sa.models import BaseDatabaseModel
+from varco_sa.provider import SQLAlchemyRepositoryProvider
+from varco_sa.repository import AsyncSQLAlchemyRepository
+from varco_sa.schema_guard import SchemaGuard, SchemaDrift, SchemaDriftReport
+from varco_sa.uow import SQLAlchemyUnitOfWork
+
+# SA-specific applicator is in varco_core (no session; pure SA expressions)
+from varco_core.query.applicator.sqlalchemy import SQLAlchemyQueryApplicator
+from varco_sa.type_coercion import registry_from_sa_model
+
+__all__ = [
+    # ── Factory + registry ─────────────────────────────────────────────────────
+    "SAModelFactory",
+    "SAModelRegistry",
+    # ── Repository + UoW ──────────────────────────────────────────────────────
+    "AsyncSQLAlchemyRepository",
+    "SQLAlchemyUnitOfWork",
+    # ── Provider ──────────────────────────────────────────────────────────────
+    "SQLAlchemyRepositoryProvider",
+    # ── Base models ───────────────────────────────────────────────────────────
+    "BaseDatabaseModel",
+    # ── Query applicator ──────────────────────────────────────────────────────
+    "SQLAlchemyQueryApplicator",
+    # ── Schema guard ──────────────────────────────────────────────────────────
+    "SchemaGuard",
+    "SchemaDrift",
+    "SchemaDriftReport",
+    # ── Type coercion ─────────────────────────────────────────────────────────
+    "registry_from_sa_model",
+    # ── Alembic helpers ───────────────────────────────────────────────────────
+    "get_target_metadata",
+    "print_create_ddl",
+    # ── Bootstrap ─────────────────────────────────────────────────────────────
+    "SAConfig",
+    "SAFastrestApp",
+]