Headless Web Scraping

Daten aus Webseiten extrahieren die einfachen HTTP-Anfragen widerstehen — JS-gerenderter Inhalt, Cloudflare-geschuetzte Seiten und dynamische SPAs — mit der Drei-Stufen-Fetcher-Architektur von scrapling und CSS-basierter Datenextraktion.

Wann verwenden

• Ziel-Seite erfordert JavaScript-Rendering (SPA, React, Vue)
• Seite hat Anti-Bot-Schutz (Cloudflare Turnstile, TLS-Fingerprinting)
• Strukturierte Extraktion mehrerer Elemente via CSS-Selektoren noetig
• Einfaches WebFetch oder requests.get() gibt leere oder blockierte Antworten zurueck
• Tabellarische Daten, Linklisten oder wiederholte DOM-Strukturen im Massstab extrahieren

Eingaben

• Erforderlich: Ziel-URL oder Liste von URLs zum Scrapen
• Erforderlich: Zu extrahierende Daten (CSS-Selektoren, Feldnamen oder Beschreibung der Ziel-Elemente)
• Optional: Fetcher-Stufen-Override (Standard: Auto-Auswahl basierend auf Site-Verhalten)
• Optional: Ausgabeformat (Standard: JSON; Alternativen: CSV, Python-Dict)
• Optional: Rate-Limit-Verzoegerung in Sekunden (Standard: 1)

Vorgehensweise

Schritt 1: Fetcher-Stufe waehlen

Bestimmen welcher scrapling-Fetcher zur Verteidigung der Ziel-Site passt.

# Decision matrix:
# 1. Fetcher        — static HTML, no JS, no anti-bot (fastest)
# 2. StealthyFetcher — Cloudflare/Turnstile, TLS fingerprint checks
# 3. DynamicFetcher  — JS-rendered SPAs, click/scroll interactions

# Quick probe: try Fetcher first, escalate on failure
from scrapling import Fetcher

fetcher = Fetcher()
response = fetcher.get("https://example.com/target-page")

if response.status == 200 and response.get_all_text():
    print("Fetcher tier sufficient")
else:
    print("Escalate to StealthyFetcher or DynamicFetcher")

Signal	Empfohlene Stufe
Statisches HTML, kein Schutz	Fetcher
403/503, Cloudflare-Challenge-Seite	StealthyFetcher
Seite laedt aber Content-Bereich ist leer	DynamicFetcher
Buttons klicken oder scrollen noetig	DynamicFetcher
altcha-CAPTCHA praesent	Keine (kann nicht automatisiert werden)

Erwartet: Eine der drei Stufen ist identifiziert. Fuer die meisten modernen Sites ist StealthyFetcher der korrekte Startpunkt.

Bei Fehler: Wenn alle drei Stufen blockierte Antworten zurueckgeben, pruefen ob die Site altcha-CAPTCHA nutzt (Proof-of-Work-Challenge die nicht umgangen werden kann). Falls ja, die Beschraenkung dokumentieren und stattdessen manuelle Extraktions-Anweisungen bereitstellen.

Schritt 2: Den Fetcher konfigurieren

Den ausgewaehlten Fetcher mit angemessenen Optionen einrichten.

from scrapling import Fetcher, StealthyFetcher, DynamicFetcher

# Tier 1: Fast HTTP with TLS fingerprint impersonation
fetcher = Fetcher()
fetcher.configure(
    timeout=30,
    retries=3,
    follow_redirects=True
)

# Tier 2: Headless Chromium with anti-detection
fetcher = StealthyFetcher()
fetcher.configure(
    headless=True,
    timeout=60,
    network_idle=True  # wait for all network requests to settle
)

# Tier 3: Full browser automation
fetcher = DynamicFetcher()
fetcher.configure(
    headless=True,
    timeout=90,
    network_idle=True,
    wait_selector="div.results"  # wait for specific element before extracting
)

Erwartet: Fetcher-Instanz ist konfiguriert und bereit. Keine Fehler bei Instanziierung. Fuer StealthyFetcher und DynamicFetcher ist ein Chromium-Binary verfuegbar (scrapling verwaltet dies automatisch beim ersten Lauf).

Bei Fehler:

• playwright oder Browser-Binary nicht gefunden -- python -m playwright install chromium ausfuehren
• Timeout bei configure() -- Timeout-Wert erhoehen oder Netzwerk-Konnektivitaet pruefen
• Import-Fehler -- scrapling installieren: pip install scrapling

