d4vinci--scrapling/docs/README_RU.md

Effortless Web Scraping for the Modern Web

Методы выбора · Выбор Fetcher · Пауки · Ротация прокси · CLI · Режим MCP

Scrapling - это адаптивный фреймворк для Web Scraping, который берёт на себя всё: от одного запроса до полномасштабного обхода сайтов.

Его парсер учится на изменениях сайтов и автоматически перемещает ваши элементы при обновлении страниц. Его Fetcher'ы обходят анти-бот системы вроде Cloudflare Turnstile прямо из коробки. А его Spider-фреймворк позволяет масштабироваться до параллельных, многосессионных обходов с Pause & Resume и автоматической ротацией Proxy - и всё это в нескольких строках Python. Одна библиотека, без компромиссов.

Молниеносно быстрые обходы с отслеживанием статистики в реальном времени и Streaming. Создано веб-скраперами для веб-скраперов и обычных пользователей - здесь есть что-то для каждого.

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

Платиновые спонсоры

	Proxidize предоставляет мобильные и резидентные прокси для скрейпинга, автоматизации браузера, SEO-мониторинга, ИИ-агентов и сбора данных. Используйте код scrapling20 для скидки 20%.
	ColdProxy предоставляет резидентные и дата-центровые прокси для стабильного веб-скрейпинга, сбора публичных данных и гео-таргетированного тестирования в более чем 195 странах.
	Scrapling справляется с Cloudflare Turnstile. Для защиты корпоративного уровня Hyper Solutions предоставляет API-эндпоинты, генерирующие валидные antibot-токены для Akamai, DataDome, Kasada и Incapsula . Простые API-вызовы, без автоматизации браузера.
	Evomi : резидентные прокси от $0.49/ГБ. Браузер для скрапинга с полностью подменённым Chromium, резидентными IP, автоматическим решением CAPTCHA и обходом анти-бот систем. Scraper API для получения результатов без лишних сложностей. Доступны интеграции с MCP и N8N.
	TikHub.io предоставляет более 900 стабильных API на 16+ платформах, включая TikTok, X, YouTube и Instagram, с более чем 40 млн наборов данных. Также предлагает AI-модели со скидкой - Claude, GPT, GEMINI и другие со скидкой до 71%.
	Закройте ноутбук. Ваши скраперы продолжают работать. PetroSky VPS - облачные серверы для непрерывной автоматизации. Машины на Windows и Linux с полным контролем. От €6,99/мес.
	Прочитайте полный обзор Scrapling на The Web Scraping Club (ноябрь 2025) - рассылка №1, посвящённая веб-скрейпингу.
	Swiftproxy предоставляет масштабируемые резидентные прокси с более чем 80 млн IP в 195+ странах, обеспечивая быстрые и надёжные соединения, автоматическую ротацию и высокую устойчивость к блокировкам. Доступна бесплатная пробная версия.
	NodeMaven - надёжный провайдер прокси с самым высоким качеством IP на рынке. Используйте промокод SCRAPLING35 для получения скидки 35% на прокси.

_{Хотите показать здесь свою рекламу? Нажмите здесь}

Спонсоры

_{Хотите показать здесь свою рекламу? Нажмите здесь и выберите подходящий вам уровень!}

---

Ключевые особенности

Spider'ы - полноценный фреймворк для обхода сайтов

• 🕷️ Scrapy-подобный Spider API: Определяйте Spider'ов с start_urls, async parse callback'ами и объектами Request/Response.
• ⚡ Параллельный обход: Настраиваемые лимиты параллелизма, ограничение скорости по домену и задержки загрузки.
• 🔄 Поддержка нескольких сессий: Единый интерфейс для HTTP-запросов и скрытных headless-браузеров в одном Spider - маршрутизируйте запросы к разным сессиям по ID.
• 💾 Pause & Resume: Persistence обхода на основе Checkpoint'ов. Нажмите Ctrl+C для мягкой остановки; перезапустите, чтобы продолжить с того места, где вы остановились.
• 📡 Режим Streaming: Стримьте извлечённые элементы по мере их поступления через async for item in spider.stream() со статистикой в реальном времени - идеально для UI, конвейеров и длительных обходов.
• 🛡️ Обнаружение заблокированных запросов: Автоматическое обнаружение и повторная отправка заблокированных запросов с настраиваемой логикой.
• 🤖 Соответствие robots.txt: Опциональный флаг robots_txt_obey, который учитывает директивы Disallow, Crawl-delay и Request-rate с кэшированием по доменам.
• 🧪 Режим разработки: Кэшируйте ответы на диск при первом запуске и воспроизводите их при последующих запусках - итерируйте над логикой parse(), не отправляя повторные запросы к целевым серверам.
• 📦 Встроенный экспорт: Экспортируйте результаты через хуки и собственный конвейер или встроенный JSON/JSONL с result.items.to_json() / result.items.to_jsonl() соответственно.

