backport changes to v3

Author: vdusek

website/versioned_docs/version-3.4/01_introduction/index.mdx

@@ -9,7 +9,16 @@ import CodeBlock from '@theme/CodeBlock';
 
 import IntroductionExample from '!!raw-loader!./code/01_introduction.py';
 
-The Apify SDK for Python is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python. It provides useful features like Actor lifecycle management, local storage emulation, and Actor event handling.
+The Apify SDK for Python is the official library for creating [Apify Actors](https://docs.apify.com/platform/actors) in Python. It provides everything you need to build an Actor and run it both locally and on the [Apify platform](https://docs.apify.com/platform). With the SDK, you can:
+
+- Manage the Actor lifecycle: initialization, graceful shutdown, status messages, rebooting, and metamorphing.
+- Work with datasets, key-value stores, and request queues, with automatic local emulation when running outside the platform.
+- Read the Actor input, including automatic decryption of secret fields.
+- React to platform events (system info, migration, abort) and persist state across migrations and restarts.
+- Manage proxies, both Apify Proxy and your own, with session and tiered-proxy support.
+- Start, call, and abort Actors and tasks, create webhooks, and reach the full Apify API client.
+- Charge users with the pay-per-event pricing model.
+- Integrate with [Crawlee](../guides/crawlee) and [Scrapy](../guides/scrapy), with guides for [Playwright](../guides/playwright) and others.
 
 <CodeBlock className="language-python">
     {IntroductionExample}

website/versioned_docs/version-3.4/01_introduction/quick-start.mdx

@@ -21,7 +21,7 @@ To create and run Actors in Apify Console, refer to the [Console documentation](
 
 To create a new Apify Actor on your computer, you can use the [Apify CLI](/cli), and select one of the [Python Actor templates](https://apify.com/templates?category=python).
 
-For example, to create an Actor from the "[beta] Python SDK" template, you can use the [`apify create` command](/cli/docs/reference#apify-create-actorname).
+For example, to create an Actor from the "Getting started with Python" template, you can use the [`apify create` command](/cli/docs/reference#apify-create-actorname).
 
 ```bash
 apify create my-first-actor --template python-start
@@ -59,15 +59,15 @@ The Actor's runtime dependencies are specified in the `requirements.txt` file, w
 The Actor's source code is in the `src` folder. This folder contains two important files:
 
 - `main.py` - which contains the main function of the Actor
-- `__main__.py` - which is the entrypoint of the Actor package setting up the Actor [logger](../concepts/logging) and executing the Actor's main function via [`asyncio.run()`](https://docs.python.org/3/library/asyncio-runner.html#asyncio.run).
+- `__main__.py` - which is the entrypoint of the Actor package, executing the Actor's main function via [`asyncio.run()`](https://docs.python.org/3/library/asyncio-runner.html#asyncio.run).
 
 <Tabs>
     <TabItem value="main.py" label="main.py" default>
         <CodeBlock className="language-python">
             {MainExample}
         </CodeBlock>
     </TabItem>
-    <TabItem value="__main__.py" label="__main.py__">
+    <TabItem value="__main__.py" label="__main__.py">
         <CodeBlock className="language-python">
             {UnderscoreMainExample}
         </CodeBlock>
@@ -79,13 +79,15 @@ We recommend keeping the entrypoint for the Actor in the `src/__main__.py` file.
 
 ## Next steps
 
+Now that you can create and run an Actor locally, explore the rest of the SDK's features and its framework integrations.
+
 ### Concepts
 
 To learn more about the features of the Apify SDK and how to use them, check out the Concepts section in the sidebar:
 
 - [Actor lifecycle](../concepts/actor-lifecycle)
 - [Actor input](../concepts/actor-input)
-- [Working with storages](../concepts/storages)
+- [Storages](../concepts/storages)
 - [Actor events & state persistence](../concepts/actor-events)
 - [Proxy management](../concepts/proxy-management)
 - [Interacting with other Actors](../concepts/interacting-with-other-actors)

website/versioned_docs/version-3.4/02_concepts/01_actor_lifecycle.mdx

@@ -106,4 +106,4 @@ Update the status only when the user's understanding of progress changes - avoid
 
 ## Conclusion
 
-This page has presented the full Actor lifecycle: initialization, execution, error handling, rebooting, shutdown and status messages. You've seen how the SDK supports both context-based and manual control patterns. For deeper dives, explore the <ApiLink to="">reference docs</ApiLink>, [guides](https://docs.apify.com/sdk/python/docs/guides/beautifulsoup-httpx), and [platform documentation](https://docs.apify.com/platform).
+This page has presented the full Actor lifecycle: initialization, execution, error handling, rebooting, shutdown and status messages. You've seen how the SDK supports both context-based and manual control patterns. For deeper dives, explore the <ApiLink to="class/Actor">`Actor`</ApiLink> API reference, [guides](../guides/beautifulsoup-httpx), and [platform documentation](https://docs.apify.com/platform).

website/versioned_docs/version-3.4/02_concepts/02_actor_input.mdx

@@ -12,7 +12,7 @@ import ApiLink from '@theme/ApiLink';
 
 The Actor gets its [input](https://docs.apify.com/platform/actors/running/input) from the input record in its default [key-value store](https://docs.apify.com/platform/storage/key-value-store).
 
-To access it, instead of reading the record manually, you can use the <ApiLink to="class/Actor#get_input">`Actor.get_input`</ApiLink> convenience method. It will get the input record key from the Actor configuration, read the record from the default key-value store,and decrypt any [secret input fields](https://docs.apify.com/platform/actors/development/secret-input).
+To access it, instead of reading the record manually, you can use the <ApiLink to="class/Actor#get_input">`Actor.get_input`</ApiLink> convenience method. It gets the input record key from the Actor configuration, reads the record from the default key-value store, and decrypts any [secret input fields](https://docs.apify.com/platform/actors/development/secret-input).
 
 For example, if an Actor received a JSON input with two fields, `{ "firstNumber": 1, "secondNumber": 2 }`, this is how you might process it:
 
@@ -34,4 +34,8 @@ The Apify platform supports [secret input fields](https://docs.apify.com/platfor
 
 No special handling is needed in your code — when you call <ApiLink to="class/Actor#get_input">`Actor.get_input`</ApiLink>, encrypted fields are automatically decrypted using the Actor's private key, which is provided by the platform via environment variables. You receive the plaintext values directly.
 
+## Conclusion
+
+This page has shown how to read Actor input with <ApiLink to="class/Actor#get_input">`Actor.get_input`</ApiLink>, how to load URL sources with <ApiLink to="class/ApifyRequestList">`ApifyRequestList`</ApiLink>, and how secret input fields are decrypted automatically when you read them.
+
 For more details on Actor input and how to define input schemas, see the [Actor input](https://docs.apify.com/platform/actors/running/input) and [input schema](https://docs.apify.com/platform/actors/development/input-schema) documentation on the Apify platform.

website/versioned_docs/version-3.4/02_concepts/03_storages.mdx

@@ -1,6 +1,6 @@
 ---
 id: storages
-title: Working with storages
+title: Storages
 description: Use datasets, key-value stores, and request queues to persist Actor data.
 ---
 
@@ -45,11 +45,11 @@ Each dataset item, key-value store record, or request in a request queue is then
 
 When developing locally, opening any storage will by default use local storage. To change this behavior and to use remote storage you have to use `force_cloud=True` argument in <ApiLink to="class/Actor#open_dataset">`Actor.open_dataset`</ApiLink>, <ApiLink to="class/Actor#open_request_queue">`Actor.open_request_queue`</ApiLink> or <ApiLink to="class/Actor#open_key_value_store">`Actor.open_key_value_store`</ApiLink>. Proper use of this argument allows you to work with both local and remote storages.
 
-Calling another remote Actor and accessing its default storage is typical use-case for using `force-cloud=True` argument to open remote Actor's storages.
+Calling another remote Actor and accessing its default storage is a typical use-case for using `force_cloud=True` argument to open remote Actor's storages.
 
 ### Local storage persistence
 
-By default, the storage contents are persisted across multiple Actor runs. To clean up the Actor storages before the running the Actor, use the `--purge` flag of the [`apify run`](https://docs.apify.com/cli/docs/reference#apify-run) command of the Apify CLI.
+By default, the storage contents are persisted across multiple Actor runs. To clean up the Actor storages before running the Actor, use the `--purge` flag of the [`apify run`](https://docs.apify.com/cli/docs/reference#apify-run) command of the Apify CLI.
 
 ```bash
 apify run --purge
@@ -106,8 +106,8 @@ To get an iterator of the data, you can use the <ApiLink to="class/Dataset#itera
 ### Exporting items
 
 You can also export the dataset items into a key-value store, as either a CSV or a JSON record,
-using the <ApiLink to="class/Dataset#export_to_csv">`Dataset.export_to_csv`</ApiLink>
-or <ApiLink to="class/Dataset#export_to_json">`Dataset.export_to_json`</ApiLink> method.
+using the <ApiLink to="class/Dataset#export_to">`Dataset.export_to`</ApiLink> method with the
+`content_type` argument set to `'csv'` or `'json'`.
 
 <RunnableCodeBlock className="language-python" language="python">
     {DatasetExportsExample}
@@ -183,6 +183,10 @@ To check if all the requests in the queue are handled, you can use the <ApiLink
 
 ## Storage clients
 
-Behind the scenes, the SDK uses storage clients to communicate with the storage backend. The appropriate client is selected automatically based on the runtime environment — on the Apify platform, data is persisted via the Apify API, while local runs use the filesystem. For most use cases, you don't need to think about storage clients at all. If you want to learn more about how storage clients work, the available implementations, or how to configure them, see the [Crawlee storage clients guide](https://crawlee.dev/python/docs/guides/storage-clients). The Apify-specific clients are available in the `apify.storage_clients` module.
+Behind the scenes, the SDK uses storage clients to communicate with the storage backend. The appropriate client is selected automatically based on the runtime environment. On the Apify platform, data is persisted via the Apify API, while local runs use the filesystem. For most use cases, you don't need to think about storage clients at all. If you want to learn more about how storage clients work, the available implementations, or how to configure them, see the [Crawlee storage clients guide](https://crawlee.dev/python/docs/guides/storage-clients). The Apify-specific clients are available in the `apify.storage_clients` module.
+
+## Conclusion
+
+This page has covered the three storage types (datasets, key-value stores, and request queues): how they are emulated on the local filesystem, how to open named and unnamed storages, and how to read from and write to each through the `Actor` shortcuts and the storage classes.
 
 For comprehensive information about storage on the Apify platform, see the [storage documentation](https://docs.apify.com/platform/storage), including the pages on [datasets](https://docs.apify.com/platform/storage/dataset), [key-value stores](https://docs.apify.com/platform/storage/key-value-store), and [request queues](https://docs.apify.com/platform/storage/request-queue).

website/versioned_docs/version-3.4/02_concepts/04_actor_events.mdx

@@ -103,4 +103,8 @@ You can optionally specify a `key` (the key-value store key under which the stat
     {UseStateExample}
 </RunnableCodeBlock>
 
+## Conclusion
+
+This page has described the events emitted during a run (`SYSTEM_INFO`, `MIGRATING`, `ABORTING`, `PERSIST_STATE`, and `EXIT`): how to handle them with <ApiLink to="class/Actor#on">`Actor.on`</ApiLink>, and how to persist state automatically with <ApiLink to="class/Actor#use_state">`Actor.use_state`</ApiLink>.
+
 For more details on platform events and state persistence, see the [system events](https://docs.apify.com/platform/actors/development/programming-interface/system-events) and [state persistence](https://docs.apify.com/platform/actors/development/state-persistence) documentation on the Apify platform.

website/versioned_docs/version-3.4/02_concepts/05_proxy_management.mdx

@@ -22,7 +22,7 @@ The Apify SDK provides built-in proxy management through the <ApiLink to="class/
 
 If you want to use Apify Proxy locally, make sure that you run your Actors via the Apify CLI and that you are [logged in](https://docs.apify.com/cli/docs/installation#login-with-your-apify-account) with your Apify account in the CLI.
 
-### Using Apify proxy
+### Using Apify Proxy
 
 <RunnableCodeBlock className="language-python" language="python">
     {ApifyProxyExample}
@@ -38,7 +38,7 @@ If you want to use Apify Proxy locally, make sure that you run your Actors via t
 
 All your proxy needs are managed by the <ApiLink to="class/ProxyConfiguration">`ProxyConfiguration`</ApiLink> class. You create an instance using the <ApiLink to="class/Actor#create_proxy_configuration">`Actor.create_proxy_configuration()`</ApiLink> method. Then you generate proxy URLs using the <ApiLink to="class/ProxyConfiguration#new_url">`ProxyConfiguration.new_url()`</ApiLink> method.
 
-### Apify proxy vs. your own proxies
+### Apify Proxy vs. your own proxies
 
 The `ProxyConfiguration` class covers both Apify Proxy and custom proxy URLs, so that you can easily switch between proxy providers. However, some features of the class are available only to Apify Proxy users, mainly because Apify Proxy is what one would call a super-proxy. It's not a single proxy server, but an API endpoint that allows connection through millions of different IP addresses. So the class essentially has two modes: Apify Proxy or Your proxy.
 
@@ -54,7 +54,7 @@ When no `session_id` is provided, your custom proxy URLs are rotated round-robin
     {ProxyRotationExample}
 </RunnableCodeBlock>
 
-### Apify proxy configuration
+### Apify Proxy configuration
 
 With Apify Proxy, you can select specific proxy groups to use, or countries to connect from. For even finer control, you can also target a specific subdivision (e.g. a US state) using the `subdivision_code` parameter alongside `country_code`. This allows you to get better proxy performance after some initial research.
 
@@ -106,9 +106,11 @@ You can then use that input to create the proxy configuration:
 
 ## Using the generated proxy URLs
 
+`ProxyConfiguration` only generates proxy URLs. It doesn't make requests. To route requests through the proxy, pass a generated URL to the HTTP client your Actor uses.
+
 ### HTTPX
 
-To use the generated proxy URLs with the `httpx` library, use the [`proxies`](https://www.python-httpx.org/advanced/#http-proxying) argument:
+To use the generated proxy URLs with the `httpx` library, use the [`proxy`](https://www.python-httpx.org/advanced/proxies/) argument:
 
 <RunnableCodeBlock className="language-python" language="python">
     {ProxyHttpxExample}
@@ -120,4 +122,8 @@ Make sure you have the `httpx` library installed:
 pip install httpx
 ```
 
+## Conclusion
+
+This page has explained how to manage proxies with the <ApiLink to="class/ProxyConfiguration">`ProxyConfiguration`</ApiLink> class: using Apify Proxy or your own servers, keeping sessions sticky across requests, configuring tiered proxy rotation, and feeding proxy settings from Actor input.
+
 For full details on proxy configuration options, see the <ApiLink to="class/ProxyConfiguration">`ProxyConfiguration`</ApiLink> API reference and the [Apify Proxy documentation](https://docs.apify.com/proxy).

website/versioned_docs/version-3.4/02_concepts/06_interacting_with_other_actors.mdx

@@ -63,4 +63,8 @@ When you set `gracefully=True`, the platform sends `ABORTING` and `PERSIST_STATE
     {InteractingAbortExample}
 </RunnableCodeBlock>
 
+## Conclusion
+
+This page has shown how to interact with other Actors from your code: starting a run with <ApiLink to="class/Actor#start">`Actor.start`</ApiLink>, waiting for it to finish with <ApiLink to="class/Actor#call">`Actor.call`</ApiLink> or <ApiLink to="class/Actor#call_task">`Actor.call_task`</ApiLink>, transforming a run with <ApiLink to="class/Actor#metamorph">`Actor.metamorph`</ApiLink>, and stopping one with <ApiLink to="class/Actor#abort">`Actor.abort`</ApiLink>.
+
 For the full list of methods for interacting with other Actors, see the <ApiLink to="class/Actor">`Actor`</ApiLink> API reference. For more details on running Actors and Actor tasks on the platform, see the [Actors](https://docs.apify.com/platform/actors) and [Actor tasks](https://docs.apify.com/platform/actors/tasks) documentation.

website/versioned_docs/version-3.4/02_concepts/07_webhooks.mdx

@@ -32,4 +32,8 @@ To ensure that duplicate ad-hoc webhooks won't get created in a case of Actor re
     {WebhookPreventingExample}
 </RunnableCodeBlock>
 
+## Conclusion
+
+This page has shown how to create ad-hoc webhooks dynamically with <ApiLink to="class/Actor#add_webhook">`Actor.add_webhook`</ApiLink> and how to avoid creating duplicates across Actor restarts using the `idempotency_key` parameter.
+
 For more information about webhooks, including event types and payloads, see the [Apify webhooks documentation](https://docs.apify.com/platform/integrations/webhooks).