diff --git a/docs/01_overview/code/01_introduction.py b/docs/01_introduction/code/01_introduction.py similarity index 100% rename from docs/01_overview/code/01_introduction.py rename to docs/01_introduction/code/01_introduction.py diff --git a/docs/01_overview/code/actor_structure/__init__.py b/docs/01_introduction/code/actor_structure/__init__.py similarity index 100% rename from docs/01_overview/code/actor_structure/__init__.py rename to docs/01_introduction/code/actor_structure/__init__.py diff --git a/docs/01_overview/code/actor_structure/__main__.py b/docs/01_introduction/code/actor_structure/__main__.py similarity index 100% rename from docs/01_overview/code/actor_structure/__main__.py rename to docs/01_introduction/code/actor_structure/__main__.py diff --git a/docs/01_overview/code/actor_structure/main.py b/docs/01_introduction/code/actor_structure/main.py similarity index 100% rename from docs/01_overview/code/actor_structure/main.py rename to docs/01_introduction/code/actor_structure/main.py diff --git a/docs/01_overview/code/actor_structure/py.typed b/docs/01_introduction/code/actor_structure/py.typed similarity index 100% rename from docs/01_overview/code/actor_structure/py.typed rename to docs/01_introduction/code/actor_structure/py.typed diff --git a/docs/01_overview/images/apify-create.gif b/docs/01_introduction/images/apify-create.gif similarity index 100% rename from docs/01_overview/images/apify-create.gif rename to docs/01_introduction/images/apify-create.gif diff --git a/docs/01_introduction/index.mdx b/docs/01_introduction/index.mdx new file mode 100644 index 00000000..2ed6344b --- /dev/null +++ b/docs/01_introduction/index.mdx @@ -0,0 +1,45 @@ +--- +id: overview +title: Introduction +sidebar_label: Introduction +description: 'The official library for creating Apify Actors in Python, providing tools for web scraping, automation, and data storage integration.' +--- + +The Apify SDK for Python is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python. + +It provides tools and classes for web scraping and automation, allowing you to manage Actor lifecycles, handle data storage, work with proxies, and integrate with popular Python libraries. + +## Example + +Here's a simple example of an Actor that scrapes a web page and stores the result: + +```py +from apify import Actor +from bs4 import BeautifulSoup +import requests + +async def main(): + async with Actor: + input = await Actor.get_input() + response = requests.get(input['url']) + soup = BeautifulSoup(response.content, 'html.parser') + await Actor.push_data({ 'url': input['url'], 'title': soup.title.string }) +``` + +## Features + +The Apify SDK for Python provides: + +- **Actor lifecycle management** - Handle initialization, teardown, and graceful shutdowns +- **Storage management** - Work with Datasets, Key-Value Stores, and Request Queues +- **Event handling** - Respond to Actor events like migration, abort, and system info +- **Proxy management** - Rotate and manage proxies for web scraping +- **Platform integration** - Interact with other Actors, webhooks, and the Apify API +- **Framework compatibility** - Integrate with BeautifulSoup, Playwright, Selenium, Scrapy, and Crawlee + +## Next steps + +- **[Installation](./installation)** - Install the SDK and set up your development environment +- **[Quick start](./quick-start)** - Create and run your first Actor +- **[Concepts](../concepts/actor-lifecycle)** - Learn about core SDK concepts +- **[Guides](../guides/beautiful-soup)** - See how to integrate with popular libraries diff --git a/docs/01_introduction/installation.mdx b/docs/01_introduction/installation.mdx new file mode 100644 index 00000000..e8d6c765 --- /dev/null +++ b/docs/01_introduction/installation.mdx @@ -0,0 +1,51 @@ +--- +title: Installation +sidebar_label: Installation +description: 'Learn how to install the Apify SDK for Python using pip and manage dependencies for your Actor projects.' +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import CodeBlock from '@theme/CodeBlock'; + +## Requirements + +The Apify SDK requires Python version 3.10 or above to run Python Actors locally. + +## Installation + +The Apify Python SDK is available as [`apify`](https://pypi.org/project/apify/) package on PyPi. To install it, run: + +```bash +pip install apify +``` + +When you create an Actor using the Apify CLI, the Apify SDK for Python is installed for you automatically. + +If you are not developing Apify Actors and you just need to access the Apify API from Python, +consider using the [Apify API client for Python](/api/client/python) directly. + +## Adding dependencies + +First, add the dependencies in the [`requirements.txt`](https://pip.pypa.io/en/stable/reference/requirements-file-format/) file in the Actor source folder. + +Then activate the virtual environment in `.venv`: + + + + { +`source .venv/bin/activate` + } + + + { +`.venv\\Scripts\\activate` + } + + + +Finally, install the dependencies: + +```bash +python -m pip install -r requirements.txt +``` diff --git a/docs/01_overview/index.mdx b/docs/01_introduction/quick-start.mdx similarity index 68% rename from docs/01_overview/index.mdx rename to docs/01_introduction/quick-start.mdx index f9ab4741..1ebfca8d 100644 --- a/docs/01_overview/index.mdx +++ b/docs/01_introduction/quick-start.mdx @@ -1,47 +1,18 @@ --- -title: Overview -sidebar_label: Overview +title: Quick start +sidebar_label: Quick start +description: 'Get started with the Apify SDK for Python by creating your first Actor and learning the basics.' +--- + +Learn how to create and run Actors using the Apify SDK for Python. + --- import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import CodeBlock from '@theme/CodeBlock'; -The Apify SDK for Python is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python. - -```py -from apify import Actor -from bs4 import BeautifulSoup -import requests - -async def main(): - async with Actor: - input = await Actor.get_input() - response = requests.get(input['url']) - soup = BeautifulSoup(response.content, 'html.parser') - await Actor.push_data({ 'url': input['url'], 'title': soup.title.string }) -``` - -## Requirements - -The Apify SDK requires Python version 3.10 or above to run Python Actors locally. - -## Installation - -The Apify Python SDK is available as [`apify`](https://pypi.org/project/apify/) package on PyPi. To install it, run: - -```bash -pip install apify -``` - -When you create an Actor using the Apify CLI, the Apify SDK for Python is installed for you automatically. - -If you are not developing Apify Actors and you just need to access the Apify API from Python, -consider using the [Apify API client for Python](/api/client/python) directly. - -## Quick start - -### Creating Actors +## Step 1: Creating Actors To create and run Actors in Apify Console, refer to the [Console documentation](/platform/actors/development/quick-start/web-ide). @@ -55,9 +26,9 @@ apify create my-first-actor --template python-start This will create a new folder called `my-first-actor`, download and extract the "Getting started with Python" Actor template there, create a virtual environment in `my-first-actor/.venv`, and install the Actor dependencies in it. -![actor create command run](../01_overview/images/apify-create.gif) +![actor create command run](./images/apify-create.gif) -#### Running the Actor +## Step 2: Running the Actor To run the Actor, you can use the [`apify run` command](/cli/docs/reference#apify-run): @@ -74,7 +45,7 @@ This command: The Actor input, for example, will be in `storage/key_value_stores/default/INPUT.json`. -## Actor structure +## Step 3: Understanding Actor structure All Python Actor templates follow the same structure. @@ -122,31 +93,6 @@ asyncio.run(main())` If you want to modify the Actor structure, you need to make sure that your Actor is executable as a module, via `python -m src`, as that is the command started by `apify run` in the Apify CLI. We recommend keeping the entrypoint for the Actor in the `src/__main__.py` file. -## Adding dependencies - -First, add the dependencies in the [`requirements.txt`](https://pip.pypa.io/en/stable/reference/requirements-file-format/) file in the Actor source folder. - -Then activate the virtual environment in `.venv`: - - - - { -`source .venv/bin/activate` - } - - - { -`.venv\\Scripts\\activate` - } - - - -Finally, install the dependencies: - -```bash -python -m pip install -r requirements.txt -``` - ## Next steps ### Guides diff --git a/docs/02_concepts/10_logging.mdx b/docs/02_concepts/09_logging.mdx similarity index 96% rename from docs/02_concepts/10_logging.mdx rename to docs/02_concepts/09_logging.mdx index 6bdb754b..c1bd26c6 100644 --- a/docs/02_concepts/10_logging.mdx +++ b/docs/02_concepts/09_logging.mdx @@ -5,10 +5,10 @@ title: Logging import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock'; -import LogConfigExample from '!!raw-loader!roa-loader!./code/10_log_config.py'; -import LoggerUsageExample from '!!raw-loader!roa-loader!./code/10_logger_usage.py'; -import RedirectLog from '!!raw-loader!roa-loader!./code/10_redirect_log.py'; -import RedirectLogExistingRun from '!!raw-loader!roa-loader!./code/10_redirect_log_existing_run.py'; +import LogConfigExample from '!!raw-loader!roa-loader!./code/09_log_config.py'; +import LoggerUsageExample from '!!raw-loader!roa-loader!./code/09_logger_usage.py'; +import RedirectLog from '!!raw-loader!roa-loader!./code/09_redirect_log.py'; +import RedirectLogExistingRun from '!!raw-loader!roa-loader!./code/09_redirect_log_existing_run.py'; The Apify SDK is logging useful information through the [`logging`](https://docs.python.org/3/library/logging.html) module from Python's standard library, into the logger with the name `apify`. diff --git a/docs/02_concepts/11_configuration.mdx b/docs/02_concepts/10_configuration.mdx similarity index 96% rename from docs/02_concepts/11_configuration.mdx rename to docs/02_concepts/10_configuration.mdx index bcc4ea00..4d1e83e8 100644 --- a/docs/02_concepts/11_configuration.mdx +++ b/docs/02_concepts/10_configuration.mdx @@ -5,7 +5,7 @@ title: Actor configuration import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock'; -import ConfigExample from '!!raw-loader!roa-loader!./code/11_config.py'; +import ConfigExample from '!!raw-loader!roa-loader!./code/10_config.py'; The [`Actor`](../../reference/class/Actor) class gets configured using the [`Configuration`](../../reference/class/Configuration) class, which initializes itself based on the provided environment variables. diff --git a/docs/02_concepts/12_pay_per_event.mdx b/docs/02_concepts/11_pay_per_event.mdx similarity index 97% rename from docs/02_concepts/12_pay_per_event.mdx rename to docs/02_concepts/11_pay_per_event.mdx index 503d3158..cfde957d 100644 --- a/docs/02_concepts/12_pay_per_event.mdx +++ b/docs/02_concepts/11_pay_per_event.mdx @@ -4,8 +4,8 @@ title: Pay-per-event monetization description: Monetize your Actors using the pay-per-event pricing model --- -import ActorChargeSource from '!!raw-loader!roa-loader!./code/12_actor_charge.py'; -import ConditionalActorChargeSource from '!!raw-loader!roa-loader!./code/12_conditional_actor_charge.py'; +import ActorChargeSource from '!!raw-loader!roa-loader!./code/11_actor_charge.py'; +import ConditionalActorChargeSource from '!!raw-loader!roa-loader!./code/11_conditional_actor_charge.py'; import ApiLink from '@site/src/components/ApiLink'; import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock'; diff --git a/docs/02_concepts/code/10_log_config.py b/docs/02_concepts/code/09_log_config.py similarity index 100% rename from docs/02_concepts/code/10_log_config.py rename to docs/02_concepts/code/09_log_config.py diff --git a/docs/02_concepts/code/10_logger_usage.py b/docs/02_concepts/code/09_logger_usage.py similarity index 100% rename from docs/02_concepts/code/10_logger_usage.py rename to docs/02_concepts/code/09_logger_usage.py diff --git a/docs/02_concepts/code/10_redirect_log.py b/docs/02_concepts/code/09_redirect_log.py similarity index 100% rename from docs/02_concepts/code/10_redirect_log.py rename to docs/02_concepts/code/09_redirect_log.py diff --git a/docs/02_concepts/code/10_redirect_log_existing_run.py b/docs/02_concepts/code/09_redirect_log_existing_run.py similarity index 100% rename from docs/02_concepts/code/10_redirect_log_existing_run.py rename to docs/02_concepts/code/09_redirect_log_existing_run.py diff --git a/docs/02_concepts/code/11_config.py b/docs/02_concepts/code/10_config.py similarity index 100% rename from docs/02_concepts/code/11_config.py rename to docs/02_concepts/code/10_config.py diff --git a/docs/02_concepts/code/12_actor_charge.py b/docs/02_concepts/code/11_actor_charge.py similarity index 100% rename from docs/02_concepts/code/12_actor_charge.py rename to docs/02_concepts/code/11_actor_charge.py diff --git a/docs/02_concepts/code/12_conditional_actor_charge.py b/docs/02_concepts/code/11_conditional_actor_charge.py similarity index 100% rename from docs/02_concepts/code/12_conditional_actor_charge.py rename to docs/02_concepts/code/11_conditional_actor_charge.py diff --git a/docs/02_concepts/09_running_webserver.mdx b/docs/03_guides/07_running_webserver.mdx similarity index 95% rename from docs/02_concepts/09_running_webserver.mdx rename to docs/03_guides/07_running_webserver.mdx index 30a80722..d9deedc1 100644 --- a/docs/02_concepts/09_running_webserver.mdx +++ b/docs/03_guides/07_running_webserver.mdx @@ -5,7 +5,7 @@ title: Running webserver in your Actor import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock'; -import WebserverExample from '!!raw-loader!roa-loader!./code/09_webserver.py'; +import WebserverExample from '!!raw-loader!roa-loader!./code/07_webserver.py'; Each Actor run on the Apify platform is assigned a unique hard-to-guess URL (for example `https://8segt5i81sokzm.runs.apify.net`), which enables HTTP access to an optional web server running inside the Actor run's container. diff --git a/docs/02_concepts/code/09_webserver.py b/docs/03_guides/code/07_webserver.py similarity index 100% rename from docs/02_concepts/code/09_webserver.py rename to docs/03_guides/code/07_webserver.py diff --git a/website/sidebars.js b/website/sidebars.js index b5e55e1e..6338267d 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -1,8 +1,15 @@ module.exports = { sidebar: [ { - type: 'doc', - id: 'overview/index', + type: 'category', + label: 'Introduction', + collapsed: false, + items: [ + { + type: 'autogenerated', + dirName: '01_introduction', + }, + ], }, { type: 'category',