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 63c1ef175..210f4eabd 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 bef7ac72d..1937f446a 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 7fab1635d..6a27dd398 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 d0076ee28..072d1f3dd 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 5832c2a76..94918cf58 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 bdb6ab3a7..ddc06f9bb 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 1a5ac0a2a..fe1ddc910 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 386aefd18..6df8a3621 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 d8859eb1e..16a96faee 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 9cf0ed118..50ee67799 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 2e4958785..4b4e8ed5c 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 b3014471c..988af5504 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 712aee81b..c79638f28 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 c62da01e0..0d5d6d1fb 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 7e7c383f5..81f18ccb3 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 662657c8f..b7843df14 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 746545761..4759f28fe 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 0057ea44b..2409a0c8c 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 83fc30803..f2b237d44 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 955f75320..3fe5a56f6 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 af790eaa3..366f32efb 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 61769d733..25af270e7 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 9865e2325..6a947e912 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 f139b2a91..ecb266f56 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 9c4cad3ec..91aefcd93 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 4df3776e2..77fd54320 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 f34233a85..be1ffb8a4 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 3f75287d5..598ca88c5 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.