docs/README_JP.md

Effortless Web Scraping for the Modern Web

選択メソッド · Fetcher の選び方 · スパイダー · プロキシローテーション · CLI · MCP モード

Scrapling は、単一のリクエストから本格的なクロールまですべてを処理する適応型 Web Scraping フレームワークです。

そのパーサーはウェブサイトの変更から学習し、ページが更新されたときに要素を自動的に再配置します。Fetcher はすぐに使える Cloudflare Turnstile などのアンチボットシステムを回避します。そして Spider フレームワークにより、Pause & Resume や自動 Proxy 回転機能を備えた並行マルチ Session クロールへとスケールアップできます — すべてわずか数行の Python で。1 つのライブラリ、妥協なし。

リアルタイム統計と Streaming による超高速クロール。Web Scraper によって、Web Scraper と一般ユーザーのために構築され、誰にでも何かがあります。

from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher
StealthyFetcher.adaptive = True
p = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True)  # レーダーの下でウェブサイトを取得！
products = p.css('.product', auto_save=True)                                        # ウェブサイトのデザイン変更に耐えるデータをスクレイプ！
products = p.css('.product', adaptive=True)                                         # 後でウェブサイトの構造が変わったら、`adaptive=True`を渡して見つける！

または本格的なクロールへスケールアップ

from scrapling.spiders import Spider, Response

class MySpider(Spider):
  name = "demo"
  start_urls = ["https://example.com/"]

  async def parse(self, response: Response):
      for item in response.css('.product'):
          yield {"title": item.css('h2::text').get()}

MySpider().start()

プラチナスポンサー

	Scrapling は Cloudflare Turnstile に対応。エンタープライズレベルの保護には、 Hyper Solutions がAkamai、DataDome、Kasada、Incapsula向けの有効な antibot トークンを生成する API エンドポイントを提供。シンプルな API 呼び出しで、ブラウザ自動化不要。
	プロキシは複雑で高価であるべきではないと考え、 BirdProxies を構築しました。 195以上のロケーションの高速レジデンシャル・ISPプロキシ、公正な価格設定、そして本物のサポート。 ランディングページでFlappyBird ゲームを試して無料データをゲット！
	Evomi ：レジデンシャルプロキシが $0.49/GB から。完全に偽装された Chromium によるスクレイピングブラウザ、レジデンシャル IP、自動 CAPTCHA 解決、アンチボットバイパス。 Scraper API で手間なく結果を取得。MCP と N8N の統合に対応。
	TikHub.io は TikTok、X、YouTube、Instagram を含む 16 以上のプラットフォームで 900 以上の安定した API を提供し、4,000 万以上のデータセットを保有。 さらに 割引 AI モデルも提供 — Claude、GPT、GEMINI など最大 71% オフ。
	Nsocks は開発者やスクレイパー向けの高速なレジデンシャルおよび ISP プロキシを提供。グローバル IP カバレッジ、高い匿名性、スマートなローテーション、自動化とデータ抽出のための信頼性の高いパフォーマンス。Xcrawl で大規模ウェブクローリングを簡素化。
	ノートパソコンを閉じても、スクレイパーは動き続けます。 PetroSky VPS - ノンストップ自動化のために構築されたクラウドサーバー。Windows と Linux マシンを完全制御。月額 €6.99 から。
	The Web Scraping Club で Scrapling の詳細レビュー（2025年11月）をお読みください。Web スクレイピング専門の No.1 ニュースレターです。
	Proxy-Seller は Web スクレイピング向けの信頼性の高いプロキシインフラを提供しています。IPv4、IPv6、ISP、レジデンシャル、モバイルプロキシに対応し、安定したパフォーマンス、幅広い地理的カバレッジ、企業規模のデータ収集に柔軟なプランを備えています。

_{ここに広告を表示したいですか？こちらをクリック}

スポンサー

_{ここに広告を表示したいですか？こちらをクリックして、あなたに合ったティアを選択してください！}

