---

name: headless-web-scraping description: > Extract data from web pages using the scrapling Python library — select the appropriate fetcher tier (HTTP, stealth Chromium, or full browser automation) based on target site defenses, configure headless browsing, and extract structured data with CSS selectors. Use when WebFetch is insufficient for JS-rendered pages, anti-bot-protected sites, or structured multi-element extraction requiring DOM traversal. license: MIT allowed-tools: Bash Read Write Grep Glob metadata: author: Philipp Thoss version: "1.0" domain: web-scraping complexity: intermediate language: Python tags: web-scraping, headless, scrapling, automation, data-extraction locale: de source_locale: en source_commit: 11edabf5 fence_basis_commit: 11edabf5 translator: "Claude + human review" translation_date: "2026-05-03"

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