muscles-data-sqlalchemy 0.1.0__py3-none-any.whl

muscles_data_sqlalchemy/__init__.py

@@ -0,0 +1,20 @@
+from __future__ import annotations
+
+from .adapter import (
+    SqlAlchemyAdapterError,
+    SqlAlchemyClientMissingError,
+    SqlAlchemyConfigError,
+    SqlAlchemyConnectionError,
+    SqlAlchemySqlResourceAdapter,
+    SqlAlchemySqlResourceFactory,
+)
+
+
+__all__ = [
+    "SqlAlchemyAdapterError",
+    "SqlAlchemyClientMissingError",
+    "SqlAlchemyConfigError",
+    "SqlAlchemyConnectionError",
+    "SqlAlchemySqlResourceAdapter",
+    "SqlAlchemySqlResourceFactory",
+]

muscles_data_sqlalchemy/adapter.py

@@ -0,0 +1,215 @@
+from __future__ import annotations
+
+import importlib
+import threading
+from collections.abc import Callable
+from dataclasses import asdict
+from typing import Any, Mapping
+
+from muscles_data.config import DataResourceConfig
+from muscles_data.errors import DataError
+from muscles_data.models import DataCapability, HealthResult, InspectResult
+
+
+_ENGINE_UNSET = object()
+_SESSION_FACTORY_UNSET = object()
+_ALLOWED_OPTIONS = {
+    "url",
+    "url_env",
+    "name",
+    "native_client",
+    "echo",
+    "pool_pre_ping",
+    "pool_size",
+    "max_overflow",
+    "connect_args",
+    "future",
+}
+_ENGINE_OPTIONS = {"echo", "pool_pre_ping", "pool_size", "max_overflow", "connect_args", "future"}
+
+
+class SqlAlchemyAdapterError(DataError):
+    """Base error for direct SQLAlchemy resource adapter failures."""
+
+
+class SqlAlchemyConfigError(ValueError, SqlAlchemyAdapterError):
+    """Raised when a SQLAlchemy resource config cannot be mapped safely."""
+
+
+class SqlAlchemyClientMissingError(SqlAlchemyAdapterError):
+    """Raised when SQLAlchemy is not installed for a direct SQLAlchemy resource."""
+
+
+class SqlAlchemyConnectionError(SqlAlchemyAdapterError):
+    """Raised when a SQLAlchemy engine/session operation fails."""
+
+
+class SqlAlchemySqlResourceAdapter:
+    resource_type = "sqlalchemy"
+
+    def __init__(
+        self,
+        config: DataResourceConfig,
+        *,
+        sqlalchemy_provider: Callable[[], Any] | None = None,
+    ) -> None:
+        self.config = config
+        self._sqlalchemy_provider = sqlalchemy_provider
+        self._sqlalchemy: Any | None = None
+        self._engine: Any = _ENGINE_UNSET
+        self._session_factory: Any = _SESSION_FACTORY_UNSET
+        self._lock = threading.RLock()
+        self.closed = False
+
+    def connection_name(self) -> str:
+        return str(self.config.options.get("name", self.config.name))
+
+    def session(self):
+        try:
+            return self.session_factory()()
+        except (SqlAlchemyClientMissingError, SqlAlchemyConfigError, SqlAlchemyConnectionError):
+            raise
+        except Exception as exc:
+            raise SqlAlchemyConnectionError(self._safe_error(exc)) from exc
+
+    def session_factory(self):
+        if self._session_factory is _SESSION_FACTORY_UNSET:
+            with self._lock:
+                if self._session_factory is _SESSION_FACTORY_UNSET:
+                    self._sqlalchemy_module()
+                    try:
+                        orm = importlib.import_module("sqlalchemy.orm")
+                        self._session_factory = orm.sessionmaker(bind=self._engine_instance())
+                    except (SqlAlchemyClientMissingError, SqlAlchemyConfigError, SqlAlchemyConnectionError):
+                        raise
+                    except Exception as exc:
+                        raise SqlAlchemyConnectionError(self._safe_error(exc)) from exc
+        return self._session_factory
+
+    def inspect(self) -> Mapping[str, Any]:
+        return asdict(
+            InspectResult(
+                name=self.config.name,
+                type=self.config.type,
+                capabilities=[],
+                initialized=self._engine is not _ENGINE_UNSET,
+                status="ok",
+                options=self.config.safe_options(),
+                details={
+                    "backend": "sqlalchemy",
+                    "connection": self.connection_name(),
+                    "engine_initialized": self._engine is not _ENGINE_UNSET,
+                },
+            )
+        )
+
+    def doctor(self) -> Mapping[str, Any]:
+        try:
+            sqlalchemy = self._sqlalchemy_module()
+            with self._engine_instance().connect() as connection:
+                connection.execute(sqlalchemy.text("SELECT 1"))
+        except Exception as exc:
+            return {
+                "status": "failed",
+                "message": self._safe_error(exc),
+                "details": {"backend": "sqlalchemy", "connection": self.connection_name()},
+            }
+        return {
+            "status": "ok",
+            "message": "SQLAlchemy connection is available",
+            "details": {"backend": "sqlalchemy", "connection": self.connection_name()},
+        }
+
+    def health(self) -> HealthResult:
+        doctor = self.doctor()
+        return HealthResult(
+            status=str(doctor.get("status", "failed")),
+            message=doctor.get("message"),
+            details=dict(doctor.get("details", {}) or {}),
+        )
+
+    def close(self) -> None:
+        if self._engine is not _ENGINE_UNSET:
+            dispose = getattr(self._engine, "dispose", None)
+            if callable(dispose):
+                dispose()
+        self.closed = True
+
+    def native_client(self):
+        return {"engine": self._engine_instance(), "session_factory": self.session_factory()}
+
+    def _engine_instance(self):
+        if self._engine is _ENGINE_UNSET:
+            with self._lock:
+                if self._engine is _ENGINE_UNSET:
+                    self._engine = self._create_engine()
+        return self._engine
+
+    def _create_engine(self):
+        self._validate_options()
+        sqlalchemy = self._sqlalchemy_module()
+        options = self.config.resolved_options()
+        kwargs = _engine_options(options)
+        try:
+            return sqlalchemy.create_engine(str(options["url"]), **kwargs)
+        except Exception as exc:
+            raise SqlAlchemyConnectionError(self._safe_error(exc)) from exc
+
+    def _sqlalchemy_module(self):
+        if self._sqlalchemy is None:
+            module = self._sqlalchemy_provider() if self._sqlalchemy_provider else _default_sqlalchemy_module()
+            if module is None:
+                raise SqlAlchemyClientMissingError("Install SQLAlchemy or muscles-data-sqlalchemy to use type=sqlalchemy")
+            self._sqlalchemy = module
+        return self._sqlalchemy
+
+    def _validate_options(self) -> None:
+        unknown = sorted(set(self.config.options) - _ALLOWED_OPTIONS)
+        if unknown:
+            names = ", ".join(unknown)
+            raise SqlAlchemyConfigError(f"Unsupported SQLAlchemy resource options: {names}")
+        if not self.config.options.get("url") and not self.config.options.get("url_env"):
+            raise SqlAlchemyConfigError("SQLAlchemy resource requires url or url_env")
+        connect_args = self.config.options.get("connect_args")
+        if connect_args is not None and not isinstance(connect_args, Mapping):
+            raise SqlAlchemyConfigError("SQLAlchemy connect_args must be a mapping")
+
+    def _safe_error(self, exc: Exception) -> str:
+        message = str(exc)
+        try:
+            url = str(self.config.resolved_options().get("url", ""))
+        except Exception:
+            url = str(self.config.options.get("url", ""))
+        if url:
+            message = message.replace(url, "***")
+        safe_url = self.config.safe_options().get("url")
+        if isinstance(safe_url, str) and safe_url != url:
+            message = message.replace(safe_url, "***")
+        return message
+
+
+class SqlAlchemySqlResourceFactory:
+    resource_type = "sqlalchemy"
+
+    def __init__(self, *, sqlalchemy_provider: Callable[[], Any] | None = None) -> None:
+        self._sqlalchemy_provider = sqlalchemy_provider
+
+    def capabilities(self, config: DataResourceConfig) -> set[DataCapability]:
+        native = {DataCapability.NATIVE_CLIENT} if bool(config.options.get("native_client")) else set()
+        return {DataCapability.SQL_SESSION, DataCapability.HEALTHCHECK} | native
+
+    def create(self, config: DataResourceConfig) -> SqlAlchemySqlResourceAdapter:
+        return SqlAlchemySqlResourceAdapter(config, sqlalchemy_provider=self._sqlalchemy_provider)
+
+
+def _engine_options(options: Mapping[str, Any]) -> dict[str, Any]:
+    output = {key: options[key] for key in _ENGINE_OPTIONS if key in options}
+    output.setdefault("future", True)
+    return output
+
+
+def _default_sqlalchemy_module():
+    try:
+        return importlib.import_module("sqlalchemy")
+    except Exception as exc:
+        raise SqlAlchemyClientMissingError("Install SQLAlchemy or muscles-data-sqlalchemy to use type=sqlalchemy") from exc

