scrapling

Scrapling — ローカルでのステルス Web スクレイピング

完全にローカルで動作する Python ライブラリです（BSD-3、D4Vinci/Scrapling）。API キーは不要で、クラウドへの依存もありません。Cloudflare ソルバー、TLS 偽装、適応型要素追跡を内蔵しています。

Scrapling と Firecrawl の使い分け

必要なこと	使用するもの	理由
URL からクリーンな Markdown を取得する	firecrawl scrape --only-main-content	LLM 向けの Markdown 変換に最適化されています
Cloudflare／アンチボットを回避する	scrapling のステルス取得	Turnstile ソルバーと Patchright ステルスを内蔵しています
特定の要素を抽出する	CSS／XPath セレクターを指定した scrapling	要素単位の精度と適応型追跡を実現します
API キーを利用できない	scrapling	完全にローカルで動作し、認証情報は一切不要です
クラウドで一括スクレイピングする	firecrawl crawl / batch-scrape	クラウドインフラストラクチャと並列処理を利用できます
サイトの再設計に備える	scrapling の適応モード	SQLite ベースの類似度マッチングを利用できます
サイト全体を並行してクロールする	scrapling の Spider フレームワーク	一時停止／再開に対応した Scrapy のような機能を備えています
Web 検索とスクレイピングを行う	firecrawl search --scrape	検索と抽出を組み合わせます

インストール

次のコマンドを一度実行すると、すべての機能を含む Scrapling をセットアップできます。

~/.claude/skills/scrapling/scripts/scrapling_install.sh

uv 経由で scrapling[all] をインストールし、Chromium とシステム依存関係をダウンロードして、すべてのフェッチャーが読み込まれることを確認します。

クイックスタート — 標準出力ラッパー

このラッパーは Scrapling の Python API を直接使用するため（CLI より高速で、curl_cffi の証明書に関する問題も回避できます）、filter_web_results.py にパイプで渡せるよう標準出力に結果を出力します。

# Basic HTTP fetch (fastest, TLS impersonation)
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://example.com

# Stealth mode (Patchright, anti-bot bypass)
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://protected.site --stealth

# Stealth + Cloudflare solver
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://cf-protected.site --stealth --solve-cloudflare

# Dynamic (Playwright Chromium, JS rendering)
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://js-heavy.site --dynamic

# With CSS selector for targeted extraction
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://example.com --css ".product-list"

# Pipe through firecrawl's filter for token efficiency
python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py https://example.com --stealth | \
  python3 ~/.claude/skills/firecrawl/scripts/filter_web_results.py --sections "Pricing" --max-chars 5000

フルパス： python3 ~/.claude/skills/scrapling/scripts/scrapling_fetch.py フラグ： --stealth、--dynamic、--css SELECTOR、--solve-cloudflare、--impersonate BROWSER、--format {text,html}、--no-headless、--timeout SECONDS

--network-idle、--real-chrome、または POST リクエストを使用する場合は、以下の CLI 直接実行の方法を使用してください。

クイックスタート — CLI 直接実行

ファイルへの出力には、Scrapling 標準の CLI を使用します。

# HTTP fetch -> markdown
scrapling extract get 'https://example.com' content.md

# HTTP with CSS selector and browser impersonation
scrapling extract get 'https://example.com' content.md --css-selector '.main-content' --impersonate chrome

# Dynamic fetch (Playwright, JS rendering)
scrapling extract fetch 'https://example.com' content.md

# Stealth with Cloudflare bypass
scrapling extract stealthy-fetch 'https://protected.site' content.md --solve-cloudflare

# Stealth with CSS selector, visible browser for debugging
scrapling extract stealthy-fetch 'https://site.com' content.md --css-selector '.data' --no-headless

3 つのフェッチャー階層

CLI 動詞	エンジン	ステルス性	JS	速度
get	curl_cffi（HTTP）	TLS 偽装	いいえ	高速
fetch	Playwright／Chromium	中	はい	中速
stealthy-fetch	Patchright／Chrome	最大	はい	低速

