pysql-executor 0.1.0__py3-none-any.whl

pysql_executor-0.1.0.dist-info/METADATA

@@ -0,0 +1,85 @@
+Metadata-Version: 2.4
+Name: pysql-executor
+Version: 0.1.0
+Summary: Backend-agnostic stored-procedure / SQL executor with a pluggable base class
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+Provides-Extra: sqlserver
+Requires-Dist: pyodbc>=4.0; extra == "sqlserver"
+
+# sql-executor (v1, 0.1.0)
+
+Backend-agnostic stored-procedure / SQL executor. `BaseSqlExecutor` owns
+connection lifecycle, commit/rollback, fetch-to-dict, chunked streaming,
+and error wrapping. A new backend only implements two methods.
+
+## Usage (SQL Server)
+
+```python
+from sql_executor import SqlServerExecutor, DatabaseError
+
+db = SqlServerExecutor(connstring="DRIVER={ODBC Driver 17 for SQL Server};...")
+
+# Stored procedure
+rows = db.call_procedure("dbo.GetIncidents", params=("2026-06-01",), fetch=True)
+
+# Raw SQL
+db.execute("UPDATE dbo.Logs SET status = ? WHERE id = ?", params=("done", 42))
+
+# Stream large result sets in chunks instead of loading everything into memory
+for row in db.stream_procedure("dbo.GetBigReport", chunk_size=1000):
+    process(row)
+
+try:
+    db.execute("DELETE FROM dbo.Logs WHERE id = ?", params=(42,))
+except DatabaseError:
+    # Always raised on failure — never swallowed as None/False.
+    raise
+```
+
+## Adding a new backend (e.g. Postgres, Oracle)
+
+Subclass `BaseSqlExecutor` and implement two methods:
+
+```python
+import psycopg2
+from sql_executor import BaseSqlExecutor
+
+class PostgresExecutor(BaseSqlExecutor):
+    driver_error = psycopg2.Error
+
+    def __init__(self, dsn: str):
+        self.dsn = dsn
+
+    def _connect(self):
+        return psycopg2.connect(self.dsn)
+
+    def _call_procedure_sql(self, sp_name, params):
+        placeholders = ",".join("%s" for _ in params)
+        return f"CALL {sp_name}({placeholders})"
+```
+
+`call_procedure`, `execute`, `stream`, and `stream_procedure` all come for
+free from the base class.
+
+## Testing
+
+`FakeExecutor` is a drop-in for `SqlServerExecutor` with no real DB:
+
+```python
+from sql_executor import FakeExecutor
+
+fake = FakeExecutor()
+fake.register("dbo.GetIncidents", lambda since: [{"id": 1, "since": since}])
+fake.call_procedure("dbo.GetIncidents", params=("2026-06-01",), fetch=True)
+```
+
+## Offline install (corporate VM, no internet)
+
+Build the wheel on a machine with internet access, then copy the `.whl`
+to the VM:
+
+```bash
+pip install --no-index --find-links=. sql_executor-0.1.0-py3-none-any.whl
+pip install pyodbc  # only needed if you use SqlServerExecutor, also offline-installed
+```

pysql_executor-0.1.0.dist-info/RECORD

@@ -0,0 +1,8 @@
+sql_executor/__init__.py,sha256=MPuKwTp_HuGCacbesI5IN9vGmHzmeRamCTV49s4--QY,715
+sql_executor/base.py,sha256=XY1KRKe1TG50toiEwMoZTvQK6id4xVbybnKjap7rEew,4366
+sql_executor/fake.py,sha256=JOcDeKdP9QVh65eqSNR-lE9woSWTYMOGj3qY0HhmMpE,1581
+sql_executor/sqlserver.py,sha256=KaccpBPHOnvzNMe8KIujvscCe4IW6_OSRshjZkuz0SQ,682
+pysql_executor-0.1.0.dist-info/METADATA,sha256=_IVCfr0QYwOADikiXTNlQkv-G6M4uMm7AfRvUtjrWFk,2476
+pysql_executor-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+pysql_executor-0.1.0.dist-info/top_level.txt,sha256=QT6VLZ2kt3I5MHLJKJcSavBGerkvIw57RvQyZu43A48,13
+pysql_executor-0.1.0.dist-info/RECORD,,