Продвинутая загрузка сайтов с поддержкой Session

• HTTP-запросы: Быстрые и скрытные HTTP-запросы с классом Fetcher. Может имитировать TLS fingerprint браузера, заголовки и использовать HTTP/3.
• Динамическая загрузка: Загрузка динамических сайтов с полной автоматизацией браузера через класс DynamicFetcher, поддерживающий Chromium от Playwright и Google Chrome.
• Обход анти-ботов: Расширенные возможности скрытности с StealthyFetcher и подмену fingerprint'ов. Может легко обойти все типы Cloudflare Turnstile/Interstitial с помощью автоматизации.
• Управление сессиями: Поддержка постоянных сессий с классами FetcherSession, StealthySession и DynamicSession для управления cookie и состоянием между запросами.
• Ротация Proxy: Встроенный ProxyRotator с циклической или пользовательскими стратегиями для всех типов сессий, а также переопределение Proxy для каждого запроса.
• Блокировка доменов и рекламы: Блокируйте запросы к определённым доменам (и их поддоменам) или включите встроенную блокировку рекламы (~3 500 известных рекламных/трекерных доменов) в браузерных Fetcher'ах.
• Защита от утечки DNS: Опциональная поддержка DNS-over-HTTPS для маршрутизации DNS-запросов через Cloudflare DoH, предотвращая утечку DNS при использовании прокси.
• Поддержка async: Полная async-поддержка во всех Fetcher'ах и выделенных async-классах сессий.

Адаптивный скрапинг и интеграция с ИИ

• 🔄 Умное отслеживание элементов: Перемещайте элементы после изменений сайта с помощью интеллектуальных алгоритмов подобия.
• 🎯 Умный гибкий выбор: CSS-селекторы, XPath-селекторы, поиск на основе фильтров, текстовый поиск, поиск по регулярным выражениям и многое другое.
• 🔍 Поиск похожих элементов: Автоматически находите элементы, похожие на найденные.
• 🤖 MCP-сервер для использования с ИИ: Встроенный MCP-сервер для Web Scraping с помощью ИИ и извлечения данных. MCP-сервер обладает мощными пользовательскими возможностями, которые используют Scrapling для извлечения целевого контента перед передачей его ИИ (Claude/Cursor/и т.д.), тем самым ускоряя операции и снижая затраты за счёт минимизации использования токенов. (демо-видео)

Высокопроизводительная и проверенная в боях архитектура

• 🚀 Молниеносная скорость: Оптимизированная производительность, превосходящая большинство Python-библиотек для скрапинга.
• 🔋 Эффективное использование памяти: Оптимизированные структуры данных и ленивая загрузка для минимального потребления памяти.
• ⚡ Быстрая сериализация JSON: В 10 раз быстрее стандартной библиотеки.
• 🏗️ Проверено в боях: Scrapling имеет не только 92% покрытия тестами и полное покрытие type hints, но и ежедневно использовался сотнями веб-скраперов в течение последнего года.

Удобный для разработчиков/веб-скраперов опыт

• 🎯 Интерактивная Web Scraping Shell: Опциональная встроенная IPython-оболочка с интеграцией Scrapling, ярлыками и новыми инструментами для ускорения разработки скриптов Web Scraping, такими как преобразование curl-запросов в запросы Scrapling и просмотр результатов запросов в браузере.
• 🚀 Используйте прямо из терминала: При желании вы можете использовать Scrapling для скрапинга URL без написания ни одной строки кода!
• 🛠️ Богатый API навигации: Расширенный обход DOM с методами навигации по родителям, братьям и детям.
• 🧬 Улучшенная обработка текста: Встроенные регулярные выражения, методы очистки и оптимизированные операции со строками.
• 📝 Автоматическая генерация селекторов: Генерация надёжных CSS/XPath-селекторов для любого элемента.
• 🔌 Знакомый API: Похож на Scrapy/BeautifulSoup с теми же псевдоэлементами, используемыми в Scrapy/Parsel.
• 📘 Полное покрытие типами: Полные type hints для отличной поддержки IDE и автодополнения кода. Вся кодовая база автоматически проверяется PyRight и MyPy при каждом изменении.
• 🔋 Готовый Docker-образ: С каждым релизом автоматически создаётся и публикуется Docker-образ, содержащий все браузеры.