Python API

要素単位の抽出、自動化、または CLI では不十分な場合に使用します。

from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher

# Simple HTTP fetch with CSS extraction
page = Fetcher.get('https://example.com', impersonate='chrome')
titles = page.css('.item h2::text').getall()
links = page.css('a::attr(href)').getall()

# Stealth with Cloudflare bypass
page = StealthyFetcher.fetch('https://protected.site',
    headless=True, solve_cloudflare=True,
    hide_canvas=True, block_webrtc=True)
data = page.css('.content').get_all_text()

# Page automation (login, click, fill)
def login(page):
    page.fill('#username', 'user')
    page.fill('#password', 'pass')
    page.click('#submit')

page = StealthyFetcher.fetch('https://app.example.com', page_action=login)

解析（取得なし）

from scrapling.parser import Selector

page = Selector("<html>...</html>")
page.css('.item::text').getall()       # CSS with pseudo-elements
page.xpath('//div[@class="item"]')     # XPath
page.find_all('div', class_='item')    # BeautifulSoup-style
page.find_by_text('Add to Cart')       # Text search
page.find_by_regex(r'Price: \$\d+')    # Regex search

適応型スクレイピング

Scrapling を代表する機能です。要素のフィンガープリントを SQLite に保存し、サイトの再設計後に類似度スコアを使って要素を再特定します。

from scrapling.fetchers import Fetcher

Fetcher.adaptive = True
page = Fetcher.get('https://example.com')

# First run: save element fingerprint
products = page.css('.product-list', auto_save=True)

# Later, after site redesign breaks the selector:
products = page.css('.product-list', adaptive=True)  # Still finds it

参照：references/adaptive-scraping.md

Spider フレームワーク

並行処理、一時停止／再開、セッションルーティングに対応したサイト全体のクロールに使用します。

from scrapling.spiders import Spider, Response, Request
from scrapling.fetchers import FetcherSession, StealthySession

class ResearchSpider(Spider):
    name = "research"
    start_urls = ["https://example.com/"]
    concurrent_requests = 10

    def configure_sessions(self, manager):
        manager.add("fast", FetcherSession(impersonate="chrome"))
        manager.add("stealth", StealthySession(headless=True), lazy=True)

    async def parse(self, response: Response):
        for link in response.css('a::attr(href)').getall():
            if "protected" in link:
                yield Request(link, sid="stealth")
            else:
                yield Request(link, sid="fast")
        for item in response.css('.article'):
            yield {"title": item.css('h2::text').get(), "url": response.url}

result = ResearchSpider().start(crawldir="./data")  # Pause/resume enabled
result.items.to_json("output.json")

トラブルシューティング

• ブラウザーが見つからない： scrapling install を実行して、ブラウザーの依存関係をダウンロードしてください
• フェッチャーのインポートエラー： フルパッケージをインストールしてください：uv pip install "scrapling[all]"
• Cloudflare に引き続きブロックされる： フラグを組み合わせてください：--solve-cloudflare --block-webrtc --hide-canvas
• HTTP フェッチャーで SSL 証明書エラーが発生する： curl_cffi に同梱されている CA 証明書は、macOS／pyenv では古くなっている場合があります。ラッパーはこれを自動的に処理します（verify=False）。Python API では、Fetcher.get() に verify=False を渡してください。
• ステルス取得が遅い： 想定どおりです。ブラウザーの自動化は、本質的に HTTP リクエストより低速です。ステルス性が不要な場合は、get（HTTP）を使用してください。

リファレンスドキュメント

ファイル	内容
references/cli-reference.md	CLI の extract コマンド（get、post、fetch、stealthy-fetch）の完全なリファレンス
references/python-api-reference.md	Python API（Fetcher、DynamicFetcher、StealthyFetcher、Sessions、Spiders）
references/adaptive-scraping.md	適応型要素追跡の詳細（保存、照合、類似度スコアリング）