muscles-sql 1.0.0__tar.gz

muscles_sql-1.0.0/PKG-INFO

@@ -0,0 +1,103 @@
+Metadata-Version: 2.4
+Name: muscles-sql
+Version: 1.0.0
+Summary: Muscles SQL data layer for repositories, migrations and AI-first workflow.
+Author-email: "Denis B." <denis@butko.info>
+License-Expression: MIT
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: muscles<2.0.0,>=1.0.0rc1
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Requires-Dist: alembic<2.0,>=1.13
+Requires-Dist: click<9.0,>=8.1
+Requires-Dist: pydantic<3.0,>=2.7
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# Muscles SQL
+
+Muscles SQL is a data layer package for SQL databases:
+- model-to-table mapping
+- engine and session management
+- repository CRUD and advanced query API (filters/operators/joins/aggregates)
+- transactions and Unit of Work (nested/savepoint/retry helpers)
+- migrations v2 commands (Alembic-compatible lazy-load)
+- inspect/doctor support with machine-readable diagnostics
+
+## Related Repositories
+
+- [`muscles`](https://github.com/butkoden/muscles) - core schemas, actions, DI and canonical documentation.
+- [`muscles-documents`](https://github.com/butkoden/muscles-documents) - document metadata/state can use SQL persistence in applications.
+- [`muscles-ai`](https://github.com/butkoden/muscles-ai) - AI/RAG flows can use SQL-backed application state without making SQL generic storage.
+- [`muscles-otel`](https://github.com/butkoden/muscles-otel) - observability hooks around SQL-backed flows.
+- [`muscles-benchmarks`](https://github.com/butkoden/muscles-benchmarks) - SQL transaction and mapping regression checks.
+
+## Quickstart
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install muscles-sql
+```
+
+For local development with the test dependencies:
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+muscles-sql doctor --url sqlite:///./app.db
+```
+
+## Named SQL Connections
+
+`muscles-sql` can manage multiple SQL connections without becoming a generic
+storage registry. The registry is SQL-only: it owns SQL connection configs,
+lazy SQLAlchemy `EngineManager` instances, sessions, inspect and doctor reports.
+
+```python
+from muscles_sql import SqlConnectionConfig, SqlConnectionRegistry
+
+registry = SqlConnectionRegistry(
+    [
+        SqlConnectionConfig(name="default", url="sqlite:///./app.db"),
+        SqlConnectionConfig(name="analytics", url="sqlite:///./analytics.db", role="read"),
+    ]
+)
+
+session = registry.session("analytics")
+report = registry.inspect("analytics")
+```
+
+CLI diagnostics can read a JSON config:
+
+```json
+{
+  "connections": {
+    "default": "sqlite:///./app.db",
+    "analytics": {"url": "sqlite:///./analytics.db", "role": "read"}
+  }
+}
+```
+
+```bash
+muscles-sql inspect --config sql-connections.json --connection analytics
+muscles-sql doctor --config sql-connections.json --all
+```
+
+Diagnostic output uses safe URLs and does not print passwords from DSNs.
+
+## Advanced Query Example
+
+```python
+from sqlalchemy import func
+from muscles_sql import FilterClause, JoinClause, QuerySpec, SqlRepository
+
+spec = QuerySpec(
+    filters=[FilterClause("status", "eq", "active")],
+    joins=[JoinClause(table=orders, on=users.c.id == orders.c.user_id)],
+    select_columns=[users.c.id, func.count(orders.c.id).label("orders_total")],
+    group_by=[users.c.id],
+    order_by=[users.c.id.asc()],
+)
+rows = SqlRepository(session, users).aggregate(spec)
+```

muscles_sql-1.0.0/README.md

@@ -0,0 +1,87 @@
+# Muscles SQL
+
+Muscles SQL is a data layer package for SQL databases:
+- model-to-table mapping
+- engine and session management
+- repository CRUD and advanced query API (filters/operators/joins/aggregates)
+- transactions and Unit of Work (nested/savepoint/retry helpers)
+- migrations v2 commands (Alembic-compatible lazy-load)
+- inspect/doctor support with machine-readable diagnostics
+
+## Related Repositories
+
+- [`muscles`](https://github.com/butkoden/muscles) - core schemas, actions, DI and canonical documentation.
+- [`muscles-documents`](https://github.com/butkoden/muscles-documents) - document metadata/state can use SQL persistence in applications.
+- [`muscles-ai`](https://github.com/butkoden/muscles-ai) - AI/RAG flows can use SQL-backed application state without making SQL generic storage.
+- [`muscles-otel`](https://github.com/butkoden/muscles-otel) - observability hooks around SQL-backed flows.
+- [`muscles-benchmarks`](https://github.com/butkoden/muscles-benchmarks) - SQL transaction and mapping regression checks.
+
+## Quickstart
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+pip install muscles-sql
+```
+
+For local development with the test dependencies:
+
+```bash
+pip install -e ".[dev]"
+pytest -q
+muscles-sql doctor --url sqlite:///./app.db
+```
+
+## Named SQL Connections
+
+`muscles-sql` can manage multiple SQL connections without becoming a generic
+storage registry. The registry is SQL-only: it owns SQL connection configs,
+lazy SQLAlchemy `EngineManager` instances, sessions, inspect and doctor reports.
+
+```python
+from muscles_sql import SqlConnectionConfig, SqlConnectionRegistry
+
+registry = SqlConnectionRegistry(
+    [
+        SqlConnectionConfig(name="default", url="sqlite:///./app.db"),
+        SqlConnectionConfig(name="analytics", url="sqlite:///./analytics.db", role="read"),
+    ]
+)
+
+session = registry.session("analytics")
+report = registry.inspect("analytics")
+```
+
+CLI diagnostics can read a JSON config:
+
+```json
+{
+  "connections": {
+    "default": "sqlite:///./app.db",
+    "analytics": {"url": "sqlite:///./analytics.db", "role": "read"}
+  }
+}
+```
+
+```bash
+muscles-sql inspect --config sql-connections.json --connection analytics
+muscles-sql doctor --config sql-connections.json --all
+```
+
+Diagnostic output uses safe URLs and does not print passwords from DSNs.
+
+## Advanced Query Example
+
+```python
+from sqlalchemy import func
+from muscles_sql import FilterClause, JoinClause, QuerySpec, SqlRepository
+
+spec = QuerySpec(
+    filters=[FilterClause("status", "eq", "active")],
+    joins=[JoinClause(table=orders, on=users.c.id == orders.c.user_id)],
+    select_columns=[users.c.id, func.count(orders.c.id).label("orders_total")],
+    group_by=[users.c.id],
+    order_by=[users.c.id.asc()],
+)
+rows = SqlRepository(session, users).aggregate(spec)
+```

muscles_sql-1.0.0/pyproject.toml

@@ -0,0 +1,36 @@
+[build-system]
+requires = ["setuptools>=69", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "muscles-sql"
+version = "1.0.0"
+description = "Muscles SQL data layer for repositories, migrations and AI-first workflow."
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.10"
+authors = [{ name = "Denis B.", email = "denis@butko.info" }]
+dependencies = [
+  "muscles>=1.0.0rc1,<2.0.0",
+  "SQLAlchemy>=2.0,<3.0",
+  "alembic>=1.13,<2.0",
+  "click>=8.1,<9.0",
+  "pydantic>=2.7,<3.0",
+]
+
+[project.optional-dependencies]
+dev = [
+  "pytest>=8.0,<9.0",
+]
+
+[project.scripts]
+muscles-sql = "muscles_sql.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+
+[tool.setuptools]
+package-dir = {"" = "src"}
+
+[tool.setuptools.packages.find]
+where = ["src"]

muscles_sql-1.0.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

muscles_sql-1.0.0/src/muscles_sql/__init__.py

@@ -0,0 +1,81 @@
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from .config import DatabaseConfig
+    from .config import SqlConnectionConfig
+    from .connections import SqlConnectionRegistry, UnknownSqlConnection
+    from .engine import EngineManager
+    from .mapping import map_model
+    from .providers import SqlResourceGeneratorProvider
+    from .query import FilterClause, JoinClause, QuerySpec
+    from .repository import SqlRepository
+    from .uow import UnitOfWork
+
+__all__ = [
+    "DatabaseConfig",
+    "SqlConnectionConfig",
+    "SqlConnectionRegistry",
+    "UnknownSqlConnection",
+    "EngineManager",
+    "map_model",
+    "SqlRepository",
+    "UnitOfWork",
+    "QuerySpec",
+    "FilterClause",
+    "JoinClause",
+    "SqlResourceGeneratorProvider",
+]
+
+
+def __getattr__(name: str):
+    if name == "DatabaseConfig":
+        from .config import DatabaseConfig
+
+        return DatabaseConfig
+    if name == "SqlConnectionConfig":
+        from .config import SqlConnectionConfig
+
+        return SqlConnectionConfig
+    if name == "SqlConnectionRegistry":
+        from .connections import SqlConnectionRegistry
+
+        return SqlConnectionRegistry
+    if name == "UnknownSqlConnection":
+        from .connections import UnknownSqlConnection
+
+        return UnknownSqlConnection
+    if name == "EngineManager":
+        from .engine import EngineManager
+
+        return EngineManager
+    if name == "map_model":
+        from .mapping import map_model
+
+        return map_model
+    if name == "SqlRepository":
+        from .repository import SqlRepository
+
+        return SqlRepository
+    if name == "UnitOfWork":
+        from .uow import UnitOfWork
+
+        return UnitOfWork
+    if name == "QuerySpec":
+        from .query import QuerySpec
+
+        return QuerySpec
+    if name == "FilterClause":
+        from .query import FilterClause
+
+        return FilterClause
+    if name == "JoinClause":
+        from .query import JoinClause
+
+        return JoinClause
+    if name == "SqlResourceGeneratorProvider":
+        from .providers import SqlResourceGeneratorProvider
+
+        return SqlResourceGeneratorProvider
+    raise AttributeError(name)

muscles_sql-1.0.0/src/muscles_sql/cli.py

@@ -0,0 +1,144 @@
+import json
+from pathlib import Path
+
+import click
+
+from .config import DatabaseConfig
+from .connections import SqlConnectionRegistry, load_connection_registry
+from .providers import SqlGenerationRequest, SqlResourceGeneratorProvider
+
+
+@click.group()
+def main():
+    pass
+
+
+def _registry_from_options(url: str | None, config_path: str | None) -> SqlConnectionRegistry:
+    if config_path:
+        return load_connection_registry(config_path)
+    if url:
+        return SqlConnectionRegistry.from_database_config(DatabaseConfig(url=url))
+    raise click.UsageError("Use --url or --config.")
+
+
+@main.command("doctor")
+@click.option("--url", required=False)
+@click.option("--config", "config_path", type=click.Path(exists=True, dir_okay=False), required=False)
+@click.option("--connection", default="default", show_default=True)
+@click.option("--all", "all_connections", is_flag=True, default=False)
+def doctor(url: str | None, config_path: str | None, connection: str, all_connections: bool):
+    registry = _registry_from_options(url, config_path)
+    report = registry.inspect_all() if all_connections else registry.inspect(connection)
+    click.echo(json.dumps(report, ensure_ascii=False))
+
+
+@main.command("inspect")
+@click.option("--url", required=False)
+@click.option("--config", "config_path", type=click.Path(exists=True, dir_okay=False), required=False)
+@click.option("--connection", default="default", show_default=True)
+def inspect_cmd(url: str | None, config_path: str | None, connection: str):
+    registry = _registry_from_options(url, config_path)
+    click.echo(json.dumps(registry.inspect(connection), ensure_ascii=False))
+
+
+@main.group("migrate")
+def migrate():
+    pass
+
+
+@migrate.command("init")
+@click.option("--dir", "target_dir", default="migrations")
+def migrate_init(target_dir: str):
+    from .migrations import init_migrations
+
+    root = init_migrations(target_dir=target_dir)
+    click.echo(str(root))
+
+
+@migrate.command("revision")
+@click.option("--dir", "target_dir", default="migrations")
+@click.option("--message", default="revision")
+@click.option("--autogenerate", is_flag=True, default=False)
+@click.option("--url", default=None)
+def migrate_revision(target_dir: str, message: str, autogenerate: bool, url: str | None):
+    from .migrations import revision
+
+    revision(message=message, target_dir=target_dir, autogenerate=autogenerate, url=url)
+    click.echo("ok")
+
+
+@migrate.command("upgrade")
+@click.option("--dir", "target_dir", default="migrations")
+@click.option("--rev", default="head")
+@click.option("--url", default=None)
+def migrate_upgrade(target_dir: str, rev: str, url: str | None):
+    from .migrations import upgrade
+
+    upgrade(rev=rev, target_dir=target_dir, url=url)
+    click.echo("ok")
+
+
+@migrate.command("downgrade")
+@click.option("--dir", "target_dir", default="migrations")
+@click.option("--rev", default="-1")
+@click.option("--url", default=None)
+def migrate_downgrade(target_dir: str, rev: str, url: str | None):
+    from .migrations import downgrade
+
+    downgrade(rev=rev, target_dir=target_dir, url=url)
+    click.echo("ok")
+
+
+@migrate.command("history")
+@click.option("--dir", "target_dir", default="migrations")
+@click.option("--url", default=None)
+def migrate_history(target_dir: str, url: str | None):
+    from .migrations import history
+
+    history(target_dir=target_dir, url=url)
+    click.echo("ok")
+
+
+@migrate.command("current")
+@click.option("--dir", "target_dir", default="migrations")
+@click.option("--url", default=None)
+def migrate_current(target_dir: str, url: str | None):
+    from .migrations import current
+
+    current(target_dir=target_dir, url=url)
+    click.echo("ok")
+
+
+@main.group("generate")
+def generate():
+    pass
+
+
+@generate.command("resource")
+@click.argument("name")
+@click.option("--sql", is_flag=True, default=False)
+def generate_resource(name: str, sql: bool):
+    if sql:
+        provider = SqlResourceGeneratorProvider()
+        generated = provider.generate(
+            project_root=Path.cwd(),
+            request=SqlGenerationRequest(
+                generator_type="sql-resource",
+                name=name,
+                force=False,
+                with_tests=False,
+            ),
+        )
+        click.echo(generated[0])
+        return
+
+    root = Path("generated")
+    root.mkdir(exist_ok=True)
+    target = root / f"{name}.py"
+    content = f"class {name.title().replace('_', '')}Resource:\n    sql_enabled = {sql}\n"
+    target.write_text(content, encoding="utf-8")
+    click.echo(str(target))
+
+
+if __name__ == "__main__":
+    main()

muscles_sql-1.0.0/src/muscles_sql/config.py

@@ -0,0 +1,46 @@
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass(slots=True)
+class DatabaseConfig:
+    url: str
+    echo: bool = False
+    pool_size: int = 5
+    max_overflow: int = 10
+    future: bool = True
+
+
+@dataclass(slots=True)
+class SqlConnectionConfig:
+    name: str
+    url: str
+    echo: bool = False
+    pool_size: int = 5
+    max_overflow: int = 10
+    future: bool = True
+    role: str | None = None
+    metadata: dict[str, Any] = field(default_factory=dict)
+
+    @property
+    def safe_url(self) -> str:
+        from sqlalchemy.engine import make_url
+
+        return make_url(self.url).render_as_string(hide_password=True)
+
+    def to_database_config(self) -> DatabaseConfig:
+        return DatabaseConfig(
+            url=self.url,
+            echo=self.echo,
+            pool_size=self.pool_size,
+            max_overflow=self.max_overflow,
+            future=self.future,
+        )
+
+    def to_contract(self) -> dict[str, Any]:
+        return {
+            "name": self.name,
+            "url": self.safe_url,
+            "role": self.role,
+            "metadata": dict(self.metadata),
+        }

muscles_sql-1.0.0/src/muscles_sql/connections.py

@@ -0,0 +1,105 @@
+from __future__ import annotations
+
+from pathlib import Path
+from typing import Any, Iterable, Mapping
+
+from .config import DatabaseConfig, SqlConnectionConfig
+from .engine import EngineManager
+
+
+class UnknownSqlConnection(KeyError):
+    def __init__(self, name: str):
+        super().__init__(f"Unknown SQL connection: {name}")
+        self.name = name
+
+
+class SqlConnectionRegistry:
+    def __init__(self, configs: Iterable[SqlConnectionConfig] | None = None):
+        self._configs: dict[str, SqlConnectionConfig] = {}
+        self._managers: dict[str, EngineManager] = {}
+        for config in configs or ():
+            self.register(config)
+
+    @classmethod
+    def from_database_config(cls, config: DatabaseConfig, *, name: str = "default") -> "SqlConnectionRegistry":
+        return cls(
+            [
+                SqlConnectionConfig(
+                    name=name,
+                    url=config.url,
+                    echo=config.echo,
+                    pool_size=config.pool_size,
+                    max_overflow=config.max_overflow,
+                    future=config.future,
+                )
+            ]
+        )
+
+    def register(self, config: SqlConnectionConfig) -> None:
+        self._configs[config.name] = config
+        self._managers.pop(config.name, None)
+
+    def names(self) -> list[str]:
+        return sorted(self._configs)
+
+    def config(self, name: str = "default") -> SqlConnectionConfig:
+        try:
+            return self._configs[name]
+        except KeyError as exc:
+            raise UnknownSqlConnection(name) from exc
+
+    def manager(self, name: str = "default") -> EngineManager:
+        if name not in self._managers:
+            self._managers[name] = EngineManager(self.config(name).to_database_config())
+        return self._managers[name]
+
+    def session_factory(self, name: str = "default"):
+        return self.manager(name).session_factory
+
+    def session(self, name: str = "default"):
+        return self.manager(name).session()
+
+    def inspect(self, name: str = "default") -> dict[str, Any]:
+        from .inspect import inspect_sql_layer
+
+        config = self.config(name)
+        report = inspect_sql_layer(self.manager(name))
+        report["connection"] = config.to_contract()
+        return report
+
+    def inspect_all(self) -> dict[str, Any]:
+        reports = {name: self.inspect(name) for name in self.names()}
+        status = "ok" if all(report.get("status") == "ok" for report in reports.values()) else "error"
+        return {"status": status, "connections": reports}
+
+
+def connection_config_from_mapping(name: str, payload: str | Mapping[str, Any]) -> SqlConnectionConfig:
+    if isinstance(payload, str):
+        return SqlConnectionConfig(name=name, url=payload)
+    return SqlConnectionConfig(
+        name=str(payload.get("name", name)),
+        url=str(payload["url"]),
+        echo=bool(payload.get("echo", False)),
+        pool_size=int(payload.get("pool_size", 5)),
+        max_overflow=int(payload.get("max_overflow", 10)),
+        future=bool(payload.get("future", True)),
+        role=payload.get("role"),
+        metadata=dict(payload.get("metadata") or {}),
+    )
+
+
+def connection_registry_from_mapping(payload: Mapping[str, Any]) -> SqlConnectionRegistry:
+    raw_connections = payload.get("connections", payload)
+    if not isinstance(raw_connections, Mapping):
+        raise ValueError("SQL connection config must contain a mapping of connections.")
+    configs = [connection_config_from_mapping(str(name), value) for name, value in raw_connections.items()]
+    return SqlConnectionRegistry(configs)
+
+
+def load_connection_registry(path: str | Path) -> SqlConnectionRegistry:
+    import json
+
+    payload = json.loads(Path(path).read_text(encoding="utf-8"))
+    if not isinstance(payload, Mapping):
+        raise ValueError("SQL connection config must be a JSON object.")
+    return connection_registry_from_mapping(payload)

muscles_sql-1.0.0/src/muscles_sql/engine.py

@@ -0,0 +1,19 @@
+from typing import Any
+
+from .config import DatabaseConfig
+
+
+class EngineManager:
+    def __init__(self, config: DatabaseConfig):
+        from sqlalchemy import create_engine
+        from sqlalchemy.orm import sessionmaker
+
+        kwargs: dict[str, Any] = {"echo": config.echo, "future": config.future}
+        if not config.url.startswith("sqlite"):
+            kwargs["pool_size"] = config.pool_size
+            kwargs["max_overflow"] = config.max_overflow
+        self.engine = create_engine(config.url, **kwargs)
+        self.session_factory = sessionmaker(bind=self.engine, autoflush=False, autocommit=False, future=True)
+
+    def session(self):
+        return self.session_factory()

muscles_sql-1.0.0/src/muscles_sql/inspect.py

@@ -0,0 +1,26 @@
+def inspect_sql_layer(engine_manager) -> dict:
+    from time import perf_counter
+    from sqlalchemy import inspect, text
+
+    started = perf_counter()
+    with engine_manager.engine.connect() as conn:
+        conn.execute(text("SELECT 1"))
+    latency_ms = round((perf_counter() - started) * 1000, 3)
+    inspector = inspect(engine_manager.engine)
+    tables = []
+    for table_name in inspector.get_table_names():
+        tables.append(
+            {
+                "name": table_name,
+                "columns": [column["name"] for column in inspector.get_columns(table_name)],
+                "indexes": [index["name"] for index in inspector.get_indexes(table_name)],
+                "pk": inspector.get_pk_constraint(table_name).get("constrained_columns", []),
+            }
+        )
+    return {
+        "status": "ok",
+        "dialect": engine_manager.engine.dialect.name,
+        "driver": engine_manager.engine.dialect.driver,
+        "latency_ms": latency_ms,
+        "tables": tables,
+    }