Skip to content

Commit 3fee70a

Browse files
refactor: restructure documentation (#647)
## Summary - Restructured documentation from flat structure to numbered hierarchical organization (`01_introduction`, `02_concepts`, `03_guides`), matching the pattern used in [apify-client-js#850](apify/apify-client-js#850) - Renamed `01_overview` to `01_introduction` with simplified overview and separate quick start page - Renamed `03_examples` to `03_guides` - Simplified overview page by removing content duplicated in the quick start guide (authentication, running Actors, providing input, getting results) - Updated sidebar, docusaurus config, and landing page redirect 🤖 Generated with [Claude Code](https://claude.com/claude-code) --------- Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>
1 parent d4d8b68 commit 3fee70a

26 files changed

Lines changed: 174 additions & 162 deletions
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.
File renamed without changes.

‎docs/01_introduction/index.mdx‎

Lines changed: 58 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,58 @@
1+
---
2+
id: introduction
3+
title: Overview
4+
sidebar_label: Overview
5+
slug: /
6+
description: "The official Python library to access the Apify API, with automatic retries, async support, and comprehensive API coverage."
7+
---
8+
9+
import Tabs from '@theme/Tabs';
10+
import TabItem from '@theme/TabItem';
11+
import CodeBlock from '@theme/CodeBlock';
12+
13+
import UsageAsyncExample from '!!raw-loader!./code/01_usage_async.py';
14+
import UsageSyncExample from '!!raw-loader!./code/01_usage_sync.py';
15+
16+
The Apify API client for Python is the official library to access the [Apify REST API](/api/v2) from your Python applications. It provides useful features like automatic retries and convenience functions that improve the experience of using the Apify API.
17+
18+
The client simplifies interaction with the Apify platform by providing:
19+
20+
- Intuitive methods for working with [Actors](/platform/actors), [datasets](/platform/storage/dataset), [key-value stores](/platform/storage/key-value-store), and other Apify resources
21+
- Both synchronous and asynchronous interfaces for flexible integration
22+
- Built-in [retries with exponential backoff](../02_concepts/05_retries.mdx) for failed requests
23+
- Comprehensive API coverage with JSON encoding (UTF-8) for all requests and responses
24+
25+
## Prerequisites
26+
27+
`apify-client` requires Python 3.11 or higher. Python is available for download on the [official website](https://www.python.org/downloads/). Check your current Python version by running:
28+
29+
```bash
30+
python --version
31+
```
32+
33+
## Installation
34+
35+
The Apify client is available as the [`apify-client`](https://pypi.org/project/apify-client/) package on PyPI.
36+
37+
```bash
38+
pip install apify-client
39+
```
40+
41+
## Quick example
42+
43+
Here's an example showing how to run an Actor and retrieve its results:
44+
45+
<Tabs>
46+
<TabItem value="AsyncExample" label="Async client" default>
47+
<CodeBlock className="language-python">
48+
{UsageAsyncExample}
49+
</CodeBlock>
50+
</TabItem>
51+
<TabItem value="SyncExample" label="Sync client">
52+
<CodeBlock className="language-python">
53+
{UsageSyncExample}
54+
</CodeBlock>
55+
</TabItem>
56+
</Tabs>
57+
58+
> You can find your API token in the [Integrations section](https://console.apify.com/account/integrations) of Apify Console. See the [Quick start guide](./quick-start.mdx) for more details on authentication.
Lines changed: 106 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,106 @@
1+
---
2+
id: quick-start
3+
title: Quick start
4+
sidebar_label: Quick start
5+
description: "Get started with the Apify API client for Python by running an Actor and retrieving results from its dataset."
6+
---
7+
8+
import Tabs from '@theme/Tabs';
9+
import TabItem from '@theme/TabItem';
10+
import CodeBlock from '@theme/CodeBlock';
11+
12+
import AuthAsyncExample from '!!raw-loader!./code/02_auth_async.py';
13+
import AuthSyncExample from '!!raw-loader!./code/02_auth_sync.py';
14+
import InputAsyncExample from '!!raw-loader!./code/03_input_async.py';
15+
import InputSyncExample from '!!raw-loader!./code/03_input_sync.py';
16+
import DatasetAsyncExample from '!!raw-loader!./code/03_dataset_async.py';
17+
import DatasetSyncExample from '!!raw-loader!./code/03_dataset_sync.py';
18+
19+
Learn how to authenticate, run Actors, and retrieve results using the Apify API client for Python.
20+
21+
---
22+
23+
## Step 1: Authenticate the client
24+
25+
To use the client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token). You can find your token under the [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing it (`MY-APIFY-TOKEN`) as a parameter to the `ApifyClient` constructor.
26+
27+
<Tabs>
28+
<TabItem value="AsyncExample" label="Async client" default>
29+
<CodeBlock className="language-python">
30+
{AuthAsyncExample}
31+
</CodeBlock>
32+
</TabItem>
33+
<TabItem value="SyncExample" label="Sync client">
34+
<CodeBlock className="language-python">
35+
{AuthSyncExample}
36+
</CodeBlock>
37+
</TabItem>
38+
</Tabs>
39+
40+
:::warning Secure access
41+
42+
The API token is used to authorize your requests to the Apify API. You can be charged for the usage of the underlying services, so do not share your API token with untrusted parties or expose it on the client side of your applications.
43+
44+
:::
45+
46+
## Step 2: Run an Actor
47+
48+
To start an Actor, call the [`apify_client.actor()`](/reference/class/ActorClient) method with the Actor's ID (e.g., `john-doe/my-cool-actor`). The Actor's ID is a combination of the Actor owner's username and the Actor name. You can run both your own Actors and Actors from [Apify Store](https://apify.com/store).
49+
50+
To define the Actor's input, pass a dictionary to the [`call()`](/reference/class/ActorClient#call) method that matches the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema). The input can include URLs to scrape, search terms, or other configuration data.
51+
52+
<Tabs>
53+
<TabItem value="AsyncExample" label="Async client" default>
54+
<CodeBlock className="language-python">
55+
{InputAsyncExample}
56+
</CodeBlock>
57+
</TabItem>
58+
<TabItem value="SyncExample" label="Sync client">
59+
<CodeBlock className="language-python">
60+
{InputSyncExample}
61+
</CodeBlock>
62+
</TabItem>
63+
</Tabs>
64+
65+
## Step 3: Get results from the dataset
66+
67+
To get the results from the dataset, call the [`apify_client.dataset()`](/reference/class/DatasetClient) method with the dataset ID, then call [`list_items()`](/reference/class/DatasetClient#list_items) to retrieve the data. You can get the dataset ID from the Actor's run dictionary (represented by `defaultDatasetId`).
68+
69+
<Tabs>
70+
<TabItem value="AsyncExample" label="Async client" default>
71+
<CodeBlock className="language-python">
72+
{DatasetAsyncExample}
73+
</CodeBlock>
74+
</TabItem>
75+
<TabItem value="SyncExample" label="Sync client">
76+
<CodeBlock className="language-python">
77+
{DatasetSyncExample}
78+
</CodeBlock>
79+
</TabItem>
80+
</Tabs>
81+
82+
:::note Dataset access
83+
84+
Running an Actor might take time, depending on the Actor's complexity and the amount of data it processes. If you want only to get data and have an immediate response, you should access the existing dataset of the finished [Actor run](https://docs.apify.com/platform/actors/running/runs-and-builds#runs).
85+
86+
:::
87+
88+
## Next steps
89+
90+
### Concepts
91+
92+
To learn more about how the client works, check out the Concepts section in the sidebar:
93+
94+
- [Asyncio support](../02_concepts/01_async_support.mdx) - asynchronous programming with the client
95+
- [Single and collection clients](../02_concepts/02_single_collection_clients.mdx) - resource clients and collection clients
96+
- [Error handling](../02_concepts/04_error_handling.mdx) - automatic data extraction and error debugging
97+
- [Retries](../02_concepts/05_retries.mdx) - automatic retries with exponential backoff
98+
- [Pagination](../02_concepts/08_pagination.mdx) - iterating through large result sets
99+
100+
### Guides
101+
102+
For practical examples of common tasks, see the Guides section:
103+
104+
- [Pass input to an Actor](../03_guides/01_passing_input_to_actor.mdx)
105+
- [Retrieve Actor data](../03_guides/03_retrieve_actor_data.mdx)
106+
- [Integrate with data libraries](../03_guides/04_integration_with_data_libraries.mdx)

0 commit comments

Comments
 (0)