Schritt 3: Daten holen und extrahieren

Zur Ziel-URL navigieren und strukturierte Daten mit CSS-Selektoren extrahieren.

# Fetch the page
response = fetcher.get("https://example.com/target-page")

# Single element extraction
title = response.find("h1.page-title")
if title:
    print(title.get_all_text())

# Multiple elements
items = response.find_all("div.result-item")
for item in items:
    name = item.find("span.name")
    price = item.find("span.price")
    print(f"{name.get_all_text()}: {price.get_all_text()}")

# Get attribute values
links = response.find_all("a.product-link")
urls = [link.get("href") for link in links]

# Get raw HTML content of an element
detail_html = response.find("div.description").html_content

Schluessel-API-Referenz:

Methode	Zweck
response.find("selector")	Erstes passendes Element
response.find_all("selector")	Alle passenden Elemente
element.get("attr")	Attributwert (href, src, data-*)
element.get_all_text()	Alle Text-Inhalte, rekursiv
element.html_content	Rohes Inner-HTML

Erwartet: Extrahierte Daten entsprechen dem sichtbaren Seiteninhalt. Elemente sind nicht None und Text-Inhalt ist nicht leer fuer befuellte Seiten.

Bei Fehler:

• find() gibt None zurueck -- das tatsaechliche HTML inspizieren (response.html_content) um den Selektor zu verifizieren; die Seite kann andere Klassennamen als erwartet nutzen
• Leerer Text aus get_all_text() -- Inhalt kann in Shadow-DOM oder Iframe sein; DynamicFetcher mit wait_selector versuchen
• .css_first() NICHT nutzen -- dies ist nicht Teil der scrapling-API (haeufige Verwechslung mit anderen Bibliotheken)

Schritt 4: Versagen und Grenzfaelle behandeln

Fallback-Logik fuer CAPTCHA-Detection, leere Antworten und Session-Anforderungen implementieren.

import time

def scrape_with_fallback(url, selector):
    """Try each fetcher tier in order, with CAPTCHA detection."""
    tiers = [
        ("Fetcher", Fetcher),
        ("StealthyFetcher", StealthyFetcher),
        ("DynamicFetcher", DynamicFetcher),
    ]

    for tier_name, tier_class in tiers:
        fetcher = tier_class()
        fetcher.configure(headless=True, timeout=60)

        try:
            response = fetcher.get(url)
        except Exception as error:
            print(f"{tier_name} failed: {error}")
            continue

        # Detect CAPTCHA / challenge pages
        page_text = response.get_all_text().lower()
        if "altcha" in page_text or "proof of work" in page_text:
            print(f"altcha CAPTCHA detected -- cannot automate")
            return None

        if response.status == 403 or response.status == 503:
            print(f"{tier_name} blocked (HTTP {response.status}), escalating")
            continue

        result = response.find(selector)
        if result and result.get_all_text().strip():
            return result.get_all_text()

        print(f"{tier_name} returned empty content, escalating")

    print("All tiers exhausted. Manual extraction required.")
    return None

Erwartet: Funktion gibt extrahierten Text bei Erfolg zurueck oder None mit einer Diagnose-Nachricht wenn alle Stufen scheitern. CAPTCHA-Seiten werden erkannt und gemeldet statt unendlich neu versucht.

Bei Fehler:

• Alle Stufen geben 403 zurueck -- die Site blockiert allen automatisierten Zugriff (haeufig bei WIPO, TMview, manchen Regierungsdatenbanken); die URL als manuellen-Zugriff-erfordernd dokumentieren
• Timeout-Fehler -- die Seite kann hinter einem langsamen CDN sein; Timeout auf 120s erhoehen
• Session-/Cookie-Fehler -- die Site kann Login erfordern; Cookie-Handhabung hinzufuegen oder zuerst authentifizieren

Schritt 5: Rate-Limiting und ethisches Scraping

Verzoegerungen implementieren und Site-Policies respektieren bevor im Massstab gelaufen wird.

import time
import urllib.robotparser

def check_robots_txt(base_url, target_path):
    """Check if scraping is allowed by robots.txt."""
    rp = urllib.robotparser.RobotFileParser()
    rp.set_url(f"{base_url}/robots.txt")
    rp.read()
    return rp.can_fetch("*", f"{base_url}{target_path}")

