graph-crawler 4.0.4

Sync-First бібліотека для побудови графу веб-сайтів - просто як requests!

GraphCrawler

Python бібліотека для сканування веб-сайтів та побудови графу їх структури.

🚀 Python 3.14 Optimizations

GraphCrawler 4.0 оптимізований для Python 3.14 з підтримкою free-threading:

• ⚡ 2-4x швидше HTML парсинг (free-threading)
• 🚀 3.2x швидше end-to-end crawling
• 📉 16% менше memory usage
• ⏱️ 30% швидший startup

Free-threading Mode (рекомендовано)

# Увімкнути free-threading для максимальної швидкості
export PYTHON_GIL=0
python your_script.py

Встановлення

pip install -e .

Optional dependencies

# Playwright driver (для JavaScript сайтів)
pip install -e ".[playwright]"

# Векторизація тексту (плагін)
pip install -e ".[embeddings]"

# Content extractors (плагіни)
pip install -e ".[articles]"

# MongoDB/PostgreSQL storage
pip install -e ".[mongodb,postgresql]"

# Все разом
pip install -e ".[all]"

Швидкий старт

import graph_crawler as gc

# Синхронний API (рекомендовано)
graph = gc.crawl("https://example.com")

print(f"Знайдено {len(graph.nodes)} сторінок")
print(f"Знайдено {len(graph.edges)} посилань")

API

Sync API

import graph_crawler as gc

# Функція crawl()
graph = gc.crawl(
    "https://example.com",
    max_depth=3,        # Максимальна глибина (default: 3)
    max_pages=100,      # Максимум сторінок (default: 100)
    same_domain=True,   # Тільки поточний домен (default: True)
    timeout=300,        # Таймаут в секундах
    request_delay=0.5,  # Затримка між запитами (default: 0.5)
    driver="http",      # "http", "async", "playwright"
)

# Клас Crawler (reusable)
with gc.Crawler(max_depth=3) as crawler:
    graph1 = crawler.crawl("https://site1.com")
    graph2 = crawler.crawl("https://site2.com")

Async API

import asyncio
import graph_crawler as gc

async def main():
    # Функція async_crawl()
    graph = await gc.async_crawl("https://example.com")
    
    # Клас AsyncCrawler (паралельний краулінг)
    async with gc.AsyncCrawler() as crawler:
        graphs = await asyncio.gather(
            crawler.crawl("https://site1.com"),
            crawler.crawl("https://site2.com"),
        )
    return graphs

graphs = asyncio.run(main())

Операції з графом

# Статистика
stats = graph.get_stats()
# {'total_nodes': 47, 'scanned_nodes': 45, 'total_edges': 156, ...}

# Пошук вузла
node = graph.get_node_by_url("https://example.com/page")

# Операції над графами
merged = graph1 + graph2      # Об'єднання
diff = graph2 - graph1        # Різниця
common = graph1 & graph2      # Перетин

# Порівняння
if graph1 < graph2:
    print("graph1 є підграфом graph2")

# Експорт
graph.export_edges("edges.json", format="json")
graph.export_edges("edges.csv", format="csv")
graph.export_edges("graph.dot", format="dot")

URL Rules

from graph_crawler import crawl, URLRule

rules = [
    URLRule(pattern=r".*\.pdf$", should_scan=False),     # Ігнорувати PDF
    URLRule(pattern=r"/products/", priority=10),         # Високий пріоритет
    URLRule(pattern=r"/admin/", should_scan=False),      # Ігнорувати admin
]

graph = crawl("https://example.com", url_rules=rules)

Плагіни

from graph_crawler import crawl, BaseNodePlugin, NodePluginType

class CustomPlugin(BaseNodePlugin):
    @property
    def name(self):
        return "custom_plugin"
    
    @property
    def plugin_type(self):
        return NodePluginType.ON_HTML_PARSED
    
    def execute(self, context):
        # context.html_tree - BeautifulSoup об'єкт
        # context.extracted_links - список посилань
        # context.user_data - словник для даних
        images = context.html_tree.find_all('img')
        context.user_data['image_count'] = len(images)
        return context

graph = crawl("https://example.com", plugins=[CustomPlugin()])

Драйвери

Драйвер	Опис	Використання
http	Async HTTP (aiohttp)	Статичні сайти (default)
async	Alias для http	Зворотня сумісність
playwright	Браузер з JS рендерингом	JavaScript сайти

# HTTP драйвер (default)
graph = gc.crawl("https://example.com", driver="http")

# Playwright для JavaScript сайтів
graph = gc.crawl("https://spa-example.com", driver="playwright")

Storage

Storage	Опис	Рекомендовано для
memory	В пам'яті	< 1,000 сторінок
json	JSON файл	1,000 - 20,000 сторінок
sqlite	SQLite база	20,000+ сторінок
postgresql	PostgreSQL	Великі проекти
mongodb	MongoDB	Великі проекти

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

graph_crawler/
├── api/              # Simple API (crawl, Crawler, async_crawl)
├── client/           # GraphCrawlerClient
├── core/             # Node, Edge, Graph, Events, Models
├── crawler/          # Spider, Scheduler, LinkProcessor, Filters
├── drivers/          # HTTP, Playwright драйвери
├── storage/          # Memory, JSON, SQLite, PostgreSQL, MongoDB
├── plugins/          # Node плагіни (vectorization, content_extractors)
├── middleware/       # Rate limiting, Retry, Robots.txt, Proxy
├── factories/        # Driver, Storage factories
├── containers/       # Dependency Injection containers
├── adapters/         # BeautifulSoup adapter
├── exporters/        # JSON, CSV, DOT exporters
└── utils/            # URL utils, DNS cache, Bloom filter

Тестування

pytest
pytest --cov=package_crawler

Вимоги

• Python 3.11+ (мінімальна версія)
• Залежності: див. requirements.txt

Яку версію Python обрати?

Версія	Рекомендовано для	Примітки
3.14	Максимальна швидкість	Free-threading (GIL=0), ~3.2x швидше
3.12-3.13	Візуалізація з коробки	Стабільні залежності (pyvis, networkx)
3.11	Сумісність	Всі функції працюють

Рекомендації для Python 3.14

# Free-threading для максимальної швидкості (рекомендовано)
export PYTHON_GIL=0

# JIT compiler (увімкнено за замовчуванням)
export PYTHON_JIT=1

# Запуск
python your_crawler.py

Очікувані результати:

• GIL enabled: ~115 pages/sec
• GIL disabled (free-threading): ~320 pages/sec (3.2x швидше!)

⚠️ Примітка: Деякі залежності візуалізації (pyvis, plotly) можуть бути нестабільні на Python 3.14. Якщо потрібна візуалізація з коробки — використовуйте Python 3.12 або 3.13.

Ліцензія

MIT

Автор

0-EternalJunior-0