add find_all() for easy retrieval of all records and find_iter() for constant memory iteration over many records

Author: purificant

README.md

@@ -27,11 +27,18 @@ user = await User.create(name="Ada", email="ada@example.com")
 # retrieve
 user = await User.get(uid)
 
-# query
+# query (paginated)
 users = await User.find(constraints=[
     constraint("status", ConstraintType.EQUALS, "active")
 ])
 
+# query all matching records
+all_users = await User.find_all()
+
+# iterate with constant memory
+async for user in User.find_iter():
+    process(user)
+
 # update
 user.name = "Ada Lovelace"
 await user.save()
@@ -113,6 +120,7 @@ HTTP connections are pooled per event loop, avoiding reconnection overhead when
 - **Pydantic ORM:** define models once, get validation and autocomplete
 - **Connection pooling:** automatic per-event-loop client reuse
 - **Rich query constraints:** pythonic filtering using Bubble's constraint system
+- **Efficient iteration:** `find_iter()` streams records with constant memory
 - **Upsert with duplicate handling:** `create_or_update` with configurable strategies
 - **Configurable retries:** plug in your own retry policy via `tenacity`
 - **UID validation:** catch invalid Bubble IDs at the model level
@@ -179,14 +187,23 @@ user = await User.create(name="Ada Lovelace", email="ada@example.com")
 # retrieve
 user = await User.get("1234567890x1234567890")
 
-# query with constraints
+# query with constraints (single page)
 from bubble_data_api_client import constraint, ConstraintType
 
 active_users = await User.find(constraints=[
     constraint("status", ConstraintType.EQUALS, "active"),
     constraint("age", ConstraintType.GREATER_THAN, 18),
 ])
 
+# get all matching records as a list
+all_active = await User.find_all(constraints=[
+    constraint("status", ConstraintType.EQUALS, "active"),
+])
+
+# iterate through all records with constant memory
+async for user in User.find_iter():
+    print(user.name)
+
 # update
 user.name = "Ada L."
 await user.save()
@@ -202,13 +219,13 @@ The `create_or_update` method handles the common "upsert" pattern with configura
 ```python
 from bubble_data_api_client import OnMultiple
 
-# basic upsert - match by external_id, create if not found
+# basic upsert, matches by external_id and creates if not found
 user, created = await User.create_or_update(
     match={"external_id": "ext-123"},
     data={"name": "Updated Name", "email": "new@example.com"},
     on_multiple=OnMultiple.ERROR,
 )
-# returns (User, bool) - the model instance and whether it was created
+# returns (User, bool): the instance and whether it was created
 ```
 
 ### Duplicate Handling Strategies
@@ -252,6 +269,32 @@ results = await User.find(constraints=constraints)
 
 Available constraint types: `EQUALS`, `NOT_EQUAL`, `IS_EMPTY` (any field), `IS_NOT_EMPTY` (any field), `TEXT_CONTAINS`, `NOT_TEXT_CONTAINS`, `GREATER_THAN`, `LESS_THAN`, `IN`, `NOT_IN`, `CONTAINS`, `NOT_CONTAINS`, `EMPTY` (list fields), `NOT_EMPTY` (list fields), `GEOGRAPHIC_SEARCH`.
 
+## Querying Records
+
+Three methods for fetching records, depending on your needs:
+
+| Method | Returns | Use case |
+|--------|---------|----------|
+| `find()` | `list` | Single page with manual pagination via `cursor`/`limit` |
+| `find_all()` | `list` | All matching records collected into memory |
+| `find_iter()` | `AsyncIterator` | All matching records with constant memory |
+
+```python
+# find(): single page, you control pagination
+page1 = await User.find(limit=100)
+page2 = await User.find(limit=100, cursor=100)
+
+# find_all(): fetches all pages, returns when complete
+all_users = await User.find_all(constraints=[...])
+print(f"Got {len(all_users)} users")
+
+# find_iter(): streams records with constant memory
+async for user in User.find_iter(constraints=[...]):
+    await process(user)  # each record processed as it arrives
+```
+
+Both `find_all()` and `find_iter()` handle pagination internally, fetching pages of `page_size` (default 100) until all records are retrieved.
+
 ## Type-Safe Bubble UIDs
 
 Validate Bubble record IDs at the type level:

src/bubble_data_api_client/client/orm.py

@@ -1,12 +1,13 @@
 import http
 import typing
+from collections.abc import AsyncIterator
 from datetime import datetime
 
 import httpx
 from pydantic import BaseModel as PydanticBaseModel
 from pydantic import Field
 
-from bubble_data_api_client.client.raw_client import RawClient
+from bubble_data_api_client.client.raw_client import AdditionalSortField, RawClient
 from bubble_data_api_client.constraints import Constraint, ConstraintType, constraint
 from bubble_data_api_client.exceptions import UnknownFieldError
 from bubble_data_api_client.types import BubbleField, OnMultiple
