More review comments

Author: Pijukatel

docs/02_concepts/08_pagination.mdx

@@ -12,6 +12,8 @@ import ApiLink from '@site/src/components/ApiLink';
 
 import PaginationAsyncExample from '!!raw-loader!./code/08_pagination_async.py';
 import PaginationSyncExample from '!!raw-loader!./code/08_pagination_sync.py';
+import IterateItemsAsyncExample from '!!raw-loader!./code/08_iterate_items_async.py';
+import IterateItemsSyncExample from '!!raw-loader!./code/08_iterate_items_sync.py';
 
 
 Most methods named `list` or `list_something` in the Apify client return a <ApiLink to="class/ListPage">`ListPage`</ApiLink>  object. This object provides a consistent interface for working with paginated data and includes the following properties:

src/apify_client/_iterable_list_page.py

@@ -124,7 +124,7 @@ def __aiter__(self) -> AsyncIterator[T]:
         return self._get_async_iterator()
 
     def __await__(self) -> Generator[Any, Any, ListPage[T]]:
-        """Return an awaitable that resolves to an `IterableListPage` containing the first page."""
+        """Return an awaitable that resolves to a `ListPage` containing the first page of results."""
         return self._awaitable_first_page().__await__()
 
 

src/apify_client/_resource_clients/key_value_store.py