pysql_executor-0.1.0.dist-info/WHEEL

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

pysql_executor-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+sql_executor

sql_executor/__init__.py

@@ -0,0 +1,23 @@
+from .base import BaseSqlExecutor, DatabaseError
+from .fake import FakeExecutor
+
+__all__ = [
+    "BaseSqlExecutor",
+    "DatabaseError",
+    "SqlServerExecutor",
+    "FakeExecutor",
+]
+
+__version__ = "0.1.0"
+
+
+def __getattr__(name: str):
+    # Lazy import: SqlServerExecutor pulls in pyodbc (+ system unixODBC),
+    # which not every environment has (e.g. running tests with FakeExecutor
+    # only). Importing it on first access keeps `from sql_executor import
+    # FakeExecutor` working even if pyodbc isn't installed.
+    if name == "SqlServerExecutor":
+        from .sqlserver import SqlServerExecutor
+
+        return SqlServerExecutor
+    raise AttributeError(f"module {__name__!r} has no attribute {name!r}")

sql_executor/base.py

@@ -0,0 +1,120 @@
+"""Backend-agnostic base for stored-procedure / SQL executors.
+
+Template Method pattern: this class owns everything that's the same
+across DB backends (cursor lifecycle, commit/rollback, fetch-to-dict,
+chunked streaming, error wrapping). A subclass only has to implement:
+
+  - _connect()              -> open a DB-API 2.0 connection
+  - _call_procedure_sql()   -> dialect-specific "call this SP" string
+
+Everything else (call_procedure, execute, stream, stream_procedure) is
+inherited for free. See sqlserver.py for a ~15-line concrete example.
+"""
+
+from __future__ import annotations
+
+import abc
+import logging
+from contextlib import contextmanager
+from typing import Any, Dict, Iterator, List, Sequence
+
+logger = logging.getLogger(__name__)
+
+
+class DatabaseError(Exception):
+    """Raised when a stored procedure / SQL execution fails.
+
+    Callers should catch this rather than checking for None/False —
+    it's always raised on failure, never swallowed.
+    """
+
+
+def _rows_to_dicts(cursor) -> List[Dict[str, Any]]:
+    columns = [col[0].lower() for col in cursor.description]
+    return [dict(zip(columns, row)) for row in cursor.fetchall()]
+
+
+class BaseSqlExecutor(abc.ABC):
+    # Subclass should override with their driver's exception type,
+    # e.g. `pyodbc.Error`, `psycopg2.Error`, `cx_Oracle.Error`.
+    # Left as plain Exception here so a forgetful subclass still works,
+    # just with a less precise catch.
+    driver_error: type = Exception
+
+    # ---- subclasses must implement -------------------------------------
+    @abc.abstractmethod
+    def _connect(self):
+        """Return a new DB-API 2.0 connection."""
+
+    @abc.abstractmethod
+    def _call_procedure_sql(self, sp_name: str, params: Sequence[Any]) -> str:
+        """Return the dialect-specific SQL string to call a stored procedure."""
+
+    # ---- shared cursor lifecycle ----------------------------------------
+    @contextmanager
+    def _get_cursor(self):
+        conn = self._connect()
+        try:
+            cursor = conn.cursor()
+            yield cursor
+            conn.commit()
+        except Exception:
+            conn.rollback()
+            raise
+        finally:
+            conn.close()
+
+    def _run(self, sql: str, params: Sequence[Any], fetch: bool):
+        try:
+            with self._get_cursor() as cursor:
+                if params:
+                    cursor.execute(sql, params)
+                else:
+                    cursor.execute(sql)
+                return _rows_to_dicts(cursor) if fetch else True
+        except self.driver_error as db_ex:
+            logger.exception("DB error executing: %s", sql)
+            raise DatabaseError(str(db_ex)) from db_ex
+
+    # ---- public API ----------------------------------------------------
+    def call_procedure(
+        self, sp_name: str, params: Sequence[Any] = (), fetch: bool = False
+    ):
+        sql = self._call_procedure_sql(sp_name, params)
+        return self._run(sql, tuple(params), fetch)
+
+    def execute(self, sql: str, params: Sequence[Any] = (), fetch: bool = False):
+        """Run raw SQL (SELECT/INSERT/UPDATE/DELETE)."""
+        return self._run(sql, tuple(params), fetch)
+
+    def stream(
+        self,
+        sql: str,
+        params: Sequence[Any] = (),
+        chunk_size: int = 500,
+    ) -> Iterator[Dict[str, Any]]:
+        """Yield rows in chunks — for big SELECTs or SPs returning lots of rows."""
+        try:
+            with self._get_cursor() as cursor:
+                cursor.arraysize = chunk_size
+                if params:
+                    cursor.execute(sql, params)
+                else:
+                    cursor.execute(sql)
+                columns = [col[0].lower() for col in cursor.description]
+
+                while True:
+                    rows = cursor.fetchmany(chunk_size)
+                    if not rows:
+                        break
+                    for row in rows:
+                        yield dict(zip(columns, row))
+        except self.driver_error as db_ex:
+            logger.exception("DB error streaming: %s", sql)
+            raise DatabaseError(str(db_ex)) from db_ex
+
+    def stream_procedure(
+        self, sp_name: str, params: Sequence[Any] = (), chunk_size: int = 500
+    ) -> Iterator[Dict[str, Any]]:
+        sql = self._call_procedure_sql(sp_name, params)
+        yield from self.stream(sql, tuple(params), chunk_size)

