docs: address review comments on Scrapling guide

Author: vdusek

docs/03_guides/07_scrapling.mdx

@@ -61,6 +61,30 @@ Note that:
 - `response.urljoin(link_href)` resolves relative links against the page URL, so you can enqueue them directly.
 - The `impersonate='chrome'` and `stealthy_headers=True` options make the request look like it comes from a real Chrome browser, which, combined with Apify Proxy, reduces the chance of being blocked.
 
+## Adaptive selectors
+
+The example above uses plain CSS selectors. Scrapling can also track the elements you scrape and relocate them when a website changes its markup, so a redesign doesn't immediately break your scraper. This is most useful for scrapers that revisit the same pages over time, rather than one-off crawls.
+
+1. Enable adaptive matching once on the fetcher:
+
+    ```python
+    AsyncFetcher.configure(adaptive=True)
+    ```
+
+2. On the first run, pass `auto_save=True` when you select an element. Scrapling records a fingerprint of that element, keyed by the selector:
+
+    ```python
+    title = response.css('h1.product-title::text', auto_save=True).get()
+    ```
+
+3. On a later run, if the selector no longer matches because the page changed, pass `adaptive=True` with the same selector. Scrapling uses the saved fingerprint to find the element in its new location:
+
+    ```python
+    title = response.css('h1.product-title::text', adaptive=True).get()
+    ```
+
+Scrapling keeps these fingerprints in a local SQLite database. On the Apify platform the Actor's filesystem doesn't persist between runs, so to keep them across runs, store that database in a [key-value store](https://docs.apify.com/platform/storage/key-value-store) and restore it on startup. For details, see [Scrapling's adaptive parsing documentation](https://scrapling.readthedocs.io/en/latest/parsing/adaptive.html).
+
 ## 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. In the example above, `main` creates a proxy configuration with `Actor.create_proxy_configuration` and passes a fresh proxy URL to `scrape_page` for every request, which forwards it to Scrapling's `proxy` argument.
@@ -75,13 +99,33 @@ Scrapling accepts the proxy as a URL string (for example `http://user:pass@proxy
 scrapling install
 ```
 
-Switching the example Actor from HTTP to a real browser takes only one code change. Swap the `AsyncFetcher.get` call in `scrape_page` for `DynamicFetcher.async_fetch`. The parsing API is identical, so the rest of the Actor stays the same:
+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">
     {ScraplingBrowserScraper}
 </CodeBlock>
 
-To run this on the Apify platform, build on top of the [Apify Playwright base image](https://hub.docker.com/r/apify/actor-python-playwright), which already ships a browser together with all of its system-level dependencies, and run `scrapling install` during the Docker build to download the browser binaries that Scrapling expects.
+Note that:
+
+- `AsyncDynamicSession` launches one browser and keeps it open across `session.fetch` calls, so the crawl doesn't pay the browser-startup cost on every page.
+- The proxy URL is passed per fetch, so each page can go through a fresh Apify Proxy IP while sharing the same browser.
+
+To run this on the Apify platform, build on top of the [Apify Playwright base image](https://hub.docker.com/r/apify/actor-python-playwright), which already ships a browser together with all of its system-level dependencies, and run `scrapling install` during the Docker build to download the browser binaries that Scrapling expects:
+
+```docker title="Dockerfile"
+FROM apify/actor-python-playwright:3.14
+
+# Install the Actor's Python dependencies.
+COPY requirements.txt ./
+RUN pip install -r requirements.txt
+
+# Download the browser binaries that Scrapling's browser fetchers need.
+RUN scrapling install
+
+# Copy in the source code and launch the Actor as a module.
+COPY . ./
+CMD ["python", "-m", "src"]
+```
 
 ## Conclusion
 
@@ -92,5 +136,6 @@ In this guide, you learned how to use Scrapling in your Apify Actors. You can no
 - [Scrapling: Official documentation](https://scrapling.readthedocs.io/)
 - [Scrapling: Fetchers](https://scrapling.readthedocs.io/en/latest/fetching/choosing/)
 - [Scrapling: Parsing and selecting elements](https://scrapling.readthedocs.io/en/latest/parsing/selection/)
+- [Scrapling: Adaptive parsing](https://scrapling.readthedocs.io/en/latest/parsing/adaptive.html)
 - [Scrapling: GitHub repository](https://github.com/D4Vinci/Scrapling)
 - [Apify: Proxy management](https://docs.apify.com/platform/proxy)

docs/03_guides/code/07_scrapling_browser.py

@@ -1,21 +1,22 @@
+import asyncio
 from typing import Any
+from urllib.parse import urlsplit
 
-from scrapling.fetchers import DynamicFetcher
+from scrapling.fetchers import AsyncDynamicSession
+
+from apify import Actor, Request
+from apify.storages import RequestQueue
 
 
 async def scrape_page(
+    session: AsyncDynamicSession,
     url: str,
     *,
     proxy_url: str | None = None,
 ) -> tuple[dict[str, Any], list[str]]:
-    """Fetch a page in a real browser with Scrapling and return data and links."""
+    """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 DynamicFetcher.async_fetch(
-        url,
-        proxy=proxy_url,
-        headless=True,
-        network_idle=True,
-    )
+    response = await session.fetch(url, proxy=proxy_url, network_idle=True)
 
     data = {
         'url': url,
@@ -25,11 +26,94 @@ async def scrape_page(
         'h3s': response.css('h3::text').getall(),
     }
 
-    # Collect absolute links from the page.
+    # Keep only absolute links on the same host.
     links: list[str] = []
+    host = urlsplit(url).netloc
     for href in response.css('a::attr(href)').getall():
         link_url = response.urljoin(href)
-        if link_url.startswith(('http://', 'https://')):
+        if not link_url.startswith(('http://', 'https://')):
+            continue
+        if urlsplit(link_url).netloc == host:
             links.append(link_url)
 
     return data, links
+
+
+async def enqueue_links(
+    request_queue: RequestQueue,
+    links: list[str],
+    *,
+    depth: int,
+    max_depth: int,
+) -> None:
+    """Enqueue the links one level deeper, unless max_depth was reached."""
+    if depth >= max_depth:
+        return
+
+    for link_url in links:
+        Actor.log.info(f'Enqueuing {link_url} ...')
+        request = Request.from_url(link_url)
+        request.crawl_depth = depth + 1
+        await request_queue.add_request(request)
+
+
+async def main() -> None:
+    async with Actor:
+        # Read the Actor input.
+        actor_input = await Actor.get_input() or {}
+        start_urls = actor_input.get('startUrls', [{'url': 'https://crawlee.dev'}])
+        max_depth = actor_input.get('maxDepth', 1)
+
+        if not start_urls:
+            Actor.log.info('No start URLs specified in Actor input, exiting...')
+            await Actor.exit()
+
+        # Set up Apify Proxy and the request queue.
+        proxy_configuration = await Actor.create_proxy_configuration()
+        request_queue = await Actor.open_request_queue()
+
+        # Enqueue the start URLs (crawl depth defaults to 0).
+        for start_url in start_urls:
+            url = start_url.get('url')
+            Actor.log.info(f'Enqueuing start URL: {url}')
+            await request_queue.add_request(Request.from_url(url))
+
+        # Cap the crawl; raise or remove to follow more pages.
+        max_requests = 50
+        handled_requests = 0
+
+        # Open the browser once and reuse it for every page in the crawl.
+        async with AsyncDynamicSession(headless=True) as session:
+            while handled_requests < max_requests and (
+                request := await request_queue.fetch_next_request()
+            ):
+                handled_requests += 1
+                url = request.url
+                depth = request.crawl_depth
+                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)
+                    await Actor.push_data(data)
+                    Actor.log.info(
+                        f'Stored data from {url} '
+                        f'(title={data["title"]!r}, {len(links)} links found).'
+                    )
+                    await enqueue_links(
+                        request_queue, links, depth=depth, max_depth=max_depth
+                    )
+
+                except Exception:
+                    Actor.log.exception(f'Cannot extract data from {url}.')
+
+                finally:
+                    await request_queue.mark_request_as_handled(request)
+
+
+if __name__ == '__main__':
+    asyncio.run(main())