- default page_size to 500 in list_reservations / list_jobs

  (client, sync wrapper, CLI) to match SubscriptionsClient
- drop section-divider banner comments from cli/quota.py and
  both quota test files
- convert inline test comment to a docstring in
  test_list_reservations_respects_limit
- align docstring cross-reference links to subscription_request.py
  style ([full.path.Class.method][])

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

Author: asonnenschein

planet/cli/quota.py

@@ -62,11 +62,6 @@ def quota(ctx, base_url):
     ctx.obj['BASE_URL'] = base_url
 
 
-# ---------------------------------------------------------------------------
-# Products
-# ---------------------------------------------------------------------------
-
-
 @quota.group()
 def products():
     """Commands for inspecting products that support quota reservations."""
@@ -106,11 +101,6 @@ async def products_list(ctx, supports_reservation, pretty, compact):
         echo_json(results, pretty)
 
 
-# ---------------------------------------------------------------------------
-# Reservations
-# ---------------------------------------------------------------------------
-
-
 @quota.group()
 def reservations():
     """Commands for managing quota reservations."""
@@ -131,8 +121,9 @@ def reservations():
               help='Filter by `{field}` or `{field}__{op}`. May be repeated.')
 @click.option('--page-size',
               type=click.INT,
-              default=None,
-              help='Number of reservations to return per page.')
+              default=500,
+              show_default=True,
+              help='Number of results to return per page.')
 async def reservations_list(ctx,
                             pretty,
                             limit,
@@ -277,11 +268,6 @@ async def reservation_estimate(ctx,
         echo_json(result, pretty)
 
 
-# ---------------------------------------------------------------------------
-# Jobs
-# ---------------------------------------------------------------------------
-
-
 @quota.group()
 def jobs():
     """Commands for tracking bulk quota reservation jobs."""

planet/clients/quota.py

@@ -110,7 +110,7 @@ async def list_reservations(
         fields: Optional[str] = None,
         sort: Optional[str] = None,
         filters: Optional[Dict[str, Any]] = None,
-        page_size: Optional[int] = None,
+        page_size: int = 500,
     ) -> AsyncIterator[dict]:
         """Iterate over quota reservations.
 
@@ -134,8 +134,7 @@ async def list_reservations(
             ClientError: on a client error.
         """
         params = self._filter_params(fields=fields, sort=sort, filters=filters)
-        if page_size is not None:
-            params['limit'] = page_size
+        params['limit'] = page_size
 
         url = f'{self._reservations_url}/'
         try:
@@ -225,7 +224,7 @@ async def bulk_create_reservations(
 
         Use this endpoint for large batches of AOI references. The response
         includes a `job_id` whose progress can be tracked with
-        [`get_job`][planet.clients.quota.QuotaClient.get_job].
+        [planet.clients.quota.QuotaClient.get_job][].
 
         Parameters:
             aoi_refs: List of AOI feature references.
@@ -307,7 +306,7 @@ async def list_jobs(
         fields: Optional[str] = None,
         sort: Optional[str] = None,
         filters: Optional[Dict[str, Any]] = None,
-        page_size: Optional[int] = None,
+        page_size: int = 500,
     ) -> AsyncIterator[dict]:
         """Iterate over bulk quota reservation jobs.
 
@@ -328,8 +327,7 @@ async def list_jobs(
             ClientError: on a client error.
         """
         params = self._filter_params(fields=fields, sort=sort, filters=filters)
-        if page_size is not None:
-            params['limit'] = page_size
+        params['limit'] = page_size
 
         url = f'{self._reservations_url}/jobs'
         try:
@@ -378,9 +376,9 @@ async def list_products(
         """List products available to the requesting user's organization.
 
         Use this to look up the `product_id` (the `id` field) to pass into
-        [`create_reservation`][planet.clients.quota.QuotaClient.create_reservation],
-        [`bulk_create_reservations`][planet.clients.quota.QuotaClient.bulk_create_reservations],
-        or [`estimate_reservation`][planet.clients.quota.QuotaClient.estimate_reservation].
+        [planet.clients.quota.QuotaClient.create_reservation][],
+        [planet.clients.quota.QuotaClient.bulk_create_reservations][],
+        or [planet.clients.quota.QuotaClient.estimate_reservation][].
 
         Parameters:
             supports_reservation: If True, only return products with

planet/sync/quota.py

@@ -51,12 +51,12 @@ def list_reservations(
         fields: Optional[str] = None,
         sort: Optional[str] = None,
         filters: Optional[Dict[str, Any]] = None,
-        page_size: Optional[int] = None,
+        page_size: int = 500,
     ) -> Iterator[dict]:
         """Iterate over quota reservations.
 
-        See [QuotaClient.list_reservations][planet.clients.quota.QuotaClient.list_reservations]
-        for parameter details.
+        See [planet.clients.quota.QuotaClient.list_reservations][] for
+        parameter details.
         """
         return self._client._aiter_to_iter(
             self._client.list_reservations(limit=limit,
@@ -98,7 +98,7 @@ def bulk_create_reservations(
         """Submit a bulk quota reservation job.
 
         Returns a payload with `job_id` and `status` - track progress with
-        [get_job][planet.sync.quota.QuotaAPI.get_job].
+        [planet.sync.quota.QuotaAPI.get_job][].
         """
         return self._client._call_sync(
             self._client.bulk_create_reservations(aoi_refs,
@@ -123,7 +123,7 @@ def list_jobs(
         fields: Optional[str] = None,
         sort: Optional[str] = None,
         filters: Optional[Dict[str, Any]] = None,
-        page_size: Optional[int] = None,
+        page_size: int = 500,
     ) -> Iterator[dict]:
         """Iterate over bulk quota reservation jobs."""
         return self._client._aiter_to_iter(
@@ -144,9 +144,9 @@ def list_products(
         """List products available to the requesting user's organization.
 
         Use this to look up the `product_id` (the `id` field) to pass into
-        [create_reservation][planet.sync.quota.QuotaAPI.create_reservation],
-        [bulk_create_reservations][planet.sync.quota.QuotaAPI.bulk_create_reservations],
-        or [estimate_reservation][planet.sync.quota.QuotaAPI.estimate_reservation].
+        [planet.sync.quota.QuotaAPI.create_reservation][],
+        [planet.sync.quota.QuotaAPI.bulk_create_reservations][],
+        or [planet.sync.quota.QuotaAPI.estimate_reservation][].
 
         Parameters:
             supports_reservation: If True, only return products with

tests/integration/test_quota_api.py

@@ -84,11 +84,6 @@ def _job(jid: str = "job-abc") -> dict:
     }
 
 
-# ---------------------------------------------------------------------------
-# list_reservations
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 async def test_list_reservations_single_page():
     mock_response(RESERVATIONS_URL, _reservations_page(0, 3))
@@ -116,7 +111,7 @@ async def test_list_reservations_paginated():
 
 @respx.mock
 async def test_list_reservations_respects_limit():
-    # Two pages of two items each — limit=3 cuts iteration short.
+    """Two pages of two items each; limit=3 cuts iteration short."""
     next_url = f"{RESERVATIONS_URL}?cursor=abc"
     respx.get(RESERVATIONS_URL).mock(side_effect=[
         httpx.Response(200, json=_reservations_page(0, 2, next_url=next_url)),
@@ -149,11 +144,6 @@ async def test_list_reservations_query_params():
     assert sent["limit"] == "25"
 
 
-# ---------------------------------------------------------------------------
-# get_reservation
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 async def test_get_reservation():
     rid = 42
@@ -176,11 +166,6 @@ async def test_get_reservation_api_error():
         await cl_async.get_reservation(rid)
 
 
-# ---------------------------------------------------------------------------
-# create_reservation
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 async def test_create_reservation():
     payload = {
@@ -217,11 +202,6 @@ async def test_create_reservation_omits_collection_id_when_none():
     assert "collection_id" not in req_body
 
 
-# ---------------------------------------------------------------------------
-# bulk_create_reservations
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 async def test_bulk_create_reservations():
     bulk_url = f"{TEST_URL}/quota-reservations/bulk-reserve"
@@ -238,11 +218,6 @@ def assertf(resp):
     assert req_body == {"aoi_refs": [AOI_REF], "product_id": 100}
 
 
-# ---------------------------------------------------------------------------
-# estimate_reservation
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 async def test_estimate_reservation():
     estimate_url = f"{TEST_URL}/quota-reservations/estimate"
@@ -271,11 +246,6 @@ def assertf(resp):
     }
 
 
-# ---------------------------------------------------------------------------
-# Jobs
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 async def test_list_jobs():
     page = {"meta": {"count": 2}, "results": [_job("a"), _job("b")]}
@@ -305,11 +275,6 @@ async def test_get_job_empty_id_raises():
         await cl_async.get_job("")
 
 
-# ---------------------------------------------------------------------------
-# Products
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 async def test_list_products_list_payload():
     products = [

tests/integration/test_quota_cli.py

@@ -46,11 +46,6 @@ def _parse_json_lines(output: str):
     return [json.loads(line) for line in output.splitlines() if line.strip()]
 
 
-# ---------------------------------------------------------------------------
-# products
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 def test_cli_products_list():
     products = [
@@ -129,11 +124,6 @@ def test_cli_products_list_supports_reservation_flag():
     assert [p["id"] for p in json.loads(result.output)] == [1]
 
 
-# ---------------------------------------------------------------------------
-# reservations list / get
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 def test_cli_reservations_list():
     mock_response(RESERVATIONS_URL, _reservations_page(0, 3))
@@ -195,11 +185,6 @@ def test_cli_reservations_get():
     assert json.loads(result.output)["id"] == rid
 
 
-# ---------------------------------------------------------------------------
-# reservations create / bulk-reserve / estimate
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 def test_cli_reservation_create_aoi_ref_flags():
     """Repeated --aoi-ref flags accumulate into a list."""
@@ -336,11 +321,6 @@ def test_cli_reservation_estimate():
     assert json.loads(result.output) == payload
 
 
-# ---------------------------------------------------------------------------
-# jobs list / get
-# ---------------------------------------------------------------------------
-
-
 @respx.mock
 def test_cli_jobs_list():
     page = {"meta": {"count": 2}, "results": [_job("a"), _job("b")]}