Начало работы

Давайте кратко покажем, на что способен Scrapling, без глубокого погружения.

Базовое использование

HTTP-запросы с поддержкой Session

from scrapling.fetchers import Fetcher, FetcherSession

with FetcherSession(impersonate='chrome') as session:  # Используйте последнюю версию TLS fingerprint Chrome
    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'ы

Создавайте полноценные обходчики с параллельными запросами, несколькими типами сессий и 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:

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():
            # Направляйте защищённые страницы через stealth-сессию
            if "protected" in link:
                yield Request(link, sid="stealth")
            else:
                yield Request(link, sid="fast", callback=self.parse)  # явный callback

Приостанавливайте и возобновляйте длительные обходы с помощью Checkpoint'ов, запуская Spider следующим образом:

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

И он работает точно так же!

Примеры async Session

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

async with FetcherSession(http3=True) as session:  # `FetcherSession` контекстно-осведомлён и может работать как в sync, так и в async-режимах
    page1 = session.get('https://quotes.toscrape.com/')
    page2 = session.get('https://quotes.toscrape.com/', impersonate='firefox135')

# Использование async-сессии
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, это будет Markdown-представление HTML-содержимого; если заканчивается на .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

Note

Есть множество дополнительных возможностей, но мы хотим сохранить эту страницу краткой, включая MCP-сервер и интерактивную Web Scraping Shell. Ознакомьтесь с полной документацией здесь

Тесты производительности

Scrapling не только мощный - он ещё и невероятно быстрый. Следующие тесты производительности сравнивают парсер Scrapling с последними версиями других популярных библиотек.

Тест скорости извлечения текста (5000 вложенных элементов)

#	Библиотека	Время (мс)	vs Scrapling
1	Scrapling	1.98	1.0x
2	Parsel/Scrapy	1.99	1.005
3	Raw Lxml	2.48	1.253
4	PyQuery	23.15	~12x
5	Selectolax	196.09	~99x
6	MechanicalSoup	1531.24	~773.4x
7	BS4 with Lxml	1535.19	~775.3x
8	BS4 with html5lib	3388.16	~1711.2x

Производительность подобия элементов и текстового поиска

Возможности адаптивного поиска элементов Scrapling значительно превосходят альтернативы:

Библиотека	Время (мс)	vs Scrapling
Scrapling	2.29	1.0x
AutoScraper	12.46	5.441x

Все тесты производительности представляют собой средние значения более 100 запусков. См. benchmarks.py для методологии.

Установка

Scrapling требует Python 3.10 или выше:

pip install scrapling

Important

Эта установка включает только движок парсера и его зависимости, без каких-либо Fetcher'ов или зависимостей командной строки. Поэтому импорт чего-либо из scrapling.fetchers или scrapling.spiders, как в примерах выше, вызовет ModuleNotFoundError при такой установке. Если вы собираетесь использовать какие-либо Fetcher'ы или Spider'ы, сначала установите зависимости 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

Вы также можете установить Docker-образ со всеми дополнениями и браузерами с помощью следующей команды из DockerHub:

docker pull pyd4vinci/scrapling

Или скачайте его из реестра GitHub:

docker pull ghcr.io/d4vinci/scrapling:latest

Этот образ автоматически создаётся и публикуется с помощью GitHub Actions и основной ветки репозитория.

Участие в разработке

Мы приветствуем участие! Пожалуйста, прочитайте наши руководства по участию в разработке перед началом работы.

Отказ от ответственности

Caution

Эта библиотека предоставляется только в образовательных и исследовательских целях. Используя эту библиотеку, вы соглашаетесь соблюдать местные и международные законы о скрапинге данных и конфиденциальности. Авторы и участники не несут ответственности за любое неправомерное использование этого программного обеспечения. Всегда уважайте условия обслуживания веб-сайтов и файлы 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

---

Разработано и создано с ❤️ Карим Шоаир.