Universal Web Parser (EASY + PRO)

Готовый к работе асинхронный парсер/краулер на Python 3.11+. Один файл —

• EASY — для обычных пользователей: даёте TXT со списком сайтов, получаете CSV/JSONL/SQLite с готовыми метаданными.
• PRO — для продвинутых: гибкий JSON‑конфиг, CSS/XPath, пагинация, сбор внутренних ссылок, фильтры URL, кэш,
  robots.txt
  , ретраи, прокси.

Быстрый девиз: “Минимум настроек, максимум пользы. При необходимости — полный контроль.”

Содержание

• Особенности

• Требования и установка

• Быстрый старт

  • EASY‑режим (самый простой вариант)
  • PRO‑режим (тонкая настройка)

• Примеры команд

• Файл

  sites.txt
  (для EASY)

• Форматы вывода

• Как это работает под капотом

• Конфигурация PRO — подробности

  • Пример конфига (CSS)
  • Пример конфига (XPath)
  • Пагинация и обход ссылок
  • Фильтры URL
  • Сеть: параллелизм, задержки, кэш, прокси

• Тюнинг производительности

• Диагностика и отладка

• ЧАВО (FAQ)

• Юридические и этические заметки

• Структура проекта

• Лицензия

Особенности

• Асинхронный сбор на aiohttp, чистое логирование, аккуратные ретраи.
• EASY‑режим: без правки кода — TXT со списком сайтов → готовый файл данных.
• PRO‑режим: селекторы CSS/XPath (
  ::text
  ,
  ::texts
  ,
  ::attr(name)
  ), пагинация, обнаружение ссылок.
• Уважение
  robots.txt
  , задержки, ограничение одновременных запросов.
• Кэш HTML на диск (TTL) + файл состояния для возобновления.
• Экспорт в CSV, JSONL, SQLite (имя таблицы задаётся опцией).
• Реалистичные User‑Agent строки, поддержка прокси (random/round_robin).

Требования и установка

• Python: 3.11 и выше.
• Зависимости:

Совет: создайте виртуальное окружение

python -m venv .venv && source .venv/bin/activate

(Windows:

.venv\\Scripts\\activate

).

Быстрый старт

EASY‑режим (самый простой вариант)

1. Создайте
   sites.txt
   (по одному URL на строку; пустые строки и строки с
   #
   игнорируются):

https://quotes.toscrape.com/
https://books.toscrape.com/
https://www.python.org/

2. Запустите сбор и получите CSV:

Другие варианты сохранения:

3. Чтобы обойти также несколько внутренних страниц того же домена:

По умолчанию EASY собирает:

PRO‑режим (тонкая настройка)

Работа через JSON‑конфиг. Сначала посмотрите текущие дефолты:

Сохраните их в файл и отредактируйте под свой сайт:

Запуск с конфигом:

Проверка селекторов на одном URL (без сохранения):

Примеры команд

Файл

sites.txt

(для EASY)

• Каждый URL с новой строки.
• Пустые строки и строки, начинающиеся на
  #
  , игнорируются.
• Если протокол опущен, он будет автоматически проставлен как
  https://
  .

Пример:

https://quotes.toscrape.com/
https://books.toscrape.com/
www.python.org
# комментарий

Форматы вывода

CSV

• Удобен для Excel/Google Sheets.
• Списки преобразуются в одну строку (через запятую).

JSONL

• По одной записи в строке. Хорош для потоковой обработки и больших объёмов.

SQLite

• Один файл базы данных. Таблица задаётся опцией
  --sqlite-table
  .
• Пример запроса:

Как это работает под капотом

• Асинхронные запросы через aiohttp.
• Вежливость: случайные задержки,
  per_host_delay
  , respect_robots.
• Кэш HTML (
  .cache/
  , TTL) — ускоряет повторные прогоны.
• Файл состояния (
  .state/visited_urls.txt
  ) — защищает от повторного обхода и позволяет продолжать.
• Обработка ошибок с ретраями и экспоненциальной паузой.

Конфигурация PRO — подробности

Пример конфига (CSS)

Пример конфига (XPath)

Суффиксы:

::text

— строка,

::texts

— список строк,

::attr(href)

— значение атрибута. Для ссылок/картинок значения автоматически приводятся к абсолютным URL через

urljoin

.

Пагинация и обход ссылок

• follow_next
  : указывает селектор кнопки «вперёд» и атрибут со ссылкой.
• discover_links
  : дополнительный сбор ссылок на странице (например, ссылки на карточки):

Фильтры URL

• url_filters.include
  — только URL, подходящие под любой из regex.
• url_filters.exclude
  — отбрасываются, если подходят под любой из regex.

Сеть: параллелизм, задержки, кэш, прокси

• concurrency
  — одновременных запросов.
• delay_range: [min, max]
  — случайная задержка между запросами.
• per_host_delay
  — пауза между запросами к одному хосту.
• cache_ttl
  — время жизни HTML в кэше (секунды).
• proxies
  — список прокси,
  proxy_mode: random | round_robin
  .

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

• Умеренно повышайте
  concurrency
  (например, 8 → 16), наблюдая за стабильностью.
• Для «тяжёлых» сайтов увеличьте
  per_host_delay
  (например, 0.5–1.0 сек).
• Временно отключите
  respect_robots
  только для локальных тестов на своих стендах.
• При повторных прогонах используйте кэш (
  cache_ttl
  ) и состояние — это ускорит сбор.

Диагностика и отладка

• Включите подробные логи:
  --debug
  .
• Снимки HTML сохраняются в
  .snapshots/
  (только при
  --debug
  ).
• Быстрый тест селекторов:
  test-url
  .
• Проверяйте регулярки фильтров URL на сайте regex101.com (внимательно экранируйте
  \
  ).

ЧАВО (FAQ)

Ничего не собралось. Что делать?

1. Запустите
   test-url
   и посмотрите, что возвращают селекторы.
2. Возможно, сайт отдаёт разметку динамически (JS). Попробуйте XPath, другие селекторы или статические страницы.
3. Включите
   --debug
   и изучите снапшот HTML в
   .snapshots/
   .

Как не перегружать сайт? Установите

Можно ли идти глубже по сайту в EASY? Да:

Как добавить прокси? В конфиге:

Где лежат кэш и состояние? Кэш:

Как открыть SQLite‑вывод?

Юридические и этические заметки

• Всегда проверяйте условия использования и правовые ограничения целевого сайта.
• Соблюдайте
  robots.txt
  и разумные лимиты скорости.
• Не собирайте персональные данные без правового основания.

Структура проекта

.
├── universal_web_parser.py   # основной файл
├── sites.txt                 # список сайтов (для EASY)
├── data/                     # папка для результатов (CSV/JSONL/SQLite)
├── .cache/                   # кэш HTML
├── .state/                   # файл состояния посещённых URL
└── .snapshots/               # HTML-снимки для отладки (при --debug)

Лицензия

Код предоставляется «как есть». Используйте и модифицируйте свободно. При цитировании лучше указывать источник: Universal Web Parser (EASY + PRO).

Контакты и помощь

Нужна настройка под конкретный сайт (карточки товаров, каталоги, новости, антибот‑обход, прокси‑ротация)? Опишите домен и желаемые поля — подготовим готовый конфиг/пример запуска.