docs: Move code samples to files and other updates

Makefile

@@ -2,8 +2,6 @@
         integration-tests format check-async-docstrings check-code fix-async-docstrings \
         build-api-reference build-docs run-docs
 
-DIRS_WITH_CODE = src tests scripts
-
 # This is default for local testing, but GitHub workflows override it to a higher value in CI
 INTEGRATION_TESTS_CONCURRENCY = 1
 
@@ -23,11 +21,11 @@ publish-to-pypi:
 	poetry publish --no-interaction -vv
 
 lint:
-	poetry run ruff format --check $(DIRS_WITH_CODE)
-	poetry run ruff check $(DIRS_WITH_CODE)
+	poetry run ruff format --check
+	poetry run ruff check
 
 type-check:
-	poetry run mypy $(DIRS_WITH_CODE)
+	poetry run mypy
 
 unit-tests:
 	poetry run pytest --numprocesses=auto --verbose --cov=src/apify_client tests/unit
@@ -39,8 +37,8 @@ integration-tests:
 	poetry run pytest --numprocesses=$(INTEGRATION_TESTS_CONCURRENCY) tests/integration
 
 format:
-	poetry run ruff check --fix $(DIRS_WITH_CODE)
-	poetry run ruff format $(DIRS_WITH_CODE)
+	poetry run ruff check --fix
+	poetry run ruff format
 
 check-async-docstrings:
 	poetry run python scripts/check_async_docstrings.py

docs/01_overview/01_introduction.mdx