---

主な機能

Spider — 本格的なクロールフレームワーク

• 🕷️ Scrapy 風の Spider API：start_urls、async parse callback、Request/Response オブジェクトで Spider を定義。
• ⚡ 並行クロール：設定可能な並行数制限、ドメインごとのスロットリング、ダウンロード遅延。
• 🔄 マルチ Session サポート：HTTP リクエストとステルスヘッドレスブラウザの統一インターフェース — ID によって異なる Session にリクエストをルーティング。
• 💾 Pause & Resume：Checkpoint ベースのクロール永続化。Ctrl+C で正常にシャットダウン；再起動すると中断したところから再開。
• 📡 Streaming モード：async for item in spider.stream() でリアルタイム統計とともにスクレイプされたアイテムを Streaming で受信 — UI、パイプライン、長時間実行クロールに最適。
• 🛡️ ブロックされたリクエストの検出：カスタマイズ可能なロジックによるブロックされたリクエストの自動検出とリトライ。
• 📦 組み込みエクスポート：フックや独自のパイプライン、または組み込みの JSON/JSONL で結果をエクスポート。それぞれresult.items.to_json() / result.items.to_jsonl()を使用。

Session サポート付き高度なウェブサイト取得

• HTTP リクエスト：Fetcher クラスで高速かつステルスな HTTP リクエスト。ブラウザの TLS fingerprint、ヘッダーを模倣し、HTTP/3 を使用可能。
• 動的読み込み：Playwright の Chromium と Google Chrome をサポートする DynamicFetcher クラスによる完全なブラウザ自動化で動的ウェブサイトを取得。
• アンチボット回避：StealthyFetcher と fingerprint 偽装による高度なステルス機能。自動化で Cloudflare の Turnstile/Interstitial のすべてのタイプを簡単に回避。
• Session 管理：リクエスト間で Cookie と状態を管理するための FetcherSession、StealthySession、DynamicSession クラスによる永続的な Session サポート。
• Proxy 回転：すべての Session タイプに対応したラウンドロビンまたはカスタム戦略の組み込み ProxyRotator、さらにリクエストごとの Proxy オーバーライド。
• ドメインブロック：ブラウザベースの Fetcher で特定のドメイン（およびそのサブドメイン）へのリクエストをブロック。
• async サポート：すべての Fetcher および専用 async Session クラス全体での完全な async サポート。

適応型スクレイピングと AI 統合

• 🔄 スマート要素追跡：インテリジェントな類似性アルゴリズムを使用してウェブサイトの変更後に要素を再配置。
• 🎯 スマート柔軟選択：CSS セレクタ、XPath セレクタ、フィルタベース検索、テキスト検索、正規表現検索など。
• 🔍 類似要素の検出：見つかった要素に類似した要素を自動的に特定。
• 🤖 AI と使用する MCP サーバー：AI 支援 Web Scraping とデータ抽出のための組み込み MCP サーバー。MCP サーバーは、AI（Claude/Cursor など）に渡す前に Scrapling を活用してターゲットコンテンツを抽出する強力でカスタムな機能を備えており、操作を高速化し、トークン使用量を最小限に抑えることでコストを削減します。（デモ動画）

高性能で実戦テスト済みのアーキテクチャ

• 🚀 超高速：ほとんどの Python スクレイピングライブラリを上回る最適化されたパフォーマンス。
• 🔋 メモリ効率：最小のメモリフットプリントのための最適化されたデータ構造と遅延読み込み。
• ⚡ 高速 JSON シリアル化：標準ライブラリの 10 倍の速度。
• 🏗️ 実戦テスト済み：Scrapling は 92% のテストカバレッジと完全な型ヒントカバレッジを備えているだけでなく、過去1年間に数百人の Web Scraper によって毎日使用されてきました。

開発者/Web Scraper にやさしい体験

