rename list() to find(), add efficient count()

Author: purificant

src/bubble_data_api_client/client/orm.py

@@ -6,7 +6,7 @@
 from pydantic import Field
 
 from bubble_data_api_client.client.raw_client import RawClient
-from bubble_data_api_client.constraints import ConstraintTypes, constraint
+from bubble_data_api_client.constraints import Constraint, ConstraintTypes, constraint
 
 
 def _get_client() -> RawClient:
@@ -48,7 +48,7 @@ async def get_many(cls, uids: list[str]) -> dict[str, typing.Self]:
         """Retrieve multiple things by their unique IDs, keyed by uid."""
         if not uids:
             return {}
-        items: list[typing.Self] = await cls.list(
+        items: list[typing.Self] = await cls.find(
             constraints=[constraint("_id", ConstraintTypes.IN, uids)],
         )
         return {item.uid: item for item in items}
@@ -65,10 +65,10 @@ async def delete(self) -> None:
             response.raise_for_status()
 
     @classmethod
-    async def list(
+    async def find(
         cls,
         *,
-        constraints: list | None = None,
+        constraints: list[Constraint] | None = None,
         cursor: int | None = None,
         limit: int | None = None,
         sort_field: str | None = None,
@@ -77,7 +77,7 @@ async def list(
         additional_sort_fields: list | None = None,
     ) -> list[typing.Self]:
         async with _get_client() as client:
-            response = await client.list(
+            response = await client.find(
                 cls._typename,
                 constraints=constraints,
                 cursor=cursor,
@@ -89,3 +89,9 @@ async def list(
             )
             response.raise_for_status()
             return [cls(**item) for item in response.json()["response"]["results"]]
+
+    @classmethod
+    async def count(cls, *, constraints: list[Constraint] | None = None) -> int:
+        """Return total count of objects matching constraints."""
+        async with _get_client() as client:
+            return await client.count(cls._typename, constraints=constraints)

src/bubble_data_api_client/client/raw_client.py

@@ -64,7 +64,7 @@ async def replace(self, typename: str, uid: str, data: typing.Any) -> httpx.Resp
         return await self._transport.put(f"/{typename}/{uid}", json=data)
 
     # https://manual.bubble.io/core-resources/api/the-bubble-api/the-data-api/data-api-requests#get-a-list-of-things
-    async def list(
+    async def find(
         self,
         typename: str,
         *,
@@ -94,3 +94,14 @@ async def list(
             params["additional_sort_fields"] = json.dumps(additional_sort_fields)
 
         return await self._transport.get(f"/{typename}", params=params)
+
+    async def count(
+        self,
+        typename: str,
+        *,
+        constraints: list[Constraint] | None = None,
+    ) -> int:
+        """Return total count of objects matching constraints."""
+        response = await self.find(typename, constraints=constraints, limit=1)
+        body = response.json()["response"]
+        return body["count"] + body["remaining"]

src/tests/integration/test_orm.py

@@ -32,8 +32,8 @@ async def test_orm_integration():
     assert isinstance(thing3, IntegrationTestModel)
     assert thing3.text == "test2"
 
-    # list
-    things = await IntegrationTestModel.list(
+    # find
+    things = await IntegrationTestModel.find(
         constraints=[{"key": "_id", "constraint_type": "equals", "value": thing3.uid}]
     )
     assert len(things) == 1