@@ -0,0 +1,26 @@
+---
+id: introduction
+title: Introduction
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+import UsageAsyncExample from '!!raw-loader!./code/01_usage_async.py';
+import UsageSyncExample from '!!raw-loader!./code/01_usage_sync.py';
+
+The [Apify client for Python](https://github.com/apify/apify-client-python) 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. All requests and responses (including errors) are encoded in JSON format with UTF-8 encoding. The client provides both synchronous and asynchronous interfaces.
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {UsageAsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {UsageSyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>

docs/01_overview/02_setting_up.mdx

@@ -0,0 +1,71 @@
+---
+id: setting-up
+title: Setting up
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+import AsyncExample from '!!raw-loader!./code/02_auth_async.py';
+import SyncExample from '!!raw-loader!./code/02_auth_sync.py';
+
+This guide will help you get started with [Apify client for Python](https://github.com/apify/apify-client-python) by setting it up on your computer. Follow the steps below to ensure a smooth installation process.
+
+## Prerequisites
+
+Before installing `apify-client` itself, make sure that your system meets the following requirements:
+
+- **Python 3.9 or higher**: `apify-client` requires Python 3.9 or a newer version. You can download Python from the [official website](https://www.python.org/downloads/).
+- **Python package manager**: While this guide uses Pip (the most common package manager), you can also use any package manager you want. You can download Pip from the [official website](https://pip.pypa.io/en/stable/installation/).
+
+### Verifying prerequisites
+
+To check if Python and the Pip package manager are installed, run the following commands:
+
+```sh
+python --version
+```
+
+```sh
+pip --version
+```
+
+If these commands return the respective versions, you're ready to continue.
+
+## Installation
+
+Apify client for Python is available as the [`apify-client`](https://pypi.org/project/crawlee/) package on PyPI. To install it, run:
+
+```sh
+pip install apify-client
+```
+
+After installation, verify that `apify-client` is installed correctly by checking its version:
+
+```sh
+python -c 'import apify_client; print(apify_client.__version__)'
+```
+
+## Authentication and initialization
+
+To use the client, you need an [API token](https://docs.apify.com/platform/integrations/api#api-token). You can find your token under [Integrations](https://console.apify.com/account/integrations) tab in Apify Console. Copy the token and initialize the client by providing the token (`MY-APIFY-TOKEN`) as a parameter to the `ApifyClient` constructor.
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {AsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {SyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>
+
+:::warning Secure access
+
+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.
+
+:::

docs/01_overview/03_getting_started.mdx

@@ -0,0 +1,74 @@
+---
+id: getting-started
+title: Getting started
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+import UsageAsyncExample from '!!raw-loader!./code/01_usage_async.py';
+import UsageSyncExample from '!!raw-loader!./code/01_usage_sync.py';
+import InputAsyncExample from '!!raw-loader!./code/03_input_async.py';
+import InputSyncExample from '!!raw-loader!./code/03_input_sync.py';
+import DatasetAsyncExample from '!!raw-loader!./code/03_dataset_async.py';
+import DatasetSyncExample from '!!raw-loader!./code/03_dataset_sync.py';
+
+This guide will walk you through how to use the [Apify Client for Python](https://github.com/apify/apify-client-python) to run [Actors](https://apify.com/actors) on the [Apify platform](https://docs.apify.com/platform), provide input to them, and retrieve results from their datasets. You'll learn the basics of running serverless programs (we're calling them Actors) and managing their output efficiently.
+
+## Running your first Actor
+
+To start an Actor, you need its ID (e.g., `john-doe/my-cool-actor`) and an API token. The Actor's ID is a combination of the username and the Actor owner's username. Use the [`ActorClient`](/reference/class/ActorClient) to run the Actor and wait for it to complete. You can run both your own Actors and [Actors from Apify store](https://docs.apify.com/platform/actors/running/actors-in-store).
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {UsageAsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {UsageSyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>
+
+## Providing input to Actor
+
+Actors often require input, such as URLs to scrape, search terms, or other configuration data. You can pass input as a JSON object when starting the Actor using the [`ActorClient.call`](/reference/class/ActorClient#call) method. Actors respect the input schema defined in the Actor's [input schema](https://docs.apify.com/platform/actors/development/actor-definition/input-schema).
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {InputAsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {InputSyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>
+
+## Getting results from the dataset
+
+To get the results from the dataset, you can use the [`DatasetClient`](/reference/class/DatasetClient) ([`ApifyClient.dataset`](/reference/class/ApifyClient#dataset) ) and [`DatasetClient.list_items`](/reference/class/DatasetClient#list_items) method. You need to pass the dataset ID to define which dataset you want to access. You can get the dataset ID from the Actor's run dictionary (represented by `defaultDatasetId`).
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {InputAsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {InputSyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>
+
+:::note Dataset access
+
+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).
+
+:::

docs/01_overview/code/01_usage_async.py

@@ -0,0 +1,21 @@
+from apify_client import ApifyClientAsync
+
+# You can find your API token at https://console.apify.com/settings/integrations.
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+async def main() -> None:
+    apify_client = ApifyClientAsync(TOKEN)
+
+    # Start an Actor and wait for it to finish.
+    actor_client = apify_client.actor('john-doe/my-cool-actor')
+    call_result = await actor_client.call()
+
+    if call_result is None:
+        print('Actor run failed.')
+        return
+
+    # Fetch results from the Actor run's default dataset.
+    dataset_client = apify_client.dataset(call_result['defaultDatasetId'])
+    list_items_result = await dataset_client.list_items()
+    print(f'Dataset: {list_items_result}')

docs/01_overview/code/01_usage_sync.py

@@ -0,0 +1,21 @@
+from apify_client import ApifyClient
+
+# You can find your API token at https://console.apify.com/settings/integrations.
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+def main() -> None:
+    apify_client = ApifyClient(TOKEN)
+
+    # Start an Actor and wait for it to finish.
+    actor_client = apify_client.actor('john-doe/my-cool-actor')
+    call_result = actor_client.call()
+
+    if call_result is None:
+        print('Actor run failed.')
+        return
+
+    # Fetch results from the Actor run's default dataset.
+    dataset_client = apify_client.dataset(call_result['defaultDatasetId'])
+    list_items_result = dataset_client.list_items()
+    print(f'Dataset: {list_items_result}')

docs/01_overview/code/02_auth_async.py

@@ -0,0 +1,8 @@
+from apify_client import ApifyClientAsync
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+async def main() -> None:
+    # Client initialization with the API token.
+    apify_client = ApifyClientAsync(TOKEN)

docs/01_overview/code/02_auth_sync.py

@@ -0,0 +1,8 @@
+from apify_client import ApifyClient
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+def main() -> None:
+    # Client initialization with the API token.
+    apify_client = ApifyClient(TOKEN)

docs/01_overview/code/03_dataset_async.py

@@ -0,0 +1,11 @@
+from apify_client import ApifyClientAsync
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+async def main() -> None:
+    apify_client = ApifyClientAsync(TOKEN)
+    dataset_client = apify_client.dataset('dataset-id')
+
+    # Lists items from the Actor's dataset.
+    dataset_items = (await dataset_client.list_items()).items

docs/01_overview/code/03_dataset_sync.py

@@ -0,0 +1,11 @@
+from apify_client import ApifyClient
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+def main() -> None:
+    apify_client = ApifyClient(TOKEN)
+    dataset_client = apify_client.dataset('dataset-id')
+
+    # Lists items from the Actor's dataset.
+    dataset_items = dataset_client.list_items().items

docs/01_overview/code/03_input_async.py

@@ -0,0 +1,16 @@
+from apify_client import ApifyClientAsync
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+async def main() -> None:
+    apify_client = ApifyClientAsync(TOKEN)
+    actor_client = apify_client.actor('username/actor-name')
+
+    # Define the input for the Actor.
+    run_input = {
+        'some': 'input',
+    }
+
+    # Start an Actor and waits for it to finish.
+    call_result = await actor_client.call(run_input=run_input)

docs/01_overview/code/03_input_sync.py

@@ -0,0 +1,16 @@
+from apify_client import ApifyClient
+
+TOKEN = 'MY-APIFY-TOKEN'
+
+
+def main() -> None:
+    apify_client = ApifyClient(TOKEN)
+    actor_client = apify_client.actor('username/actor-name')
+
+    # Define the input for the Actor.
+    run_input = {
+        'some': 'input',
+    }
+
+    # Start an Actor and waits for it to finish.
+    call_result = actor_client.call(run_input=run_input)

docs/02_concepts/01_async_support.mdx

@@ -0,0 +1,18 @@
+---
+id: asyncio-support
+title: Asyncio support
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+import AsyncSupportExample from '!!raw-loader!./code/01_async_support.py';
+
+The package provides an asynchronous version of the client, [`ApifyClientAsync`](/reference/class/ApifyClientAsync), which allows you to interact with the Apify API using Python's standard async/await syntax. This enables you to perform non-blocking operations, see the Python [asyncio documentation](https://docs.python.org/3/library/asyncio-task.html) for more information.
+
+The following example demonstrates how to run an Actor asynchronously and stream its logs while it is running:
+
+<CodeBlock className="language-python">
+    {AsyncSupportExample}
+</CodeBlock>

docs/02_concepts/02_single_collection_clients.mdx

@@ -0,0 +1,48 @@
+---
+id: single-and-collection-clients
+title: Single and collection clients
+---
+
+import Tabs from '@theme/Tabs';
+import TabItem from '@theme/TabItem';
+import CodeBlock from '@theme/CodeBlock';
+
+import CollectionAsyncExample from '!!raw-loader!./code/02_collection_async.py';
+import CollectionSyncExample from '!!raw-loader!./code/02_collection_sync.py';
+import SingleAsyncExample from '!!raw-loader!./code/02_single_async.py';
+import SingleSyncExample from '!!raw-loader!./code/02_single_sync.py';
+
+The Apify client interface is designed to be consistent and intuitive across all of its components. When you call specific methods on the main client, you create specialized clients to manage individual API resources. There are two main types of clients:
+
+- [`ActorClient`](/reference/class/ActorClient) - Manages a single resource.
+- [`ActorCollectionClient`](/reference/class/ActorCollectionClient) - Manages a collection of resources.
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {CollectionAsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {CollectionSyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>
+
+The resource ID can be the resource's `id` or a combination of `username/resource-name`.
+
+<Tabs>
+    <TabItem value="AsyncExample" label="Async client" default>
+        <CodeBlock className="language-python">
+            {SingleAsyncExample}
+        </CodeBlock>
+    </TabItem>
+    <TabItem value="SyncExample" label="Sync client">
+        <CodeBlock className="language-python">
+            {SingleSyncExample}
+        </CodeBlock>
+    </TabItem>
+</Tabs>
+
+By utilizing the appropriate collection or resource client, you can simplify how you interact with the Apify API.