• 🎯 インタラクティブ Web Scraping Shell：Scrapling 統合、ショートカット、curl リクエストを Scrapling リクエストに変換したり、ブラウザでリクエスト結果を表示したりするなどの新しいツールを備えたオプションの組み込み IPython Shell で、Web Scraping スクリプトの開発を加速。
• 🚀 ターミナルから直接使用：オプションで、コードを一行も書かずに Scrapling を使用して URL をスクレイプできます！
• 🛠️ 豊富なナビゲーション API：親、兄弟、子のナビゲーションメソッドによる高度な DOM トラバーサル。
• 🧬 強化されたテキスト処理：組み込みの正規表現、クリーニングメソッド、最適化された文字列操作。
• 📝 自動セレクタ生成：任意の要素に対して堅牢な CSS/XPath セレクタを生成。
• 🔌 馴染みのある API：Scrapy/Parsel で使用されている同じ疑似要素を持つ Scrapy/BeautifulSoup に似た設計。
• 📘 完全な型カバレッジ：優れた IDE サポートとコード補完のための完全な型ヒント。コードベース全体が変更のたびにPyRightとMyPyで自動的にスキャンされます。
• 🔋 すぐに使える Docker イメージ：各リリースで、すべてのブラウザを含む Docker イメージが自動的にビルドおよびプッシュされます。

はじめに

深く掘り下げずに、Scrapling にできることの簡単な概要をお見せしましょう。

基本的な使い方

Session サポート付き HTTP リクエスト

from scrapling.fetchers import Fetcher, FetcherSession

with FetcherSession(impersonate='chrome') as session:  # Chrome の TLS fingerprint の最新バージョンを使用
    page = session.get('https://quotes.toscrape.com/', stealthy_headers=True)
    quotes = page.css('.quote .text::text').getall()

# または一回限りのリクエストを使用
page = Fetcher.get('https://quotes.toscrape.com/')
quotes = page.css('.quote .text::text').getall()

高度なステルスモード

from scrapling.fetchers import StealthyFetcher, StealthySession

with StealthySession(headless=True, solve_cloudflare=True) as session:  # 完了するまでブラウザを開いたままにする
    page = session.fetch('https://nopecha.com/demo/cloudflare', google_search=False)
    data = page.css('#padded_content a').getall()

# または一回限りのリクエストスタイル、このリクエストのためにブラウザを開き、完了後に閉じる
page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')
data = page.css('#padded_content a').getall()

完全なブラウザ自動化

from scrapling.fetchers import DynamicFetcher, DynamicSession

with DynamicSession(headless=True, disable_resources=False, network_idle=True) as session:  # 完了するまでブラウザを開いたままにする
    page = session.fetch('https://quotes.toscrape.com/', load_dom=False)
    data = page.xpath('//span[@class="text"]/text()').getall()  # お好みであれば XPath セレクタを使用

# または一回限りのリクエストスタイル、このリクエストのためにブラウザを開き、完了後に閉じる
page = DynamicFetcher.fetch('https://quotes.toscrape.com/')
data = page.css('.quote .text::text').getall()

Spider

並行リクエスト、複数の Session タイプ、Pause & Resume を備えた本格的なクローラーを構築：

from scrapling.spiders import Spider, Request, Response

class QuotesSpider(Spider):
    name = "quotes"
    start_urls = ["https://quotes.toscrape.com/"]
    concurrent_requests = 10

    async def parse(self, response: Response):
        for quote in response.css('.quote'):
            yield {
                "text": quote.css('.text::text').get(),
                "author": quote.css('.author::text').get(),
            }

        next_page = response.css('.next a')
        if next_page:
            yield response.follow(next_page[0].attrib['href'])

result = QuotesSpider().start()
print(f"{len(result.items)}件の引用をスクレイプしました")
result.items.to_json("quotes.json")

単一の Spider で複数の Session タイプを使用：

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

