meterbase 0.3.0__tar.gz → 0.4.0__tar.gz

{meterbase-0.3.0 → meterbase-0.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: meterbase
-Version: 0.3.0
+Version: 0.4.0
 Summary: Python SDK for the Meterbase engine
 Project-URL: Homepage, https://meterbase.tech
 Project-URL: Documentation, https://meterbase.tech/docs
@@ -278,7 +278,7 @@ id and gives them a first plan, and running it again changes nothing:
 ensured = meterbase.customers.ensure(
     external_id="acct_1",
     name="Acme",  # applied only when it creates the customer
-    plan="free",  # a plan key
+    plan="free",  # a plan's key or id
 )
 ensured.created, ensured.plan_result, ensured.customer.plan
 ```
@@ -303,7 +303,6 @@ customer = meterbase.customers.create(
 )
 
 found = meterbase.customers.retrieve_by_external_id("acct_1")  # or None
-everyone = meterbase.customers.list(include_deleted=True).data
 
 meterbase.customers.update(customer.id, name="Acme Inc")
 meterbase.customers.delete(customer.id)  # soft delete, idempotent
@@ -328,6 +327,27 @@ embed is which plan, and `customers.plan.retrieve` is where instructions are
 identified. `None` means they hold no plan, which is a default deny — a
 customer with no plan and no grant is denied.
 
+**Lists come a page at a time.** `customers.list` answers one page, newest
+first: `limit` customers, 100 unless you set it and at most 1,000. `list_all`
+follows the pages for you, fetching each one as the loop reaches it:
+
+```python
+page = meterbase.customers.list(plan="pro", limit=1000)
+page.data  #      the newest 1,000 customers on pro
+page.has_more  #  True when another page follows the last of them
+
+for customer in meterbase.customers.list_all(has_plan=False):
+    ...  # every customer holding no plan
+```
+
+On the async client it is `async for customer in meterbase.customers.list_all()`.
+`plan`, a key or an id, and `has_plan` filter on the plan in force now; a
+pending change counts once it lands. `include_deleted=True` adds deleted
+customers. To page by hand, pass the last `id` as `starting_after` while
+`has_more` is `True`. A walk reads no customer twice, and one created while it
+runs is not in it. Both raise before sending when `plan` or `starting_after` is
+`None`, which would otherwise widen the list.
+
 `customers.list` stays lean and does not embed, along with `create`, `update`
 and `delete`; the same read would run per row for an answer most callers of a
 list do not want.
@@ -994,6 +1014,12 @@ Pre-1.0, the minor version is where breaking changes land — deliberately, so a
 change that will not run against your code cannot arrive as a patch. The SDK
 follows the engine's API, as the TypeScript SDK (`mbase-sdk`) does.
 
+**0.4.0** pages the customer list, and adds `customers.list_all` and the
+`limit`, `starting_after`, `plan` and `has_plan` parameters. One change can break
+code: `customers.list()` answers one page of 100, newest first, where it used to
+answer every customer. Iterate `list_all` to read them all. The engine pages the
+same way, so 0.3.0 and earlier now read only the newest 100.
+
 **0.3.0** adds an `idempotency_key` on grants and plan changes, which also makes
 them safe to retry, `replayed` on their answers, and `IdempotencyKeyReusedError`.
 Nothing in it breaks code written for 0.2.0.

{meterbase-0.3.0 → meterbase-0.4.0}/README.md

@@ -251,7 +251,7 @@ id and gives them a first plan, and running it again changes nothing:
 ensured = meterbase.customers.ensure(
     external_id="acct_1",
     name="Acme",  # applied only when it creates the customer
-    plan="free",  # a plan key
+    plan="free",  # a plan's key or id
 )
 ensured.created, ensured.plan_result, ensured.customer.plan
 ```
@@ -276,7 +276,6 @@ customer = meterbase.customers.create(
 )
 
 found = meterbase.customers.retrieve_by_external_id("acct_1")  # or None
-everyone = meterbase.customers.list(include_deleted=True).data
 
 meterbase.customers.update(customer.id, name="Acme Inc")
 meterbase.customers.delete(customer.id)  # soft delete, idempotent
@@ -301,6 +300,27 @@ embed is which plan, and `customers.plan.retrieve` is where instructions are
 identified. `None` means they hold no plan, which is a default deny — a
 customer with no plan and no grant is denied.
 
+**Lists come a page at a time.** `customers.list` answers one page, newest
+first: `limit` customers, 100 unless you set it and at most 1,000. `list_all`
+follows the pages for you, fetching each one as the loop reaches it:
+
+```python
+page = meterbase.customers.list(plan="pro", limit=1000)
+page.data  #      the newest 1,000 customers on pro
+page.has_more  #  True when another page follows the last of them
+
+for customer in meterbase.customers.list_all(has_plan=False):
+    ...  # every customer holding no plan
+```
+
+On the async client it is `async for customer in meterbase.customers.list_all()`.
+`plan`, a key or an id, and `has_plan` filter on the plan in force now; a
+pending change counts once it lands. `include_deleted=True` adds deleted
+customers. To page by hand, pass the last `id` as `starting_after` while
+`has_more` is `True`. A walk reads no customer twice, and one created while it
+runs is not in it. Both raise before sending when `plan` or `starting_after` is
+`None`, which would otherwise widen the list.
+
 `customers.list` stays lean and does not embed, along with `create`, `update`
 and `delete`; the same read would run per row for an answer most callers of a
 list do not want.
@@ -967,6 +987,12 @@ Pre-1.0, the minor version is where breaking changes land — deliberately, so a
 change that will not run against your code cannot arrive as a patch. The SDK
 follows the engine's API, as the TypeScript SDK (`mbase-sdk`) does.
 
+**0.4.0** pages the customer list, and adds `customers.list_all` and the
+`limit`, `starting_after`, `plan` and `has_plan` parameters. One change can break
+code: `customers.list()` answers one page of 100, newest first, where it used to
+answer every customer. Iterate `list_all` to read them all. The engine pages the
+same way, so 0.3.0 and earlier now read only the newest 100.
+
 **0.3.0** adds an `idempotency_key` on grants and plan changes, which also makes
 them safe to retry, `replayed` on their answers, and `IdempotencyKeyReusedError`.
 Nothing in it breaks code written for 0.2.0.

{meterbase-0.3.0 → meterbase-0.4.0}/src/meterbase/_async/resources/customers.py

@@ -1,10 +1,10 @@
 from __future__ import annotations
 
-from collections.abc import Mapping, Sequence
+from collections.abc import AsyncIterator, Mapping, Sequence
 from typing import Any, overload
 
-from ..._http import require_external_id, segment
-from ..._models import ListResult, list_of
+from ..._http import require_external_id, require_list_filters, segment
+from ..._models import Page, list_of, page_of
 from ..._not_given import NOT_GIVEN, NotGiven
 from ...errors import NotFoundError
 from ...types import (
@@ -78,7 +78,7 @@ class AsyncCustomers:
         happened.
 
         `name` and `metadata` apply only to a customer this creates. `plan` is
-        a plan key; omit it to leave the plan alone. `cycle_anchor`, RFC 3339,
+        a plan's key or id; omit it to leave the plan alone. `cycle_anchor`, RFC 3339,
         only with `plan` and never in the future, is used only when this call
         assigns the plan. `mint_one_time=False` writes the plan's one-time
         grants already spent, for an imported customer whose remaining bonus
@@ -105,17 +105,75 @@ class AsyncCustomers:
         )
 
     async def list(
-        self, *, include_deleted: bool | NotGiven = NOT_GIVEN
-    ) -> ListResult[Customer]:
-        """Lean: a listing does not embed the plan. Read one customer for
-        that."""
+        self,
+        *,
+        limit: int | NotGiven = NOT_GIVEN,
+        starting_after: str | NotGiven = NOT_GIVEN,
+        plan: str | NotGiven = NOT_GIVEN,
+        has_plan: bool | NotGiven = NOT_GIVEN,
+        include_deleted: bool | NotGiven = NOT_GIVEN,
+    ) -> Page[Customer]:
+        """
+        One page, newest first: `limit` customers, 100 unless set and at most
+        1,000. Pass the last `id` as `starting_after` for the next page, while
+        `has_more` is `True`; `list_all` does that for you.
+
+        `plan`, a key or an id, and `has_plan` filter on the plan in force now;
+        a pending change counts once it lands. Lean: a page does not embed the
+        plan. Read one customer for that.
+
+        Raises `MeterbaseError` before sending when `plan` or `starting_after`
+        is `None`.
+        """
+        require_list_filters("list", plan, starting_after)
+
         return await self._api.request(
             "GET",
             "/v1/customers",
-            list_of(Customer),
-            query={"include_deleted": include_deleted},
+            page_of(Customer),
+            query={
+                "limit": limit,
+                "starting_after": starting_after,
+                "plan": plan,
+                "has_plan": has_plan,
+                "include_deleted": include_deleted,
+            },
         )
 
