apify-client 3.2.2b1__tar.gz → 3.2.2b3__tar.gz

{apify_client-3.2.2b1 → apify_client-3.2.2b3}/CHANGELOG.md

@@ -8,6 +8,12 @@ All notable changes to this project will be documented in this file.
 ### 🚀 Features
 
 - Stream request bodies from files, iterables, and responses ([#1060](https://github.com/apify/apify-client-python/pull/1060)) ([9be215b](https://github.com/apify/apify-client-python/commit/9be215b23a13de0abc4a255a18450cc764e7a6c7)) by [@vdusek](https://github.com/vdusek), closes [#972](https://github.com/apify/apify-client-python/issues/972)
+- Retry starting a run on memory and concurrent-runs limits ([#1081](https://github.com/apify/apify-client-python/pull/1081)) ([3dd8ca5](https://github.com/apify/apify-client-python/commit/3dd8ca5fe4d2537cb009cb310ba12b39927a9558)) by [@vdusek](https://github.com/vdusek), closes [#1071](https://github.com/apify/apify-client-python/issues/1071)
+- Add live iteration over a run's dataset items ([#1079](https://github.com/apify/apify-client-python/pull/1079)) ([6aa8ead](https://github.com/apify/apify-client-python/commit/6aa8ead676a3520f6a418597eb62f319a3d19d30)) by [@vdusek](https://github.com/vdusek), closes [#1065](https://github.com/apify/apify-client-python/issues/1065)
+
+### 🐛 Bug Fixes
+
+- Add missing `readme` field to `Profile` model ([#1086](https://github.com/apify/apify-client-python/pull/1086)) ([ae17148](https://github.com/apify/apify-client-python/commit/ae1714891c4f70d66ab4964c1783fee0a96776f1)) by [@apify-service-account](https://github.com/apify-service-account)
 
 
 <!-- git-cliff-unreleased-end -->

{apify_client-3.2.2b1 → apify_client-3.2.2b3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: apify_client
-Version: 3.2.2b1
+Version: 3.2.2b3
 Summary: Apify API client for Python
 Keywords: apify,api,client,automation,crawling,scraping
 Author: Apify Technologies s.r.o.

{apify_client-3.2.2b1 → apify_client-3.2.2b3}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "apify_client"
-version = "3.2.2b1"
+version = "3.2.2b3"
 description = "Apify API client for Python"
 license = "Apache-2.0"
 license-files = ["LICENSE"]
@@ -246,7 +246,7 @@ disable_timestamp = true
 keep_model_order = true
 
 [tool.apify.openapi-spec]
-version = "v2-2026-08-31T125154Z"
+version = "v2-2026-10-01T153946Z"
 
 [tool.uv]
 exclude-newer = "24 hours"

{apify_client-3.2.2b1 → apify_client-3.2.2b3}/pyproject.toml.orig

@@ -4,7 +4,7 @@ build-backend = "uv_build"
 
 [project]
 name = "apify_client"
-version = "3.2.2b1"
+version = "3.2.2b3"
 description = "Apify API client for Python"
 authors = [{ name = "Apify Technologies s.r.o.", email = "support@apify.com" }]
 license = "Apache-2.0"
@@ -250,7 +250,7 @@ keep_model_order = true
 # workflow committing nothing unless the models changed. A local regeneration that only moves this line is that
 # same case - drop it rather than committing it alone.
 [tool.apify.openapi-spec]
-version = "v2-2026-08-31T125154Z"
+version = "v2-2026-10-01T153946Z"
 
 [tool.uv]
 # Minimal defense against supply-chain atatcks.

{apify_client-3.2.2b1 → apify_client-3.2.2b3}/src/apify_client/_models.py

@@ -595,6 +595,12 @@ class Build(BaseModel):
     build_number: Annotated[
         str, Field(examples=['0.1.1'], pattern='^([0-9]|[1-9][0-9])\\.([0-9]|[1-9][0-9])(\\.[1-9][0-9]{0,4})$')
     ]
+    image_digest: Annotated[
+        str | None, Field(examples=['1b2f1e8c0d5a4c7f9e3b6a2d8c4e0f7a5b9d3c1e6f8a2b4d0c7e9f1a3b5d7c9e'])
+    ] = None
+    """
+    Digest of the built Docker image manifest, without the `sha256:` prefix. Compare digests of two builds to find out whether their image contents differ. `null` if the digest is not available.
+    """
     act_version: Annotated[ActVersion | None, Field(title='BuildActVersion')] = None
     """
     Snapshot of the Actor version that this build was created from.
@@ -2280,6 +2286,10 @@ class Profile(BaseModel):
         alias_generator=to_camel,
     )
     bio: Annotated[str | None, Field(examples=['I started web scraping in 1985 using Altair BASIC.'])] = None
+    readme: Annotated[str | None, Field(examples=['### Hello world 👋🏻\nI build web scrapers.'])] = None
+    """
+    Markdown README shown on the user's public profile page.
+    """
     name: Annotated[str | None, Field(examples=['Jane Doe'])] = None
     picture_url: Annotated[AnyUrl | None, Field(examples=['https://apify.com/img/anonymous_user_picture.png'])] = None
     github_username: Annotated[str | None, Field(examples=['torvalds.'])] = None

{apify_client-3.2.2b1 → apify_client-3.2.2b3}/src/apify_client/_resource_clients/_resource_client.py

@@ -42,6 +42,7 @@ class ResourceClientBase(metaclass=WithLogDetailsClient):
         client_registry: Any,
         resource_id: str | None = None,
         params: dict | None = None,
+        api_base_url: str | None = None,
     ) -> None:
         """Initialize the resource client.
 
@@ -53,11 +54,13 @@ class ResourceClientBase(metaclass=WithLogDetailsClient):
             client_registry: Bundle of client classes for dependency injection.
             resource_id: Optional resource ID for single-resource clients.
             params: Optional default parameters for all requests.
+            api_base_url: Base URL of the API itself, for clients of top-level resources. Defaults to `base_url`.
         """
         if resource_path.endswith('/'):
             raise ValueError('resource_path must not end with "/"')
 
         self._base_url = base_url
+        self._api_base_url = api_base_url or base_url
         self._public_base_url = public_base_url
         self._http_client = http_client
         self._default_params = params or {}
@@ -82,11 +85,12 @@ class ResourceClientBase(metaclass=WithLogDetailsClient):
     def _base_client_kwargs(self) -> dict[str, Any]:
         """Base kwargs for creating nested/child clients.
 
-        Returns dict with base_url, public_base_url, http_client, and client_registry. Caller adds
+        Returns dict with base_url, api_base_url, public_base_url, http_client, and client_registry. Caller adds
         resource_path, resource_id, and params as needed.
         """
         return {
             'base_url': self._resource_url,
+            'api_base_url': self._api_base_url,
             'public_base_url': self._public_base_url,
             'http_client': self._http_client,
             'client_registry': self._client_registry,
@@ -197,6 +201,7 @@ class ResourceClient(ResourceClientBase):
         client_registry: ClientRegistry,
         resource_id: str | None = None,
         params: dict | None = None,
+        api_base_url: str | None = None,
     ) -> None:
         """Initialize the resource client.
 
@@ -208,6 +213,7 @@ class ResourceClient(ResourceClientBase):
             client_registry: Bundle of client classes for dependency injection.
             resource_id: Optional resource ID for single-resource clients.
             params: Optional default parameters for all requests.
+            api_base_url: Base URL of the API itself, for clients of top-level resources. Defaults to `base_url`.
         """
         super().__init__(
             base_url=base_url,
@@ -217,6 +223,7 @@ class ResourceClient(ResourceClientBase):
             client_registry=client_registry,
             resource_id=resource_id,
             params=params,
+            api_base_url=api_base_url,
         )
 
     def _get(self, *, timeout: Timeout) -> dict | None:
@@ -389,6 +396,7 @@ class ResourceClientAsync(ResourceClientBase):
         client_registry: ClientRegistryAsync,
         resource_id: str | None = None,
         params: dict | None = None,
+        api_base_url: str | None = None,
     ) -> None:
         """Initialize the resource client.
 
@@ -400,6 +408,7 @@ class ResourceClientAsync(ResourceClientBase):
             client_registry: Bundle of client classes for dependency injection.
             resource_id: Optional resource ID for single-resource clients.
             params: Optional default parameters for all requests.
+            api_base_url: Base URL of the API itself, for clients of top-level resources. Defaults to `base_url`.
         """
         super().__init__(
             base_url=base_url,
@@ -409,6 +418,7 @@ class ResourceClientAsync(ResourceClientBase):
             client_registry=client_registry,
             resource_id=resource_id,
             params=params,
+            api_base_url=api_base_url,
         )
 
     async def _get(self, *, timeout: Timeout) -> dict | None:

{apify_client-3.2.2b1 → apify_client-3.2.2b3}/src/apify_client/_resource_clients/actor.py

@@ -26,6 +26,11 @@ from apify_client._resource_clients._resource_client import ResourceClient, Reso
 from apify_client._utils.encoding import encode_key_value_store_record_value, encode_webhooks_to_base64
 from apify_client._utils.http import response_to_dict
 from apify_client._utils.time import to_seconds
+from apify_client._utils.wait_for_resources import (
+    prepare_resendable_body,
+    start_waiting_for_resources,
+    start_waiting_for_resources_async,
+)
 
 if TYPE_CHECKING:
     from datetime import timedelta
@@ -229,6 +234,7 @@ class ActorClient(ResourceClient):
         force_permission_level: ActorPermissionLevel | None = None,
         wait_for_finish: int | None = None,
         webhooks: WebhooksList | None = None,
+        wait_for_resources: bool | timedelta = False,
         timeout: Timeout = 'medium',
     ) -> Run:
         """Start the Actor and immediately return the Run object.
@@ -263,12 +269,21 @@ class ActorClient(ResourceClient):
                     * `event_types`: List of `WebhookEventType` values which trigger the webhook.
                     * `request_url`: URL to which to send the webhook HTTP request.
                     * `payload_template`: Optional template for the request payload.
+            wait_for_resources: Retry the start while the account lacks the memory or a concurrent-run slot for the run,
+                that is while the API rejects it with an `ApifyApiError` of type `actor-memory-limit-exceeded` or
+                `concurrent-runs-limit-exceeded`. Both clear as other runs or builds finish. The start is retried
+                every 10 seconds, and any other error is raised right away. `True` retries until the run starts, a
+                `timedelta` stops retrying after that long and raises the last error. A run that requests more memory
+                than the whole memory limit of the account is rejected with `actor-memory-limit-exceeded` as well and
+                never starts, so `True` retries it forever. A streamed `run_input` that cannot be rewound, such as a
+                generator, is sent only once, so its start is not retried.
             timeout: Timeout for the API HTTP request.
 
         Returns:
             The run object.
         """
         run_input, content_type = encode_key_value_store_record_value(run_input, content_type=content_type)
+        run_input, wait_for_resources = prepare_resendable_body(run_input, wait_for_resources=wait_for_resources)
 
         request_params = self._build_params(
             build=build,
@@ -282,13 +297,16 @@ class ActorClient(ResourceClient):
             webhooks=encode_webhooks_to_base64(webhooks),
         )
 
-        response = self._http_client.call(
-            url=self._build_url('runs'),
-            method='POST',
-            headers={'content-type': content_type},
-            data=run_input,
-            params=request_params,
-            timeout=timeout,
+        response = start_waiting_for_resources(
+            lambda: self._http_client.call(
+                url=self._build_url('runs'),
+                method='POST',
+                headers={'content-type': content_type},
+                data=run_input,
+                params=request_params,
+                timeout=timeout,
+            ),
+            wait_for_resources=wait_for_resources,
         )
 
         result = response_to_dict(response)
@@ -308,6 +326,7 @@ class ActorClient(ResourceClient):
         webhooks: WebhooksList | None = None,
         force_permission_level: ActorPermissionLevel | None = None,
         wait_duration: timedelta | None = None,
+        wait_for_resources: bool | timedelta = False,
         logger: Logger | Literal['default'] | None = 'default',
         timeout: Timeout = 'no_timeout',
     ) -> Run | None:
@@ -341,6 +360,14 @@ class ActorClient(ResourceClient):
                 a webhook set up for the Actor, you do not have to add it again here.
             wait_duration: The maximum time the server waits for the run to finish. If not provided,
                 waits indefinitely.
+            wait_for_resources: Retry the start while the account lacks the memory or a concurrent-run slot for the run,
+                that is while the API rejects it with an `ApifyApiError` of type `actor-memory-limit-exceeded` or
+                `concurrent-runs-limit-exceeded`. Both clear as other runs or builds finish. The start is retried
+                every 10 seconds, and any other error is raised right away. `True` retries until the run starts, a
+                `timedelta` stops retrying after that long and raises the last error. A run that requests more memory
+                than the whole memory limit of the account is rejected with `actor-memory-limit-exceeded` as well and
+                never starts, so `True` retries it forever. The time spent retrying doesn't count toward
+                `wait_duration`.
             logger: Logger used to redirect logs from the Actor run. Using "default" literal means that a predefined
                 default logger will be used. Setting `None` will disable any log propagation. Passing custom logger
                 will redirect logs to the provided logger. The logger is also used to capture status and status message
@@ -361,6 +388,7 @@ class ActorClient(ResourceClient):
             run_timeout=run_timeout,
             webhooks=webhooks,
             force_permission_level=force_permission_level,
+            wait_for_resources=wait_for_resources,
             timeout=timeout,
         )
         run_client = self._client_registry.run_client(
@@ -740,6 +768,7 @@ class ActorClientAsync(ResourceClientAsync):
         force_permission_level: ActorPermissionLevel | None = None,
         wait_for_finish: int | None = None,
         webhooks: WebhooksList | None = None,
+        wait_for_resources: bool | timedelta = False,
         timeout: Timeout = 'medium',
     ) -> Run:
         """Start the Actor and immediately return the Run object.
@@ -774,12 +803,21 @@ class ActorClientAsync(ResourceClientAsync):
                     * `event_types`: List of `WebhookEventType` values which trigger the webhook.
                     * `request_url`: URL to which to send the webhook HTTP request.
                     * `payload_template`: Optional template for the request payload.
+            wait_for_resources: Retry the start while the account lacks the memory or a concurrent-run slot for the run,
+                that is while the API rejects it with an `ApifyApiError` of type `actor-memory-limit-exceeded` or
+                `concurrent-runs-limit-exceeded`. Both clear as other runs or builds finish. The start is retried
+                every 10 seconds, and any other error is raised right away. `True` retries until the run starts, a
+                `timedelta` stops retrying after that long and raises the last error. A run that requests more memory
+                than the whole memory limit of the account is rejected with `actor-memory-limit-exceeded` as well and
+                never starts, so `True` retries it forever. A streamed `run_input` that cannot be rewound, such as a
+                generator, is sent only once, so its start is not retried.
             timeout: Timeout for the API HTTP request.
 
         Returns:
             The run object.
         """
         run_input, content_type = encode_key_value_store_record_value(run_input, content_type=content_type)
+        run_input, wait_for_resources = prepare_resendable_body(run_input, wait_for_resources=wait_for_resources)
 
         request_params = self._build_params(
             build=build,
@@ -793,13 +831,16 @@ class ActorClientAsync(ResourceClientAsync):
             webhooks=encode_webhooks_to_base64(webhooks),
         )
 
-        response = await self._http_client.call(
-            url=self._build_url('runs'),
-            method='POST',
-            headers={'content-type': content_type},
-            data=run_input,
-            params=request_params,
-            timeout=timeout,
+        response = await start_waiting_for_resources_async(
+            lambda: self._http_client.call(
+                url=self._build_url('runs'),
+                method='POST',
+                headers={'content-type': content_type},
+                data=run_input,
+                params=request_params,
+                timeout=timeout,
+            ),
+            wait_for_resources=wait_for_resources,
         )
 
         result = response_to_dict(response)
@@ -819,6 +860,7 @@ class ActorClientAsync(ResourceClientAsync):
         webhooks: WebhooksList | None = None,
         force_permission_level: ActorPermissionLevel | None = None,
         wait_duration: timedelta | None = None,
+        wait_for_resources: bool | timedelta = False,
         logger: Logger | Literal['default'] | None = 'default',
         timeout: Timeout = 'no_timeout',
     ) -> Run | None:
@@ -852,6 +894,14 @@ class ActorClientAsync(ResourceClientAsync):
                 a webhook set up for the Actor, you do not have to add it again here.
             wait_duration: The maximum time the server waits for the run to finish. If not provided,
                 waits indefinitely.
+            wait_for_resources: Retry the start while the account lacks the memory or a concurrent-run slot for the run,
+                that is while the API rejects it with an `ApifyApiError` of type `actor-memory-limit-exceeded` or
+                `concurrent-runs-limit-exceeded`. Both clear as other runs or builds finish. The start is retried
+                every 10 seconds, and any other error is raised right away. `True` retries until the run starts, a
+                `timedelta` stops retrying after that long and raises the last error. A run that requests more memory
+                than the whole memory limit of the account is rejected with `actor-memory-limit-exceeded` as well and
+                never starts, so `True` retries it forever. The time spent retrying doesn't count toward
+                `wait_duration`.
             logger: Logger used to redirect logs from the Actor run. Using "default" literal means that a predefined
                 default logger will be used. Setting `None` will disable any log propagation. Passing custom logger
                 will redirect logs to the provided logger. The logger is also used to capture status and status message
@@ -872,6 +922,7 @@ class ActorClientAsync(ResourceClientAsync):
             run_timeout=run_timeout,
             webhooks=webhooks,
             force_permission_level=force_permission_level,
+            wait_for_resources=wait_for_resources,
             timeout=timeout,
         )
 

{apify_client-3.2.2b1 → apify_client-3.2.2b3}/src/apify_client/_resource_clients/run.py

@@ -10,7 +10,8 @@ from typing import TYPE_CHECKING, Any
 from apify_client._docs import docs_group
 from apify_client._logging import create_redirect_logger
 from apify_client._models import Run, RunResponse
-from apify_client._resource_clients._resource_client import ResourceClient, ResourceClientAsync
+from apify_client._pagination import DEFAULT_CHUNK_SIZE
+from apify_client._resource_clients._resource_client import _TERMINAL_STATUSES, ResourceClient, ResourceClientAsync
 from apify_client._status_message_watcher import StatusMessageWatcher, StatusMessageWatcherAsync
 from apify_client._streamed_log import StreamedLog, StreamedLogAsync
 from apify_client._utils.encoding import encode_key_value_store_record_value
@@ -19,6 +20,7 @@ from apify_client._utils.time import to_seconds
 
 if TYPE_CHECKING:
     import logging
+    from collections.abc import AsyncIterator, Iterator
     from decimal import Decimal
 
     from apify_client._literals import GeneralAccess
@@ -32,6 +34,7 @@ if TYPE_CHECKING:
         RequestQueueClient,
         RequestQueueClientAsync,
     )
+    from apify_client._resource_clients.dataset import DatasetItemsPage
     from apify_client.types import Timeout
 
 
@@ -469,6 +472,122 @@ class RunClient(ResourceClient):
 
         return StatusMessageWatcher(run_client=self, to_logger=to_logger, check_period=check_period)
 
+    def iterate_dataset_items(
+        self,
+        *,
+        offset: int | None = None,
+        limit: int | None = None,
+        clean: bool | None = None,
+        fields: list[str] | None = None,
+        omit: list[str] | None = None,
+        unwind: list[str] | None = None,
+        skip_empty: bool | None = None,
+        skip_hidden: bool | None = None,
+        chunk_size: int | None = None,
+        poll_interval: timedelta = timedelta(seconds=5),
+        timeout: Timeout = 'long',
+    ) -> Iterator[dict]:
+        """Iterate over the items of the run's default dataset while the run is still producing them.
+
+        While the run has not finished, each poll yields the rows below the dataset's `item_count` and then waits up to
+        `poll_interval` for the run to finish, so the last rows are read as soon as it does. Each page is requested with
+        a `limit` that ends at `item_count`, so it covers exactly the rows it asks for, whatever the filters or `unwind`
+        do to the items. `item_count` lags a few seconds behind the pushed items, so once the run reaches a terminal
+        status, the rows past it are read a page at a time until none are left, and the iterator returns. On a
+        `last_run()` client, the iterator sticks to the run that its first request resolves to.
+
+        https://docs.apify.com/api/v2#/reference/datasets/item-collection/get-items
+
+        Args:
+            offset: Number of items that should be skipped at the start. The default value is 0.
+            limit: Maximum number of dataset rows to scan. Fewer items are yielded when filters drop some, more
+                when `unwind` splits a row into several. By default there is no limit.
+            clean: If True, returns only non-empty items and skips hidden fields (i.e. fields starting with
+                the # character). The clean parameter is just a shortcut for skip_hidden=True and skip_empty=True
+                parameters.
+            fields: A list of fields which should be picked from the items, only these fields will remain in
+                the resulting record objects.
+            omit: A list of fields which should be omitted from the items.
+            unwind: A list of fields which should be unwound, in order which they should be processed. Each field
+                should be either an array or an object. If the field is an array then every element of the array
+                will become a separate record and merged with parent object. If the unwound field is an object then
+                it is merged with the parent object.
+            skip_empty: If True, then empty items are skipped from the output.
+            skip_hidden: If True, then hidden fields are skipped from the output, i.e. fields starting with
+                the # character.
+            chunk_size: Maximum number of dataset rows requested per API call.
+            poll_interval: How long to wait for the run to finish between polls.
+            timeout: Timeout for each API HTTP request.
+
+        Yields:
+            An item from the dataset.
+        """
+        page_size = chunk_size or DEFAULT_CHUNK_SIZE
+        position = offset or 0
+        end = position + limit if limit else None
+
+        run = self.get(timeout=timeout)
+        # A `last_run()` client resolves `runs/last` per request, so a newer run would swap the dataset mid-iteration.
+        run_client = (
+            self._client_registry.run_client(
+                resource_id=run.id,
+                base_url=self._api_base_url,
+                public_base_url=self._public_base_url,
+                http_client=self._http_client,
+                client_registry=self._client_registry,
+            )
+            if run is not None and run.id != self._resource_id
+            else self
+        )
+        dataset_client = run_client.dataset()
+
+        def list_page(page_offset: int, page_limit: int) -> DatasetItemsPage:
+            return dataset_client.list_items(
+                offset=page_offset,
+                limit=page_limit,
+                clean=clean,
+                fields=fields,
+                omit=omit,
+                unwind=unwind,
+                skip_empty=skip_empty,
+                skip_hidden=skip_hidden,
+                timeout=timeout,
+            )
+
+        while True:
+            is_finished = run is None or run.status in _TERMINAL_STATUSES
+            dataset = dataset_client.get(timeout=timeout)
+            item_count = dataset.item_count if dataset else 0
+            if end is not None:
+                item_count = min(item_count, end)
+
+            while position < item_count:
+                page_limit = min(page_size, item_count - position)
+                page = list_page(position, page_limit)
+                yield from page.items
+                position += page_limit
+
+            if end is not None and position >= end:
+                return
+            if is_finished:
+                break
+            run = run_client.wait_for_finish(wait_duration=poll_interval, timeout=timeout)
+
+        while True:
+            page_limit = min(page_size, end - position) if end is not None else page_size
+            page = list_page(position, page_limit)
+            yield from page.items
+            # Only an empty page marks the end, as filters can shorten a full one. A page that `clean`, `skip_empty` or
+            # `unwind` emptied past a lagging `item_count` reports no scanned rows either, so a plain read checks.
+            if not page.count and (
+                not (clean or skip_empty or unwind)
+                or not dataset_client.list_items(offset=position, limit=1, timeout=timeout).items
+            ):
+                return
+            position += page_limit
+            if end is not None and position >= end:
+                return
+
 
 @docs_group('Resource clients')
 class RunClientAsync(ResourceClientAsync):
@@ -903,3 +1022,121 @@ class RunClientAsync(ResourceClientAsync):
             to_logger = create_redirect_logger(f'apify.{name}')
 
         return StatusMessageWatcherAsync(run_client=self, to_logger=to_logger, check_period=check_period)
+
+    async def iterate_dataset_items(
+        self,
+        *,
+        offset: int | None = None,
+        limit: int | None = None,
+        clean: bool | None = None,
+        fields: list[str] | None = None,
+        omit: list[str] | None = None,
+        unwind: list[str] | None = None,
+        skip_empty: bool | None = None,
+        skip_hidden: bool | None = None,
+        chunk_size: int | None = None,
+        poll_interval: timedelta = timedelta(seconds=5),
+        timeout: Timeout = 'long',
+    ) -> AsyncIterator[dict]:
+        """Iterate over the items of the run's default dataset while the run is still producing them.
+
+        While the run has not finished, each poll yields the rows below the dataset's `item_count` and then waits up to
+        `poll_interval` for the run to finish, so the last rows are read as soon as it does. Each page is requested with
+        a `limit` that ends at `item_count`, so it covers exactly the rows it asks for, whatever the filters or `unwind`
+        do to the items. `item_count` lags a few seconds behind the pushed items, so once the run reaches a terminal
+        status, the rows past it are read a page at a time until none are left, and the iterator returns. On a
+        `last_run()` client, the iterator sticks to the run that its first request resolves to.
+
+        https://docs.apify.com/api/v2#/reference/datasets/item-collection/get-items
+
+        Args:
+            offset: Number of items that should be skipped at the start. The default value is 0.
+            limit: Maximum number of dataset rows to scan. Fewer items are yielded when filters drop some, more
+                when `unwind` splits a row into several. By default there is no limit.
+            clean: If True, returns only non-empty items and skips hidden fields (i.e. fields starting with
+                the # character). The clean parameter is just a shortcut for skip_hidden=True and skip_empty=True
+                parameters.
+            fields: A list of fields which should be picked from the items, only these fields will remain in
+                the resulting record objects.
+            omit: A list of fields which should be omitted from the items.
+            unwind: A list of fields which should be unwound, in order which they should be processed. Each field
+                should be either an array or an object. If the field is an array then every element of the array
+                will become a separate record and merged with parent object. If the unwound field is an object then
+                it is merged with the parent object.
+            skip_empty: If True, then empty items are skipped from the output.
+            skip_hidden: If True, then hidden fields are skipped from the output, i.e. fields starting with
+                the # character.
+            chunk_size: Maximum number of dataset rows requested per API call.
+            poll_interval: How long to wait for the run to finish between polls.
+            timeout: Timeout for each API HTTP request.
+
+        Yields:
+            An item from the dataset.
+        """
+        page_size = chunk_size or DEFAULT_CHUNK_SIZE
+        position = offset or 0
+        end = position + limit if limit else None
+
+        run = await self.get(timeout=timeout)
+        # A `last_run()` client resolves `runs/last` per request, so a newer run would swap the dataset mid-iteration.
+        run_client = (
+            self._client_registry.run_client(
+                resource_id=run.id,
+                base_url=self._api_base_url,
+                public_base_url=self._public_base_url,
+                http_client=self._http_client,
+                client_registry=self._client_registry,
+            )
+            if run is not None and run.id != self._resource_id
+            else self
+        )
+        dataset_client = run_client.dataset()
+
+        async def list_page(page_offset: int, page_limit: int) -> DatasetItemsPage:
+            return await dataset_client.list_items(
+                offset=page_offset,
+                limit=page_limit,
+                clean=clean,
+                fields=fields,
+                omit=omit,
+                unwind=unwind,
+                skip_empty=skip_empty,
+                skip_hidden=skip_hidden,
+                timeout=timeout,
+            )
+
+        while True:
+            is_finished = run is None or run.status in _TERMINAL_STATUSES
+            dataset = await dataset_client.get(timeout=timeout)
+            item_count = dataset.item_count if dataset else 0
+            if end is not None:
+                item_count = min(item_count, end)
+
+            while position < item_count:
+                page_limit = min(page_size, item_count - position)
+                page = await list_page(position, page_limit)
+                for item in page.items:
+                    yield item
+                position += page_limit
+
+            if end is not None and position >= end:
+                return
+            if is_finished:
+                break
+            run = await run_client.wait_for_finish(wait_duration=poll_interval, timeout=timeout)
+
+        while True:
+            page_limit = min(page_size, end - position) if end is not None else page_size
+            page = await list_page(position, page_limit)
+            for item in page.items:
+                yield item
+            # Only an empty page marks the end, as filters can shorten a full one. A page that `clean`, `skip_empty` or
+            # `unwind` emptied past a lagging `item_count` reports no scanned rows either, so a plain read checks.
+            if not page.count and (
+                not (clean or skip_empty or unwind)
+                or not (await dataset_client.list_items(offset=position, limit=1, timeout=timeout)).items
+            ):
+                return
+            position += page_limit
+            if end is not None and position >= end:
+                return

{apify_client-3.2.2b1 → apify_client-3.2.2b3}/src/apify_client/_resource_clients/task.py

@@ -18,6 +18,7 @@ from apify_client._resource_clients._resource_client import ResourceClient, Reso
 from apify_client._utils.encoding import encode_webhooks_to_base64
 from apify_client._utils.http import response_to_dict
 from apify_client._utils.time import to_seconds
+from apify_client._utils.wait_for_resources import start_waiting_for_resources, start_waiting_for_resources_async
 
 if TYPE_CHECKING:
     from datetime import timedelta
@@ -221,6 +222,7 @@ class TaskClient(ResourceClient):
         restart_on_error: bool | None = None,
         wait_for_finish: int | None = None,
         webhooks: WebhooksList | None = None,
+        wait_for_resources: bool | timedelta = False,
         timeout: Timeout = 'medium',
     ) -> Run:
         """Start the task and immediately return the Run object.
@@ -248,6 +250,13 @@ class TaskClient(ResourceClient):
                     * `event_types`: List of `WebhookEventType` values which trigger the webhook.
                     * `request_url`: URL to which to send the webhook HTTP request.
                     * `payload_template`: Optional template for the request payload.
+            wait_for_resources: Retry the start while the account lacks the memory or a concurrent-run slot for the run,
+                that is while the API rejects it with an `ApifyApiError` of type `actor-memory-limit-exceeded` or
+                `concurrent-runs-limit-exceeded`. Both clear as other runs or builds finish. The start is retried
+                every 10 seconds, and any other error is raised right away. `True` retries until the run starts, a
+                `timedelta` stops retrying after that long and raises the last error. A run that requests more memory
+                than the whole memory limit of the account is rejected with `actor-memory-limit-exceeded` as well and
+                never starts, so `True` retries it forever.
             timeout: Timeout for the API HTTP request.
 
         Returns:
@@ -266,13 +275,16 @@ class TaskClient(ResourceClient):
             webhooks=encode_webhooks_to_base64(webhooks),
         )
 
-        response = self._http_client.call(
-            url=self._build_url('runs'),
-            method='POST',
-            headers={'content-type': 'application/json; charset=utf-8'},
-            json=task_input.model_dump() if task_input is not None else None,
-            params=request_params,
-            timeout=timeout,
+        response = start_waiting_for_resources(
+            lambda: self._http_client.call(
+                url=self._build_url('runs'),
+                method='POST',
+                headers={'content-type': 'application/json; charset=utf-8'},
+                json=task_input.model_dump() if task_input is not None else None,
+                params=request_params,
+                timeout=timeout,
+            ),
+            wait_for_resources=wait_for_resources,
         )
 
         result = response_to_dict(response)
@@ -289,6 +301,7 @@ class TaskClient(ResourceClient):
         restart_on_error: bool | None = None,
         webhooks: WebhooksList | None = None,
         wait_duration: timedelta | None = None,
+        wait_for_resources: bool | timedelta = False,
         timeout: Timeout = 'no_timeout',
     ) -> Run | None:
         """Start a task and wait for it to finish before returning the Run object.
@@ -314,6 +327,14 @@ class TaskClient(ResourceClient):
                 the Actor or task, you do not have to add it again here.
             wait_duration: The maximum time the server waits for the task run to finish. If not provided,
                 waits indefinitely.
+            wait_for_resources: Retry the start while the account lacks the memory or a concurrent-run slot for the run,
+                that is while the API rejects it with an `ApifyApiError` of type `actor-memory-limit-exceeded` or
+                `concurrent-runs-limit-exceeded`. Both clear as other runs or builds finish. The start is retried
+                every 10 seconds, and any other error is raised right away. `True` retries until the run starts, a
+                `timedelta` stops retrying after that long and raises the last error. A run that requests more memory
+                than the whole memory limit of the account is rejected with `actor-memory-limit-exceeded` as well and
+                never starts, so `True` retries it forever. The time spent retrying doesn't count toward
+                `wait_duration`.
             timeout: Timeout for the API HTTP request.
 
         Returns:
@@ -327,6 +348,7 @@ class TaskClient(ResourceClient):
             run_timeout=run_timeout,
             restart_on_error=restart_on_error,
             webhooks=webhooks,
+            wait_for_resources=wait_for_resources,
             timeout=timeout,
         )
 
@@ -602,6 +624,7 @@ class TaskClientAsync(ResourceClientAsync):
         restart_on_error: bool | None = None,
         wait_for_finish: int | None = None,
         webhooks: WebhooksList | None = None,
+        wait_for_resources: bool | timedelta = False,
         timeout: Timeout = 'medium',
     ) -> Run:
         """Start the task and immediately return the Run object.
@@ -629,6 +652,13 @@ class TaskClientAsync(ResourceClientAsync):
                     * `event_types`: List of `WebhookEventType` values which trigger the webhook.
                     * `request_url`: URL to which to send the webhook HTTP request.
                     * `payload_template`: Optional template for the request payload.
+            wait_for_resources: Retry the start while the account lacks the memory or a concurrent-run slot for the run,
+                that is while the API rejects it with an `ApifyApiError` of type `actor-memory-limit-exceeded` or
+                `concurrent-runs-limit-exceeded`. Both clear as other runs or builds finish. The start is retried
+                every 10 seconds, and any other error is raised right away. `True` retries until the run starts, a
+                `timedelta` stops retrying after that long and raises the last error. A run that requests more memory
+                than the whole memory limit of the account is rejected with `actor-memory-limit-exceeded` as well and
+                never starts, so `True` retries it forever.
             timeout: Timeout for the API HTTP request.
 
         Returns:
@@ -647,13 +677,16 @@ class TaskClientAsync(ResourceClientAsync):
             webhooks=encode_webhooks_to_base64(webhooks),
         )
 
-        response = await self._http_client.call(
-            url=self._build_url('runs'),
-            method='POST',
-            headers={'content-type': 'application/json; charset=utf-8'},
-            json=task_input.model_dump() if task_input is not None else None,
-            params=request_params,
-            timeout=timeout,
+        response = await start_waiting_for_resources_async(
+            lambda: self._http_client.call(
+                url=self._build_url('runs'),
+                method='POST',
+                headers={'content-type': 'application/json; charset=utf-8'},
+                json=task_input.model_dump() if task_input is not None else None,
+                params=request_params,
+                timeout=timeout,
+            ),
+            wait_for_resources=wait_for_resources,
         )
 
         result = response_to_dict(response)
@@ -670,6 +703,7 @@ class TaskClientAsync(ResourceClientAsync):
         restart_on_error: bool | None = None,
         webhooks: WebhooksList | None = None,
         wait_duration: timedelta | None = None,
+        wait_for_resources: bool | timedelta = False,
         timeout: Timeout = 'no_timeout',
     ) -> Run | None:
         """Start a task and wait for it to finish before returning the Run object.
@@ -695,6 +729,14 @@ class TaskClientAsync(ResourceClientAsync):
                 the Actor or task, you do not have to add it again here.
             wait_duration: The maximum time the server waits for the task run to finish. If not provided,
                 waits indefinitely.
+            wait_for_resources: Retry the start while the account lacks the memory or a concurrent-run slot for the run,
+                that is while the API rejects it with an `ApifyApiError` of type `actor-memory-limit-exceeded` or
+                `concurrent-runs-limit-exceeded`. Both clear as other runs or builds finish. The start is retried
+                every 10 seconds, and any other error is raised right away. `True` retries until the run starts, a
+                `timedelta` stops retrying after that long and raises the last error. A run that requests more memory
+                than the whole memory limit of the account is rejected with `actor-memory-limit-exceeded` as well and
+                never starts, so `True` retries it forever. The time spent retrying doesn't count toward
+                `wait_duration`.
             timeout: Timeout for the API HTTP request.
 
         Returns:
@@ -708,6 +750,7 @@ class TaskClientAsync(ResourceClientAsync):
             run_timeout=run_timeout,
             restart_on_error=restart_on_error,
             webhooks=webhooks,
+            wait_for_resources=wait_for_resources,
             timeout=timeout,
         )
         run_client = self._client_registry.run_client(

apify_client-3.2.2b3/src/apify_client/_utils/wait_for_resources.py

@@ -0,0 +1,82 @@
+from __future__ import annotations
+
+import asyncio
+import time
+from datetime import timedelta
+from typing import TYPE_CHECKING, Any, TypeVar
+
+from apify_client._logging import logger
+from apify_client.errors import ApifyApiError
+from apify_client.http_clients._streamed_body import StreamedRequestBody
+
+if TYPE_CHECKING:
+    from collections.abc import Awaitable, Callable
+
+T = TypeVar('T')
+
+RESOURCE_LIMIT_ERROR_TYPES = frozenset({'actor-memory-limit-exceeded', 'concurrent-runs-limit-exceeded'})
+"""Error types the API rejects a run start with while the account has no free memory or concurrent-run slot for it.
+
+Both clear as other runs or builds finish.
+"""
+
+WAIT_FOR_RESOURCES_COOLDOWN = timedelta(seconds=10)
+"""Cooldown between two attempts to start a run that was rejected for lack of resources."""
+
+
+def prepare_resendable_body(data: Any, *, wait_for_resources: bool | timedelta) -> tuple[Any, bool | timedelta]:
+    """Wrap a streamed request body once, so every start attempt sends the same body.
+
+    A seekable `io.IOBase` source is rewound before each attempt. Any other streamed source is used up by the first
+    attempt, so the returned `wait_for_resources` is `False` and a start rejected for lack of resources is not retried.
+    """
+    if wait_for_resources is False or not StreamedRequestBody.is_streamable(data):
+        return data, wait_for_resources
+    body = data if isinstance(data, StreamedRequestBody) else StreamedRequestBody(data)
+    return body, wait_for_resources if body.rewindable else False
+
+
+def _next_delay(exc: ApifyApiError, deadline: float | None) -> float:
+    """Return the seconds to sleep before the next attempt, or re-raise `exc` if no attempt should follow."""
+    if exc.type not in RESOURCE_LIMIT_ERROR_TYPES:
+        raise exc
+    delay = WAIT_FOR_RESOURCES_COOLDOWN.total_seconds()
+    if deadline is not None:
+        remaining = deadline - time.monotonic()
+        if remaining <= 0:
+            raise exc
+        delay = min(delay, remaining)
+    logger.info('Not enough resources to start the run, retrying in %.3gs: %s', delay, exc.message)
+    return delay
+
+
+def start_waiting_for_resources(start: Callable[[], T], *, wait_for_resources: bool | timedelta) -> T:
+    """Make the `start` request, retrying it every `WAIT_FOR_RESOURCES_COOLDOWN` while it fails for lack of resources.
+
+    `True` retries until the request succeeds, a `timedelta` bounds the retrying, after which the last error is raised.
+    Any other error is raised right away.
+    """
+    if wait_for_resources is False:
+        return start()
+    deadline = None if wait_for_resources is True else time.monotonic() + wait_for_resources.total_seconds()
+    while True:
+        try:
+            return start()
+        except ApifyApiError as exc:
+            time.sleep(_next_delay(exc, deadline))
+
+
+async def start_waiting_for_resources_async(
+    start: Callable[[], Awaitable[T]],
+    *,
+    wait_for_resources: bool | timedelta,
+) -> T:
+    """Async variant of `start_waiting_for_resources`."""
+    if wait_for_resources is False:
+        return await start()
+    deadline = None if wait_for_resources is True else time.monotonic() + wait_for_resources.total_seconds()
+    while True:
+        try:
+            return await start()
+        except ApifyApiError as exc:
+            await asyncio.sleep(_next_delay(exc, deadline))