@@ -125,7 +126,7 @@ async def find(
         sort_field: str | None = None,
         descending: bool | None = None,
         exclude_remaining: bool | None = None,
-        additional_sort_fields: list | None = None,
+        additional_sort_fields: list[AdditionalSortField] | None = None,
     ) -> list[typing.Self]:
         async with _get_client() as client:
             response = await client.find(
@@ -141,6 +142,59 @@ async def find(
             response.raise_for_status()
             return [cls(**item) for item in response.json()["response"]["results"]]
 
+    @classmethod
+    async def find_iter(
+        cls,
+        *,
+        constraints: list[Constraint] | None = None,
+        page_size: int = 100,
+        sort_field: str | None = None,
+        descending: bool | None = None,
+        additional_sort_fields: list[AdditionalSortField] | None = None,
+    ) -> AsyncIterator[typing.Self]:
+        """Iterate through all matching records with constant memory usage."""
+        cursor: int = 0
+        async with _get_client() as client:
+            while True:
+                response = await client.find(
+                    cls._typename,
+                    constraints=constraints,
+                    cursor=cursor,
+                    limit=page_size,
+                    sort_field=sort_field,
+                    descending=descending,
+                    additional_sort_fields=additional_sort_fields,
+                )
+                response.raise_for_status()
+                body = response.json()["response"]
+                for item in body["results"]:
+                    yield cls(**item)
+                if body["remaining"] == 0:
+                    break
+                cursor += len(body["results"])
+
+    @classmethod
+    async def find_all(
+        cls,
+        *,
+        constraints: list[Constraint] | None = None,
+        page_size: int = 100,
+        sort_field: str | None = None,
+        descending: bool | None = None,
+        additional_sort_fields: list[AdditionalSortField] | None = None,
+    ) -> list[typing.Self]:
+        """Return all matching records as a list."""
+        return [
+            item
+            async for item in cls.find_iter(
+                constraints=constraints,
+                page_size=page_size,
+                sort_field=sort_field,
+                descending=descending,
+                additional_sort_fields=additional_sort_fields,
+            )
+        ]
+
     @classmethod
     async def count(cls, *, constraints: list[Constraint] | None = None) -> int:
         """Return total count of objects matching constraints."""

src/tests/unit/client/test_orm.py

@@ -209,3 +209,141 @@ class User(BubbleModel, typename="user"):
             update_data={"nonexistent": "value"},
             on_multiple=OnMultiple.ERROR,
         )
+
+
+@respx.mock
+async def test_find_iter_single_page(configured_client: None) -> None:
+    """Verify find_iter yields all items from a single page."""
+
+    class User(BubbleModel, typename="user"):
+        name: str
+
+    respx.get("https://example.com/user").mock(
+        return_value=httpx.Response(
+            200,
+            json={
+                "response": {
+                    "results": [
+                        {"_id": "1", "name": "Alice"},
+                        {"_id": "2", "name": "Bob"},
+                    ],
+                    "count": 2,
+                    "remaining": 0,
+                }
+            },
+        )
+    )
+
+    users = [user async for user in User.find_iter()]
+
+    assert len(users) == 2
+    assert users[0].uid == "1"
+    assert users[0].name == "Alice"
+    assert users[1].uid == "2"
+    assert users[1].name == "Bob"
+
+
+@respx.mock
+async def test_find_iter_multiple_pages(configured_client: None) -> None:
+    """Verify find_iter fetches all pages and yields items from each."""
+
+    class User(BubbleModel, typename="user"):
+        name: str
+
+    route = respx.get("https://example.com/user")
+    route.side_effect = [
+        httpx.Response(
+            200,
+            json={
+                "response": {
+                    "results": [{"_id": "1", "name": "Alice"}],
+                    "count": 1,
+                    "remaining": 2,
+                }
+            },
+        ),
+        httpx.Response(
+            200,
+            json={
+                "response": {
+                    "results": [{"_id": "2", "name": "Bob"}],
+                    "count": 1,
+                    "remaining": 1,
+                }
+            },
+        ),
+        httpx.Response(
+            200,
+            json={
+                "response": {
+                    "results": [{"_id": "3", "name": "Charlie"}],
+                    "count": 1,
+                    "remaining": 0,
+                }
+            },
+        ),
+    ]
+
+    users = [user async for user in User.find_iter(page_size=1)]
+
+    assert len(users) == 3
+    assert [u.name for u in users] == ["Alice", "Bob", "Charlie"]
+    assert route.call_count == 3
+
+
+@respx.mock
+async def test_find_iter_empty_results(configured_client: None) -> None:
+    """Verify find_iter handles empty results."""
+
+    class User(BubbleModel, typename="user"):
+        name: str
+
+    respx.get("https://example.com/user").mock(
+        return_value=httpx.Response(
+            200,
+            json={"response": {"results": [], "count": 0, "remaining": 0}},
+        )
+    )
+
+    users = [user async for user in User.find_iter()]
+
+    assert users == []
+
+
+@respx.mock
+async def test_find_all_returns_list(configured_client: None) -> None:
+    """Verify find_all returns all items as a list."""
+
+    class User(BubbleModel, typename="user"):
+        name: str
+
+    route = respx.get("https://example.com/user")
+    route.side_effect = [
+        httpx.Response(
+            200,
+            json={
+                "response": {
+                    "results": [{"_id": "1", "name": "Alice"}],
+                    "count": 1,
+                    "remaining": 1,
+                }
+            },
+        ),
+        httpx.Response(
+            200,
+            json={
+                "response": {
+                    "results": [{"_id": "2", "name": "Bob"}],
+                    "count": 1,
+                    "remaining": 0,
+                }
+            },
+        ),
+    ]
+
+    users = await User.find_all(page_size=1)
+
+    assert isinstance(users, list)
+    assert len(users) == 2
+    assert users[0].name == "Alice"
+    assert users[1].name == "Bob"