muscles_data_sqlalchemy-0.1.0.dist-info/METADATA

@@ -0,0 +1,80 @@
+Metadata-Version: 2.4
+Name: muscles-data-sqlalchemy
+Version: 0.1.0
+Summary: SQLAlchemy SqlResourcePort adapter for muscles-data
+Author-email: "Denis B." <denis@butko.info>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: muscles-data<1.0.0,>=0.1.0
+Requires-Dist: SQLAlchemy<3.0,>=2.0
+Provides-Extra: dev
+Requires-Dist: pytest<9.0,>=8.0; extra == "dev"
+
+# muscles-data-sqlalchemy
+
+SQLAlchemy adapter package for `muscles-data`.
+
+This package is intentionally separate from `muscles-data`: the core package
+owns typed ports, resource runtime and diagnostics, while this package owns the
+SQLAlchemy-backed `SqlResourcePort` adapter.
+
+Use this package when a project wants direct SQLAlchemy sessions through the
+same data resource runtime without wiring `muscles-sql` first.
+
+## Related packages
+
+- Core runtime and port contracts:
+  [`muscles-data`](https://github.com/butkoden/muscles-data)
+- Elasticsearch search adapter:
+  [`muscles-data-elasticsearch`](https://github.com/butkoden/muscles-data-elasticsearch)
+- OpenSearch search adapter:
+  [`muscles-data-opensearch`](https://github.com/butkoden/muscles-data-opensearch)
+- Redis key-value/lock/stream adapter:
+  [`muscles-data-redis`](https://github.com/butkoden/muscles-data-redis)
+- Qdrant vector adapter:
+  [`muscles-data-qdrant`](https://github.com/butkoden/muscles-data-qdrant)
+- MongoDB document-store adapter:
+  [`muscles-data-mongodb`](https://github.com/butkoden/muscles-data-mongodb)
+- S3 object-store adapter:
+  [`muscles-data-s3`](https://github.com/butkoden/muscles-data-s3)
+- Executable example:
+  [`example_data_sqlalchemy_1`](https://github.com/butkoden/muscular-example/tree/master/example_data_sqlalchemy_1)
+
+## Usage
+
+Register the factory in the project composition root:
+
+```python
+from muscles_data.catalog import DataAdapterCatalog
+from muscles_data.ports import SqlResourcePort
+from muscles_data.runtime import DataRuntime
+from muscles_data_sqlalchemy import SqlAlchemySqlResourceFactory
+
+catalog = DataAdapterCatalog.with_defaults()
+catalog.register(SqlAlchemySqlResourceFactory())
+
+runtime = DataRuntime(config=config, catalog=catalog)
+sql = runtime.require_port("sql.local", SqlResourcePort)
+```
+
+Resource config stays in the project:
+
+```yaml
+data:
+  resources:
+    sql.local:
+      type: sqlalchemy
+      url: sqlite:///:memory:
+      name: local_sqlite
+      pool_pre_ping: true
+      native_client: false
+```
+
+`data.resources.list` does not create the engine. The engine/session factory is
+created lazily by `session()`, `session_factory()`, explicit native access or
+`data.doctor`.
+
+Application code should use `SqlResourcePort`; direct engine/session-factory
+access is only an advanced escape hatch with `native_client: true`.
+
+See `muscular-example/example_data_sqlalchemy_1` for an executable example.

muscles_data_sqlalchemy-0.1.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+muscles_data_sqlalchemy/__init__.py,sha256=5_u2yroYfLJ-AnduDarOAvn0-RoCVLU88H4pZ56nUoI,465
+muscles_data_sqlalchemy/adapter.py,sha256=yY_K8uRlXF-XPeIs7MlzHc-h46UJB6l2MakBQPJv2aQ,8127
+muscles_data_sqlalchemy-0.1.0.dist-info/METADATA,sha256=LZijzuvRXFUzVkgwyMgIl9waH_d-IgFxNzzakTsG_Jo,2817
+muscles_data_sqlalchemy-0.1.0.dist-info/WHEEL,sha256=K260EYznzXsJYBQGqmI8VTxEdiZYNvDZwW9cBh9-_MA,91
+muscles_data_sqlalchemy-0.1.0.dist-info/top_level.txt,sha256=bXh2_zYVyyKeu-0HjWavLwYf-n2G5Ti7fELlfJl0sIU,24
+muscles_data_sqlalchemy-0.1.0.dist-info/RECORD,,

muscles_data_sqlalchemy-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (83.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

muscles_data_sqlalchemy-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+muscles_data_sqlalchemy