AxiomQuery 0.2.0__tar.gz → 0.3.0__tar.gz

{axiomquery-0.2.0 → axiomquery-0.3.0}/CHANGELOG.md

@@ -7,6 +7,22 @@ Versioning follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ---
 
+## [0.3.0] — 2026-04-26
+
+### Added
+
+- `search()` / `asearch()` — streaming iteration over large result sets via SQLAlchemy server-side cursors with `yield_per=1000`
+  - Sync `search()` returns a Python iterator (consume with `for`); async `asearch()` returns an `AsyncScalarResult` (consume with `async for`)
+  - Single-pass; no `limit` / `offset` (use `list()` / `alist()` for paginated/materialised access)
+- `DEFAULT_PREFETCH = 1000` module-level constant in `engine.py`
+- Internal `_build_stmt()` helper consolidating the `select + where + order_by + limit + offset` block shared by `list` / `alist` / `search` / `asearch` / `read_group`
+
+### Changed
+
+- `list()` / `alist()` continue to return a materialised `list` — behaviour and signature unchanged from 0.2.0 callers' perspective
+
+---
+
 ## [0.2.0] — 2026-04-13
 
 ### Added

{axiomquery-0.2.0 → axiomquery-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: AxiomQuery
-Version: 0.2.0
+Version: 0.3.0
 Summary: Specification-based query and aggregation engine for SQLAlchemy 2.0 ORM models
 Project-URL: Source Code, https://github.com/Axiom-Dev-Labs/AxiomQuery
 Project-URL: Bug Tracker, https://github.com/Axiom-Dev-Labs/AxiomQuery/issues

{axiomquery-0.2.0 → axiomquery-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "AxiomQuery"
-version = "0.2.0"
+version = "0.3.0"
 description = "Specification-based query and aggregation engine for SQLAlchemy 2.0 ORM models"
 readme = "README.md"
 license = { file = "LICENSE" }

{axiomquery-0.2.0 → axiomquery-0.3.0}/src/axiom_query/__init__.py

@@ -1,6 +1,6 @@
 """axiom_query — standalone specification-based query engine for SQLAlchemy ORM models."""
 
-__version__ = "0.2.0"
+__version__ = "0.3.0"
 
 from axiom_query.engine import QueryEngine
 from axiom_query.errors import QueryError

{axiomquery-0.2.0 → axiomquery-0.3.0}/src/axiom_query/engine.py

@@ -15,6 +15,9 @@ from axiom_query.parser import parse_domain
 from axiom_query.schema import ModelSchema, derive_schema
 
 
+DEFAULT_PREFETCH = 1000
+
+
 def _get_dialect_name(session) -> str:
     """Extract dialect name from a sync or async SQLAlchemy session."""
     # AsyncSession has a .bind attribute (AsyncEngine)
@@ -38,7 +41,14 @@ class QueryEngine:
     Usage::
 
         engine = QueryEngine(Order)
-        records = engine.list(session, domain=[["status", "=", "CONFIRMED"]])
+
+        # Materialised page
+        page = engine.list(session, domain=[["status", "=", "CONFIRMED"]], limit=20)
+
+        # Streaming iteration over every match (no len/indexing)
+        for order in engine.search(session, domain=[["status", "=", "CONFIRMED"]]):
+            process(order)
+
         groups, total = engine.read_group(session, groupby=["status"], aggregates=["__count"])
     """
 
@@ -46,6 +56,21 @@ class QueryEngine:
         self._model = model_class
         self._schema: ModelSchema = derive_schema(model_class)
 
+    # ── Statement builder ────────────────────────────────────────────────
+
+    def _build_stmt(self, domain, order_by, limit, offset):
+        stmt = select(self._model)
+        if domain is not None:
+            spec = parse_domain(domain)
+            stmt = stmt.where(compile_domain(spec, self._schema))
+        if order_by is not None:
+            stmt = self._apply_order_by(stmt, order_by)
+        if limit is not None:
+            stmt = stmt.limit(limit)
+        if offset is not None:
+            stmt = stmt.offset(offset)
+        return stmt
+
     # ── Sync API ─────────────────────────────────────────────────────────
 
     def list(
@@ -56,24 +81,36 @@ class QueryEngine:
         offset: int | None = None,
         order_by: list | None = None,
     ) -> list:
-        """Return all records matching the optional domain filter."""
-        stmt = select(self._model)
+        """Return all records matching the optional domain filter as a list.
 
-        if domain is not None:
-            spec = parse_domain(domain)
-            where = compile_domain(spec, self._schema)
-            stmt = stmt.where(where)
+        Materialises the full result. Use ``search()`` for streaming over large
+        result sets.
+        """
+        stmt = self._build_stmt(domain, order_by, limit, offset)
+        return list(session.execute(stmt).scalars().all())
 
-        if order_by is not None:
-            stmt = self._apply_order_by(stmt, order_by)
+    def search(
+        self,
+        session: Session,
+        domain: Any = None,
+        order_by: list | None = None,
+    ):
+        """Stream records for batch processing.
 
-        if limit is not None:
-            stmt = stmt.limit(limit)
-        if offset is not None:
-            stmt = stmt.offset(offset)
+        Returns an iterator yielding ORM instances from a server-side cursor,
+        fetched in batches of ``DEFAULT_PREFETCH`` (1000) rows. Single-pass —
+        iterate once and don't store the iterator for re-use.
 
-        result = session.execute(stmt)
-        return list(result.scalars().all())
+        No ``limit`` / ``offset``: this method is for processing every matching
+        row. Use ``list()`` if you need pagination, ``len()``, or indexing.
+
+        Driver note: true streaming requires a database driver with server-side
+        cursor support (psycopg2, asyncpg). SQLite degrades to client-side
+        iteration but remains correct.
+        """
+        stmt = self._build_stmt(domain, order_by, limit=None, offset=None)
+        streaming_stmt = stmt.execution_options(yield_per=DEFAULT_PREFETCH)
+        return iter(session.scalars(streaming_stmt))
 
     def read_group(
         self,
@@ -128,24 +165,34 @@ class QueryEngine:
         offset: int | None = None,
         order_by: list | None = None,
     ) -> list:
-        """Async variant of list()."""
-        stmt = select(self._model)
+        """Async variant of ``list()`` — returns a materialised list."""
+        stmt = self._build_stmt(domain, order_by, limit, offset)
+        result = await session.execute(stmt)
+        return list(result.scalars().all())
 
-        if domain is not None:
-            spec = parse_domain(domain)
-            where = compile_domain(spec, self._schema)
-            stmt = stmt.where(where)
+    async def asearch(
+        self,
+        session,
+        domain: Any = None,
+        order_by: list | None = None,
+    ):
+        """Async variant of ``search()`` — returns an async iterator.
 
-        if order_by is not None:
-            stmt = self._apply_order_by(stmt, order_by)
+        Consume with ``async for``::
 
-        if limit is not None:
-            stmt = stmt.limit(limit)
-        if offset is not None:
-            stmt = stmt.offset(offset)
+            async for record in await engine.asearch(session, domain=...):
+                process(record)
 
-        result = await session.execute(stmt)
-        return list(result.scalars().all())
+        Streams ORM instances in batches of ``DEFAULT_PREFETCH`` (1000) rows
+        from a server-side cursor. Single-pass; no ``limit`` / ``offset``.
+
+        Driver note: true streaming requires a server-side cursor capable
+        driver (asyncpg). aiosqlite iterates correctly but without driver-level
+        streaming.
+        """
+        stmt = self._build_stmt(domain, order_by, limit=None, offset=None)
+        streaming_stmt = stmt.execution_options(yield_per=DEFAULT_PREFETCH)
+        return await session.stream_scalars(streaming_stmt)
 
     async def aread_group(
         self,

axiomquery-0.3.0/tests/test_asearch.py

@@ -0,0 +1,82 @@
+"""Tests for QueryEngine.asearch() — async streaming iteration."""
+
+from __future__ import annotations
+
+import pytest
+from sqlalchemy import event
+
+from axiom_query.engine import DEFAULT_PREFETCH
+from conftest import Order
+
+
+@pytest.mark.asyncio
+async def test_asearch_iterates_all_records(async_session, engine):
+    result = await engine.asearch(async_session)
+    records = [r async for r in result]
+    assert len(records) == 3
+    assert all(isinstance(r, Order) for r in records)
+
+
+@pytest.mark.asyncio
+async def test_asearch_with_domain(async_session, engine):
+    result = await engine.asearch(async_session, domain=[["status", "=", "CONFIRMED"]])
+    records = [r async for r in result]
+    assert len(records) == 2
+    assert all(r.status == "CONFIRMED" for r in records)
+
+
+@pytest.mark.asyncio
+async def test_asearch_with_m2o_domain(async_session, engine):
+    result = await engine.asearch(async_session, domain=[["customer.name", "=", "Alice"]])
+    records = [r async for r in result]
+    assert len(records) == 1
+    assert records[0].id == 1
+
+
+@pytest.mark.asyncio
+async def test_asearch_supports_order_by(async_session, engine):
+    result = await engine.asearch(async_session, order_by=[["total", "desc"]])
+    records = [r async for r in result]
+    assert [r.total for r in records] == [200, 100, 50]
+
+
+@pytest.mark.asyncio
+async def test_asearch_empty_result(async_session, engine):
+    result = await engine.asearch(async_session, domain=[["status", "=", "NONEXISTENT"]])
+    records = [r async for r in result]
+    assert records == []
+
+
+@pytest.mark.asyncio
+async def test_asearch_no_pagination_args(async_session, engine):
+    with pytest.raises(TypeError):
+        await engine.asearch(async_session, limit=10)
+    with pytest.raises(TypeError):
+        await engine.asearch(async_session, offset=5)
+
+
+@pytest.mark.asyncio
+async def test_asearch_uses_yield_per(async_session, engine, seeded_async_engine):
+    """Verify the SQL is issued with yield_per=DEFAULT_PREFETCH."""
+    captured = []
+
+    def listener(conn, cursor, statement, parameters, context, executemany):
+        captured.append(context.execution_options)
+
+    # AsyncEngine wraps a sync Engine; events attach to the sync engine
+    sync_engine = seeded_async_engine.sync_engine
+    event.listen(sync_engine, "before_cursor_execute", listener)
+    try:
+        result = await engine.asearch(async_session)
+        records = [r async for r in result]
+        assert len(records) == 3
+    finally:
+        event.remove(sync_engine, "before_cursor_execute", listener)
+
+    assert len(captured) >= 1, f"expected >=1 statement, got {len(captured)}"
+    # Find our SELECT statement (there may be other queries on the connection)
+    yield_per_stmts = [opts for opts in captured if opts.get("yield_per") == DEFAULT_PREFETCH]
+    assert len(yield_per_stmts) == 1, (
+        f"expected 1 statement with yield_per={DEFAULT_PREFETCH}, "
+        f"got {len(yield_per_stmts)}"
+    )

axiomquery-0.3.0/tests/test_search.py

@@ -0,0 +1,97 @@
+"""Tests for QueryEngine.search() — streaming iteration."""
+
+from __future__ import annotations
+
+from collections.abc import Iterator
+
+import pytest
+from sqlalchemy import event
+
+from axiom_query.engine import DEFAULT_PREFETCH
+from conftest import Order
+
+
+def test_search_returns_iterator(session, engine):
+    result = engine.search(session)
+    assert isinstance(result, Iterator)
+
+
+def test_search_iterates_all_records(session, engine):
+    records = list(engine.search(session))
+    assert len(records) == 3
+    assert all(isinstance(r, Order) for r in records)
+
+
+def test_search_with_domain(session, engine):
+    records = list(engine.search(session, domain=[["status", "=", "CONFIRMED"]]))
+    assert len(records) == 2
+    assert all(r.status == "CONFIRMED" for r in records)
+
+
+def test_search_with_or_domain(session, engine):
+    records = list(
+        engine.search(
+            session,
+            domain={"or": [["status", "=", "CONFIRMED"], ["status", "=", "DRAFT"]]},
+        )
+    )
+    assert len(records) == 3
+
+
+def test_search_with_m2o_domain(session, engine):
+    records = list(engine.search(session, domain=[["customer.name", "=", "Alice"]]))
+    assert len(records) == 1
+    assert records[0].id == 1
+
+
+def test_search_supports_order_by(session, engine):
+    records = list(engine.search(session, order_by=[["total", "desc"]]))
+    assert [r.total for r in records] == [200, 100, 50]
+
+
+def test_search_empty_result(session, engine):
+    records = list(engine.search(session, domain=[["status", "=", "NONEXISTENT"]]))
+    assert records == []
+
+
+def test_search_no_pagination_args(session, engine):
+    with pytest.raises(TypeError):
+        engine.search(session, limit=10)
+    with pytest.raises(TypeError):
+        engine.search(session, offset=5)
+
+
+def test_search_uses_yield_per(session, engine, seeded_engine):
+    """Verify the SQL is issued with yield_per=DEFAULT_PREFETCH."""
+    captured = []
+
+    def listener(conn, cursor, statement, parameters, context, executemany):
+        captured.append(context.execution_options)
+
+    event.listen(seeded_engine, "before_cursor_execute", listener)
+    try:
+        list(engine.search(session))
+    finally:
+        event.remove(seeded_engine, "before_cursor_execute", listener)
+
+    assert len(captured) == 1, f"expected 1 statement, got {len(captured)}"
+    assert captured[0].get("yield_per") == DEFAULT_PREFETCH
+
+
+def test_search_is_single_pass(session, engine):
+    """Iterating the same result a second time yields nothing (iterator exhausted)."""
+    result = engine.search(session)
+    first_pass = list(result)
+    second_pass = list(result)
+    assert len(first_pass) == 3
+    assert second_pass == []
+
+
+def test_search_break_does_not_block_session(session, engine):
+    """Breaking out of iteration should not leave the session in a bad state."""
+    for record in engine.search(session):
+        if record.id == 1:
+            break
+    # Session should still be usable
+    records = engine.list(session)
+    assert len(records) == 3