Skip to content

Commit d52bc8d

Browse files
vdusekclaude
andauthored
docs: Add versioned docs for v0.6 (#725)
- Add versioned docs for Client v0.6 docs (last zero-based version) - Fix `SUCEEDED` → `SUCCEEDED` typo in v0.6 API typedoc - Add `**/changelog.md` exclusion to `typos.toml` - Remove inner `.gitignore` files from versioned docs dirs, use top-level `.gitignore` instead --------- Co-authored-by: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
1 parent 6ae308d commit d52bc8d

File tree

15 files changed

+23721
-4
lines changed

15 files changed

+23721
-4
lines changed

.gitignore

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -63,6 +63,7 @@ Session.vim
6363

6464
# Docs
6565
docs/changelog.md
66+
website/versioned_docs/*/changelog.md
6667

6768
# Website build artifacts, node dependencies
6869
website/build

typos.toml

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -13,7 +13,8 @@ extend-exclude = [
1313
"*.lock",
1414
"*.min.js",
1515
"*.min.css",
16-
"CHANGELOG.md",
16+
"**/CHANGELOG.md",
17+
"**/changelog.md",
1718
]
1819

1920
[default.extend-words]
Lines changed: 41 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,41 @@
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 and convenience functions."
7+
---
8+
9+
The [Apify client for Python](https://github.com/apify/apify-client-python) (`apify_client`) is the official library to access the [Apify REST API](https://docs.apify.com/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.
10+
11+
## Prerequisites
12+
13+
`apify-client` requires Python 3.7 or higher. Python is available for download on the [official website](https://www.python.org/downloads/). Check your current Python version by running:
14+
15+
```bash
16+
python --version
17+
```
18+
19+
## Installation
20+
21+
The Apify client is available as the [`apify-client`](https://pypi.org/project/apify-client/) package on PyPI.
22+
23+
```bash
24+
pip install apify-client
25+
```
26+
27+
## Quick example
28+
29+
```python
30+
from apify_client import ApifyClient
31+
32+
apify_client = ApifyClient('MY-APIFY-TOKEN')
33+
34+
# Start an actor and wait for it to finish
35+
actor_call = apify_client.actor('john-doe/my-cool-actor').call()
36+
37+
# Fetch results from the actor's default dataset
38+
dataset_items = apify_client.dataset(actor_call['defaultDatasetId']).list_items().items
39+
```
40+
41+
> 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) for more details.
Lines changed: 51 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,51 @@
1+
---
2+
id: quick-start
3+
title: Quick start
4+
sidebar_label: Quick start
5+
description: "Get started with the Apify client for Python."
6+
---
7+
8+
## Installation
9+
10+
```bash
11+
pip install apify-client
12+
```
13+
14+
## Authentication
15+
16+
To use the Apify API, you need an API token. You can find your token in the [Integrations section](https://console.apify.com/account/integrations) of Apify Console.
17+
18+
```python
19+
from apify_client import ApifyClient
20+
21+
apify_client = ApifyClient('MY-APIFY-TOKEN')
22+
```
23+
24+
## Running an Actor
25+
26+
The simplest way to run an Actor is to use the `call` method, which starts the Actor and waits for it to finish.
27+
28+
```python
29+
from apify_client import ApifyClient
30+
31+
apify_client = ApifyClient('MY-APIFY-TOKEN')
32+
33+
# Start an actor and wait for it to finish
34+
actor_call = apify_client.actor('john-doe/my-cool-actor').call()
35+
36+
# Fetch results from the actor's default dataset
37+
dataset_items = apify_client.dataset(actor_call['defaultDatasetId']).list_items().items
38+
```
39+
40+
## Working with datasets
41+
42+
```python
43+
# Get (or create, if it doesn't exist) a dataset with the name of my-dataset
44+
my_dataset = apify_client.datasets().get_or_create(name='my-dataset')
45+
46+
# Append items to the end of the dataset
47+
apify_client.dataset(my_dataset['id']).push_items([{'foo': 1}, {'bar': 2}])
48+
49+
# List items in the dataset
50+
items = apify_client.dataset(my_dataset['id']).list_items().items
51+
```
Lines changed: 46 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
---
2+
title: Single and collection clients
3+
---
4+
5+
The `ApifyClient` interface follows a generic pattern that is applicable to all of its components. By calling individual methods of `ApifyClient`, specific clients which target individual API resources are created. There are two types of those clients. A client for management of a single resource and a client for a collection of resources.
6+
7+
### Collection clients
8+
9+
```python
10+
from apify_client import ApifyClient
11+
apify_client = ApifyClient('MY-APIFY-TOKEN')
12+
13+
# Collection clients do not require a parameter
14+
actor_collection_client = apify_client.actors()
15+
# Create an actor with the name: my-actor
16+
my_actor = actor_collection_client.create(name='my-actor')
17+
# List all of your actors
18+
actor_list = actor_collection_client.list().items
19+
```
20+
21+
```python
22+
# Collection clients do not require a parameter
23+
dataset_collection_client = apify_client.datasets()
24+
# Get (or create, if it doesn't exist) a dataset with the name of my-dataset
25+
my_dataset = dataset_collection_client.get_or_create(name='my-dataset')
26+
```
27+
28+
### Resource clients
29+
30+
```python
31+
# Resource clients accept an ID of the resource
32+
actor_client = apify_client.actor('john-doe/my-actor')
33+
# Fetch the john-doe/my-actor object from the API
34+
my_actor = actor_client.get()
35+
# Start the run of john-doe/my-actor and return the Run object
36+
my_actor_run = actor_client.start()
37+
```
38+
39+
```python
40+
# Resource clients accept an ID of the resource
41+
dataset_client = apify_client.dataset('john-doe/my-dataset')
42+
# Append items to the end of john-doe/my-dataset
43+
dataset_client.push_items([{'foo': 1}, {'bar': 2}])
44+
```
45+
46+
> The ID of the resource can be either the `id` of the said resource, or a combination of your `username/resource-name`.
Lines changed: 21 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,21 @@
1+
---
2+
title: Nested clients
3+
---
4+
5+
Sometimes clients return other clients. That's to simplify working with nested collections, such as runs of a given actor.
6+
7+
```python
8+
from apify_client import ApifyClient
9+
apify_client = ApifyClient('MY-APIFY-TOKEN')
10+
11+
actor_client = apify_client.actor('john-doe/my-actor')
12+
runs_client = actor_client.runs()
13+
# List the last 10 runs of the john-doe/hello-world actor
14+
actor_runs = runs_client.list(limit=10, desc=True).items
15+
16+
# Select the last run of the john-doe/hello-world actor that finished
17+
# with a SUCCEEDED status
18+
last_succeeded_run_client = actor_client.last_run(status='SUCCEEDED')
19+
# Fetch items from the run's dataset
20+
dataset_items = last_succeeded_run_client.dataset().list_items().items
21+
```
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Error handling
3+
---
4+
5+
Based on the endpoint, the client automatically extracts the relevant data and returns it in the expected format. Date strings are automatically converted to `datetime.datetime` objects.
6+
7+
For exceptions, we throw an `ApifyApiError`, which wraps the plain JSON errors returned by API and enriches them with other context for easier debugging.
8+
9+
```python
10+
from apify_client import ApifyClient
11+
12+
apify_client = ApifyClient('MY-APIFY-TOKEN')
13+
14+
try:
15+
actor = apify_client.actor('non-existent-actor').get()
16+
except Exception as e:
17+
print(f'Error: {e}')
18+
```
Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,15 @@
1+
---
2+
title: Retries with exponential backoff
3+
---
4+
5+
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.
6+
7+
```python
8+
from apify_client import ApifyClient
9+
10+
apify_client = ApifyClient(
11+
'MY-APIFY-TOKEN',
12+
max_retries=8,
13+
min_delay_between_retries_millis=500,
14+
)
15+
```
Lines changed: 18 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,18 @@
1+
---
2+
title: Pagination
3+
---
4+
5+
Most methods named `list` or `list_something` return a `ListPage` object, containing properties `items`, `total`, `offset`, `count` and `limit`. There are some exceptions though, like `list_keys` or `list_head` which paginate differently. The results you're looking for are always stored under `items` and you can use the `limit` property to get only a subset of results. Other properties can be available depending on the method.
6+
7+
```python
8+
from apify_client import ApifyClient
9+
10+
apify_client = ApifyClient('MY-APIFY-TOKEN')
11+
12+
# List first 10 actors
13+
actors = apify_client.actors().list(limit=10)
14+
print(f'Total actors: {actors.total}')
15+
print(f'Returned: {actors.count}')
16+
for actor in actors.items:
17+
print(actor['name'])
18+
```
Lines changed: 10 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,10 @@
1+
[
2+
{
3+
"entryPoints": { "index": { "label": "Index", "path": "src/apify_client" } },
4+
"packageRoot": "..",
5+
"packagePath": ".",
6+
"packageSlug": ".",
7+
"packageName": "apify-client",
8+
"packageVersion": "0.6.0"
9+
}
10+
]

0 commit comments

Comments
 (0)