docs: backport runnable code example fixes to v3 versioned docs (#1004)

Backports the documentation fixes from #1002 into the v3 versioned docs
(`website/versioned_docs/version-3.4/`). The original PR only updated
the next (`docs/`) docs, so the released v3 guides were left out of
sync.

The changes were applied by extracting #1002's diff and re-pointing it
at the versioned tree. Every touched file is now byte-identical to its
`docs/` counterpart.

What it carries over:
- Lower the page cap from 50 to 10 across all crawling examples, so the
browser-based ones finish within the 180s runnable-demo timeout.
- Selenium: slim the runnable example to a plain crawler, and move the
proxy-auth extension into a separate, non-runnable snippet
(`code/04_selenium_proxy.py`).
- Browser Use: make it non-runnable (needs an LLM API key the shared
runner can't provide); same note added to the Scrapy and
Scrapling-browser examples.
- Pydantic: log a readable validation summary and fail cleanly via
`Actor.fail`.

Author: vdusek

docs/03_guides/code/07_scrapling_browser.py

@@ -11,12 +11,10 @@
 async def scrape_page(
     session: AsyncDynamicSession,
     url: str,
-    *,
-    proxy_url: str | None = None,
 ) -> tuple[dict[str, Any], list[str]]:
     """Fetch a page through the shared browser session and return data and links."""
     # `network_idle` waits until the page stops making network requests.
-    response = await session.fetch(url, proxy=proxy_url, network_idle=True)
+    response = await session.fetch(url, network_idle=True)
 
     data = {
         'url': url,
@@ -70,6 +68,11 @@ async def main() -> None:
 
         # Set up Apify Proxy and the request queue.
         proxy_configuration = await Actor.create_proxy_configuration()
+        # Scrapling's browser session takes a single proxy at construction time.
+        # Per-fetch proxy rotation would need a different session mode. Apify Proxy
+        # rotates the exit IP itself, so one session-level proxy URL still varies the
+        # IP across requests.
+        proxy_url = await proxy_configuration.new_url() if proxy_configuration else None
         request_queue = await Actor.open_request_queue()
 
         # Enqueue the start URLs (crawl depth defaults to 0).
@@ -82,8 +85,8 @@ async def main() -> None:
         max_requests = 10
         handled_requests = 0
 
-        # Open the browser once and reuse it for every page in the crawl.
-        async with AsyncDynamicSession(headless=True) as session:
+        # Open the browser once (via Apify Proxy) and reuse it for every page.
+        async with AsyncDynamicSession(headless=True, proxy=proxy_url) as session:
             while handled_requests < max_requests and (
                 request := await request_queue.fetch_next_request()
             ):
@@ -93,12 +96,7 @@ async def main() -> None:
                 Actor.log.info(f'Scraping {url} (depth={depth}) ...')
 
                 try:
-                    # Fresh proxy URL per request (None if no proxy).
-                    proxy_url = None
-                    if proxy_configuration:
-                        proxy_url = await proxy_configuration.new_url()
-
-                    data, links = await scrape_page(session, url, proxy_url=proxy_url)
+                    data, links = await scrape_page(session, url)
                     await Actor.push_data(data)
                     Actor.log.info(
                         f'Stored data from {url} '

website/versioned_docs/version-3.4/03_guides/04_selenium.mdx

@@ -4,9 +4,11 @@ title: Browser automation with Selenium
 description: Build an Apify Actor that scrapes dynamic web pages using Selenium WebDriver.
 ---
 
+import CodeBlock from '@theme/CodeBlock';
 import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
 
 import SeleniumExample from '!!raw-loader!roa-loader!./code/04_selenium.py';
+import SeleniumProxyExample from '!!raw-loader!./code/04_selenium_proxy.py';
 
 In this guide, you'll learn how to use [Selenium](https://www.selenium.dev/) for browser automation and web scraping in your Apify Actors.
 
@@ -42,9 +44,15 @@ It uses Selenium ChromeDriver to open the pages in an automated Chrome browser,
 
 ## Using Apify Proxy
 
-Running on the Apify platform gives your scraper access to [Apify Proxy](https://docs.apify.com/platform/proxy), which rotates IP addresses to avoid rate limiting and blocking. The example creates a proxy configuration with `Actor.create_proxy_configuration` and routes the browser through it for the whole run.
+Running on the Apify platform gives your scraper access to [Apify Proxy](https://docs.apify.com/platform/proxy), which rotates IP addresses to avoid rate limiting and blocking. The runnable example Actor skips the proxy to stay simple. This section extends it to route the browser through Apify Proxy. The snippet below isn't a complete, runnable Actor on its own. It shows only the proxy-specific parts you add to the example Actor.
 
-Chrome ignores the credentials passed in the `--proxy-server` flag. Because of that, configure an authenticated proxy such as Apify Proxy from inside a small extension. The `proxy_auth_extension` helper builds one at runtime: its service worker sets the proxy server and answers the browser's authentication challenge with the username and password. Note that the new headless mode (`--headless=new`) is required for Chrome to load the extension. To select specific proxy groups or a country, pass the relevant arguments to `Actor.create_proxy_configuration`. For details, see [Proxy management](../concepts/proxy-management).
+Chrome ignores the credentials passed in the `--proxy-server` flag. To use an authenticated proxy such as Apify Proxy, configure it from inside a small extension. The `proxy_auth_extension` helper builds one at runtime. Its service worker sets the proxy server and answers the browser's authentication challenge with the username and password. The proxy-aware `build_chrome_driver` below replaces the simple one from the example Actor and loads that extension. The new headless mode (`--headless=new`) is required for Chrome to load it.
+
+<CodeBlock className="language-python">
+    {SeleniumProxyExample}
+</CodeBlock>
+
+To wire the proxy into the example Actor, create the proxy configuration in `main` with `Actor.create_proxy_configuration`, get a URL with `await proxy_configuration.new_url()`, and pass it to `build_chrome_driver`. To select specific proxy groups or a country, pass the relevant arguments to `Actor.create_proxy_configuration`. For details, see [Proxy management](../concepts/proxy-management).
 
 ## Conclusion
 

website/versioned_docs/version-3.4/03_guides/06_scrapy.mdx

@@ -73,6 +73,7 @@ For further details, see the [Scrapy migration guide](https://docs.apify.com/cli
 
 The following example shows a Scrapy Actor that scrapes page titles and enqueues links found on each page. This example aligns with the structure provided in the Apify Actor templates.
 
+{/* Not runnable from the docs: a Scrapy Actor is a multi-file project, while the "Run on Apify" runner executes a single self-contained snippet. */}
 <Tabs>
     <TabItem value="__main__.py" label="__main__.py">
         <CodeBlock className="language-python">

website/versioned_docs/version-3.4/03_guides/07_scrapling.mdx

@@ -4,11 +4,10 @@ title: Adaptive scraping with Scrapling
 description: Build an Apify Actor that scrapes web pages using the Scrapling adaptive web scraping library.
 ---
 
-import CodeBlock from '@theme/CodeBlock';
 import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
 
 import ScraplingExample from '!!raw-loader!roa-loader!./code/07_scrapling.py';
-import ScraplingBrowserScraper from '!!raw-loader!./code/07_scrapling_browser.py';
+import ScraplingBrowserScraper from '!!raw-loader!roa-loader!./code/07_scrapling_browser.py';
 
 In this guide, you'll learn how to use the [Scrapling](https://scrapling.readthedocs.io/) library for adaptive web scraping in your Apify Actors.
 
@@ -101,9 +100,9 @@ scrapling install
 
 To switch the example from HTTP to a real browser, fetch each page through a browser session instead of `AsyncFetcher`. Opening a fresh browser for every page would be wasteful, so `main` enters an `AsyncDynamicSession` once and reuses it for the whole crawl, while `scrape_page` fetches with `session.fetch`. The parsing API is identical, so the extraction code stays the same:
 
-<CodeBlock className="language-python">
+<RunnableCodeBlock className="language-python" language="python">
     {ScraplingBrowserScraper}
-</CodeBlock>
+</RunnableCodeBlock>
 
 Note that:
 

website/versioned_docs/version-3.4/03_guides/09_browser_use.mdx

@@ -4,9 +4,9 @@ title: Browser AI agents with Browser Use
 description: Build an Apify Actor that automates a browser with an LLM agent using the Browser Use library.
 ---
 
-import RunnableCodeBlock from '@site/src/components/RunnableCodeBlock';
+import CodeBlock from '@theme/CodeBlock';
 
-import BrowserUseExample from '!!raw-loader!roa-loader!./code/09_browser_use.py';
+import BrowserUseExample from '!!raw-loader!./code/09_browser_use.py';
 
 In this guide, you'll learn how to use the [Browser Use](https://browser-use.com/) library to drive a browser with an LLM agent in your Apify Actors.
 
@@ -46,9 +46,10 @@ The following Actor runs a Browser Use agent for a single task and stores its st
 
 The whole Actor fits in a single file. A `run_agent_task` helper holds the Browser Use-specific logic: it defines the output schema and builds the LLM, browser, and agent. The `main` coroutine handles the [Actor](https://docs.apify.com/platform/actors) lifecycle, reads the input, sets up [Apify Proxy](https://docs.apify.com/platform/proxy), runs the agent, and stores the result:
 
-<RunnableCodeBlock className="language-python" language="python">
+{/* Not runnable from the docs: the agent needs an LLM API key (OPENAI_API_KEY) that the shared example runner does not provide. */}
+<CodeBlock className="language-python">
     {BrowserUseExample}
-</RunnableCodeBlock>
+</CodeBlock>
 
 Note that:
 

website/versioned_docs/version-3.4/03_guides/11_pydantic.mdx

@@ -56,7 +56,7 @@ The following Actor declares its input as a Pydantic `BaseModel`, validates the
 ### About the validation
 
 - `model_validate` parses the raw dictionary into a typed `ActorInput` instance. It fills in defaults and guarantees every field is valid, or raises a `ValidationError` that describes every problem at once.
-- Catching that error, logging a readable summary, and re-raising makes the Actor fail fast with a clear explanation right at the start, rather than crashing with an obscure error somewhere deep in the run. Because the body runs inside `async with Actor:`, the re-raised exception automatically marks the run as `FAILED`.
+- Catching that error, logging a readable summary, and failing the run with <ApiLink to="class/Actor#fail">`Actor.fail`</ApiLink> marks the run as `FAILED` with a clear status message. It fails fast right at the start with a readable explanation, instead of crashing with a raw traceback deeper in the run.
 - The error messages refer to the fields by their input-schema aliases. For invalid input like `{"searchTerms": [], "maxResults": 999, "outputFormat": "xml"}`, the log shows exactly what's wrong:
 
   ```text

website/versioned_docs/version-3.4/03_guides/code/01_beautifulsoup_httpx.py

@@ -82,7 +82,7 @@ async def main() -> None:
             await request_queue.add_request(Request.from_url(url))
 
         # Cap the crawl. Raise or remove the limit to follow more pages.
-        max_requests = 50
+        max_requests = 10
         handled_requests = 0
 
         while handled_requests < max_requests and (

website/versioned_docs/version-3.4/03_guides/code/02_parsel_impit.py

@@ -82,7 +82,7 @@ async def main() -> None:
             await request_queue.add_request(Request.from_url(url))
 
         # Cap the crawl. Raise or remove the limit to follow more pages.
-        max_requests = 50
+        max_requests = 10
         handled_requests = 0
 
         while handled_requests < max_requests and (

website/versioned_docs/version-3.4/03_guides/code/03_playwright.py

@@ -94,7 +94,7 @@ async def main() -> None:
             await request_queue.add_request(Request.from_url(url))
 
         # Cap the crawl. Raise or remove the limit to follow more pages.
-        max_requests = 50
+        max_requests = 10
         handled_requests = 0
 
         Actor.log.info('Launching Playwright...')

website/versioned_docs/version-3.4/03_guides/code/04_selenium.py

@@ -1,10 +1,6 @@
 import asyncio
-import json
-from pathlib import Path
-from tempfile import mkdtemp
 from typing import Any
 from urllib.parse import urljoin, urlsplit
-from zipfile import ZipFile
 
 from selenium import webdriver
 from selenium.webdriver.chrome.options import Options as ChromeOptions
@@ -18,71 +14,17 @@
 # On the Apify platform, it's already in the Actor's Docker image.
 
 
-def proxy_auth_extension(proxy_url: str) -> str:
-    """Build a Chrome extension that routes Chrome through an authenticated proxy."""
-    parts = urlsplit(proxy_url)
-
-    manifest = {
-        'name': 'Apify Proxy',
-        'version': '1.0.0',
-        'manifest_version': 3,
-        'permissions': ['proxy', 'webRequest', 'webRequestAuthProvider'],
-        'host_permissions': ['<all_urls>'],
-        'background': {'service_worker': 'background.js'},
-        'minimum_chrome_version': '108',
-    }
-
-    # The service worker sets the proxy and answers the auth challenge.
-    proxy_config = json.dumps(
-        {
-            'mode': 'fixed_servers',
-            'rules': {
-                'singleProxy': {
-                    'scheme': parts.scheme,
-                    'host': parts.hostname,
-                    'port': parts.port,
-                },
-            },
-        }
-    )
-    credentials = json.dumps(
-        {'username': parts.username or '', 'password': parts.password or ''}
-    )
-    background = (
-        'chrome.proxy.settings.set('
-        '{value: ' + proxy_config + ', scope: "regular"});\n'
-        'chrome.webRequest.onAuthRequired.addListener(\n'
-        '    () => ({authCredentials: ' + credentials + '}),\n'
-        '    {urls: ["<all_urls>"]},\n'
-        '    ["blocking"],\n'
-        ');\n'
-    )
-
-    extension_path = Path(mkdtemp()) / 'apify_proxy.zip'
-    with ZipFile(extension_path, 'w') as archive:
-        archive.writestr('manifest.json', json.dumps(manifest))
-        archive.writestr('background.js', background)
-    return str(extension_path)
-
-
-def build_chrome_driver(proxy_url: str | None = None) -> webdriver.Chrome:
-    """Create a headless Chrome WebDriver, optionally routed through a proxy."""
+def build_chrome_driver() -> webdriver.Chrome:
+    """Create a headless Chrome WebDriver suitable for a container."""
     chrome_options = ChromeOptions()
 
     if Actor.configuration.headless:
-        # The new headless mode is required to load the proxy extension.
         chrome_options.add_argument('--headless=new')
 
     chrome_options.add_argument('--no-sandbox')
     chrome_options.add_argument('--disable-dev-shm-usage')
     chrome_options.add_argument('--disable-gpu')
 
-    if proxy_url:
-        chrome_options.add_extension(proxy_auth_extension(proxy_url))
-        chrome_options.add_argument(
-            '--disable-features=DisableLoadExtensionCommandLineSwitch'
-        )
-
     return webdriver.Chrome(options=chrome_options)
 
 
@@ -140,9 +82,6 @@ async def main() -> None:
             Actor.log.info('No start URLs specified in Actor input, exiting...')
             await Actor.exit()
 
-        # Selenium proxies at the browser level, so one URL is shared per run.
-        proxy_configuration = await Actor.create_proxy_configuration()
-
         # Open the request queue and enqueue the start URLs (crawl depth 0).
         request_queue = await Actor.open_request_queue()
         for start_url in start_urls:
@@ -151,16 +90,11 @@ async def main() -> None:
             await request_queue.add_request(Request.from_url(url))
 
         # Cap the crawl. Raise or remove the limit to follow more pages.
-        max_requests = 50
+        max_requests = 10
         handled_requests = 0
 
-        # Fresh proxy URL for the run (None if no proxy).
-        proxy_url = None
-        if proxy_configuration:
-            proxy_url = await proxy_configuration.new_url()
-
         Actor.log.info('Launching Chrome WebDriver...')
-        driver = build_chrome_driver(proxy_url)
+        driver = build_chrome_driver()
 
         while handled_requests < max_requests and (
             request := await request_queue.fetch_next_request()