+    async def list_all(
+        self,
+        *,
+        limit: int | NotGiven = NOT_GIVEN,
+        starting_after: str | NotGiven = NOT_GIVEN,
+        plan: str | NotGiven = NOT_GIVEN,
+        has_plan: bool | NotGiven = NOT_GIVEN,
+        include_deleted: bool | NotGiven = NOT_GIVEN,
+    ) -> AsyncIterator[Customer]:
+        """
+        Every customer, newest first, from `starting_after` on when it is
+        given, one page of `limit` at a time as the loop asks for more:
+        `async for customer in client.customers.list_all(): ...`.
+
+        A customer created during the walk is not in it, and none is read
+        twice.
+        """
+        require_list_filters("list_all", plan, starting_after)
+
+        while True:
+            page = await self.list(
+                limit=limit,
+                starting_after=starting_after,
+                plan=plan,
+                has_plan=has_plan,
+                include_deleted=include_deleted,
+            )
+            for customer in page.data:
+                starting_after = customer.id
+                yield customer
+
+            if not page.has_more or not page.data:
+                return
+
     async def retrieve(self, id: str) -> CustomerWithPlan:
         """
         One customer, with the plan they hold. `plan` is the one in force now

{meterbase-0.3.0 → meterbase-0.4.0}/src/meterbase/_http.py

@@ -86,6 +86,21 @@ def require_external_id(method: str, external_id: object) -> None:
         )
 
 
+def require_list_filters(method: str, plan: object, starting_after: object) -> None:
+    """
+    Dropped from the query, a `None` would widen the list: every customer
+    rather than one plan's, or the first page again rather than the next.
+    """
+    for name, value, instead in (
+        ("plan", plan, "omit it to list every customer"),
+        ("starting_after", starting_after, "omit it to start at the newest"),
+    ):
+        if value is None:
+            raise MeterbaseError(
+                f"customers.{method} was given {name}=None; {instead}."
+            )
+
+
 def require_key_filter(key: object) -> None:
     """
     Dropped from the query, a `None` key would list every grant where a