class MultiSessionSpider(Spider):
    name = "multi"
    start_urls = ["https://example.com/"]

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

    async def parse(self, response: Response):
        for link in response.css('a::attr(href)').getall():
            # 保護されたページはステルス Session を通してルーティング
            if "protected" in link:
                yield Request(link, sid="stealth")
            else:
                yield Request(link, sid="fast", callback=self.parse)  # 明示的な callback

Checkpoint を使用して長時間のクロールをPause & Resume：

QuotesSpider(crawldir="./crawl_data").start()

Ctrl+C を押すと正常に一時停止し、進捗は自動的に保存されます。後で Spider を再度起動する際に同じcrawldirを渡すと、中断したところから再開します。

高度なパースとナビゲーション

from scrapling.fetchers import Fetcher

# 豊富な要素選択とナビゲーション
page = Fetcher.get('https://quotes.toscrape.com/')

# 複数の選択メソッドで引用を取得
quotes = page.css('.quote')  # CSS セレクタ
quotes = page.xpath('//div[@class="quote"]')  # XPath
quotes = page.find_all('div', {'class': 'quote'})  # BeautifulSoup スタイル
# 以下と同じ
quotes = page.find_all('div', class_='quote')
quotes = page.find_all(['div'], class_='quote')
quotes = page.find_all(class_='quote')  # など...
# テキスト内容で要素を検索
quotes = page.find_by_text('quote', tag='div')

# 高度なナビゲーション
quote_text = page.css('.quote')[0].css('.text::text').get()
quote_text = page.css('.quote').css('.text::text').getall()  # チェーンセレクタ
first_quote = page.css('.quote')[0]
author = first_quote.next_sibling.css('.author::text')
parent_container = first_quote.parent

# 要素の関連性と類似性
similar_elements = first_quote.find_similar()
below_elements = first_quote.below_elements()

ウェブサイトを取得せずにパーサーをすぐに使用することもできます：

from scrapling.parser import Selector

page = Selector("<html>...</html>")

まったく同じ方法で動作します！

非同期 Session 管理の例

import asyncio
from scrapling.fetchers import FetcherSession, AsyncStealthySession, AsyncDynamicSession

async with FetcherSession(http3=True) as session:  # `FetcherSession` はコンテキストアウェアで、同期/非同期両方のパターンで動作可能
    page1 = session.get('https://quotes.toscrape.com/')
    page2 = session.get('https://quotes.toscrape.com/', impersonate='firefox135')

# 非同期 Session の使用
async with AsyncStealthySession(max_pages=2) as session:
    tasks = []
    urls = ['https://example.com/page1', 'https://example.com/page2']

    for url in urls:
        task = session.fetch(url)
        tasks.append(task)

    print(session.get_pool_stats())  # オプション - ブラウザタブプールのステータス（ビジー/フリー/エラー）
    results = await asyncio.gather(*tasks)
    print(session.get_pool_stats())

CLI とインタラクティブ Shell

Scrapling には強力なコマンドラインインターフェースが含まれています：

インタラクティブ Web Scraping Shell を起動

scrapling shell

プログラミングせずに直接ページをファイルに抽出（デフォルトでbodyタグ内のコンテンツを抽出）。出力ファイルが.txtで終わる場合、ターゲットのテキストコンテンツが抽出されます。.mdで終わる場合、HTML コンテンツの Markdown 表現になります。.html で終わる場合、HTML コンテンツそのものになります。

scrapling extract get 'https://example.com' content.md
scrapling extract get 'https://example.com' content.txt --css-selector '#fromSkipToProducts' --impersonate 'chrome'  # CSS セレクタ'#fromSkipToProducts'に一致するすべての要素
scrapling extract fetch 'https://example.com' content.md --css-selector '#fromSkipToProducts' --no-headless
scrapling extract stealthy-fetch 'https://nopecha.com/demo/cloudflare' captchas.html --css-selector '#padded_content a' --solve-cloudflare

MCP サーバーやインタラクティブ Web Scraping Shell など、他にも多くの追加機能がありますが、このページは簡潔に保ちたいと思います。完全なドキュメントはこちらをご覧ください

