From 8e6ad44317ffa30a3829f6294d281c94ba12127d Mon Sep 17 00:00:00 2001 From: Vlada Dusek Date: Thu, 2 Apr 2026 09:30:03 +0200 Subject: [PATCH] docs: fix factual errors and standardize frontmatter across all doc pages MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Fix several factual errors in docs: wrong error handling pattern (except Exception as ApifyApiError → except ApifyApiError as err), incorrect default retry count (8 → 4), outdated parameter name (min_delay_between_retries_millis → min_delay_between_retries), wrong start() description, outdated README dict access. Add description field to all frontmatter and standardize guide titles to imperative form. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 5 +++-- docs/01_introduction/code/03_input_async.py | 2 +- docs/01_introduction/code/03_input_sync.py | 2 +- docs/01_introduction/index.mdx | 3 +-- docs/01_introduction/quick-start.mdx | 3 +-- docs/02_concepts/01_async_support.mdx | 1 + .../02_single_collection_clients.mdx | 1 + docs/02_concepts/03_nested_clients.mdx | 1 + docs/02_concepts/04_error_handling.mdx | 1 + docs/02_concepts/05_retries.mdx | 9 +++++---- docs/02_concepts/06_logging.mdx | 1 + docs/02_concepts/07_convenience_methods.mdx | 6 ++++-- docs/02_concepts/08_pagination.mdx | 1 + docs/02_concepts/09_streaming.mdx | 1 + docs/02_concepts/10_custom_http_clients.mdx | 1 + docs/02_concepts/code/03_nested_async.py | 7 ++++--- docs/02_concepts/code/03_nested_sync.py | 7 ++++--- docs/02_concepts/code/04_error_async.py | 17 ++++++++++++----- docs/02_concepts/code/04_error_sync.py | 15 ++++++++++----- docs/02_concepts/code/07_call_async.py | 4 ++-- docs/02_concepts/code/07_call_sync.py | 4 ++-- docs/03_guides/01_passing_input_to_actor.mdx | 3 ++- .../02_manage_tasks_for_reusable_input.mdx | 1 + docs/03_guides/03_retrieve_actor_data.mdx | 1 + .../04_integration_with_data_libraries.mdx | 3 ++- docs/03_guides/05_custom_http_client.mdx | 3 ++- docs/04_upgrading/upgrading_to_v2.md | 1 + docs/04_upgrading/upgrading_to_v3.md | 1 + 28 files changed, 68 insertions(+), 37 deletions(-) diff --git a/README.md b/README.md index 63c1ef17..210f4eab 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,8 @@ apify_client = ApifyClient('MY-APIFY-TOKEN') actor_call = apify_client.actor('john-doe/my-cool-actor').call() # Fetch results from the Actor's default dataset -dataset_items = apify_client.dataset(actor_call['defaultDatasetId']).list_items().items +if actor_call is not None: + dataset_items = apify_client.dataset(actor_call.default_dataset_id).list_items().items ``` ## Features @@ -46,7 +47,7 @@ Based on the endpoint, the client automatically extracts the relevant data and r ### Retries with exponential backoff -Network communication sometimes fails. The client will automatically retry requests that failed due to a network error, an internal error of the Apify API (HTTP 500+) or rate limit error (HTTP 429). By default, it will retry up to 8 times. First retry will be attempted after ~500ms, second after ~1000ms and so on. You can configure those parameters using the `max_retries` and `min_delay_between_retries_millis` options of the `ApifyClient` constructor. +Network communication sometimes fails. The client will automatically retry requests that failed due to a network error, an internal error of the Apify API (HTTP 500+) or rate limit error (HTTP 429). By default, it will retry up to 4 times. First retry will be attempted after ~500ms, second after ~1000ms and so on. You can configure those parameters using the `max_retries` and `min_delay_between_retries` options of the `ApifyClient` constructor. ### Support for asynchronous usage diff --git a/docs/01_introduction/code/03_input_async.py b/docs/01_introduction/code/03_input_async.py index bef7ac72..1937f446 100644 --- a/docs/01_introduction/code/03_input_async.py +++ b/docs/01_introduction/code/03_input_async.py @@ -12,5 +12,5 @@ async def main() -> None: 'some': 'input', } - # Start an Actor and waits for it to finish. + # Start an Actor and wait for it to finish. call_result = await actor_client.call(run_input=run_input) diff --git a/docs/01_introduction/code/03_input_sync.py b/docs/01_introduction/code/03_input_sync.py index 7fab1635..6a27dd39 100644 --- a/docs/01_introduction/code/03_input_sync.py +++ b/docs/01_introduction/code/03_input_sync.py @@ -12,5 +12,5 @@ def main() -> None: 'some': 'input', } - # Start an Actor and waits for it to finish. + # Start an Actor and wait for it to finish. call_result = actor_client.call(run_input=run_input) diff --git a/docs/01_introduction/index.mdx b/docs/01_introduction/index.mdx index d0076ee2..072d1f3d 100644 --- a/docs/01_introduction/index.mdx +++ b/docs/01_introduction/index.mdx @@ -1,9 +1,8 @@ --- id: introduction title: Overview -sidebar_label: Overview slug: / -description: "The official Python library to access the Apify API, with automatic retries, async support, and comprehensive API coverage." +description: The official Python library to access the Apify API, with automatic retries, async support, and comprehensive API coverage. --- import Tabs from '@theme/Tabs'; diff --git a/docs/01_introduction/quick-start.mdx b/docs/01_introduction/quick-start.mdx index 5832c2a7..94918cf5 100644 --- a/docs/01_introduction/quick-start.mdx +++ b/docs/01_introduction/quick-start.mdx @@ -1,8 +1,7 @@ --- id: quick-start title: Quick start -sidebar_label: Quick start -description: "Get started with the Apify API client for Python by running an Actor and retrieving results from its dataset." +description: Get started with the Apify API client for Python by running an Actor and retrieving results from its dataset. --- import Tabs from '@theme/Tabs'; diff --git a/docs/02_concepts/01_async_support.mdx b/docs/02_concepts/01_async_support.mdx index bdb6ab3a..ddc06f9b 100644 --- a/docs/02_concepts/01_async_support.mdx +++ b/docs/02_concepts/01_async_support.mdx @@ -1,6 +1,7 @@ --- id: asyncio-support title: Asyncio support +description: Use the async client for non-blocking API calls with Python asyncio. --- import Tabs from '@theme/Tabs'; diff --git a/docs/02_concepts/02_single_collection_clients.mdx b/docs/02_concepts/02_single_collection_clients.mdx index 1a5ac0a2..fe1ddc91 100644 --- a/docs/02_concepts/02_single_collection_clients.mdx +++ b/docs/02_concepts/02_single_collection_clients.mdx @@ -1,6 +1,7 @@ --- id: single-and-collection-clients title: Single and collection clients +description: Understand the two types of resource clients, single-resource and collection clients. --- import Tabs from '@theme/Tabs'; diff --git a/docs/02_concepts/03_nested_clients.mdx b/docs/02_concepts/03_nested_clients.mdx index 386aefd1..6df8a362 100644 --- a/docs/02_concepts/03_nested_clients.mdx +++ b/docs/02_concepts/03_nested_clients.mdx @@ -1,6 +1,7 @@ --- id: nested-clients title: Nested clients +description: Access related resources directly through nested client methods. --- import Tabs from '@theme/Tabs'; diff --git a/docs/02_concepts/04_error_handling.mdx b/docs/02_concepts/04_error_handling.mdx index d8859eb1..16a96fae 100644 --- a/docs/02_concepts/04_error_handling.mdx +++ b/docs/02_concepts/04_error_handling.mdx @@ -1,6 +1,7 @@ --- id: error-handling title: Error handling +description: Handle API errors with the ApifyApiError exception and automatic data parsing. --- import Tabs from '@theme/Tabs'; diff --git a/docs/02_concepts/05_retries.mdx b/docs/02_concepts/05_retries.mdx index 9cf0ed11..50ee6779 100644 --- a/docs/02_concepts/05_retries.mdx +++ b/docs/02_concepts/05_retries.mdx @@ -1,6 +1,7 @@ --- id: retries title: Retries +description: Configure automatic retries with exponential backoff for failed requests. --- import Tabs from '@theme/Tabs'; @@ -10,13 +11,13 @@ import CodeBlock from '@theme/CodeBlock'; import RetriesAsyncExample from '!!raw-loader!./code/05_retries_async.py'; import RetriesSyncExample from '!!raw-loader!./code/05_retries_sync.py'; -When dealing with network communication, failures can occasionally occur. The Apify client automatically retries requests that fail due to: +The Apify client automatically retries requests that fail due to: - Network errors - Internal errors in the Apify API (HTTP status codes 500 and above) - Rate limit errors (HTTP status code 429) -By default, the client will retry a failed request up to 8 times. The retry intervals use an exponential backoff strategy: +By default, the client retries a failed request up to 4 times. The retry intervals use an exponential backoff strategy: - The first retry occurs after approximately 500 milliseconds. - The second retry occurs after approximately 1,000 milliseconds, and so on. @@ -24,9 +25,9 @@ By default, the client will retry a failed request up to 8 times. The retry inte You can customize this behavior using the following options in the [`ApifyClient`](/reference/class/ApifyClient) constructor: - `max_retries`: Defines the maximum number of retry attempts. -- `min_delay_between_retries_millis`: Sets the minimum delay between retries (in milliseconds). +- `min_delay_between_retries`: Sets the minimum delay between retries as a `timedelta`. -Retries with exponential backoff are a common strategy for handling network errors. They help to reduce the load on the server and increase the chances of a successful request. +Retries with exponential backoff help reduce the load on the server and increase the chances of a successful request. diff --git a/docs/02_concepts/06_logging.mdx b/docs/02_concepts/06_logging.mdx index 2e495878..4b4e8ed5 100644 --- a/docs/02_concepts/06_logging.mdx +++ b/docs/02_concepts/06_logging.mdx @@ -1,6 +1,7 @@ --- id: logging title: Logging +description: Configure debug logging to inspect API requests and responses. --- import Tabs from '@theme/Tabs'; diff --git a/docs/02_concepts/07_convenience_methods.mdx b/docs/02_concepts/07_convenience_methods.mdx index b3014471..988af550 100644 --- a/docs/02_concepts/07_convenience_methods.mdx +++ b/docs/02_concepts/07_convenience_methods.mdx @@ -1,6 +1,7 @@ --- id: convenience-methods title: Convenience methods +description: Use high-level methods for running Actors, waiting for results, and accessing data. --- import Tabs from '@theme/Tabs'; @@ -12,8 +13,9 @@ import CallSyncExample from '!!raw-loader!./code/07_call_sync.py'; The Apify client provides several convenience methods to handle actions that the API alone cannot perform efficiently, such as waiting for an Actor run to finish without running into network timeouts. These methods simplify common tasks and enhance the usability of the client. -- [`ActorClient.call`](/reference/class/ActorClient#call) - Starts an Actor and waits for it to finish, handling network timeouts internally. -- [`ActorClient.start`](/reference/class/ActorClient#start) - Explicitly waits for an Actor run to finish with customizable timeouts. +- [`ActorClient.call`](/reference/class/ActorClient#call) - Starts an Actor and waits for it to finish, handling network timeouts internally. Waits indefinitely by default, or up to the specified `wait_duration`. +- [`ActorClient.start`](/reference/class/ActorClient#start) - Starts an Actor and immediately returns the Run object without waiting for it to finish. +- [`RunClient.wait_for_finish`](/reference/class/RunClient#wait_for_finish) - Waits for an already-started run to reach a terminal status. Additionally, storage-related resources offer flexible options for data retrieval: diff --git a/docs/02_concepts/08_pagination.mdx b/docs/02_concepts/08_pagination.mdx index 712aee81..c79638f2 100644 --- a/docs/02_concepts/08_pagination.mdx +++ b/docs/02_concepts/08_pagination.mdx @@ -1,6 +1,7 @@ --- id: pagination title: Pagination +description: Paginate through large result sets using ListPage or generator-based iteration. --- import Tabs from '@theme/Tabs'; diff --git a/docs/02_concepts/09_streaming.mdx b/docs/02_concepts/09_streaming.mdx index c62da01e..0d5d6d1f 100644 --- a/docs/02_concepts/09_streaming.mdx +++ b/docs/02_concepts/09_streaming.mdx @@ -1,6 +1,7 @@ --- id: streaming-resources title: Streaming resources +description: Stream large datasets, key-value store records, and logs without loading them into memory. --- import Tabs from '@theme/Tabs'; diff --git a/docs/02_concepts/10_custom_http_clients.mdx b/docs/02_concepts/10_custom_http_clients.mdx index 7e7c383f..81f18ccb 100644 --- a/docs/02_concepts/10_custom_http_clients.mdx +++ b/docs/02_concepts/10_custom_http_clients.mdx @@ -1,6 +1,7 @@ --- id: custom-http-clients title: Custom HTTP clients +description: Replace the default HTTP client with a custom implementation. --- import Tabs from '@theme/Tabs'; diff --git a/docs/02_concepts/code/03_nested_async.py b/docs/02_concepts/code/03_nested_async.py index 662657c8..b7843df1 100644 --- a/docs/02_concepts/code/03_nested_async.py +++ b/docs/02_concepts/code/03_nested_async.py @@ -1,4 +1,5 @@ from apify_client import ApifyClientAsync +from apify_client._models import ActorJobStatus TOKEN = 'MY-APIFY-TOKEN' @@ -9,11 +10,11 @@ async def main() -> None: actor_client = apify_client.actor('username/actor-name') runs_client = actor_client.runs() - # List the last 10 runs of the Actor + # List the last 10 runs of the Actor. actor_runs = (await runs_client.list(limit=10, desc=True)).items - # Select the last run of the Actor that finished with a SUCCEEDED status - last_succeeded_run_client = actor_client.last_run(status='SUCCEEDED') # ty: ignore[invalid-argument-type] + # Select the last run of the Actor that finished with a SUCCEEDED status. + last_succeeded_run_client = actor_client.last_run(status=ActorJobStatus.SUCCEEDED) # Get dataset actor_run_dataset_client = last_succeeded_run_client.dataset() diff --git a/docs/02_concepts/code/03_nested_sync.py b/docs/02_concepts/code/03_nested_sync.py index 74654576..4759f28f 100644 --- a/docs/02_concepts/code/03_nested_sync.py +++ b/docs/02_concepts/code/03_nested_sync.py @@ -1,4 +1,5 @@ from apify_client import ApifyClient +from apify_client._models import ActorJobStatus TOKEN = 'MY-APIFY-TOKEN' @@ -9,11 +10,11 @@ def main() -> None: actor_client = apify_client.actor('username/actor-name') runs_client = actor_client.runs() - # List the last 10 runs of the Actor + # List the last 10 runs of the Actor. actor_runs = runs_client.list(limit=10, desc=True).items - # Select the last run of the Actor that finished with a SUCCEEDED status - last_succeeded_run_client = actor_client.last_run(status='SUCCEEDED') # ty: ignore[invalid-argument-type] + # Select the last run of the Actor that finished with a SUCCEEDED status. + last_succeeded_run_client = actor_client.last_run(status=ActorJobStatus.SUCCEEDED) # Get dataset actor_run_dataset_client = last_succeeded_run_client.dataset() diff --git a/docs/02_concepts/code/04_error_async.py b/docs/02_concepts/code/04_error_async.py index 0057ea44..2409a0c8 100644 --- a/docs/02_concepts/code/04_error_async.py +++ b/docs/02_concepts/code/04_error_async.py @@ -1,4 +1,7 @@ +import asyncio + from apify_client import ApifyClientAsync +from apify_client.errors import ApifyApiError TOKEN = 'MY-APIFY-TOKEN' @@ -7,9 +10,13 @@ async def main() -> None: apify_client = ApifyClientAsync(TOKEN) try: - # Try to list items from non-existing dataset - dataset_client = apify_client.dataset('not-existing-dataset-id') + # Try to list items from a non-existing dataset. + dataset_client = apify_client.dataset('non-existing-dataset-id') dataset_items = (await dataset_client.list_items()).items - except Exception as ApifyApiError: - # The exception is an instance of ApifyApiError - print(ApifyApiError) + except ApifyApiError as err: + # The client raises ApifyApiError for API errors. + print(f'API error: {err}') + + +if __name__ == '__main__': + asyncio.run(main()) diff --git a/docs/02_concepts/code/04_error_sync.py b/docs/02_concepts/code/04_error_sync.py index 83fc3080..f2b237d4 100644 --- a/docs/02_concepts/code/04_error_sync.py +++ b/docs/02_concepts/code/04_error_sync.py @@ -1,4 +1,5 @@ from apify_client import ApifyClient +from apify_client.errors import ApifyApiError TOKEN = 'MY-APIFY-TOKEN' @@ -7,9 +8,13 @@ def main() -> None: apify_client = ApifyClient(TOKEN) try: - # Try to list items from non-existing dataset - dataset_client = apify_client.dataset('not-existing-dataset-id') + # Try to list items from a non-existing dataset. + dataset_client = apify_client.dataset('non-existing-dataset-id') dataset_items = dataset_client.list_items().items - except Exception as ApifyApiError: - # The exception is an instance of ApifyApiError - print(ApifyApiError) + except ApifyApiError as err: + # The client raises ApifyApiError for API errors. + print(f'API error: {err}') + + +if __name__ == '__main__': + main() diff --git a/docs/02_concepts/code/07_call_async.py b/docs/02_concepts/code/07_call_async.py index 955f7532..3fe5a56f 100644 --- a/docs/02_concepts/code/07_call_async.py +++ b/docs/02_concepts/code/07_call_async.py @@ -7,8 +7,8 @@ async def main() -> None: apify_client = ApifyClientAsync(TOKEN) actor_client = apify_client.actor('username/actor-name') - # Start an Actor and waits for it to finish + # Start an Actor and wait for it to finish. finished_actor_run = await actor_client.call() - # Starts an Actor and waits maximum 60s (1 minute) for the finish + # Start an Actor and wait up to 60 seconds for it to finish. actor_run = await actor_client.start(wait_for_finish=60) diff --git a/docs/02_concepts/code/07_call_sync.py b/docs/02_concepts/code/07_call_sync.py index af790eaa..366f32ef 100644 --- a/docs/02_concepts/code/07_call_sync.py +++ b/docs/02_concepts/code/07_call_sync.py @@ -7,8 +7,8 @@ def main() -> None: apify_client = ApifyClient(TOKEN) actor_client = apify_client.actor('username/actor-name') - # Start an Actor and waits for it to finish + # Start an Actor and wait for it to finish. finished_actor_run = actor_client.call() - # Starts an Actor and waits maximum 60s (1 minute) for the finish + # Start an Actor and wait up to 60 seconds for it to finish. actor_run = actor_client.start(wait_for_finish=60) diff --git a/docs/03_guides/01_passing_input_to_actor.mdx b/docs/03_guides/01_passing_input_to_actor.mdx index 61769d73..25af270e 100644 --- a/docs/03_guides/01_passing_input_to_actor.mdx +++ b/docs/03_guides/01_passing_input_to_actor.mdx @@ -1,6 +1,7 @@ --- id: passing-input-to-actor -title: Passing input to Actor +title: Pass input to an Actor +description: Run an Actor with custom input data and retrieve results. --- import Tabs from '@theme/Tabs'; diff --git a/docs/03_guides/02_manage_tasks_for_reusable_input.mdx b/docs/03_guides/02_manage_tasks_for_reusable_input.mdx index 9865e232..6a947e91 100644 --- a/docs/03_guides/02_manage_tasks_for_reusable_input.mdx +++ b/docs/03_guides/02_manage_tasks_for_reusable_input.mdx @@ -1,6 +1,7 @@ --- id: manage-tasks-for-reusable-input title: Manage tasks for reusable input +description: Create and manage tasks with reusable input configurations. --- import Tabs from '@theme/Tabs'; diff --git a/docs/03_guides/03_retrieve_actor_data.mdx b/docs/03_guides/03_retrieve_actor_data.mdx index f139b2a9..ecb266f5 100644 --- a/docs/03_guides/03_retrieve_actor_data.mdx +++ b/docs/03_guides/03_retrieve_actor_data.mdx @@ -1,6 +1,7 @@ --- id: retrieve-actor-data title: Retrieve Actor data +description: Fetch, paginate, and merge datasets from Actor runs. --- import Tabs from '@theme/Tabs'; diff --git a/docs/03_guides/04_integration_with_data_libraries.mdx b/docs/03_guides/04_integration_with_data_libraries.mdx index 9c4cad3e..91aefcd9 100644 --- a/docs/03_guides/04_integration_with_data_libraries.mdx +++ b/docs/03_guides/04_integration_with_data_libraries.mdx @@ -1,6 +1,7 @@ --- id: integration-with-data-libraries -title: Integration with data libraries +title: Integrate with data libraries +description: Load Apify dataset items into Pandas DataFrames for analysis. --- import Tabs from '@theme/Tabs'; diff --git a/docs/03_guides/05_custom_http_client.mdx b/docs/03_guides/05_custom_http_client.mdx index 4df3776e..77fd5432 100644 --- a/docs/03_guides/05_custom_http_client.mdx +++ b/docs/03_guides/05_custom_http_client.mdx @@ -1,6 +1,7 @@ --- id: custom-http-client-httpx -title: Using HTTPX as the HTTP client +title: Use HTTPX as the HTTP client +description: Replace the default Impit HTTP client with one based on HTTPX. --- import ApiLink from '@site/src/components/ApiLink'; diff --git a/docs/04_upgrading/upgrading_to_v2.md b/docs/04_upgrading/upgrading_to_v2.md index f34233a8..be1ffb8a 100644 --- a/docs/04_upgrading/upgrading_to_v2.md +++ b/docs/04_upgrading/upgrading_to_v2.md @@ -1,6 +1,7 @@ --- id: upgrading-to-v2 title: Upgrading to v2 +description: Breaking changes and migration guide from v1 to v2. --- This page summarizes the breaking changes between Apify Python API Client v1.x and v2.0. diff --git a/docs/04_upgrading/upgrading_to_v3.md b/docs/04_upgrading/upgrading_to_v3.md index 3f75287d..598ca88c 100644 --- a/docs/04_upgrading/upgrading_to_v3.md +++ b/docs/04_upgrading/upgrading_to_v3.md @@ -1,6 +1,7 @@ --- id: upgrading-to-v3 title: Upgrading to v3 +description: Breaking changes and migration guide from v2 to v3. --- This page summarizes the breaking changes between Apify Python API Client v2.x and v3.0.