{meterbase-0.3.0 → meterbase-0.4.0}/src/meterbase/_models.py

@@ -111,11 +111,23 @@ class ListResult(Model, Generic[_T]):
             ]
 
 
+class Page(ListResult[_T]):
+    """One page of a paged list. `has_more` is `True` when another page follows
+    the last item in `data`."""
+
+    has_more: bool
+
+
 def list_of(item: type[_M]) -> Callable[[Mapping[str, Any]], ListResult[_M]]:
     """Reads a listing whose rows are `item`."""
     return lambda raw: ListResult(raw, item)
 
 
+def page_of(item: type[_M]) -> Callable[[Mapping[str, Any]], Page[_M]]:
+    """Reads a page whose rows are `item`."""
+    return lambda raw: Page(raw, item)
+
+
 def construct(cast_to: Callable[[dict[str, Any]], _T], data: Any) -> _T:
     """Reads a response body as the object a call answers with."""
     if not is_object(data):

{meterbase-0.3.0 → meterbase-0.4.0}/src/meterbase/_sync/resources/customers.py

@@ -4,11 +4,11 @@
 
 from __future__ import annotations
 
-from collections.abc import Mapping, Sequence
+from collections.abc import Iterator, Mapping, Sequence
 from typing import Any, overload
 
-from ..._http import require_external_id, segment
-from ..._models import ListResult, list_of
+from ..._http import require_external_id, require_list_filters, segment
+from ..._models import Page, list_of, page_of
 from ..._not_given import NOT_GIVEN, NotGiven
 from ...errors import NotFoundError
 from ...types import (
@@ -82,7 +82,7 @@ class Customers:
         happened.
 
         `name` and `metadata` apply only to a customer this creates. `plan` is
-        a plan key; omit it to leave the plan alone. `cycle_anchor`, RFC 3339,
+        a plan's key or id; omit it to leave the plan alone. `cycle_anchor`, RFC 3339,
         only with `plan` and never in the future, is used only when this call
         assigns the plan. `mint_one_time=False` writes the plan's one-time
         grants already spent, for an imported customer whose remaining bonus
@@ -109,17 +109,75 @@ class Customers:
         )
 
     def list(
-        self, *, include_deleted: bool | NotGiven = NOT_GIVEN
-    ) -> ListResult[Customer]:
-        """Lean: a listing does not embed the plan. Read one customer for
-        that."""
+        self,
+        *,
+        limit: int | NotGiven = NOT_GIVEN,
+        starting_after: str | NotGiven = NOT_GIVEN,
+        plan: str | NotGiven = NOT_GIVEN,
+        has_plan: bool | NotGiven = NOT_GIVEN,
+        include_deleted: bool | NotGiven = NOT_GIVEN,
+    ) -> Page[Customer]:
+        """
+        One page, newest first: `limit` customers, 100 unless set and at most
+        1,000. Pass the last `id` as `starting_after` for the next page, while
+        `has_more` is `True`; `list_all` does that for you.
+
+        `plan`, a key or an id, and `has_plan` filter on the plan in force now;
+        a pending change counts once it lands. Lean: a page does not embed the
+        plan. Read one customer for that.
+
+        Raises `MeterbaseError` before sending when `plan` or `starting_after`
+        is `None`.
+        """
+        require_list_filters("list", plan, starting_after)
+
         return self._api.request(
             "GET",
             "/v1/customers",
-            list_of(Customer),
-            query={"include_deleted": include_deleted},
+            page_of(Customer),
+            query={
+                "limit": limit,
+                "starting_after": starting_after,
+                "plan": plan,
+                "has_plan": has_plan,
+                "include_deleted": include_deleted,
+            },
         )
 