パフォーマンスベンチマーク

Scrapling は強力であるだけでなく、超高速です。以下のベンチマークは、Scrapling のパーサーを他の人気ライブラリの最新バージョンと比較しています。

テキスト抽出速度テスト（5000 個のネストされた要素）

#	ライブラリ	時間 (ms)	vs Scrapling
1	Scrapling	2.02	1.0x
2	Parsel/Scrapy	2.04	1.01
3	Raw Lxml	2.54	1.257
4	PyQuery	24.17	~12x
5	Selectolax	82.63	~41x
6	MechanicalSoup	1549.71	~767.1x
7	BS4 with Lxml	1584.31	~784.3x
8	BS4 with html5lib	3391.91	~1679.1x

要素類似性とテキスト検索のパフォーマンス

Scrapling の適応型要素検索機能は代替手段を大幅に上回ります：

ライブラリ	時間 (ms)	vs Scrapling
Scrapling	2.39	1.0x
AutoScraper	12.45	5.209x

すべてのベンチマークは 100 回以上の実行の平均を表します。方法論についてはbenchmarks.pyを参照してください。

インストール

Scrapling には Python 3.10 以上が必要です：

pip install scrapling

このインストールにはパーサーエンジンとその依存関係のみが含まれており、Fetcher やコマンドライン依存関係は含まれていません。

オプションの依存関係

1. 以下の追加機能、Fetcher、またはそれらのクラスのいずれかを使用する場合は、Fetcher の依存関係とブラウザの依存関係を次のようにインストールする必要があります：

   pip install "scrapling[fetchers]"
   
   scrapling install           # normal install
   scrapling install  --force  # force reinstall
   

   これにより、すべてのブラウザ、およびそれらのシステム依存関係とfingerprint 操作依存関係がダウンロードされます。

   または、コマンドを実行する代わりにコードからインストールすることもできます：

   from scrapling.cli import install
   
   install([], standalone_mode=False)          # normal install
   install(["--force"], standalone_mode=False) # force reinstall
   

2. 追加機能：

   • MCP サーバー機能をインストール：

     pip install "scrapling[ai]"
     

   • Shell 機能（Web Scraping Shell とextractコマンド）をインストール：

     pip install "scrapling[shell]"
     

   • すべてをインストール：

     pip install "scrapling[all]"
     

     これらの追加機能のいずれかの後（まだインストールしていない場合）、scrapling installでブラウザの依存関係をインストールする必要があることを忘れないでください

Docker

DockerHub から次のコマンドですべての追加機能とブラウザを含む Docker イメージをインストールすることもできます：

docker pull pyd4vinci/scrapling

または GitHub レジストリからダウンロード：

docker pull ghcr.io/d4vinci/scrapling:latest

このイメージは、GitHub Actions とリポジトリのメインブランチを使用して自動的にビルドおよびプッシュされます。

貢献

貢献を歓迎します！始める前に貢献ガイドラインをお読みください。

免責事項

このライブラリは教育および研究目的のみで提供されています。このライブラリを使用することにより、地域および国際的なデータスクレイピングおよびプライバシー法に準拠することに同意したものとみなされます。著者および貢献者は、このソフトウェアの誤用について責任を負いません。常にウェブサイトの利用規約とrobots.txt ファイルを尊重してください。

🎓 引用

研究目的で当ライブラリを使用された場合は、以下の参考文献で引用してください：

  @misc{scrapling,
    author = {Karim Shoair},
    title = {Scrapling},
    year = {2024},
    url = {https://github.com/D4Vinci/Scrapling},
    note = {An adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl!}
  }

ライセンス

この作品は BSD-3-Clause ライセンスの下でライセンスされています。

謝辞

このプロジェクトには次から適応されたコードが含まれています：

• Parsel（BSD ライセンス）— translator サブモジュールに使用

---

Karim Shoair によって❤️でデザインおよび作成されました。