def scrape_urls(urls, selector, delay=1.0):
    """Scrape multiple URLs with rate limiting."""
    results = []
    fetcher = StealthyFetcher()
    fetcher.configure(headless=True, timeout=60)

    for url in urls:
        response = fetcher.get(url)
        data = response.find(selector)
        if data:
            results.append(data.get_all_text())

        time.sleep(delay)  # respect the server

    return results

Ethische Scraping-Checkliste:

1. robots.txt vor dem Scrapen pruefen -- Disallow-Direktiven respektieren
2. Mindestens 1 Sekunde Verzoegerung zwischen Anfragen nutzen
3. Den Scraper mit einem beschreibenden User-Agent identifizieren wenn moeglich
4. Persoenliche Daten nicht ohne Rechtsbasis scrapen
5. Antworten lokal cachen um redundante Anfragen zu vermeiden
6. Sofort stoppen bei einem 429 (Too Many Requests)

Erwartet: Scraping laeuft mit kontrollierter Rate. robots.txt wird vor Bulk-Operationen geprueft. Keine 429-Antworten ausgeloest.

Bei Fehler:

• 429 Too Many Requests -- Verzoegerung auf 3-5 Sekunden erhoehen oder stoppen und spaeter wiederholen
• robots.txt verbietet den Pfad -- die Direktive respektieren; nicht ueberschreiben
• IP-Bann -- sofort mit Scrapen aufhoeren; das Rate-Limiting war unzureichend. Wenn Zugriff legitim ist (oeffentliche Daten, ToS-erlaubt, robots.txt-respektiert) und fortgefahren werden muss, siehe rotate-scraping-proxies fuer Netzwerk-Schicht-Eskalation

Validierung

• Korrekte Fetcher-Stufe ist ausgewaehlt (nicht ueber- oder unterdimensioniert fuer das Ziel)
• configure()-Methode wird genutzt (nicht deprecated Constructor-Kwargs)
• CSS-Selektoren passen zur tatsaechlichen Seitenstruktur (gegen Seitenquelle verifiziert)
• .find() / .find_all()-API wird genutzt (nicht .css_first() oder andere Bibliotheks-Methoden)
• CAPTCHA-Detection ist vorhanden (altcha-Seiten werden gemeldet, nicht erneut versucht)
• Rate-Limiting ist fuer Multi-URL-Scraping implementiert
• robots.txt wird vor Bulk-Operationen geprueft
• Extrahierte Daten sind nicht leer und strukturell korrekt

Haeufige Stolperfallen

• .css_first() statt .find() nutzen: scrapling nutzt .find() und .find_all() zur Element-Auswahl -- .css_first() gehoert zu einer anderen Bibliothek und wird AttributeError werfen
• Mit DynamicFetcher beginnen: Immer zuerst Fetcher versuchen, dann eskalieren -- DynamicFetcher ist 10-50x langsamer aufgrund vollstaendigen Browser-Starts
• Constructor-Kwargs statt configure(): scrapling v0.4.x deprecatete das Uebergeben von Optionen an den Constructor; immer die configure()-Methode nutzen
• altcha-CAPTCHA ignorieren: Keine Fetcher-Stufe kann altcha-Proof-of-Work-Challenges loesen -- frueh erkennen und auf manuelle Anweisungen zurueckfallen
• Kein Rate-Limiting: Selbst wenn die Site keine 429 zurueckgibt, kann aggressives Scraping deine IP gebannt werden lassen oder Service-Degradation verursachen
• Stabile Selektoren annehmen: Website-CSS-Klassen aendern sich haeufig -- Selektoren gegen aktuelle Seitenquelle vor jeder Scraping-Kampagne validieren

Verwandte Skills

• rotate-scraping-proxies -- Netzwerk-Schicht-Eskalation wenn Client-Side-Stealth erschoepft ist und IP-Banns legitimen, ToS-erlaubten Zugriff blockieren
• use-graphql-api -- strukturierte API-Queries wenn die Site einen GraphQL-Endpoint anbietet (Scraping vorzuziehen)
• serialize-data-formats -- extrahierte Daten in JSON, CSV oder andere Formate konvertieren
• deploy-searxng -- selbst-gehostete Suchmaschine die Ergebnisse aus mehreren Quellen aggregiert
• forage-solutions -- breiteres Muster zum Sammeln von Information aus diversen Quellen

<!-- Keep under 500 lines. Extract large examples to references/EXAMPLES.md if needed. -->