+    def list_all(
+        self,
+        *,
+        limit: int | NotGiven = NOT_GIVEN,
+        starting_after: str | NotGiven = NOT_GIVEN,
+        plan: str | NotGiven = NOT_GIVEN,
+        has_plan: bool | NotGiven = NOT_GIVEN,
+        include_deleted: bool | NotGiven = NOT_GIVEN,
+    ) -> Iterator[Customer]:
+        """
+        Every customer, newest first, from `starting_after` on when it is
+        given, one page of `limit` at a time as the loop asks for more:
+        `for customer in client.customers.list_all(): ...`.
+
+        A customer created during the walk is not in it, and none is read
+        twice.
+        """
+        require_list_filters("list_all", plan, starting_after)
+
+        while True:
+            page = self.list(
+                limit=limit,
+                starting_after=starting_after,
+                plan=plan,
+                has_plan=has_plan,
+                include_deleted=include_deleted,
+            )
+            for customer in page.data:
+                starting_after = customer.id
+                yield customer
+
+            if not page.has_more or not page.data:
+                return
+
     def retrieve(self, id: str) -> CustomerWithPlan:
         """
         One customer, with the plan they hold. `plan` is the one in force now

meterbase-0.4.0/src/meterbase/_version.py

@@ -0,0 +1 @@
+__version__ = "0.4.0"

{meterbase-0.3.0 → meterbase-0.4.0}/src/meterbase/types.py

@@ -12,7 +12,7 @@ from __future__ import annotations
 
 from typing import Any, Literal, TypedDict
 
-from ._models import ListResult, Model
+from ._models import ListResult, Model, Page
 
 __all__ = [
     "Allowance",
@@ -45,6 +45,7 @@ __all__ = [
     "MeterUsage",
     "MeterUsageHistory",
     "Model",
+    "Page",
     "Period",
     "Plan",
     "PlanAllowance",

meterbase-0.3.0/src/meterbase/_version.py

@@ -1 +0,0 @@
-__version__ = "0.3.0"