velocity-python 0.1.30__tar.gz → 0.1.31__tar.gz

{velocity_python-0.1.30/src/velocity_python.egg-info → velocity_python-0.1.31}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.30
+Version: 0.1.31
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.30 → velocity_python-0.1.31}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "velocity-python"
-version = "0.1.30"
+version = "0.1.31"
 authors = [
   { name="Velocity Team", email="info@codeclubs.org" },
 ]

{velocity_python-0.1.30 → velocity_python-0.1.31}/src/velocity/__init__.py

@@ -1,4 +1,4 @@
-__version__ = version = "0.1.30"
+__version__ = version = "0.1.31"
 
 import importlib as _importlib
 

{velocity_python-0.1.30 → velocity_python-0.1.31}/src/velocity/db/core/table.py

@@ -1186,6 +1186,52 @@ class Table:
             raise Exception("sql_only is not supported for list queries")
         return self.select(*args, **kwds).all()
 
+    def stream(
+        self,
+        columns=None,
+        where=None,
+        orderby=None,
+        groupby=None,
+        having=None,
+        fetch_size: int = 5_000,
+    ):
+        """Stream a large result set via a PostgreSQL server-side cursor.
+
+        Unlike :meth:`select`, this never buffers the entire result in memory.
+        Rows are fetched from the database *fetch_size* at a time via
+        ``DECLARE … CURSOR FOR`` / ``FETCH N`` / ``CLOSE``.
+
+        Must be used as a context manager::
+
+            with tx.table("transactions").stream(where={"year": 2026}) as cur:
+                for result in cur:
+                    headers = result.headers        # column names, first batch
+                    rows    = result.as_list().all()
+
+        Args:
+            columns:    Column expression(s) to SELECT (default ``*``).
+            where:      Filter dict or raw SQL fragment, same as :meth:`select`.
+            orderby:    ORDER BY expression, same as :meth:`select`.
+            groupby:    GROUP BY expression.
+            having:     HAVING clause.
+            fetch_size: Rows per round-trip (default 5 000).
+
+        Returns:
+            A :class:`~velocity.db.core.transaction.ServerCursor` context
+            manager whose iterator yields :class:`~velocity.db.core.result.Result`
+            objects, one per batch.
+        """
+        sql, vals = self.sql.select(
+            self.tx,
+            columns=columns,
+            table=self.name,
+            where=where,
+            orderby=orderby,
+            groupby=groupby,
+            having=having,
+        )
+        return self.tx.stream(sql, vals, fetch_size=fetch_size)
+
     def query(
         self,
         columns=None,

{velocity_python-0.1.30 → velocity_python-0.1.31}/src/velocity/db/core/transaction.py

@@ -2,6 +2,7 @@ import logging
 import os
 import time as _time
 import traceback
+import uuid
 from collections import OrderedDict
 
 from velocity.db.core.row import Row
@@ -87,6 +88,71 @@ def _summarize_sql(sql, limit=None):
     return compact
 
 
+class ServerCursor:
+    """Context manager and iterator for streaming large result sets via a
+    PostgreSQL server-side cursor (``DECLARE … CURSOR FOR`` / ``FETCH N`` /
+    ``CLOSE``).
+
+    Do not instantiate directly — use :meth:`Transaction.stream` or
+    :meth:`Table.stream` instead.
+
+    Each iteration yields a :class:`Result` containing up to *fetch_size* rows.
+    When the result set is exhausted the loop ends, and the cursor is
+    ``CLOSE``d automatically on ``__exit__``, even when an exception is raised
+    inside the ``with`` block.
+
+    Example::
+
+        with tx.stream(sql, vals, fetch_size=5000) as cursor:
+            for result in cursor:
+                headers = result.headers        # column names, first batch
+                rows    = result.as_list().all()
+    """
+
+    def __init__(self, tx: "Transaction", sql: str, vals=None, fetch_size: int = 5_000):
+        self._tx = tx
+        self._sql = sql
+        self._vals = vals
+        self._fetch_size = fetch_size
+        self._name = f"vc_{uuid.uuid4().hex[:8]}"
+        self._open = False
+
+    # ── context manager ───────────────────────────────────────────────────────
+
+    def __enter__(self) -> "ServerCursor":
+        self._tx.execute(
+            f"DECLARE {self._name} CURSOR FOR {self._sql}",
+            self._vals,
+        )
+        self._open = True
+        return self
+
+    def __exit__(self, *args) -> bool:
+        if self._open:
+            try:
+                self._tx.execute(f"CLOSE {self._name}")
+            except Exception:
+                pass
+            self._open = False
+        return False  # do not suppress exceptions
+
+    # ── iterator ──────────────────────────────────────────────────────────────
+
+    def __iter__(self) -> "ServerCursor":
+        return self
+
+    def __next__(self) -> Result:
+        """Fetch the next batch from the server-side cursor.
+
+        Returns a :class:`Result`; raises :class:`StopIteration` when the
+        result set is exhausted.
+        """
+        result = self._tx.execute(f"FETCH {self._fetch_size} FROM {self._name}")
+        if not result:  # Result.__bool__ pre-fetches one row; False → empty
+            raise StopIteration
+        return result
+
+
 class Transaction:
     """
     Encapsulates a single transaction in the database (connection + commit/rollback).
@@ -302,6 +368,25 @@ class Transaction:
         """
         return self._execute(sql, parms, cursor=self.cursor())
 
+    def stream(self, sql: str, vals=None, fetch_size: int = 5_000) -> ServerCursor:
+        """Return a :class:`ServerCursor` for streaming a large result set
+        without buffering all rows in memory at once.
+
+        The cursor uses PostgreSQL ``DECLARE … CURSOR FOR`` / ``FETCH N`` /
+        ``CLOSE`` and must be used as a context manager::
+
+            with tx.stream(sql, vals, fetch_size=5000) as cursor:
+                for result in cursor:
+                    headers = result.headers
+                    rows    = result.as_list().all()
+
+        Args:
+            sql:        A SELECT statement (with ``%s`` placeholders if needed).
+            vals:       Positional parameters matching the placeholders, or None.
+            fetch_size: Rows fetched per round-trip (default 5 000).
+        """
+        return ServerCursor(self, sql, vals, fetch_size=fetch_size)
+
     def commit(self):
         """
         Commits the current transaction if there's an open connection.

{velocity_python-0.1.30 → velocity_python-0.1.31/src/velocity_python.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: velocity-python
-Version: 0.1.30
+Version: 0.1.31
 Summary: A rapid application development library for interfacing with data storage
 Author-email: Velocity Team <info@codeclubs.org>
 License-Expression: MIT

{velocity_python-0.1.30 → velocity_python-0.1.31}/src/velocity_python.egg-info/SOURCES.txt

@@ -178,6 +178,7 @@ tests/test_row_cache_staleness.py
 tests/test_row_dirty_tracking.py
 tests/test_schema_migrations.py
 tests/test_security_hardening.py
+tests/test_server_cursor.py
 tests/test_spreadsheet_functions.py
 tests/test_sqs_per_record_transactions.py
 tests/test_sys_modified_count_postgres_demo.py

velocity_python-0.1.31/tests/test_server_cursor.py

@@ -0,0 +1,168 @@
+"""
+Tests for ServerCursor / Transaction.stream() / Table.stream().
+"""
+
+import pytest
+from unittest.mock import MagicMock, call, patch
+
+from velocity.db.core.transaction import ServerCursor
+from velocity.db.core.result import Result
+
+
+# ── helpers ───────────────────────────────────────────────────────────────────
+
+def _make_tx(execute_side_effects=None):
+    """Return a mock Transaction whose execute() returns the given side effects."""
+    tx = MagicMock()
+    if execute_side_effects is not None:
+        tx.execute.side_effect = execute_side_effects
+    return tx
+
+
+def _result(rows, headers=None):
+    """Return a mock Result that iterates over rows and has the given headers."""
+    r = MagicMock(spec=Result)
+    r.__bool__ = MagicMock(return_value=bool(rows))
+    r.headers = headers or [f"col{i}" for i in range(len(rows[0]) if rows else 0)]
+    r.as_list.return_value.all.return_value = list(rows)
+    return r
+
+
+def _empty_result():
+    """Return a falsy mock Result (no rows)."""
+    r = MagicMock(spec=Result)
+    r.__bool__ = MagicMock(return_value=False)
+    return r
+
+
+# ── ServerCursor unit tests ───────────────────────────────────────────────────
+
+class TestServerCursorContextManager:
+    def test_enter_issues_declare(self):
+        tx = _make_tx()
+        cursor = ServerCursor(tx, "SELECT 1", fetch_size=100)
+        cursor.__enter__()
+        declare_call = tx.execute.call_args_list[0]
+        assert "DECLARE" in declare_call[0][0]
+        assert "CURSOR FOR" in declare_call[0][0]
+        assert "SELECT 1" in declare_call[0][0]
+
+    def test_exit_issues_close(self):
+        tx = _make_tx()
+        cursor = ServerCursor(tx, "SELECT 1")
+        cursor._open = True
+        cursor._name = "vc_test1234"
+        cursor.__exit__(None, None, None)
+        close_call = tx.execute.call_args_list[-1]
+        assert "CLOSE vc_test1234" in close_call[0][0]
+
+    def test_exit_not_called_when_not_open(self):
+        tx = _make_tx()
+        cursor = ServerCursor(tx, "SELECT 1")
+        cursor._open = False
+        cursor.__exit__(None, None, None)
+        tx.execute.assert_not_called()
+
+    def test_exit_swallows_close_errors(self):
+        tx = _make_tx()
+        tx.execute.side_effect = Exception("connection lost")
+        cursor = ServerCursor(tx, "SELECT 1")
+        cursor._open = True
+        # should not raise
+        cursor.__exit__(None, None, None)
+
+    def test_exit_returns_false(self):
+        tx = _make_tx()
+        cursor = ServerCursor(tx, "SELECT 1")
+        assert cursor.__exit__(None, None, None) is False
+
+    def test_unique_cursor_names(self):
+        tx = _make_tx()
+        names = {ServerCursor(tx, "SELECT 1")._name for _ in range(50)}
+        assert len(names) == 50
+
+
+class TestServerCursorIteration:
+    def test_yields_result_per_batch(self):
+        batch1 = _result([(1, "a"), (2, "b")])
+        batch2 = _empty_result()
+        tx = _make_tx(execute_side_effects=[MagicMock(), batch1, batch2])  # DECLARE, FETCH, FETCH
+
+        results = []
+        with ServerCursor(tx, "SELECT id, name FROM t", fetch_size=2) as cur:
+            for result in cur:
+                results.append(result)
+
+        assert results == [batch1]
+
+    def test_multiple_batches(self):
+        b1 = _result([(i,) for i in range(5)])
+        b2 = _result([(i,) for i in range(5, 10)])
+        empty = _empty_result()
+        tx = _make_tx(execute_side_effects=[MagicMock(), b1, b2, empty])
+
+        results = []
+        with ServerCursor(tx, "SELECT id FROM t", fetch_size=5) as cur:
+            for result in cur:
+                results.append(result)
+
+        assert results == [b1, b2]
+
+    def test_empty_table_yields_nothing(self):
+        empty = _empty_result()
+        tx = _make_tx(execute_side_effects=[MagicMock(), empty])
+
+        results = []
+        with ServerCursor(tx, "SELECT id FROM t") as cur:
+            for result in cur:
+                results.append(result)
+
+        assert results == []
+
+    def test_close_called_on_exception(self):
+        batch = _result([(1,)])
+        tx = _make_tx(execute_side_effects=[MagicMock(), batch])
+        cursor_name = None
+
+        try:
+            with ServerCursor(tx, "SELECT 1") as cur:
+                cursor_name = cur._name
+                for _ in cur:
+                    raise RuntimeError("mid-loop error")
+        except RuntimeError:
+            pass
+
+        last_call = tx.execute.call_args_list[-1][0][0]
+        assert f"CLOSE {cursor_name}" in last_call
+
+    def test_fetch_uses_correct_size(self):
+        empty = _empty_result()
+        tx = _make_tx(execute_side_effects=[MagicMock(), empty])
+
+        with ServerCursor(tx, "SELECT 1", fetch_size=1234) as cur:
+            for _ in cur:
+                pass
+
+        fetch_call = tx.execute.call_args_list[1][0][0]
+        assert "FETCH 1234" in fetch_call
+
+    def test_vals_passed_to_declare(self):
+        tx = _make_tx()
+        cursor = ServerCursor(tx, "SELECT * FROM t WHERE id = %s", vals=(42,))
+        cursor.__enter__()
+        declare_call = tx.execute.call_args_list[0]
+        assert declare_call[0][1] == (42,)
+
+
+# ── Transaction.stream() ──────────────────────────────────────────────────────
+
+class TestTransactionStream:
+    def test_returns_server_cursor(self):
+        from velocity.db.core.transaction import Transaction
+        tx = MagicMock(spec=Transaction)
+        # call the real stream() via unbound method
+        sc = Transaction.stream(tx, "SELECT 1", (1, 2), fetch_size=100)
+        assert isinstance(sc, ServerCursor)
+        assert sc._sql == "SELECT 1"
+        assert sc._vals == (1, 2)
+        assert sc._fetch_size == 100