@@ -162,13 +162,14 @@ def list_keys(
         https://docs.apify.com/api/v2#/reference/key-value-stores/key-collection/get-list-of-keys
 
         Args:
-            limit: Number of keys to be returned. Maximum value is 1000.
+            limit: Total number of keys to yield across all pages when iterating. The API caps each
+                individual request at 1000 keys; use `chunk_size` to control the per-request size.
             exclusive_start_key: All keys up to this one (including) are skipped from the result.
             collection: The name of the collection in store schema to list keys from.
             prefix: The prefix of the keys to be listed.
             signature: Signature used to access the items.
-            chunk_size: Maximum number of keys requested per API call when iterating. Only relevant
-                when iterating across pages.
+            chunk_size: Maximum number of keys requested per API call when iterating. Capped at
+                1000 by the API. Only relevant when iterating across pages.
             timeout: Timeout for the API HTTP request.
 
         Returns:
@@ -218,13 +219,14 @@ def iterate_keys(
         https://docs.apify.com/api/v2#/reference/key-value-stores/key-collection/get-list-of-keys
 
         Args:
-            limit: Number of keys to be returned. Maximum value is 1000.
+            limit: Total number of keys to yield across all pages. The API caps each individual
+                request at 1000 keys; use `chunk_size` to control the per-request size.
             exclusive_start_key: All keys up to this one (including) are skipped from the result.
             collection: The name of the collection in store schema to list keys from.
             prefix: The prefix of the keys to be listed.
             signature: Signature used to access the items.
-            chunk_size: Maximum number of keys requested per API call when iterating. Only relevant
-                when iterating across pages.
+            chunk_size: Maximum number of keys requested per API call when iterating. Capped at
+                1000 by the API. Only relevant when iterating across pages.
             timeout: Timeout for the API HTTP request.
 
         Yields:
@@ -476,7 +478,7 @@ def create_keys_public_url(
         Any other options (like `limit` or `prefix`) will be included as query parameters in the URL.
 
         Args:
-            limit: Number of keys to be returned. Maximum value is 1000.
+            limit: Number of keys to be returned by the signed request. Maximum value is 1000.
             exclusive_start_key: All keys up to this one (including) are skipped from the result.
             collection: The name of the collection in store schema to list keys from.
             prefix: The prefix of the keys to be listed.
@@ -600,13 +602,14 @@ def list_keys(
         https://docs.apify.com/api/v2#/reference/key-value-stores/key-collection/get-list-of-keys
 
         Args:
-            limit: Number of keys to be returned. Maximum value is 1000.
+            limit: Total number of keys to yield across all pages when iterating. The API caps each
+                individual request at 1000 keys; use `chunk_size` to control the per-request size.
             exclusive_start_key: All keys up to this one (including) are skipped from the result.
             collection: The name of the collection in store schema to list keys from.
             prefix: The prefix of the keys to be listed.
             signature: Signature used to access the items.
-            chunk_size: Maximum number of keys requested per API call when iterating. Only relevant
-                when iterating across pages.
+            chunk_size: Maximum number of keys requested per API call when iterating. Capped at
+                1000 by the API. Only relevant when iterating across pages.
             timeout: Timeout for the API HTTP request.
 
         Returns:
@@ -656,13 +659,14 @@ async def iterate_keys(
         https://docs.apify.com/api/v2#/reference/key-value-stores/key-collection/get-list-of-keys
 
         Args:
-            limit: Number of keys to be returned. Maximum value is 1000.
+            limit: Total number of keys to yield across all pages. The API caps each individual
+                request at 1000 keys; use `chunk_size` to control the per-request size.
             exclusive_start_key: All keys up to this one (including) are skipped from the result.
             collection: The name of the collection in store schema to list keys from.
             prefix: The prefix of the keys to be listed.
             signature: Signature used to access the items.
-            chunk_size: Maximum number of keys requested per API call when iterating. Only relevant
-                when iterating across pages.
+            chunk_size: Maximum number of keys requested per API call when iterating. Capped at
+                1000 by the API. Only relevant when iterating across pages.
             timeout: Timeout for the API HTTP request.
 
         Yields:
@@ -917,7 +921,7 @@ async def create_keys_public_url(
         Any other options (like `limit` or `prefix`) will be included as query parameters in the URL.
 
         Args:
-            limit: Number of keys to be returned. Maximum value is 1000.
+            limit: Number of keys to be returned by the signed request. Maximum value is 1000.
             exclusive_start_key: All keys up to this one (including) are skipped from the result.
             collection: The name of the collection in store schema to list keys from.
             prefix: The prefix of the keys to be listed.

tests/integration/test_request_queue.py

@@ -265,8 +265,8 @@ async def test_request_queue_list_requests(client: ApifyClient | ApifyClientAsyn
 
         assert isinstance(list_response, ListPage)
         assert isinstance(list_response.items, list)
-        assert isinstance(list_response.items[0], Request)
         assert len(list_response.items) == 5
+        assert isinstance(list_response.items[0], Request)
     finally:
         await maybe_await(rq_client.delete())
 
@@ -335,8 +335,8 @@ async def test_request_queue_batch_add_requests(client: ApifyClient | ApifyClien
 
         assert isinstance(list_response, ListPage)
         assert isinstance(list_response.items, list)
-        assert isinstance(list_response.items[0], Request)
         assert len(list_response.items) == 10
+        assert isinstance(list_response.items[0], Request)
     finally:
         await maybe_await(rq_client.delete())
 
@@ -366,8 +366,8 @@ async def test_request_queue_batch_delete_requests(client: ApifyClient | ApifyCl
 
         assert isinstance(list_response, ListPage)
         assert isinstance(list_response.items, list)
-        assert isinstance(list_response.items[0], Request)
         assert len(list_response.items) == 10
+        assert isinstance(list_response.items[0], Request)
         requests_to_delete: list[RequestDeleteInputDict] = [
             {'unique_key': item.unique_key} for item in list_response.items[:5]
         ]
@@ -388,8 +388,8 @@ async def test_request_queue_batch_delete_requests(client: ApifyClient | ApifyCl
 
         assert isinstance(remaining, ListPage)
         assert isinstance(remaining.items, list)
-        assert isinstance(remaining.items[0], Request)
         assert len(remaining.items) == 5
+        assert isinstance(remaining.items[0], Request)
     finally:
         await maybe_await(rq_client.delete())
 

tests/integration/test_webhook.py

@@ -173,8 +173,8 @@ async def test_webhook_dispatches(client: ApifyClient | ApifyClientAsync) -> Non
         dispatches = await maybe_await(webhook_client.dispatches().list())
         assert isinstance(dispatches, ListPage)
         assert isinstance(dispatches.items, list)
-        assert isinstance(dispatches.items[0], WebhookDispatch)
         assert len(dispatches.items) > 0
+        assert isinstance(dispatches.items[0], WebhookDispatch)
 
     finally:
         await maybe_await(webhook_client.delete())