scrapling

Scrapling

適応型で高性能な Python ウェブスクレイピングライブラリです。BeautifulSoup より774倍高速です。ウェブサイトの構造が変わっても、要素を自動的に再配置します。

主な機能： HTTP／ブラウザーによるフェッチ、Cloudflare のバイパス、適応型セレクター、Spider クロールフレームワーク、プロキシローテーション、CLI ツール、AI エージェント向け MCP サーバー。

v0.4 の破壊的変更： css_first()／xpath_first() は削除されました。代わりに .css('.sel').first または .css('.sel').get() を使用してください。css('::text') と css('::attr()') は TextHandler ではなく、Selector オブジェクトを返すようになりました。Response.body は常に bytes です。

クイックスタート

from scrapling.fetchers import Fetcher

page = Fetcher.get('https://example.com')
titles = page.css('.title::text')
links = page.css('a.link::attr(href)').getall()

# Response metadata
print(page.status, page.headers, page.cookies)

グローバル設定

Fetcher.configure(adaptive=True, encoding="utf-8", keep_comments=False)

フェッチャーの選択

必要なもの	使用するもの	理由
静的 HTML	Fetcher	最速、TLS スプーフィング
JavaScript コンテンツ	DynamicFetcher	Playwright ブラウザー
Cloudflare／ボット対策	StealthyFetcher	Camoufox + ステルス機能
複数ページのクロール	Spider	非同期クロールフレームワーク

フェッチャーのオプションについて詳しくは、references/fetchers.md を参照してください。

よく使うパターン

基本的なスクレイピング

from scrapling.fetchers import Fetcher

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

for quote in page.css('.quote'):
    text = quote.css('.text').first.text
    author = quote.css('.author').first.text
    print(f'{text} - {author}')

JavaScript でレンダリングされたコンテンツ

from scrapling.fetchers import DynamicFetcher

page = DynamicFetcher.fetch(
    'https://spa-app.com',
    headless=True,
    network_idle=True,
    wait_selector='.content-loaded'
)

Cloudflare のバイパス

from scrapling.fetchers import StealthyFetcher

page = StealthyFetcher.fetch(
    'https://protected-site.com',
    solve_cloudflare=True,
    humanize=True,
    headless=True
)

Cookie を使ったセッション

from scrapling.fetchers import FetcherSession

with FetcherSession(impersonate='chrome') as session:
    session.get('https://site.com/login')
    dashboard = session.get('https://site.com/dashboard')

複数ページのクロール（Spider）

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()

Spider フレームワークの詳細については、references/spiders.md を参照してください。

プロキシローテーション

from scrapling.engines.toolbelt import ProxyRotator

rotator = ProxyRotator(["http://proxy1:8080", "http://proxy2:8080"])
page = Fetcher.get('https://example.com', proxy_rotator=rotator)

適応型セレクター（自己修復）

from scrapling import Selector

# Save element properties on first visit (storage defaults to SQLite)
selector = Selector(html, url='https://example.com', adaptive=True)
products = selector.css('.product-card', auto_save=True)

# On subsequent runs, relocate even if structure changed
products = selector.css('.product-card', adaptive=True)

要素の選択

# CSS (recommended)
page.css('.class')              # Multiple → Selectors list
page.css('.class').first        # Single (safe, returns None if missing)
page.css('.class').get()        # First as TextHandler (alias: extract_first)
page.css('.title::text')        # Text extraction → Selector objects
page.css('a::attr(href)')       # Attribute → Selector objects

# XPath
page.xpath('//div[@id="main"]')
page.xpath('//h1').first

# BeautifulSoup-style
page.find('div', class_='content')
page.find_all('a', attrs={'data-type': 'link'})

# Text search (no tag= param — filter by tag separately if needed)
page.find_by_text('Add to Cart')
page.css('button').filter(lambda el: el.text == 'Add to Cart').first

注： .first と .last は安全なアクセサーです。IndexError を発生させず、代わりに None を返します。

ナビゲーションと高度な選択については、references/selectors.md を参照してください。

要素のナビゲーション

el = page.css('.target').first
el.parent                # Parent element
el.children              # Child elements
el.next                  # Next sibling
el.previous              # Previous sibling
el.siblings              # All siblings
el.text                  # Inner text
el.text.clean()          # Whitespace-normalized text
el.attrib['href']        # Attribute access

既存の HTML を解析する

from scrapling.parser import Selector

html = '<div class="item">Content</div>'
page = Selector(html)
content = page.css('.item').first.text

CLI の使用方法

# Interactive shell
scrapling shell

# Extract from URL (output format by extension: .html, .md, .txt)
scrapling extract get 'https://example.com' output.md --css-selector '.content'

# Dynamic content with browser
scrapling extract fetch 'https://spa.com' out.html --network-idle

# Cloudflare bypass
scrapling extract stealthy-fetch 'https://site.com' out.html --solve-cloudflare

すべてのコマンドとオプションについては、references/cli.md を参照してください。

エラー処理

from scrapling.fetchers import Fetcher

try:
    page = Fetcher.get('https://example.com', timeout=10)  # seconds
    element = page.css('.target').first
    if element:
        print(element.text)
    else:
        print('Element not found')
except Exception as e:
    print(f'Request failed: {e}')

MCP サーバー（AI 連携）

AI エージェント（Claude Desktop／Code）が自然言語でスクレイピングできるようにします。

pip install "scrapling[ai]"
scrapling install

ツール：get、bulk_get、fetch、bulk_fetch、stealthy_fetch、bulk_stealthy_fetch

設定については、references/mcp.md を参照してください。

リソース

• references/fetchers.md - フェッチャーのオプションと設定の詳細
• references/selectors.md - セレクターメソッドと要素のナビゲーション
• references/spiders.md - Spider クロールフレームワーク
• references/cli.md - CLI コマンドのリファレンス
• references/adaptive.md - 自己修復型セレクターシステム
• references/mcp.md - AI 連携向け MCP サーバー
• scripts/scrape_list.py - リスト項目を JSON／CSV に抽出する CLI ツール