sql_executor/fake.py

@@ -0,0 +1,44 @@
+"""In-memory test double — no real DB connection involved."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Sequence
+
+from .base import BaseSqlExecutor
+
+
+class FakeExecutor(BaseSqlExecutor):
+    """Register a Python callable per stored-procedure name and call it
+    just like the real thing, for unit tests.
+
+        fake = FakeExecutor()
+        fake.register("dbo.GetIncidents", lambda since: [{"id": 1}])
+        fake.call_procedure("dbo.GetIncidents", params=("2026-06-01",), fetch=True)
+    """
+
+    driver_error = Exception
+
+    def __init__(self):
+        self.handlers: Dict[str, Callable[..., Any]] = {}
+
+    def register(self, sp_name: str, handler: Callable[..., Any]):
+        self.handlers[sp_name] = handler
+
+    def _connect(self):
+        raise NotImplementedError("FakeExecutor never opens a real connection")
+
+    def _call_procedure_sql(self, sp_name: str, params: Sequence[Any]) -> str:
+        # Unused — call_procedure is overridden below instead of going
+        # through _run()/_connect(), since there's no real cursor here.
+        return sp_name
+
+    def call_procedure(
+        self, sp_name: str, params: Sequence[Any] = (), fetch: bool = False
+    ):
+        if sp_name not in self.handlers:
+            raise ValueError(f"No handler registered for {sp_name!r}")
+        result = self.handlers[sp_name](*params)
+        return result if fetch else True
+
+    def execute(self, sql: str, params: Sequence[Any] = (), fetch: bool = False):
+        raise NotImplementedError("FakeExecutor only fakes stored procedures")

sql_executor/sqlserver.py

@@ -0,0 +1,25 @@
+"""SQL Server backend — the only piece that knows about pyodbc."""
+
+from __future__ import annotations
+
+from typing import Any, Sequence
+
+import pyodbc
+
+from .base import BaseSqlExecutor
+
+
+class SqlServerExecutor(BaseSqlExecutor):
+    """Stored-procedure / SQL executor for SQL Server, backed by pyodbc."""
+
+    driver_error = pyodbc.Error
+
+    def __init__(self, connstring: str):
+        self.connstring = connstring
+
+    def _connect(self):
+        return pyodbc.connect(self.connstring)
+
+    def _call_procedure_sql(self, sp_name: str, params: Sequence[Any]) -> str:
+        placeholders = ",".join("?" for _ in params)
+        return f"EXEC {sp_name} {placeholders}".strip()