+ + Effortless Web Scraping for the Modern Web +
+
-
- 
-
- Easy, effortless Web Scraping as it should be!
-
+ العربيه | Español | Deutsch | 简体中文 | 日本語 | Русский
+
@@ -27,44 +31,45 @@ Automated translations: [العربيه](README_AR.md) | [Español](README_ES.md
- - Selection methods - - · - - Choosing a fetcher - - · - - CLI - - · - - MCP mode - - · - - Migrating from Beautifulsoup - + Selection methods + · + Choosing a fetcher + · + CLI + · + MCP mode + · + Migrating from Beautifulsoup
-**Stop fighting anti-bot systems. Stop rewriting selectors after every website update.** +Scrapling is an adaptive Web Scraping framework that handles everything from a single request to a full-scale crawl. -Scrapling isn't just another Web Scraping library. It's the first **adaptive** scraping library that learns from website changes and evolves with them. While other libraries break when websites update their structure, Scrapling automatically relocates your elements and keeps your scrapers running. +Its parser learns from website changes and automatically relocates your elements when pages update. Its fetchers bypass anti-bot systems like Cloudflare Turnstile out of the box. And its spider framework lets you scale up to concurrent, multi-session crawls with pause/resume and automatic proxy rotation — all in a few lines of Python. One library, zero compromises. -Built for the modern Web, Scrapling features **its own rapid parsing engine** and fetchers to handle all Web Scraping challenges you face or will face. Built by Web Scrapers for Web Scrapers and regular users, there's something for everyone. +Blazing fast crawls with real-time stats and streaming. Built by Web Scrapers for Web Scrapers and regular users, there's something for everyone. ```python ->> from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher ->> StealthyFetcher.adaptive = True -# Fetch websites' source under the radar! ->> page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) ->> print(page.status) -200 ->> products = page.css('.product', auto_save=True) # Scrape data that survives website design changes! ->> # Later, if the website structure changes, pass `adaptive=True` ->> products = page.css('.product', adaptive=True) # and Scrapling still finds them! +from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher +StealthyFetcher.adaptive = True +page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) # Fetch website under the radar! +products = page.css('.product', auto_save=True) # Scrape data that survives website design changes! +products = page.css('.product', adaptive=True) # Later, if the website structure changes, pass `adaptive=True` to find them! ``` +Or scale up to full crawls +```python +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() +``` + # Sponsors @@ -77,6 +82,7 @@ Built for the modern Web, Scrapling features **its own rapid parsing engine** an
+
@@ -89,16 +95,27 @@ Built for the modern Web, Scrapling features **its own rapid parsing engine** an
## Key Features
+### Spiders — A Full Crawling Framework
+- 🕷️ **Scrapy-like Spider API**: Define spiders with `start_urls`, async `parse` callbacks, and `Request`/`Response` objects.
+- ⚡ **Concurrent Crawling**: Configurable concurrency limits, per-domain throttling, and download delays.
+- 🔄 **Multi-Session Support**: Unified interface for HTTP requests, and stealthy headless browsers in a single spider — route requests to different sessions by ID.
+- 💾 **Pause & Resume**: Checkpoint-based crawl persistence. Press Ctrl+C for a graceful shutdown; restart to resume from where you left off.
+- 📡 **Streaming Mode**: Stream scraped items as they arrive via `async for item in spider.stream()` with real-time stats — ideal for UI, pipelines, and long-running crawls.
+- 🛡️ **Blocked Request Detection**: Automatic detection and retry of blocked requests with customizable logic.
+- 📦 **Built-in Export**: Export results through hooks and your own pipeline or the built-in JSON/JSONL with `result.items.to_json()` / `result.items.to_jsonl()` respectively.
+
### Advanced Websites Fetching with Session Support
-- **HTTP Requests**: Fast and stealthy HTTP requests with the `Fetcher` class. Can impersonate browsers' TLS fingerprint, headers, and use HTTP3.
+- **HTTP Requests**: Fast and stealthy HTTP requests with the `Fetcher` class. Can impersonate browsers' TLS fingerprint, headers, and use HTTP/3.
- **Dynamic Loading**: Fetch dynamic websites with full browser automation through the `DynamicFetcher` class supporting Playwright's Chromium and Google's Chrome.
- **Anti-bot Bypass**: Advanced stealth capabilities with `StealthyFetcher` and fingerprint spoofing. Can easily bypass all types of Cloudflare's Turnstile/Interstitial with automation.
- **Session Management**: Persistent session support with `FetcherSession`, `StealthySession`, and `DynamicSession` classes for cookie and state management across requests.
+- **Proxy Rotation**: Built-in `ProxyRotator` with round-robin or custom strategies across all session types, plus per-request proxy overrides.
+- **Domain Blocking**: Block requests to specific domains (and their subdomains) in browser-based fetchers.
- **Async Support**: Complete async support across all fetchers and dedicated async session classes.
### Adaptive Scraping & AI Integration
- 🔄 **Smart Element Tracking**: Relocate elements after website changes using intelligent similarity algorithms.
-- 🎯 **Smart Flexible Selection**: CSS selectors, XPath selectors, filter-based search, text search, regex search, and more.
+- 🎯 **Smart Flexible Selection**: CSS selectors, XPath selectors, filter-based search, text search, regex search, and more.
- 🔍 **Find Similar Elements**: Automatically locate elements similar to found elements.
- 🤖 **MCP Server to be used with AI**: Built-in MCP server for AI-assisted Web Scraping and data extraction. The MCP server features powerful, custom capabilities that leverage Scrapling to extract targeted content before passing it to the AI (Claude/Cursor/etc), thereby speeding up operations and reducing costs by minimizing token usage. ([demo video](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
@@ -110,51 +127,107 @@ Built for the modern Web, Scrapling features **its own rapid parsing engine** an
### Developer/Web Scraper Friendly Experience
- 🎯 **Interactive Web Scraping Shell**: Optional built-in IPython shell with Scrapling integration, shortcuts, and new tools to speed up Web Scraping scripts development, like converting curl requests to Scrapling requests and viewing requests results in your browser.
-- 🚀 **Use it directly from the Terminal**: Optionally, you can use Scrapling to scrape a URL without writing a single code!
+- 🚀 **Use it directly from the Terminal**: Optionally, you can use Scrapling to scrape a URL without writing a single line of code!
- 🛠️ **Rich Navigation API**: Advanced DOM traversal with parent, sibling, and child navigation methods.
- 🧬 **Enhanced Text Processing**: Built-in regex, cleaning methods, and optimized string operations.
- 📝 **Auto Selector Generation**: Generate robust CSS/XPath selectors for any element.
- 🔌 **Familiar API**: Similar to Scrapy/BeautifulSoup with the same pseudo-elements used in Scrapy/Parsel.
-- 📘 **Complete Type Coverage**: Full type hints for excellent IDE support and code completion.
+- 📘 **Complete Type Coverage**: Full type hints for excellent IDE support and code completion. The entire codebase is automatically scanned with **PyRight** and **MyPy** with each change.
- 🔋 **Ready Docker image**: With each release, a Docker image containing all browsers is automatically built and pushed.
## Getting Started
-### Basic Usage
-```python
-from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher
-from scrapling.fetchers import FetcherSession, StealthySession, DynamicSession
+Let's give you a quick glimpse of what Scrapling can do without deep diving.
+
+### Basic Usage
+HTTP requests with session support
+```python
+from scrapling.fetchers import Fetcher, FetcherSession
-# HTTP requests with session support
with FetcherSession(impersonate='chrome') as session: # Use latest version of Chrome's TLS fingerprint
page = session.get('https://quotes.toscrape.com/', stealthy_headers=True)
- quotes = page.css('.quote .text::text')
+ quotes = page.css('.quote .text::text').getall()
# Or use one-off requests
page = Fetcher.get('https://quotes.toscrape.com/')
-quotes = page.css('.quote .text::text')
+quotes = page.css('.quote .text::text').getall()
+```
+Advanced stealth mode
+```python
+from scrapling.fetchers import StealthyFetcher, StealthySession
-# Advanced stealth mode (Keep the browser open until you finish)
-with StealthySession(headless=True, solve_cloudflare=True) as session:
+with StealthySession(headless=True, solve_cloudflare=True) as session: # Keep the browser open until you finish
page = session.fetch('https://nopecha.com/demo/cloudflare', google_search=False)
- data = page.css('#padded_content a')
+ data = page.css('#padded_content a').getall()
# Or use one-off request style, it opens the browser for this request, then closes it after finishing
page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')
-data = page.css('#padded_content a')
-
-# Full browser automation (Keep the browser open until you finish)
-with DynamicSession(headless=True, disable_resources=False, network_idle=True) as session:
+data = page.css('#padded_content a').getall()
+```
+Full browser automation
+```python
+from scrapling.fetchers import DynamicFetcher, DynamicSession
+
+with DynamicSession(headless=True, disable_resources=False, network_idle=True) as session: # Keep the browser open until you finish
page = session.fetch('https://quotes.toscrape.com/', load_dom=False)
- data = page.xpath('//span[@class="text"]/text()') # XPath selector if you prefer it
+ data = page.xpath('//span[@class="text"]/text()').getall() # XPath selector if you prefer it
# Or use one-off request style, it opens the browser for this request, then closes it after finishing
page = DynamicFetcher.fetch('https://quotes.toscrape.com/')
-data = page.css('.quote .text::text')
+data = page.css('.quote .text::text').getall()
```
-> [!NOTE]
-> There's a wonderful guide to get you started quickly with Scrapling [here](https://substack.thewebscraping.club/p/scrapling-hands-on-guide) written by The Web Scraping Club. In case you find it easier to get you started than the [documentation website](https://scrapling.readthedocs.io/en/latest/).
+### Spiders
+Build full crawlers with concurrent requests, multiple session types, and pause/resume:
+```python
+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"Scraped {len(result.items)} quotes")
+result.items.to_json("quotes.json")
+```
+Use multiple session types in a single spider:
+```python
+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():
+ # Route protected pages through the stealth session
+ if "protected" in link:
+ yield Request(link, sid="stealth")
+ else:
+ yield Request(link, sid="fast", callback=self.parse) # explicit callback
+```
+Pause and resume long crawls with checkpoints by running the spider like this:
+```python
+QuotesSpider(crawldir="./crawl_data").start()
+```
+Press Ctrl+C to pause gracefully — progress is saved automatically. Later, when you start the spider again, pass the same `crawldir`, and it will resume from where it stopped.
### Advanced Parsing & Navigation
```python
@@ -175,10 +248,9 @@ quotes = page.find_all(class_='quote') # and so on...
quotes = page.find_by_text('quote', tag='div')
# Advanced navigation
-first_quote = page.css_first('.quote')
-quote_text = first_quote.css('.text::text')
-quote_text = page.css('.quote').css_first('.text::text') # Chained selectors
-quote_text = page.css_first('.quote .text').text # Using `css_first` is faster than `css` if you want the first element
+quote_text = page.css('.quote')[0].css('.text::text').get()
+quote_text = page.css('.quote').css('.text::text').getall() # Chained selectors
+first_quote = page.css('.quote')[0]
author = first_quote.next_sibling.css('.author::text')
parent_container = first_quote.parent
@@ -219,7 +291,7 @@ async with AsyncStealthySession(max_pages=2) as session:
## CLI & Interactive Shell
-Scrapling v0.3 includes a powerful command-line interface:
+Scrapling includes a powerful command-line interface:
[](https://asciinema.org/a/736339)
@@ -236,34 +308,34 @@ scrapling extract stealthy-fetch 'https://nopecha.com/demo/cloudflare' captchas.
```
> [!NOTE]
-> There are many additional features, but we want to keep this page concise, such as the MCP server and the interactive Web Scraping Shell. Check out the full documentation [here](https://scrapling.readthedocs.io/en/latest/)
+> There are many additional features, but we want to keep this page concise, including the MCP server and the interactive Web Scraping Shell. Check out the full documentation [here](https://scrapling.readthedocs.io/en/latest/)
## Performance Benchmarks
-Scrapling isn't just powerful—it's also blazing fast, and the updates since version 0.3 have delivered exceptional performance improvements across all operations. The following benchmarks compare Scrapling's parser with other popular libraries.
+Scrapling isn't just powerful—it's also blazing fast. The following benchmarks compare Scrapling's parser with the latest versions of other popular libraries.
### Text Extraction Speed Test (5000 nested elements)
| # | Library | Time (ms) | vs Scrapling |
|---|:-----------------:|:---------:|:------------:|
-| 1 | Scrapling | 1.99 | 1.0x |
-| 2 | Parsel/Scrapy | 2.01 | 1.01x |
-| 3 | Raw Lxml | 2.5 | 1.256x |
-| 4 | PyQuery | 22.93 | ~11.5x |
-| 5 | Selectolax | 80.57 | ~40.5x |
-| 6 | BS4 with Lxml | 1541.37 | ~774.6x |
-| 7 | MechanicalSoup | 1547.35 | ~777.6x |
-| 8 | BS4 with html5lib | 3410.58 | ~1713.9x |
+| 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 |
### Element Similarity & Text Search Performance
Scrapling's adaptive element finding capabilities significantly outperform alternatives:
-| Library | Time (ms) | vs Scrapling |
+| Library | Time (ms) | vs Scrapling |
|-------------|:---------:|:------------:|
-| Scrapling | 2.46 | 1.0x |
-| AutoScraper | 13.3 | 5.407x |
+| Scrapling | 2.39 | 1.0x |
+| AutoScraper | 12.45 | 5.209x |
> All benchmarks represent averages of 100+ runs. See [benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py) for methodology.
@@ -276,7 +348,7 @@ Scrapling requires Python 3.10 or higher:
pip install scrapling
```
-Starting with v0.3.2, this installation only includes the parser engine and its dependencies, without any fetchers or commandline dependencies.
+This installation only includes the parser engine and its dependencies, without any fetchers or commandline dependencies.
### Optional Dependencies
@@ -333,12 +405,5 @@ This work is licensed under the BSD-3-Clause License.
This project includes code adapted from:
- Parsel (BSD License)—Used for [translator](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/translator.py) submodule
-## Thanks and References
-
-- [Daijro](https://github.com/daijro)'s brilliant work on [BrowserForge](https://github.com/daijro/browserforge) and [Camoufox](https://github.com/daijro/camoufox)
-- [Vinyzu](https://github.com/Vinyzu)'s brilliant work on [Botright](https://github.com/Vinyzu/Botright) and [PatchRight](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)
-- [brotector](https://github.com/kaliiiiiiiiii/brotector) for browser detection bypass techniques
-- [fakebrowser](https://github.com/kkoooqq/fakebrowser) and [BotBrowser](https://github.com/botswin/BotBrowser) for fingerprinting research
-
---
-
-
-
- استخراج بيانات الويب بسهولة ويسر كما يجب أن يكون!
-
+
@@ -24,46 +29,47 @@
- - طرق الاختيار - - · - - اختيار الجالب - - · - - واجهة سطر الأوامر - - · - - وضع MCP - - · - - الانتقال من Beautifulsoup - + طرق الاختيار + · + اختيار Fetcher + · + واجهة سطر الأوامر + · + وضع MCP + · + الانتقال من Beautifulsoup
-**توقف عن محاربة أنظمة مكافحة الروبوتات. توقف عن إعادة كتابة المحددات بعد كل تحديث للموقع.** +Scrapling هو إطار عمل تكيفي لـ Web Scraping يتعامل مع كل شيء من طلب واحد إلى زحف كامل النطاق. -Scrapling ليست مجرد مكتبة أخرى لاستخراج بيانات الويب. إنها أول مكتبة استخراج **تكيفية** تتعلم من تغييرات المواقع وتتطور معها. بينما تتعطل المكتبات الأخرى عندما تحدث المواقع بنيتها، يعيد Scrapling تحديد موقع عناصرك تلقائياً ويحافظ على عمل أدوات الاستخراج الخاصة بك. +محلله يتعلم من تغييرات المواقع ويعيد تحديد موقع عناصرك تلقائياً عند تحديث الصفحات. جوالبه تتجاوز أنظمة مكافحة الروبوتات مثل Cloudflare Turnstile مباشرةً. وإطار عمل Spider الخاص به يتيح لك التوسع إلى عمليات زحف متزامنة ومتعددة الجلسات مع إيقاف/استئناف وتدوير تلقائي لـ Proxy - كل ذلك في بضعة أسطر من Python. مكتبة واحدة، بدون تنازلات. -مبني للويب الحديث، يتميز Scrapling **بمحرك تحليل سريع خاص به** وجوالب للتعامل مع جميع تحديات استخراج بيانات الويب التي تواجهها أو ستواجهها. مبني بواسطة مستخرجي الويب لمستخرجي الويب والمستخدمين العاديين، هناك شيء للجميع. +زحف سريع للغاية مع إحصائيات فورية و Streaming. مبني بواسطة مستخرجي الويب لمستخرجي الويب والمستخدمين العاديين، هناك شيء للجميع. ```python ->> from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher ->> StealthyFetcher.adaptive = True -# احصل على كود المصدر للمواقع بشكل خفي! ->> page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) ->> print(page.status) -200 ->> products = page.css('.product', auto_save=True) # استخرج البيانات التي تنجو من تغييرات تصميم الموقع! ->> # لاحقاً، إذا تغيرت بنية الموقع، مرر `adaptive=True` ->> products = page.css('.product', adaptive=True) # و Scrapling لا يزال يجدها! +from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher +StealthyFetcher.adaptive = True +page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) # احصل على الموقع بشكل خفي! +products = page.css('.product', auto_save=True) # استخرج بيانات تنجو من تغييرات تصميم الموقع! +products = page.css('.product', adaptive=True) # لاحقاً، إذا تغيرت بنية الموقع، مرر `adaptive=True` للعثور عليها! +``` +أو توسع إلى عمليات زحف كاملة +```python +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() ``` -# الرعاة + +# الرعاة @@ -74,6 +80,7 @@ Scrapling ليست مجرد مكتبة أخرى لاستخراج بيانات ا
+
@@ -86,138 +93,211 @@ Scrapling ليست مجرد مكتبة أخرى لاستخراج بيانات ا
## الميزات الرئيسية
+### Spiders — إطار عمل زحف كامل
+- 🕷️ **واجهة Spider شبيهة بـ Scrapy**: عرّف Spiders مع `start_urls`، و async `parse` callbacks، وكائنات `Request`/`Response`.
+- ⚡ **زحف متزامن**: حدود تزامن قابلة للتكوين، وتحكم بالسرعة حسب النطاق، وتأخيرات التنزيل.
+- 🔄 **دعم الجلسات المتعددة**: واجهة موحدة لطلبات HTTP، ومتصفحات خفية بدون واجهة في Spider واحد — وجّه الطلبات إلى جلسات مختلفة بالمعرّف.
+- 💾 **إيقاف واستئناف**: استمرارية الزحف القائمة على Checkpoint. اضغط Ctrl+C للإيقاف بسلاسة؛ أعد التشغيل للاستئناف من حيث توقفت.
+- 📡 **وضع Streaming**: بث العناصر المستخرجة فور وصولها عبر `async for item in spider.stream()` مع إحصائيات فورية — مثالي لواجهات المستخدم وخطوط الأنابيب وعمليات الزحف الطويلة.
+- 🛡️ **كشف الطلبات المحظورة**: كشف تلقائي وإعادة محاولة للطلبات المحظورة مع منطق قابل للتخصيص.
+- 📦 **تصدير مدمج**: صدّر النتائج عبر الخطافات وخط الأنابيب الخاص بك أو JSON/JSONL المدمج مع `result.items.to_json()` / `result.items.to_jsonl()` على التوالي.
+
### جلب متقدم للمواقع مع دعم الجلسات
-- **طلبات HTTP**: طلبات HTTP سريعة وخفية مع فئة `Fetcher`. يمكنها تقليد بصمة TLS للمتصفح والرؤوس واستخدام HTTP3.
+- **طلبات HTTP**: طلبات HTTP سريعة وخفية مع فئة `Fetcher`. يمكنها تقليد بصمة TLS للمتصفح والرؤوس واستخدام HTTP/3.
- **التحميل الديناميكي**: جلب المواقع الديناميكية مع أتمتة كاملة للمتصفح من خلال فئة `DynamicFetcher` التي تدعم Chromium من Playwright و Google Chrome.
-- **تجاوز مكافحة الروبوتات**: قدرات تخفي متقدمة مع `StealthyFetcher` وانتحال البصمات. يمكنه تجاوز جميع أنواع Turnstile/Interstitial من Cloudflare بسهولة بالأتمتة.
+- **تجاوز مكافحة الروبوتات**: قدرات تخفي متقدمة مع `StealthyFetcher` وانتحال fingerprint. يمكنه تجاوز جميع أنواع Turnstile/Interstitial من Cloudflare بسهولة بالأتمتة.
- **إدارة الجلسات**: دعم الجلسات المستمرة مع فئات `FetcherSession` و`StealthySession` و`DynamicSession` لإدارة ملفات تعريف الارتباط والحالة عبر الطلبات.
+- **تدوير Proxy**: `ProxyRotator` مدمج مع استراتيجيات round-robin أو مخصصة عبر جميع أنواع الجلسات، بالإضافة إلى تجاوزات Proxy لكل طلب.
+- **حظر النطاقات**: حظر الطلبات إلى نطاقات محددة (ونطاقاتها الفرعية) في الجوالب المعتمدة على المتصفح.
- **دعم Async**: دعم async كامل عبر جميع الجوالب وفئات الجلسات async المخصصة.
### الاستخراج التكيفي والتكامل مع الذكاء الاصطناعي
- 🔄 **تتبع العناصر الذكي**: إعادة تحديد موقع العناصر بعد تغييرات الموقع باستخدام خوارزميات التشابه الذكية.
- 🎯 **الاختيار المرن الذكي**: محددات CSS، محددات XPath، البحث القائم على الفلاتر، البحث النصي، البحث بالتعبيرات العادية والمزيد.
- 🔍 **البحث عن عناصر مشابهة**: تحديد العناصر المشابهة للعناصر الموجودة تلقائياً.
-- 🤖 **خادم MCP للاستخدام مع الذكاء الاصطناعي**: خادم MCP مدمج لاستخراج بيانات الويب بمساعدة الذكاء الاصطناعي واستخراج البيانات. يتميز خادم MCP بقدرات قوية مخصصة تستفيد من Scrapling لاستخراج المحتوى المستهدف قبل تمريره إلى الذكاء الاصطناعي (Claude/Cursor/إلخ)، وبالتالي تسريع العمليات وتقليل التكاليف عن طريق تقليل استخدام الرموز. ([فيديو توضيحي](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
+- 🤖 **خادم MCP للاستخدام مع الذكاء الاصطناعي**: خادم MCP مدمج لـ Web Scraping بمساعدة الذكاء الاصطناعي واستخراج البيانات. يتميز خادم MCP بقدرات قوية مخصصة تستفيد من Scrapling لاستخراج المحتوى المستهدف قبل تمريره إلى الذكاء الاصطناعي (Claude/Cursor/إلخ)، وبالتالي تسريع العمليات وتقليل التكاليف عن طريق تقليل استخدام الرموز. ([فيديو توضيحي](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
-### بنية عالية الأداء ومختبرة في المعارك
-- 🚀 **سريع كالبرق**: أداء محسّن يتفوق على معظم مكتبات استخراج Python.
+### بنية عالية الأداء ومختبرة ميدانياً
+- 🚀 **سريع كالبرق**: أداء محسّن يتفوق على معظم مكتبات Web Scraping في Python.
- 🔋 **فعال في استخدام الذاكرة**: هياكل بيانات محسّنة وتحميل كسول لأقل استخدام للذاكرة.
- ⚡ **تسلسل JSON سريع**: أسرع 10 مرات من المكتبة القياسية.
-- 🏗️ **مُختبر في المعارك**: لا يمتلك Scrapling فقط تغطية اختبار بنسبة 92٪ وتغطية كاملة لتلميحات الأنواع، ولكن تم استخدامه يومياً من قبل مئات مستخرجي الويب خلال العام الماضي.
+- 🏗️ **مُختبر ميدانياً**: لا يمتلك Scrapling فقط تغطية اختبار بنسبة 92٪ وتغطية كاملة لتلميحات الأنواع، بل تم استخدامه يومياً من قبل مئات مستخرجي الويب خلال العام الماضي.
### تجربة صديقة للمطورين/مستخرجي الويب
-- 🎯 **غلاف استخراج ويب تفاعلي**: غلاف IPython مدمج اختياري مع تكامل Scrapling، واختصارات، وأدوات جديدة لتسريع تطوير سكريبتات استخراج الويب، مثل تحويل طلبات curl إلى طلبات Scrapling وعرض نتائج الطلبات في متصفحك.
+- 🎯 **Shell تفاعلي لـ Web Scraping**: Shell IPython مدمج اختياري مع تكامل Scrapling، واختصارات، وأدوات جديدة لتسريع تطوير سكريبتات Web Scraping، مثل تحويل طلبات curl إلى طلبات Scrapling وعرض نتائج الطلبات في متصفحك.
- 🚀 **استخدمه مباشرة من الطرفية**: اختيارياً، يمكنك استخدام Scrapling لاستخراج عنوان URL دون كتابة سطر واحد من الكود!
-- 🛠️ **واجهة برمجة تطبيقات التنقل الغنية**: اجتياز DOM متقدم مع طرق التنقل بين الوالدين والأشقاء والأطفال.
-- 🧬 **معالجة نصوص محسّنة**: تعبيرات عادية مدمجة وطرق تنظيف وعمليات سلسلة محسّنة.
-- 📝 **إنشاء محدد تلقائي**: إنشاء محددات CSS/XPath قوية لأي عنصر.
-- 🔌 **واجهة برمجة تطبيقات مألوفة**: مشابه لـ Scrapy/BeautifulSoup مع نفس العناصر الزائفة المستخدمة في Scrapy/Parsel.
-- 📘 **تغطية كاملة للأنواع**: تلميحات نوع كاملة لدعم IDE ممتاز وإكمال الكود.
+- 🛠️ **واجهة تنقل غنية**: اجتياز DOM متقدم مع طرق التنقل بين العناصر الوالدية والشقيقة والفرعية.
+- 🧬 **معالجة نصوص محسّنة**: تعبيرات عادية مدمجة وطرق تنظيف وعمليات نصية محسّنة.
+- 📝 **إنشاء محددات تلقائي**: إنشاء محددات CSS/XPath قوية لأي عنصر.
+- 🔌 **واجهة مألوفة**: مشابه لـ Scrapy/BeautifulSoup مع نفس العناصر الزائفة المستخدمة في Scrapy/Parsel.
+- 📘 **تغطية كاملة للأنواع**: تلميحات نوع كاملة لدعم IDE ممتاز وإكمال الكود. يتم فحص قاعدة الكود بالكامل تلقائياً بواسطة **PyRight** و**MyPy** مع كل تغيير.
- 🔋 **صورة Docker جاهزة**: مع كل إصدار، يتم بناء ودفع صورة Docker تحتوي على جميع المتصفحات تلقائياً.
## البدء
-### الاستخدام الأساسي
-```python
-from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher
-from scrapling.fetchers import FetcherSession, StealthySession, DynamicSession
+لنلقِ نظرة سريعة على ما يمكن لـ Scrapling فعله دون التعمق.
+
+### الاستخدام الأساسي
+طلبات HTTP مع دعم الجلسات
+```python
+from scrapling.fetchers import Fetcher, FetcherSession
-# طلبات HTTP مع دعم الجلسات
with FetcherSession(impersonate='chrome') as session: # استخدم أحدث إصدار من بصمة TLS لـ Chrome
page = session.get('https://quotes.toscrape.com/', stealthy_headers=True)
- quotes = page.css('.quote .text::text')
+ quotes = page.css('.quote .text::text').getall()
# أو استخدم طلبات لمرة واحدة
page = Fetcher.get('https://quotes.toscrape.com/')
-quotes = page.css('.quote .text::text')
+quotes = page.css('.quote .text::text').getall()
+```
+وضع التخفي المتقدم
+```python
+from scrapling.fetchers import StealthyFetcher, StealthySession
-# وضع التخفي المتقدم (احتفظ بالمتصفح مفتوحاً حتى تنتهي)
-with StealthySession(headless=True, solve_cloudflare=True) as session:
+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')
+ data = page.css('#padded_content a').getall()
# أو استخدم نمط الطلب لمرة واحدة، يفتح المتصفح لهذا الطلب، ثم يغلقه بعد الانتهاء
page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')
-data = page.css('#padded_content a')
-
-# أتمتة المتصفح الكاملة (احتفظ بالمتصفح مفتوحاً حتى تنتهي)
-with DynamicSession(headless=True) as session:
- page = session.fetch('https://quotes.toscrape.com/', network_idle=True)
- quotes = page.css('.quote .text::text')
+data = page.css('#padded_content a').getall()
+```
+أتمتة المتصفح الكاملة
+```python
+from scrapling.fetchers import DynamicFetcher, DynamicSession
-# أو استخدم نمط الطلب لمرة واحدة
-page = DynamicFetcher.fetch('https://quotes.toscrape.com/', network_idle=True)
-quotes = page.css('.quote .text::text')
+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()
```
-### اختيار العناصر
+### Spiders
+ابنِ زواحف كاملة مع طلبات متزامنة وأنواع جلسات متعددة وإيقاف/استئناف:
```python
-# محددات CSS
-page.css('a::text') # استخراج النص
-page.css('a::attr(href)') # استخراج السمات
-page.css('a', recursive=False) # العناصر المباشرة فقط
-page.css('a', auto_save=True) # حفظ مواضع العناصر تلقائياً
+from scrapling.spiders import Spider, Request, Response
-# XPath
-page.xpath('//a/text()')
+class QuotesSpider(Spider):
+ name = "quotes"
+ start_urls = ["https://quotes.toscrape.com/"]
+ concurrent_requests = 10
-# بحث مرن
-page.find_by_text('Python', first_match=True) # البحث بالنص
-page.find_by_regex(r'\d{4}') # البحث بنمط التعبير العادي
-page.find('div', {'class': 'container'}) # البحث بالسمات
+ 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(),
+ }
-# التنقل
-element.parent # الحصول على العنصر الوالد
-element.next_sibling # الحصول على الشقيق التالي
-element.children # الحصول على الأطفال
+ next_page = response.css('.next a')
+ if next_page:
+ yield response.follow(next_page[0].attrib['href'])
-# عناصر مشابهة
-similar = page.get_similar(element) # البحث عن عناصر مشابهة
-
-# الاستخراج التكيفي
-saved_elements = page.css('.product', auto_save=True)
-# لاحقاً، عندما يتغير الموقع:
-page.css('.product', adaptive=True) # البحث عن العناصر باستخدام المواضع المحفوظة
+result = QuotesSpider().start()
+print(f"Scraped {len(result.items)} quotes")
+result.items.to_json("quotes.json")
```
-
-### استخدام الجلسة
+استخدم أنواع جلسات متعددة في Spider واحد:
```python
-from scrapling.fetchers import FetcherSession, AsyncFetcherSession
+from scrapling.spiders import Spider, Request, Response
+from scrapling.fetchers import FetcherSession, AsyncStealthySession
-# جلسة متزامنة
-with FetcherSession() as session:
- # يتم الاحتفاظ بملفات تعريف الارتباط تلقائياً
- page1 = session.get('https://quotes.toscrape.com/login')
- page2 = session.post('https://quotes.toscrape.com/login', data={'username': 'admin', 'password': 'admin'})
-
- # تبديل بصمة المتصفح إذا لزم الأمر
+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():
+ # وجّه الصفحات المحمية عبر جلسة التخفي
+ if "protected" in link:
+ yield Request(link, sid="stealth")
+ else:
+ yield Request(link, sid="fast", callback=self.parse) # callback صريح
+```
+أوقف واستأنف عمليات الزحف الطويلة مع Checkpoints بتشغيل Spider هكذا:
+```python
+QuotesSpider(crawldir="./crawl_data").start()
+```
+اضغط Ctrl+C للإيقاف بسلاسة — يتم حفظ التقدم تلقائياً. لاحقاً، عند تشغيل Spider مرة أخرى، مرر نفس `crawldir`، وسيستأنف من حيث توقف.
+
+### التحليل المتقدم والتنقل
+```python
+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()
+```
+يمكنك استخدام المحلل مباشرة إذا كنت لا تريد جلب المواقع كما يلي:
+```python
+from scrapling.parser import Selector
+
+page = Selector("...")
+```
+وهو يعمل بنفس الطريقة تماماً!
+
+### أمثلة إدارة الجلسات بشكل Async
+```python
+import asyncio
+from scrapling.fetchers import FetcherSession, AsyncStealthySession, AsyncDynamicSession
+
+async with FetcherSession(http3=True) as session: # `FetcherSession` واعٍ بالسياق ويعمل في كلا النمطين المتزامن/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())
```
-## واجهة سطر الأوامر والغلاف التفاعلي
+## واجهة سطر الأوامر والـ Shell التفاعلي
-يتضمن Scrapling v0.3 واجهة سطر أوامر قوية:
+يتضمن Scrapling واجهة سطر أوامر قوية:
[](https://asciinema.org/a/736339)
-تشغيل غلاف استخراج الويب التفاعلي
+تشغيل Shell الـ Web Scraping التفاعلي
```bash
scrapling shell
```
-استخراج الصفحات إلى ملف مباشرة دون برمجة (يستخرج المحتوى داخل وسم `body` افتراضياً). إذا انتهى ملف الإخراج بـ `.txt`، فسيتم استخراج محتوى النص للهدف. إذا انتهى بـ `.md`، فسيكون تمثيل Markdown لمحتوى HTML؛ إذا انتهى بـ `.html`، فسيكون محتوى HTML نفسه.
+استخرج الصفحات إلى ملف مباشرة دون برمجة (يستخرج المحتوى داخل وسم `body` افتراضياً). إذا انتهى ملف الإخراج بـ `.txt`، فسيتم استخراج محتوى النص للهدف. إذا انتهى بـ `.md`، فسيكون تمثيل Markdown لمحتوى HTML؛ إذا انتهى بـ `.html`، فسيكون محتوى HTML نفسه.
```bash
scrapling extract get 'https://example.com' content.md
scrapling extract get 'https://example.com' content.txt --css-selector '#fromSkipToProducts' --impersonate 'chrome' # جميع العناصر المطابقة لمحدد CSS '#fromSkipToProducts'
@@ -226,24 +306,24 @@ scrapling extract stealthy-fetch 'https://nopecha.com/demo/cloudflare' captchas.
```
> [!NOTE]
-> هناك العديد من الميزات الإضافية، لكننا نريد إبقاء هذه الصفحة موجزة، مثل خادم MCP وغلاف استخراج الويب التفاعلي. تحقق من الوثائق الكاملة [هنا](https://scrapling.readthedocs.io/en/latest/)
+> هناك العديد من الميزات الإضافية، لكننا نريد إبقاء هذه الصفحة موجزة، بما في ذلك خادم MCP والـ Shell التفاعلي لـ Web Scraping. تحقق من الوثائق الكاملة [هنا](https://scrapling.readthedocs.io/en/latest/)
## معايير الأداء
-Scrapling ليس قوياً فقط - إنه أيضاً سريع بشكل مذهل، والتحديثات منذ الإصدار 0.3 قدمت تحسينات أداء استثنائية عبر جميع العمليات. تقارن المعايير التالية محلل Scrapling مع المكتبات الشائعة الأخرى.
+Scrapling ليس قوياً فحسب — بل هو أيضاً سريع بشكل مذهل. تقارن المعايير التالية محلل Scrapling مع أحدث إصدارات المكتبات الشائعة الأخرى.
### اختبار سرعة استخراج النص (5000 عنصر متداخل)
-| # | المكتبة | الوقت (ms) | vs Scrapling |
+| # | المكتبة | الوقت (ms) | vs Scrapling |
|---|:-----------------:|:----------:|:------------:|
-| 1 | Scrapling | 1.99 | 1.0x |
-| 2 | Parsel/Scrapy | 2.01 | 1.01x |
-| 3 | Raw Lxml | 2.5 | 1.256x |
-| 4 | PyQuery | 22.93 | ~11.5x |
-| 5 | Selectolax | 80.57 | ~40.5x |
-| 6 | BS4 with Lxml | 1541.37 | ~774.6x |
-| 7 | MechanicalSoup | 1547.35 | ~777.6x |
-| 8 | BS4 with html5lib | 3410.58 | ~1713.9x |
+| 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 |
### أداء تشابه العناصر والبحث النصي
@@ -252,39 +332,39 @@ Scrapling ليس قوياً فقط - إنه أيضاً سريع بشكل مذه
| المكتبة | الوقت (ms) | vs Scrapling |
|-------------|:----------:|:------------:|
-| Scrapling | 2.46 | 1.0x |
-| AutoScraper | 13.3 | 5.407x |
+| Scrapling | 2.39 | 1.0x |
+| AutoScraper | 12.45 | 5.209x |
> تمثل جميع المعايير متوسطات أكثر من 100 تشغيل. انظر [benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py) للمنهجية.
## التثبيت
-يتطلب Scrapling Python 3.10 أو أعلى:
+يتطلب Scrapling إصدار Python 3.10 أو أعلى:
```bash
pip install scrapling
```
-بدءاً من v0.3.2، يتضمن هذا التثبيت فقط محرك المحلل وتبعياته، بدون أي جوالب أو تبعيات سطر أوامر.
+يتضمن هذا التثبيت فقط محرك المحلل وتبعياته، بدون أي جوالب أو تبعيات سطر الأوامر.
### التبعيات الاختيارية
1. إذا كنت ستستخدم أياً من الميزات الإضافية أدناه، أو الجوالب، أو فئاتها، فستحتاج إلى تثبيت تبعيات الجوالب وتبعيات المتصفح الخاصة بها على النحو التالي:
```bash
pip install "scrapling[fetchers]"
-
+
scrapling install
```
- يقوم هذا بتنزيل جميع المتصفحات، إلى جانب تبعيات النظام وتبعيات معالجة البصمات الخاصة بها.
+ يقوم هذا بتنزيل جميع المتصفحات، إلى جانب تبعيات النظام وتبعيات معالجة fingerprint الخاصة بها.
2. ميزات إضافية:
- تثبيت ميزة خادم MCP:
```bash
pip install "scrapling[ai]"
```
- - تثبيت ميزات الغلاف (غلاف استخراج الويب وأمر `extract`):
+ - تثبيت ميزات Shell (Shell الـ Web Scraping وأمر `extract`):
```bash
pip install "scrapling[shell]"
```
@@ -321,14 +401,7 @@ docker pull ghcr.io/d4vinci/scrapling:latest
## الشكر والتقدير
يتضمن هذا المشروع كوداً معدلاً من:
-- Parsel (ترخيص BSD) - يستخدم للوحدة الفرعية [translator](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/translator.py)
-
-## الشكر والمراجع
-
-- العمل الرائع لـ [Daijro](https://github.com/daijro) على [BrowserForge](https://github.com/daijro/browserforge) و[Camoufox](https://github.com/daijro/camoufox)
-- العمل الرائع لـ [Vinyzu](https://github.com/Vinyzu) على [Botright](https://github.com/Vinyzu/Botright) و[PatchRight](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)
-- [brotector](https://github.com/kaliiiiiiiiii/brotector) لتقنيات تجاوز اكتشاف المتصفح
-- [fakebrowser](https://github.com/kkoooqq/fakebrowser) و[BotBrowser](https://github.com/botswin/BotBrowser) لأبحاث البصمات
+- Parsel (ترخيص BSD) — يُستخدم للوحدة الفرعية [translator](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/translator.py)
---
-
-
-
-
- 简单、轻松的网页抓取，本该如此！
-
+
@@ -24,46 +29,47 @@
- - 选择方法 - - · - - 选择获取器 - - · - - 命令行界面 - - · - - MCP模式 - - · - - 从Beautifulsoup迁移 - + 选择方法 + · + 选择Fetcher + · + CLI + · + MCP模式 + · + 从Beautifulsoup迁移
-**停止与反机器人系统斗争。停止在每次网站更新后重写选择器。** +Scrapling是一个自适应Web Scraping框架，能处理从单个请求到大规模爬取的一切需求。 -Scrapling不仅仅是另一个网页抓取库。它是第一个**自适应**抓取库，能够从网站变化中学习并与之共同进化。当其他库在网站更新结构时失效，Scrapling会自动重新定位您的元素并保持抓取器运行。 +它的解析器能够从网站变化中学习，并在页面更新时自动重新定位您的元素。它的Fetcher能够开箱即用地绕过Cloudflare Turnstile等反机器人系统。它的Spider框架让您可以扩展到并发、多Session爬取，支持暂停/恢复和自动Proxy轮换——只需几行Python代码。一个库，零妥协。 -为现代网络而构建，Scrapling具有**自己的快速解析引擎**和获取器来处理您面临或将要面临的所有网页抓取挑战。由网页抓取者为网页抓取者和普通用户构建，适合每个人。 +极速爬取，实时统计和Streaming。由Web Scraper为Web Scraper和普通用户而构建，每个人都能找到适合自己的功能。 ```python ->> from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher ->> StealthyFetcher.adaptive = True -# 隐秘地获取网站源代码！ ->> page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) ->> print(page.status) -200 ->> products = page.css('.product', auto_save=True) # 抓取在网站设计变更后仍能存活的数据！ ->> # 之后，如果网站结构改变，传递 `adaptive=True` ->> products = page.css('.product', adaptive=True) # Scrapling仍然能找到它们！ +from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher +StealthyFetcher.adaptive = True +page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) # 隐秘地获取网站！ +products = page.css('.product', auto_save=True) # 抓取在网站设计变更后仍能存活的数据！ +products = page.css('.product', adaptive=True) # 之后，如果网站结构改变，传递 `adaptive=True` 来找到它们！ +``` +或扩展为完整爬取 +```python +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() ``` -# 赞助商 + +# 赞助商 @@ -74,6 +80,7 @@ Scrapling不仅仅是另一个网页抓取库。它是第一个**自适应**抓
+
@@ -86,122 +93,195 @@ Scrapling不仅仅是另一个网页抓取库。它是第一个**自适应**抓
## 主要特性
-### 支持会话的高级网站获取
-- **HTTP请求**：使用`Fetcher`类进行快速和隐秘的HTTP请求。可以模拟浏览器的TLS指纹、标头并使用HTTP3。
+### Spider — 完整的爬取框架
+- 🕷️ **类Scrapy的Spider API**：使用`start_urls`、async `parse` callback和`Request`/`Response`对象定义Spider。
+- ⚡ **并发爬取**：可配置的并发限制、按域名节流和下载延迟。
+- 🔄 **多Session支持**：统一接口，支持HTTP请求和隐秘无头浏览器在同一个Spider中使用——通过ID将请求路由到不同的Session。
+- 💾 **暂停与恢复**：基于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。
- **动态加载**：通过`DynamicFetcher`类使用完整的浏览器自动化获取动态网站，支持Playwright的Chromium和Google Chrome。
-- **反机器人绕过**：使用`StealthyFetcher`的高级隐秘功能和指纹伪装。可以轻松自动绕过所有类型的Cloudflare的Turnstile/Interstitial。
-- **会话管理**：使用`FetcherSession`、`StealthySession`和`DynamicSession`类持久化会话支持，用于跨请求的cookie和状态管理。
-- **异步支持**：所有获取器和专用异步会话类的完整异步支持。
+- **反机器人绕过**：使用`StealthyFetcher`的高级隐秘功能和fingerprint伪装。可以轻松自动绕过所有类型的Cloudflare Turnstile/Interstitial。
+- **Session管理**：使用`FetcherSession`、`StealthySession`和`DynamicSession`类实现持久化Session支持，用于跨请求的cookie和状态管理。
+- **Proxy轮换**：内置`ProxyRotator`，支持轮询或自定义策略，适用于所有Session类型，并支持按请求覆盖Proxy。
+- **域名屏蔽**：在基于浏览器的Fetcher中屏蔽对特定域名（及其子域名）的请求。
+- **Async支持**：所有Fetcher和专用async Session类的完整async支持。
### 自适应抓取和AI集成
- 🔄 **智能元素跟踪**：使用智能相似性算法在网站更改后重新定位元素。
- 🎯 **智能灵活选择**：CSS选择器、XPath选择器、基于过滤器的搜索、文本搜索、正则表达式搜索等。
-- 🔍 **查找相似元素**：自动定位与找到的元素相似的元素。
-- 🤖 **与AI一起使用的MCP服务器**：内置MCP服务器用于AI辅助网页抓取和数据提取。MCP服务器具有强大的自定义功能，利用Scrapling在将内容传递给AI（Claude/Cursor等）之前提取目标内容，从而加快操作并通过最小化令牌使用来降低成本。（[演示视频](https://www.youtube.com/watch?v=qyFk3ZNwOxE)）
+- 🔍 **查找相似元素**：自动定位与已找到元素相似的元素。
+- 🤖 **与AI一起使用的MCP服务器**：内置MCP服务器用于AI辅助Web Scraping和数据提取。MCP服务器具有强大的自定义功能，利用Scrapling在将内容传递给AI（Claude/Cursor等）之前提取目标内容，从而加快操作并通过最小化token使用来降低成本。（[演示视频](https://www.youtube.com/watch?v=qyFk3ZNwOxE)）
### 高性能和经过实战测试的架构
- 🚀 **闪电般快速**：优化性能超越大多数Python抓取库。
- 🔋 **内存高效**：优化的数据结构和延迟加载，最小内存占用。
- ⚡ **快速JSON序列化**：比标准库快10倍。
-- 🏗️ **经过实战测试**：Scrapling不仅拥有92%的测试覆盖率和完整的类型提示覆盖率，而且在过去一年中每天被数百名网页抓取者使用。
+- 🏗️ **经过实战测试**：Scrapling不仅拥有92%的测试覆盖率和完整的类型提示覆盖率，而且在过去一年中每天被数百名Web Scraper使用。
-### 对开发者/网页抓取者友好的体验
-- 🎯 **交互式网页抓取Shell**：可选的内置IPython shell，具有Scrapling集成、快捷方式和新工具，可加快网页抓取脚本开发，例如将curl请求转换为Scrapling请求并在浏览器中查看请求结果。
+### 对开发者/Web Scraper友好的体验
+- 🎯 **交互式Web Scraping Shell**：可选的内置IPython Shell，具有Scrapling集成、快捷方式和新工具，可加快Web Scraping脚本开发，例如将curl请求转换为Scrapling请求并在浏览器中查看请求结果。
- 🚀 **直接从终端使用**：可选地，您可以使用Scrapling抓取URL而无需编写任何代码！
- 🛠️ **丰富的导航API**：使用父级、兄弟级和子级导航方法进行高级DOM遍历。
- 🧬 **增强的文本处理**：内置正则表达式、清理方法和优化的字符串操作。
- 📝 **自动选择器生成**：为任何元素生成强大的CSS/XPath选择器。
- 🔌 **熟悉的API**：类似于Scrapy/BeautifulSoup，使用与Scrapy/Parsel相同的伪元素。
-- 📘 **完整的类型覆盖**：完整的类型提示，出色的IDE支持和代码补全。
+- 📘 **完整的类型覆盖**：完整的类型提示，出色的IDE支持和代码补全。整个代码库在每次更改时都会自动使用**PyRight**和**MyPy**扫描。
- 🔋 **现成的Docker镜像**：每次发布时，包含所有浏览器的Docker镜像会自动构建和推送。
## 入门
-### 基本用法
-```python
-from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher
-from scrapling.fetchers import FetcherSession, StealthySession, DynamicSession
+让我们快速展示Scrapling的功能，无需深入了解。
-# 支持会话的HTTP请求
-with FetcherSession(impersonate='chrome') as session: # 使用Chrome的最新版本TLS指纹
+### 基本用法
+支持Session的HTTP请求
+```python
+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')
+ quotes = page.css('.quote .text::text').getall()
# 或使用一次性请求
page = Fetcher.get('https://quotes.toscrape.com/')
-quotes = page.css('.quote .text::text')
+quotes = page.css('.quote .text::text').getall()
+```
+高级隐秘模式
+```python
+from scrapling.fetchers import StealthyFetcher, StealthySession
-# 高级隐秘模式（保持浏览器打开直到完成）
-with StealthySession(headless=True, solve_cloudflare=True) as session:
+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')
+ data = page.css('#padded_content a').getall()
# 或使用一次性请求样式，为此请求打开浏览器，完成后关闭
page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')
-data = page.css('#padded_content a')
-
-# 完整的浏览器自动化（保持浏览器打开直到完成）
-with DynamicSession(headless=True) as session:
- page = session.fetch('https://quotes.toscrape.com/', network_idle=True)
- quotes = page.css('.quote .text::text')
+data = page.css('#padded_content a').getall()
+```
+完整的浏览器自动化
+```python
+from scrapling.fetchers import DynamicFetcher, DynamicSession
-# 或使用一次性请求样式
-page = DynamicFetcher.fetch('https://quotes.toscrape.com/', network_idle=True)
-quotes = page.css('.quote .text::text')
+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类型和暂停/恢复功能的完整爬虫：
```python
-# CSS选择器
-page.css('a::text') # 提取文本
-page.css('a::attr(href)') # 提取属性
-page.css('a', recursive=False) # 仅直接元素
-page.css('a', auto_save=True) # 自动保存元素位置
+from scrapling.spiders import Spider, Request, Response
-# XPath
-page.xpath('//a/text()')
+class QuotesSpider(Spider):
+ name = "quotes"
+ start_urls = ["https://quotes.toscrape.com/"]
+ concurrent_requests = 10
-# 灵活搜索
-page.find_by_text('Python', first_match=True) # 按文本查找
-page.find_by_regex(r'\d{4}') # 按正则表达式模式查找
-page.find('div', {'class': 'container'}) # 按属性查找
+ 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(),
+ }
-# 导航
-element.parent # 获取父元素
-element.next_sibling # 获取下一个兄弟元素
-element.children # 获取子元素
+ next_page = response.css('.next a')
+ if next_page:
+ yield response.follow(next_page[0].attrib['href'])
-# 相似元素
-similar = page.get_similar(element) # 查找相似元素
-
-# 自适应抓取
-saved_elements = page.css('.product', auto_save=True)
-# 之后，当网站更改时：
-page.css('.product', adaptive=True) # 使用保存的位置查找元素
+result = QuotesSpider().start()
+print(f"抓取了 {len(result.items)} 条引用")
+result.items.to_json("quotes.json")
```
-
-### 会话使用
+在单个Spider中使用多种Session类型：
```python
-from scrapling.fetchers import FetcherSession, AsyncFetcherSession
+from scrapling.spiders import Spider, Request, Response
+from scrapling.fetchers import FetcherSession, AsyncStealthySession
-# 同步会话
-with FetcherSession() as session:
- # Cookie自动保持
- page1 = session.get('https://quotes.toscrape.com/login')
- page2 = session.post('https://quotes.toscrape.com/login', data={'username': 'admin', 'password': 'admin'})
-
- # 如需要，切换浏览器指纹
+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
+```
+通过如下方式运行Spider来暂停和恢复长时间爬取，使用Checkpoint：
+```python
+QuotesSpider(crawldir="./crawl_data").start()
+```
+按Ctrl+C优雅暂停——进度会自动保存。之后，当您再次启动Spider时，传递相同的`crawldir`，它将从上次停止的地方继续。
+
+### 高级解析与导航
+```python
+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()
+```
+如果您不想获取网站，可以直接使用解析器，如下所示：
+```python
+from scrapling.parser import Selector
+
+page = Selector("...")
+```
+用法完全相同！
+
+### Async Session管理示例
+```python
+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 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())
@@ -209,11 +289,11 @@ async with AsyncStealthySession(max_pages=2) as session:
## CLI和交互式Shell
-Scrapling v0.3包含强大的命令行界面：
+Scrapling包含强大的命令行界面：
[](https://asciinema.org/a/736339)
-启动交互式网页抓取shell
+启动交互式Web Scraping Shell
```bash
scrapling shell
```
@@ -226,24 +306,24 @@ scrapling extract stealthy-fetch 'https://nopecha.com/demo/cloudflare' captchas.
```
> [!NOTE]
-> 还有许多其他功能，但我们希望保持此页面简洁，例如MCP服务器和交互式网页抓取Shell。查看完整文档[这里](https://scrapling.readthedocs.io/en/latest/)
+> 还有许多其他功能，但我们希望保持此页面简洁，包括MCP服务器和交互式Web Scraping Shell。查看完整文档[这里](https://scrapling.readthedocs.io/en/latest/)
## 性能基准
-Scrapling不仅功能强大——它还速度极快，自0.3版本以来的更新在所有操作中都提供了卓越的性能改进。以下基准测试将Scrapling的解析器与其他流行库进行了比较。
+Scrapling不仅功能强大——它还速度极快。以下基准测试将Scrapling的解析器与其他流行库的最新版本进行了比较。
### 文本提取速度测试（5000个嵌套元素）
-| # | 库 | 时间(ms) | vs Scrapling |
-|---|:-----------------:|:-------:|:------------:|
-| 1 | Scrapling | 1.99 | 1.0x |
-| 2 | Parsel/Scrapy | 2.01 | 1.01x |
-| 3 | Raw Lxml | 2.5 | 1.256x |
-| 4 | PyQuery | 22.93 | ~11.5x |
-| 5 | Selectolax | 80.57 | ~40.5x |
-| 6 | BS4 with Lxml | 1541.37 | ~774.6x |
-| 7 | MechanicalSoup | 1547.35 | ~777.6x |
-| 8 | BS4 with html5lib | 3410.58 | ~1713.9x |
+| # | 库 | 时间(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 |
### 元素相似性和文本搜索性能
@@ -251,9 +331,9 @@ Scrapling不仅功能强大——它还速度极快，自0.3版本以来的更
Scrapling的自适应元素查找功能明显优于替代方案：
| 库 | 时间(ms) | vs Scrapling |
-|-------------|:------:|:------------:|
-| Scrapling | 2.46 | 1.0x |
-| AutoScraper | 13.3 | 5.407x |
+|-------------|:---------:|:------------:|
+| Scrapling | 2.39 | 1.0x |
+| AutoScraper | 12.45 | 5.209x |
> 所有基准测试代表100+次运行的平均值。请参阅[benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py)了解方法。
@@ -266,25 +346,25 @@ Scrapling需要Python 3.10或更高版本：
pip install scrapling
```
-从v0.3.2开始，此安装仅包括解析器引擎及其依赖项，没有任何获取器或命令行依赖项。
+此安装仅包括解析器引擎及其依赖项，没有任何Fetcher或命令行依赖项。
### 可选依赖项
-1. 如果您要使用以下任何额外功能、获取器或它们的类，您将需要安装获取器的依赖项和它们的浏览器依赖项，如下所示：
+1. 如果您要使用以下任何额外功能、Fetcher或它们的类，您将需要安装Fetcher的依赖项和它们的浏览器依赖项，如下所示：
```bash
pip install "scrapling[fetchers]"
-
+
scrapling install
```
- 这会下载所有浏览器，以及它们的系统依赖项和指纹操作依赖项。
+ 这会下载所有浏览器，以及它们的系统依赖项和fingerprint操作依赖项。
2. 额外功能：
- 安装MCP服务器功能：
```bash
pip install "scrapling[ai]"
```
- - 安装shell功能（网页抓取shell和`extract`命令）：
+ - 安装Shell功能（Web Scraping Shell和`extract`命令）：
```bash
pip install "scrapling[shell]"
```
@@ -323,12 +403,5 @@ docker pull ghcr.io/d4vinci/scrapling:latest
此项目包含改编自以下内容的代码：
- Parsel（BSD许可证）——用于[translator](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/translator.py)子模块
-## 感谢和参考
-
-- [Daijro](https://github.com/daijro)在[BrowserForge](https://github.com/daijro/browserforge)和[Camoufox](https://github.com/daijro/camoufox)上的出色工作
-- [Vinyzu](https://github.com/Vinyzu)在[Botright](https://github.com/Vinyzu/Botright)和[PatchRight](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)上的出色工作
-- [brotector](https://github.com/kaliiiiiiiiii/brotector)提供的浏览器检测绕过技术
-- [fakebrowser](https://github.com/kkoooqq/fakebrowser)和[BotBrowser](https://github.com/botswin/BotBrowser)提供的指纹识别研究
-
---
-
-
-
-
- Einfaches, müheloses Web Scraping, wie es sein sollte!
-
+
@@ -24,46 +29,47 @@
- - Auswahlmethoden - - · - - Fetcher wählen - - · - - CLI - - · - - MCP-Modus - - · - - Migration von Beautifulsoup - + Auswahlmethoden + · + Einen Fetcher wählen + · + CLI + · + MCP-Modus + · + Migration von Beautifulsoup
-**Hören Sie auf, gegen Anti-Bot-Systeme zu kämpfen. Hören Sie auf, Selektoren nach jedem Website-Update neu zu schreiben.** +Scrapling ist ein adaptives Web-Scraping-Framework, das alles abdeckt -- von einer einzelnen Anfrage bis hin zu einem umfassenden Crawl. -Scrapling ist nicht nur eine weitere Web-Scraping-Bibliothek. Es ist die erste **adaptive** Scraping-Bibliothek, die von Website-Änderungen lernt und sich mit ihnen weiterentwickelt. Während andere Bibliotheken brechen, wenn Websites ihre Struktur aktualisieren, lokalisiert Scrapling Ihre Elemente automatisch neu und hält Ihre Scraper am Laufen. +Sein Parser lernt aus Website-Änderungen und lokalisiert Ihre Elemente automatisch neu, wenn sich Seiten aktualisieren. Seine Fetcher umgehen Anti-Bot-Systeme wie Cloudflare Turnstile direkt ab Werk. Und sein Spider-Framework ermöglicht es Ihnen, auf parallele Multi-Session-Crawls mit Pause & Resume und automatischer Proxy-Rotation hochzuskalieren -- alles in wenigen Zeilen Python. Eine Bibliothek, keine Kompromisse. -Für das moderne Web entwickelt, bietet Scrapling **seine eigene schnelle Parsing-Engine** und Fetcher, um alle Web-Scraping-Herausforderungen zu bewältigen, denen Sie begegnen oder begegnen werden. Von Web Scrapern für Web Scraper und normale Benutzer entwickelt, ist für jeden etwas dabei. +Blitzschnelle Crawls mit Echtzeit-Statistiken und Streaming. Von Web Scrapern für Web Scraper und normale Benutzer entwickelt, ist für jeden etwas dabei. ```python ->> from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher ->> StealthyFetcher.adaptive = True -# Holen Sie sich Website-Quellcode unter dem Radar! ->> page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) ->> print(page.status) -200 ->> products = page.css('.product', auto_save=True) # Scrapen Sie Daten, die Website-Designänderungen überleben! ->> # Später, wenn sich die Website-Struktur ändert, übergeben Sie `adaptive=True` ->> products = page.css('.product', adaptive=True) # und Scrapling findet sie trotzdem! +from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher +StealthyFetcher.adaptive = True +page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) # Website unbemerkt abrufen! +products = page.css('.product', auto_save=True) # Daten scrapen, die Website-Designänderungen überleben! +products = page.css('.product', adaptive=True) # Später, wenn sich die Website-Struktur ändert, `adaptive=True` übergeben, um sie zu finden! +``` +Oder auf vollständige Crawls hochskalieren +```python +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() ``` -# Sponsoren + +# Sponsoren @@ -74,6 +80,7 @@ Für das moderne Web entwickelt, bietet Scrapling **seine eigene schnelle Parsin
+
@@ -86,12 +93,23 @@ Für das moderne Web entwickelt, bietet Scrapling **seine eigene schnelle Parsin
## Hauptmerkmale
-### Erweiterte Website-Abruf mit Sitzungsunterstützung
-- **HTTP-Anfragen**: Schnelle und heimliche HTTP-Anfragen mit der `Fetcher`-Klasse. Kann Browser-TLS-Fingerabdrücke, Header imitieren und HTTP3 verwenden.
-- **Dynamisches Laden**: Abrufen dynamischer Websites mit vollständiger Browser-Automatisierung über die `DynamicFetcher`-Klasse, die Playwrights Chromium und Google Chrome unterstützt.
-- **Anti-Bot-Umgehung**: Erweiterte Stealth-Fähigkeiten mit `StealthyFetcher` und Fingerabdruck-Spoofing. Kann alle Arten von Cloudflares Turnstile/Interstitial einfach mit Automatisierung umgehen.
-- **Sitzungsverwaltung**: Persistente Sitzungsunterstützung mit den Klassen `FetcherSession`, `StealthySession` und `DynamicSession` für Cookie- und Zustandsverwaltung über Anfragen hinweg.
-- **Async-Unterstützung**: Vollständige Async-Unterstützung über alle Fetcher und dedizierte Async-Sitzungsklassen hinweg.
+### Spiders -- Ein vollständiges Crawling-Framework
+- 🕷️ **Scrapy-ähnliche Spider-API**: Definieren Sie Spiders mit `start_urls`, async `parse` Callbacks und `Request`/`Response`-Objekten.
+- ⚡ **Paralleles Crawling**: Konfigurierbare Parallelitätslimits, domainbezogenes Throttling und Download-Verzögerungen.
+- 🔄 **Multi-Session-Unterstützung**: Einheitliche Schnittstelle für HTTP-Anfragen und heimliche Headless-Browser in einem einzigen Spider -- leiten Sie Anfragen per ID an verschiedene Sessions weiter.
+- 💾 **Pause & Resume**: Checkpoint-basierte Crawl-Persistenz. Drücken Sie Strg+C für ein kontrolliertes Herunterfahren; starten Sie neu, um dort fortzufahren, wo Sie aufgehört haben.
+- 📡 **Streaming-Modus**: Gescrapte Elemente in Echtzeit streamen über `async for item in spider.stream()` mit Echtzeit-Statistiken -- ideal für UI, Pipelines und lang laufende Crawls.
+- 🛡️ **Erkennung blockierter Anfragen**: Automatische Erkennung und Wiederholung blockierter Anfragen mit anpassbarer Logik.
+- 📦 **Integrierter Export**: Ergebnisse über Hooks und Ihre eigene Pipeline oder den integrierten JSON/JSONL-Export mit `result.items.to_json()` / `result.items.to_jsonl()` exportieren.
+
+### Erweitertes Website-Abrufen mit Session-Unterstützung
+- **HTTP-Anfragen**: Schnelle und heimliche HTTP-Anfragen mit der `Fetcher`-Klasse. Kann Browser-TLS-Fingerprints und Header imitieren und HTTP/3 verwenden.
+- **Dynamisches Laden**: Dynamische Websites mit vollständiger Browser-Automatisierung über die `DynamicFetcher`-Klasse abrufen, die Playwrights Chromium und Google Chrome unterstützt.
+- **Anti-Bot-Umgehung**: Erweiterte Stealth-Fähigkeiten mit `StealthyFetcher` und Fingerprint-Spoofing. Kann alle Arten von Cloudflares Turnstile/Interstitial einfach mit Automatisierung umgehen.
+- **Session-Verwaltung**: Persistente Session-Unterstützung mit den Klassen `FetcherSession`, `StealthySession` und `DynamicSession` für Cookie- und Zustandsverwaltung über Anfragen hinweg.
+- **Proxy-Rotation**: Integrierter `ProxyRotator` mit Round-Robin- oder benutzerdefinierten Strategien über alle Session-Typen hinweg, plus Proxy-Überschreibungen pro Anfrage.
+- **Domain-Blockierung**: Anfragen an bestimmte Domains (und deren Subdomains) in browserbasierten Fetchern blockieren.
+- **Async-Unterstützung**: Vollständige async-Unterstützung über alle Fetcher und dedizierte async Session-Klassen hinweg.
### Adaptives Scraping & KI-Integration
- 🔄 **Intelligente Element-Verfolgung**: Elemente nach Website-Änderungen mit intelligenten Ähnlichkeitsalgorithmen neu lokalisieren.
@@ -105,103 +123,165 @@ Für das moderne Web entwickelt, bietet Scrapling **seine eigene schnelle Parsin
- ⚡ **Schnelle JSON-Serialisierung**: 10x schneller als die Standardbibliothek.
- 🏗️ **Praxiserprobt**: Scrapling hat nicht nur eine Testabdeckung von 92% und eine vollständige Type-Hints-Abdeckung, sondern wird seit dem letzten Jahr täglich von Hunderten von Web Scrapern verwendet.
-### Entwickler/Web-Scraper-freundliche Erfahrung
+### Entwickler-/Web-Scraper-freundliche Erfahrung
- 🎯 **Interaktive Web-Scraping-Shell**: Optionale integrierte IPython-Shell mit Scrapling-Integration, Shortcuts und neuen Tools zur Beschleunigung der Web-Scraping-Skriptentwicklung, wie das Konvertieren von Curl-Anfragen in Scrapling-Anfragen und das Anzeigen von Anfrageergebnissen in Ihrem Browser.
- 🚀 **Direkt vom Terminal aus verwenden**: Optional können Sie Scrapling verwenden, um eine URL zu scrapen, ohne eine einzige Codezeile zu schreiben!
- 🛠️ **Umfangreiche Navigations-API**: Erweiterte DOM-Traversierung mit Eltern-, Geschwister- und Kind-Navigationsmethoden.
- 🧬 **Verbesserte Textverarbeitung**: Integrierte Regex, Bereinigungsmethoden und optimierte String-Operationen.
- 📝 **Automatische Selektorgenerierung**: Robuste CSS/XPath-Selektoren für jedes Element generieren.
- 🔌 **Vertraute API**: Ähnlich wie Scrapy/BeautifulSoup mit denselben Pseudo-Elementen, die in Scrapy/Parsel verwendet werden.
-- 📘 **Vollständige Typabdeckung**: Vollständige Type Hints für hervorragende IDE-Unterstützung und Code-Vervollständigung.
+- 📘 **Vollständige Typabdeckung**: Vollständige Type Hints für hervorragende IDE-Unterstützung und Code-Vervollständigung. Die gesamte Codebasis wird bei jeder Änderung automatisch mit **PyRight** und **MyPy** gescannt.
- 🔋 **Fertiges Docker-Image**: Mit jeder Veröffentlichung wird automatisch ein Docker-Image erstellt und gepusht, das alle Browser enthält.
## Erste Schritte
+Hier ein kurzer Überblick über das, was Scrapling kann, ohne zu sehr ins Detail zu gehen.
+
### Grundlegende Verwendung
+HTTP-Anfragen mit Session-Unterstützung
```python
-from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher
-from scrapling.fetchers import FetcherSession, StealthySession, DynamicSession
+from scrapling.fetchers import Fetcher, FetcherSession
-# HTTP-Anfragen mit Sitzungsunterstützung
-with FetcherSession(impersonate='chrome') as session: # Verwenden Sie die neueste Version von Chromes TLS-Fingerabdruck
+with FetcherSession(impersonate='chrome') as session: # Neueste Version von Chromes TLS-Fingerprint verwenden
page = session.get('https://quotes.toscrape.com/', stealthy_headers=True)
- quotes = page.css('.quote .text::text')
+ quotes = page.css('.quote .text::text').getall()
-# Oder verwenden Sie einmalige Anfragen
+# Oder einmalige Anfragen verwenden
page = Fetcher.get('https://quotes.toscrape.com/')
-quotes = page.css('.quote .text::text')
+quotes = page.css('.quote .text::text').getall()
+```
+Erweiterter Stealth-Modus
+```python
+from scrapling.fetchers import StealthyFetcher, StealthySession
-# Erweiterter Stealth-Modus (Browser offen halten, bis Sie fertig sind)
-with StealthySession(headless=True, solve_cloudflare=True) as session:
+with StealthySession(headless=True, solve_cloudflare=True) as session: # Browser offen halten, bis Sie fertig sind
page = session.fetch('https://nopecha.com/demo/cloudflare', google_search=False)
- data = page.css('#padded_content a')
+ data = page.css('#padded_content a').getall()
-# Oder verwenden Sie den einmaligen Anfragenstil, öffnet den Browser für diese Anfrage und schließt ihn dann nach Abschluss
+# Oder einmaligen Anfragenstil verwenden: öffnet den Browser für diese Anfrage und schließt ihn nach Abschluss
page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')
-data = page.css('#padded_content a')
-
-# Vollständige Browser-Automatisierung (Browser offen halten, bis Sie fertig sind)
-with DynamicSession(headless=True) as session:
- page = session.fetch('https://quotes.toscrape.com/', network_idle=True)
- quotes = page.css('.quote .text::text')
+data = page.css('#padded_content a').getall()
+```
+Vollständige Browser-Automatisierung
+```python
+from scrapling.fetchers import DynamicFetcher, DynamicSession
-# Oder verwenden Sie den einmaligen Anfragenstil
-page = DynamicFetcher.fetch('https://quotes.toscrape.com/', network_idle=True)
-quotes = page.css('.quote .text::text')
+with DynamicSession(headless=True, disable_resources=False, network_idle=True) as session: # Browser offen halten, bis Sie fertig sind
+ page = session.fetch('https://quotes.toscrape.com/', load_dom=False)
+ data = page.xpath('//span[@class="text"]/text()').getall() # XPath-Selektor, falls bevorzugt
+
+# Oder einmaligen Anfragenstil verwenden: öffnet den Browser für diese Anfrage und schließt ihn nach Abschluss
+page = DynamicFetcher.fetch('https://quotes.toscrape.com/')
+data = page.css('.quote .text::text').getall()
```
-### Elementauswahl
+### Spiders
+Vollständige Crawler mit parallelen Anfragen, mehreren Session-Typen und Pause & Resume erstellen:
```python
-# CSS-Selektoren
-page.css('a::text') # Text extrahieren
-page.css('a::attr(href)') # Attribute extrahieren
-page.css('a', recursive=False) # Nur direkte Elemente
-page.css('a', auto_save=True) # Elementpositionen automatisch speichern
+from scrapling.spiders import Spider, Request, Response
-# XPath
-page.xpath('//a/text()')
+class QuotesSpider(Spider):
+ name = "quotes"
+ start_urls = ["https://quotes.toscrape.com/"]
+ concurrent_requests = 10
-# Flexible Suche
-page.find_by_text('Python', first_match=True) # Nach Text suchen
-page.find_by_regex(r'\d{4}') # Nach Regex-Muster suchen
-page.find('div', {'class': 'container'}) # Nach Attributen suchen
+ 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(),
+ }
-# Navigation
-element.parent # Elternelement abrufen
-element.next_sibling # Nächstes Geschwister abrufen
-element.children # Kindelemente abrufen
+ next_page = response.css('.next a')
+ if next_page:
+ yield response.follow(next_page[0].attrib['href'])
-# Ähnliche Elemente
-similar = page.get_similar(element) # Ähnliche Elemente finden
-
-# Adaptives Scraping
-saved_elements = page.css('.product', auto_save=True)
-# Später, wenn sich die Website ändert:
-page.css('.product', adaptive=True) # Elemente mithilfe gespeicherter Positionen finden
+result = QuotesSpider().start()
+print(f"{len(result.items)} Zitate gescrapt")
+result.items.to_json("quotes.json")
```
-
-### Sitzungsverwendung
+Mehrere Session-Typen in einem einzigen Spider verwenden:
```python
-from scrapling.fetchers import FetcherSession, AsyncFetcherSession
+from scrapling.spiders import Spider, Request, Response
+from scrapling.fetchers import FetcherSession, AsyncStealthySession
-# Synchrone Sitzung
-with FetcherSession() as session:
- # Cookies werden automatisch beibehalten
- page1 = session.get('https://quotes.toscrape.com/login')
- page2 = session.post('https://quotes.toscrape.com/login', data={'username': 'admin', 'password': 'admin'})
-
- # Bei Bedarf Browser-Fingerabdruck wechseln
+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():
+ # Geschützte Seiten über die Stealth-Session leiten
+ if "protected" in link:
+ yield Request(link, sid="stealth")
+ else:
+ yield Request(link, sid="fast", callback=self.parse) # Expliziter Callback
+```
+Lange Crawls mit Checkpoints pausieren und fortsetzen, indem Sie den Spider so starten:
+```python
+QuotesSpider(crawldir="./crawl_data").start()
+```
+Drücken Sie Strg+C, um kontrolliert zu pausieren -- der Fortschritt wird automatisch gespeichert. Wenn Sie den Spider später erneut starten, übergeben Sie dasselbe `crawldir`, und er setzt dort fort, wo er aufgehört hat.
+
+### Erweitertes Parsing & Navigation
+```python
+from scrapling.fetchers import Fetcher
+
+# Umfangreiche Elementauswahl und Navigation
+page = Fetcher.get('https://quotes.toscrape.com/')
+
+# Zitate mit verschiedenen Auswahlmethoden abrufen
+quotes = page.css('.quote') # CSS-Selektor
+quotes = page.xpath('//div[@class="quote"]') # XPath
+quotes = page.find_all('div', {'class': 'quote'}) # BeautifulSoup-Stil
+# Gleich wie
+quotes = page.find_all('div', class_='quote')
+quotes = page.find_all(['div'], class_='quote')
+quotes = page.find_all(class_='quote') # und so weiter...
+# Element nach Textinhalt finden
+quotes = page.find_by_text('quote', tag='div')
+
+# Erweiterte Navigation
+quote_text = page.css('.quote')[0].css('.text::text').get()
+quote_text = page.css('.quote').css('.text::text').getall() # Verkettete Selektoren
+first_quote = page.css('.quote')[0]
+author = first_quote.next_sibling.css('.author::text')
+parent_container = first_quote.parent
+
+# Elementbeziehungen und Ähnlichkeit
+similar_elements = first_quote.find_similar()
+below_elements = first_quote.below_elements()
+```
+Sie können den Parser direkt verwenden, wenn Sie keine Websites abrufen möchten, wie unten gezeigt:
+```python
+from scrapling.parser import Selector
+
+page = Selector("...")
+```
+Und es funktioniert genau auf die gleiche Weise!
+
+### Beispiele für async Session-Verwaltung
+```python
+import asyncio
+from scrapling.fetchers import FetcherSession, AsyncStealthySession, AsyncDynamicSession
+
+async with FetcherSession(http3=True) as session: # `FetcherSession` ist kontextbewusst und kann sowohl in sync- als auch in async-Mustern arbeiten
+ page1 = session.get('https://quotes.toscrape.com/')
page2 = session.get('https://quotes.toscrape.com/', impersonate='firefox135')
-# Async-Sitzungsverwendung
+# Async-Session-Verwendung
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()) # Optional - Der Status des Browser-Tab-Pools (beschäftigt/frei/Fehler)
results = await asyncio.gather(*tasks)
print(session.get_pool_stats())
@@ -209,7 +289,7 @@ async with AsyncStealthySession(max_pages=2) as session:
## CLI & Interaktive Shell
-Scrapling v0.3 enthält eine leistungsstarke Befehlszeilenschnittstelle:
+Scrapling enthält eine leistungsstarke Befehlszeilenschnittstelle:
[](https://asciinema.org/a/736339)
@@ -217,7 +297,7 @@ Interaktive Web-Scraping-Shell starten
```bash
scrapling shell
```
-Seiten direkt ohne Programmierung in eine Datei extrahieren (Extrahiert standardmäßig den Inhalt im `body`-Tag). Wenn die Ausgabedatei mit `.txt` endet, wird der Textinhalt des Ziels extrahiert. Wenn sie mit `.md` endet, ist es eine Markdown-Darstellung des HTML-Inhalts; wenn sie mit `.html` endet, ist es der HTML-Inhalt selbst.
+Seiten direkt ohne Programmierung in eine Datei extrahieren (extrahiert standardmäßig den Inhalt im `body`-Tag). Wenn die Ausgabedatei mit `.txt` endet, wird der Textinhalt des Ziels extrahiert. Wenn sie mit `.md` endet, ist es eine Markdown-Darstellung des HTML-Inhalts; wenn sie mit `.html` endet, ist es der HTML-Inhalt selbst.
```bash
scrapling extract get 'https://example.com' content.md
scrapling extract get 'https://example.com' content.txt --css-selector '#fromSkipToProducts' --impersonate 'chrome' # Alle Elemente, die dem CSS-Selektor '#fromSkipToProducts' entsprechen
@@ -226,24 +306,24 @@ scrapling extract stealthy-fetch 'https://nopecha.com/demo/cloudflare' captchas.
```
> [!NOTE]
-> Es gibt viele zusätzliche Funktionen, aber wir möchten diese Seite prägnant halten, wie den MCP-Server und die interaktive Web-Scraping-Shell. Schauen Sie sich die vollständige Dokumentation [hier](https://scrapling.readthedocs.io/en/latest/) an
+> Es gibt viele zusätzliche Funktionen, aber wir möchten diese Seite prägnant halten, einschließlich des MCP-Servers und der interaktiven Web-Scraping-Shell. Schauen Sie sich die vollständige Dokumentation [hier](https://scrapling.readthedocs.io/en/latest/) an
## Leistungsbenchmarks
-Scrapling ist nicht nur leistungsstark – es ist auch blitzschnell, und die Updates seit Version 0.3 haben außergewöhnliche Leistungsverbesserungen bei allen Operationen gebracht. Die folgenden Benchmarks vergleichen den Parser von Scrapling mit anderen beliebten Bibliotheken.
+Scrapling ist nicht nur leistungsstark -- es ist auch blitzschnell. Die folgenden Benchmarks vergleichen Scraplings Parser mit den neuesten Versionen anderer beliebter Bibliotheken.
### Textextraktions-Geschwindigkeitstest (5000 verschachtelte Elemente)
-| # | Bibliothek | Zeit (ms) | vs Scrapling |
+| # | Bibliothek | Zeit (ms) | vs Scrapling |
|---|:-----------------:|:---------:|:------------:|
-| 1 | Scrapling | 1.99 | 1.0x |
-| 2 | Parsel/Scrapy | 2.01 | 1.01x |
-| 3 | Raw Lxml | 2.5 | 1.256x |
-| 4 | PyQuery | 22.93 | ~11.5x |
-| 5 | Selectolax | 80.57 | ~40.5x |
-| 6 | BS4 with Lxml | 1541.37 | ~774.6x |
-| 7 | MechanicalSoup | 1547.35 | ~777.6x |
-| 8 | BS4 with html5lib | 3410.58 | ~1713.9x |
+| 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 |
### Element-Ähnlichkeit & Textsuche-Leistung
@@ -252,8 +332,8 @@ Scraplings adaptive Element-Finding-Fähigkeiten übertreffen Alternativen deutl
| Bibliothek | Zeit (ms) | vs Scrapling |
|-------------|:---------:|:------------:|
-| Scrapling | 2.46 | 1.0x |
-| AutoScraper | 13.3 | 5.407x |
+| Scrapling | 2.39 | 1.0x |
+| AutoScraper | 12.45 | 5.209x |
> Alle Benchmarks stellen Durchschnittswerte von über 100 Durchläufen dar. Siehe [benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py) für die Methodik.
@@ -266,18 +346,18 @@ Scrapling erfordert Python 3.10 oder höher:
pip install scrapling
```
-Ab v0.3.2 enthält diese Installation nur die Parser-Engine und ihre Abhängigkeiten, ohne Fetcher oder Kommandozeilenabhängigkeiten.
+Diese Installation enthält nur die Parser-Engine und ihre Abhängigkeiten, ohne Fetcher oder Kommandozeilenabhängigkeiten.
### Optionale Abhängigkeiten
1. Wenn Sie eine der folgenden zusätzlichen Funktionen, die Fetcher oder ihre Klassen verwenden möchten, müssen Sie die Abhängigkeiten der Fetcher und ihre Browser-Abhängigkeiten wie folgt installieren:
```bash
pip install "scrapling[fetchers]"
-
+
scrapling install
```
- Dies lädt alle Browser zusammen mit ihren Systemabhängigkeiten und Fingerabdruck-Manipulationsabhängigkeiten herunter.
+ Dies lädt alle Browser zusammen mit ihren Systemabhängigkeiten und Fingerprint-Manipulationsabhängigkeiten herunter.
2. Zusätzliche Funktionen:
- MCP-Server-Funktion installieren:
@@ -321,14 +401,7 @@ Diese Arbeit ist unter der BSD-3-Clause-Lizenz lizenziert.
## Danksagungen
Dieses Projekt enthält angepassten Code von:
-- Parsel (BSD-Lizenz) – Verwendet für [translator](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/translator.py)-Submodul
-
-## Dank und Referenzen
-
-- [Daijros](https://github.com/daijro) brillante Arbeit an [BrowserForge](https://github.com/daijro/browserforge) und [Camoufox](https://github.com/daijro/camoufox)
-- [Vinyzus](https://github.com/Vinyzu) brillante Arbeit an [Botright](https://github.com/Vinyzu/Botright) und [PatchRight](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)
-- [brotector](https://github.com/kaliiiiiiiiii/brotector) für Browser-Erkennungs-Umgehungstechniken
-- [fakebrowser](https://github.com/kkoooqq/fakebrowser) und [BotBrowser](https://github.com/botswin/BotBrowser) für Fingerprinting-Forschung
+- Parsel (BSD-Lizenz) -- Verwendet für das [translator](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/translator.py)-Submodul
---
-
-
-
-
- ¡Web Scraping fácil y sin esfuerzo como debería ser!
-
+
@@ -24,46 +29,47 @@
- - Métodos de selección - - · - - Elegir un fetcher - - · - - CLI - - · - - Modo MCP - - · - - Migrar desde Beautifulsoup - + Metodos de seleccion + · + Elegir un fetcher + · + CLI + · + Modo MCP + · + Migrar desde Beautifulsoup
-**Deja de luchar contra sistemas anti-bot. Deja de reescribir selectores después de cada actualización del sitio web.** +Scrapling es un framework de Web Scraping adaptativo que se encarga de todo, desde una sola solicitud hasta un rastreo a gran escala. -Scrapling no es solo otra biblioteca de Web Scraping. Es la primera biblioteca de scraping **adaptativa** que aprende de los cambios de los sitios web y evoluciona con ellos. Mientras que otras bibliotecas se rompen cuando los sitios web actualizan su estructura, Scrapling relocaliza automáticamente tus elementos y mantiene tus scrapers funcionando. +Su parser aprende de los cambios de los sitios web y relocaliza automáticamente tus elementos cuando las páginas se actualizan. Sus fetchers evaden sistemas anti-bot como Cloudflare Turnstile de forma nativa. Y su framework Spider te permite escalar a rastreos concurrentes con múltiples sesiones, con Pause & Resume y rotación automática de Proxy, todo en unas pocas líneas de Python. Una biblioteca, cero compromisos. -Construido para la Web moderna, Scrapling presenta **su propio motor de análisis rápido** y fetchers para manejar todos los desafíos de Web Scraping que enfrentas o enfrentarás. Construido por Web Scrapers para Web Scrapers y usuarios regulares, hay algo para todos. +Rastreos ultrarrápidos con estadísticas en tiempo real y Streaming. Construido por Web Scrapers para Web Scrapers y usuarios regulares, hay algo para todos. ```python ->> from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher ->> StealthyFetcher.adaptive = True -# ¡Obtén el código fuente de sitios web bajo el radar! ->> page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) ->> print(page.status) -200 ->> products = page.css('.product', auto_save=True) # ¡Extrae datos que sobreviven a cambios de diseño del sitio web! ->> # Más tarde, si la estructura del sitio web cambia, pasa `adaptive=True` ->> products = page.css('.product', adaptive=True) # ¡y Scrapling aún los encuentra! +from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher +StealthyFetcher.adaptive = True +page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) # ¡Obtén el sitio web bajo el radar! +products = page.css('.product', auto_save=True) # ¡Extrae datos que sobreviven a cambios de diseño del sitio web! +products = page.css('.product', adaptive=True) # Más tarde, si la estructura del sitio web cambia, ¡pasa `adaptive=True` para encontrarlos! +``` +O escala a rastreos completos +```python +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() ``` -# Patrocinadores + +# Patrocinadores @@ -74,6 +80,7 @@ Construido para la Web moderna, Scrapling presenta **su propio motor de análisi
+
@@ -86,24 +93,35 @@ Construido para la Web moderna, Scrapling presenta **su propio motor de análisi
## Características Principales
-### Obtención Avanzada de Sitios Web con Soporte de Sesión
-- **Solicitudes HTTP**: Solicitudes HTTP rápidas y sigilosas con la clase `Fetcher`. Puede imitar la huella TLS de los navegadores, encabezados y usar HTTP3.
+### Spiders — Un Framework Completo de Rastreo
+- 🕷️ **API de Spider al estilo Scrapy**: Define spiders con `start_urls`, callbacks async `parse`, y objetos `Request`/`Response`.
+- ⚡ **Rastreo Concurrente**: Límites de concurrencia configurables, limitación por dominio y retrasos de descarga.
+- 🔄 **Soporte Multi-Session**: Interfaz unificada para solicitudes HTTP y navegadores headless sigilosos en un solo Spider — enruta solicitudes a diferentes sesiones por ID.
+- 💾 **Pause & Resume**: Persistencia de rastreo basada en Checkpoint. Presiona Ctrl+C para un cierre ordenado; reinicia para continuar desde donde lo dejaste.
+- 📡 **Modo Streaming**: Transmite elementos extraídos a medida que llegan con `async for item in spider.stream()` con estadísticas en tiempo real — ideal para UI, pipelines y rastreos de larga duración.
+- 🛡️ **Detección de Solicitudes Bloqueadas**: Detección automática y reintento de solicitudes bloqueadas con lógica personalizable.
+- 📦 **Exportación Integrada**: Exporta resultados a través de hooks y tu propio pipeline o el JSON/JSONL integrado con `result.items.to_json()` / `result.items.to_jsonl()` respectivamente.
+
+### Obtención Avanzada de Sitios Web con Soporte de Session
+- **Solicitudes HTTP**: Solicitudes HTTP rápidas y sigilosas con la clase `Fetcher`. Puede imitar el fingerprint TLS de los navegadores, encabezados y usar HTTP/3.
- **Carga Dinámica**: Obtén sitios web dinámicos con automatización completa del navegador a través de la clase `DynamicFetcher` compatible con Chromium de Playwright y Google Chrome.
-- **Evasión Anti-bot**: Capacidades de sigilo avanzadas con `StealthyFetcher` y falsificación de huellas digitales. Puede evadir fácilmente todos los tipos de Turnstile/Interstitial de Cloudflare con automatización.
-- **Gestión de Sesión**: Soporte de sesión persistente con las clases `FetcherSession`, `StealthySession` y `DynamicSession` para la gestión de cookies y estado entre solicitudes.
+- **Evasión Anti-bot**: Capacidades de sigilo avanzadas con `StealthyFetcher` y falsificación de fingerprint. Puede evadir fácilmente todos los tipos de Turnstile/Interstitial de Cloudflare con automatización.
+- **Gestión de Session**: Soporte de sesión persistente con las clases `FetcherSession`, `StealthySession` y `DynamicSession` para la gestión de cookies y estado entre solicitudes.
+- **Rotación de Proxy**: `ProxyRotator` integrado con estrategias round-robin o personalizadas en todos los tipos de sesión, además de sobrescrituras de Proxy por solicitud.
+- **Bloqueo de Dominios**: Bloquea solicitudes a dominios específicos (y sus subdominios) en fetchers basados en navegador.
- **Soporte Async**: Soporte async completo en todos los fetchers y clases de sesión async dedicadas.
### Scraping Adaptativo e Integración con IA
- 🔄 **Seguimiento Inteligente de Elementos**: Relocaliza elementos después de cambios en el sitio web usando algoritmos inteligentes de similitud.
- 🎯 **Selección Flexible Inteligente**: Selectores CSS, selectores XPath, búsqueda basada en filtros, búsqueda de texto, búsqueda regex y más.
- 🔍 **Encontrar Elementos Similares**: Localiza automáticamente elementos similares a los elementos encontrados.
-- 🤖 **Servidor MCP para usar con IA**: Servidor MCP integrado para Web Scraping asistido por IA y extracción de datos. El servidor MCP presenta capacidades poderosas y personalizadas que aprovechan Scrapling para extraer contenido específico antes de pasarlo a la IA (Claude/Cursor/etc), acelerando así las operaciones y reduciendo costos al minimizar el uso de tokens. ([video demo](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
+- 🤖 **Servidor MCP para usar con IA**: Servidor MCP integrado para Web Scraping asistido por IA y extracción de datos. El servidor MCP presenta capacidades potentes y personalizadas que aprovechan Scrapling para extraer contenido específico antes de pasarlo a la IA (Claude/Cursor/etc), acelerando así las operaciones y reduciendo costos al minimizar el uso de tokens. ([video demo](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
### Arquitectura de Alto Rendimiento y Probada en Batalla
-- 🚀 **Ultrarrápido**: Rendimiento optimizado que supera a la mayoría de las bibliotecas de scraping de Python.
+- 🚀 **Ultrarrápido**: Rendimiento optimizado que supera a la mayoría de las bibliotecas de Web Scraping de Python.
- 🔋 **Eficiente en Memoria**: Estructuras de datos optimizadas y carga diferida para una huella de memoria mínima.
- ⚡ **Serialización JSON Rápida**: 10 veces más rápido que la biblioteca estándar.
-- 🏗️ **Probado en batalla**: Scrapling no solo tiene una cobertura de prueba del 92% y cobertura completa de type hints, sino que ha sido utilizado diariamente por cientos de Web Scrapers durante el último año.
+- 🏗️ **Probado en batalla**: Scrapling no solo tiene una cobertura de pruebas del 92% y cobertura completa de type hints, sino que ha sido utilizado diariamente por cientos de Web Scrapers durante el último año.
### Experiencia Amigable para Desarrolladores/Web Scrapers
- 🎯 **Shell Interactivo de Web Scraping**: Shell IPython integrado opcional con integración de Scrapling, atajos y nuevas herramientas para acelerar el desarrollo de scripts de Web Scraping, como convertir solicitudes curl a solicitudes Scrapling y ver resultados de solicitudes en tu navegador.
@@ -112,96 +130,158 @@ Construido para la Web moderna, Scrapling presenta **su propio motor de análisi
- 🧬 **Procesamiento de Texto Mejorado**: Métodos integrados de regex, limpieza y operaciones de cadena optimizadas.
- 📝 **Generación Automática de Selectores**: Genera selectores CSS/XPath robustos para cualquier elemento.
- 🔌 **API Familiar**: Similar a Scrapy/BeautifulSoup con los mismos pseudo-elementos usados en Scrapy/Parsel.
-- 📘 **Cobertura Completa de Tipos**: Type hints completos para excelente soporte de IDE y autocompletado de código.
+- 📘 **Cobertura Completa de Tipos**: Type hints completos para excelente soporte de IDE y autocompletado de código. Todo el código fuente se escanea automáticamente con **PyRight** y **MyPy** en cada cambio.
- 🔋 **Imagen Docker Lista**: Con cada lanzamiento, se construye y publica automáticamente una imagen Docker que contiene todos los navegadores.
-## Empezando
+## Primeros Pasos
+
+Aquí tienes un vistazo rápido de lo que Scrapling puede hacer sin entrar en profundidad.
### Uso Básico
+Solicitudes HTTP con soporte de sesión
```python
-from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher
-from scrapling.fetchers import FetcherSession, StealthySession, DynamicSession
+from scrapling.fetchers import Fetcher, FetcherSession
-# Solicitudes HTTP con soporte de sesión
-with FetcherSession(impersonate='chrome') as session: # Usa la última versión de la huella TLS de Chrome
+with FetcherSession(impersonate='chrome') as session: # Usa la última versión del fingerprint TLS de Chrome
page = session.get('https://quotes.toscrape.com/', stealthy_headers=True)
- quotes = page.css('.quote .text::text')
+ quotes = page.css('.quote .text::text').getall()
# O usa solicitudes de una sola vez
page = Fetcher.get('https://quotes.toscrape.com/')
-quotes = page.css('.quote .text::text')
+quotes = page.css('.quote .text::text').getall()
+```
+Modo sigiloso avanzado
+```python
+from scrapling.fetchers import StealthyFetcher, StealthySession
-# Modo sigiloso avanzado (Mantén el navegador abierto hasta que termines)
-with StealthySession(headless=True, solve_cloudflare=True) as session:
+with StealthySession(headless=True, solve_cloudflare=True) as session: # Mantén el navegador abierto hasta que termines
page = session.fetch('https://nopecha.com/demo/cloudflare', google_search=False)
- data = page.css('#padded_content a')
+ data = page.css('#padded_content a').getall()
# O usa el estilo de solicitud de una sola vez, abre el navegador para esta solicitud, luego lo cierra después de terminar
page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')
-data = page.css('#padded_content a')
-
-# Automatización completa del navegador (Mantén el navegador abierto hasta que termines)
-with DynamicSession(headless=True) as session:
- page = session.fetch('https://quotes.toscrape.com/', network_idle=True)
- quotes = page.css('.quote .text::text')
+data = page.css('#padded_content a').getall()
+```
+Automatización completa del navegador
+```python
+from scrapling.fetchers import DynamicFetcher, DynamicSession
-# O usa el estilo de solicitud de una sola vez
-page = DynamicFetcher.fetch('https://quotes.toscrape.com/', network_idle=True)
-quotes = page.css('.quote .text::text')
+with DynamicSession(headless=True, disable_resources=False, network_idle=True) as session: # Mantén el navegador abierto hasta que termines
+ page = session.fetch('https://quotes.toscrape.com/', load_dom=False)
+ data = page.xpath('//span[@class="text"]/text()').getall() # Selector XPath si lo prefieres
+
+# O usa el estilo de solicitud de una sola vez, abre el navegador para esta solicitud, luego lo cierra después de terminar
+page = DynamicFetcher.fetch('https://quotes.toscrape.com/')
+data = page.css('.quote .text::text').getall()
```
-### Selección de Elementos
+### Spiders
+Construye rastreadores completos con solicitudes concurrentes, múltiples tipos de sesión y Pause & Resume:
```python
-# CSS selectors
-page.css('a::text') # Extracta texto
-page.css('a::attr(href)') # Extracta atributos
-page.css('a', recursive=False) # Solo elementos directos
-page.css('a', auto_save=True) # Guarda posiciones de los elementos automáticamente
+from scrapling.spiders import Spider, Request, Response
-# XPath
-page.xpath('//a/text()')
+class QuotesSpider(Spider):
+ name = "quotes"
+ start_urls = ["https://quotes.toscrape.com/"]
+ concurrent_requests = 10
-# Búsqueda flexible
-page.find_by_text('Python', first_match=True) # Encuentra por texto
-page.find_by_regex(r'\d{4}') # Encuentra por patrón regex
-page.find('div', {'class': 'container'}) # Encuentra por atributos
+ 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(),
+ }
-# Navegación
-element.parent # Obtener elemento padre
-element.next_sibling # Obtener siguiente hermano
-element.children # Obtener hijos
+ next_page = response.css('.next a')
+ if next_page:
+ yield response.follow(next_page[0].attrib['href'])
-# Elementos similares
-similar = page.get_similar(element) # Encuentra elementos similares
-
-# Scraping adaptativo
-saved_elements = page.css('.product', auto_save=True)
-# Más tarde, cuando el sitio web cambia:
-page.css('.product', adaptive=True) # Encuentra elementos usando posiciones guardadas
+result = QuotesSpider().start()
+print(f"Se extrajeron {len(result.items)} citas")
+result.items.to_json("quotes.json")
```
-
-### Uso de Sesión
+Usa múltiples tipos de sesión en un solo Spider:
```python
-from scrapling.fetchers import FetcherSession, AsyncFetcherSession
+from scrapling.spiders import Spider, Request, Response
+from scrapling.fetchers import FetcherSession, AsyncStealthySession
-# Sesión sincrónica
-with FetcherSession() as session:
- # Las cookies se mantienen automáticamente
- page1 = session.get('https://quotes.toscrape.com/login')
- page2 = session.post('https://quotes.toscrape.com/login', data={'username': 'admin', 'password': 'admin'})
-
- # Cambiar fingerprint del navegador si es necesario
+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():
+ # Enruta las páginas protegidas a través de la sesión sigilosa
+ if "protected" in link:
+ yield Request(link, sid="stealth")
+ else:
+ yield Request(link, sid="fast", callback=self.parse) # callback explícito
+```
+Pausa y reanuda rastreos largos con checkpoints ejecutando el Spider así:
+```python
+QuotesSpider(crawldir="./crawl_data").start()
+```
+Presiona Ctrl+C para pausar de forma ordenada — el progreso se guarda automáticamente. Después, cuando inicies el Spider de nuevo, pasa el mismo `crawldir`, y continuará desde donde se detuvo.
+
+### Análisis Avanzado y Navegación
+```python
+from scrapling.fetchers import Fetcher
+
+# Selección rica de elementos y navegación
+page = Fetcher.get('https://quotes.toscrape.com/')
+
+# Obtén citas con múltiples métodos de selección
+quotes = page.css('.quote') # Selector CSS
+quotes = page.xpath('//div[@class="quote"]') # XPath
+quotes = page.find_all('div', {'class': 'quote'}) # Estilo BeautifulSoup
+# Igual que
+quotes = page.find_all('div', class_='quote')
+quotes = page.find_all(['div'], class_='quote')
+quotes = page.find_all(class_='quote') # y así sucesivamente...
+# Encuentra elementos por contenido de texto
+quotes = page.find_by_text('quote', tag='div')
+
+# Navegación avanzada
+quote_text = page.css('.quote')[0].css('.text::text').get()
+quote_text = page.css('.quote').css('.text::text').getall() # Selectores encadenados
+first_quote = page.css('.quote')[0]
+author = first_quote.next_sibling.css('.author::text')
+parent_container = first_quote.parent
+
+# Relaciones y similitud de elementos
+similar_elements = first_quote.find_similar()
+below_elements = first_quote.below_elements()
+```
+Puedes usar el parser directamente si no necesitas obtener sitios web, como se muestra a continuación:
+```python
+from scrapling.parser import Selector
+
+page = Selector("...")
+```
+¡Y funciona exactamente de la misma manera!
+
+### Ejemplos de Gestión de Session Async
+```python
+import asyncio
+from scrapling.fetchers import FetcherSession, AsyncStealthySession, AsyncDynamicSession
+
+async with FetcherSession(http3=True) as session: # `FetcherSession` es consciente del contexto y puede funcionar tanto en patrones sync/async
+ page1 = session.get('https://quotes.toscrape.com/')
page2 = session.get('https://quotes.toscrape.com/', impersonate='firefox135')
# Uso de sesión 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()) # Opcional - El estado del pool de pestañas del navegador (ocupado/libre/error)
results = await asyncio.gather(*tasks)
print(session.get_pool_stats())
@@ -209,11 +289,11 @@ async with AsyncStealthySession(max_pages=2) as session:
## CLI y Shell Interactivo
-Scrapling v0.3 incluye una poderosa interfaz de línea de comandos:
+Scrapling incluye una poderosa interfaz de línea de comandos:
[](https://asciinema.org/a/736339)
-Lanzar shell interactivo de Web Scraping
+Lanzar el Shell interactivo de Web Scraping
```bash
scrapling shell
```
@@ -226,24 +306,24 @@ scrapling extract stealthy-fetch 'https://nopecha.com/demo/cloudflare' captchas.
```
> [!NOTE]
-> Hay muchas características adicionales, pero queremos mantener esta página concisa, como el servidor MCP y el Shell Interactivo de Web Scraping. Consulta la documentación completa [aquí](https://scrapling.readthedocs.io/en/latest/)
+> Hay muchas características adicionales, pero queremos mantener esta página concisa, incluyendo el servidor MCP y el Shell Interactivo de Web Scraping. Consulta la documentación completa [aquí](https://scrapling.readthedocs.io/en/latest/)
## Benchmarks de Rendimiento
-Scrapling no solo es poderoso, también es increíblemente rápido, y las actualizaciones desde la versión 0.3 han brindado mejoras de rendimiento excepcionales en todas las operaciones. Los siguientes benchmarks comparan el analizador de Scrapling con otras bibliotecas populares.
+Scrapling no solo es potente, también es ultrarrápido. Los siguientes benchmarks comparan el parser de Scrapling con las últimas versiones de otras bibliotecas populares.
### Prueba de Velocidad de Extracción de Texto (5000 elementos anidados)
-| # | Biblioteca | Tiempo (ms) | vs Scrapling |
+| # | Biblioteca | Tiempo (ms) | vs Scrapling |
|---|:-----------------:|:-----------:|:------------:|
-| 1 | Scrapling | 1.99 | 1.0x |
-| 2 | Parsel/Scrapy | 2.01 | 1.01x |
-| 3 | Raw Lxml | 2.5 | 1.256x |
-| 4 | PyQuery | 22.93 | ~11.5x |
-| 5 | Selectolax | 80.57 | ~40.5x |
-| 6 | BS4 with Lxml | 1541.37 | ~774.6x |
-| 7 | MechanicalSoup | 1547.35 | ~777.6x |
-| 8 | BS4 with html5lib | 3410.58 | ~1713.9x |
+| 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 |
### Rendimiento de Similitud de Elementos y Búsqueda de Texto
@@ -252,8 +332,8 @@ Las capacidades de búsqueda adaptativa de elementos de Scrapling superan signif
| Biblioteca | Tiempo (ms) | vs Scrapling |
|-------------|:-----------:|:------------:|
-| Scrapling | 2.46 | 1.0x |
-| AutoScraper | 13.3 | 5.407x |
+| Scrapling | 2.39 | 1.0x |
+| AutoScraper | 12.45 | 5.209x |
> Todos los benchmarks representan promedios de más de 100 ejecuciones. Ver [benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py) para la metodología.
@@ -266,29 +346,29 @@ Scrapling requiere Python 3.10 o superior:
pip install scrapling
```
-A partir de v0.3.2, esta instalación solo incluye el motor de análisis y sus dependencias, sin ningún fetcher o dependencias de línea de comandos.
+Esta instalación solo incluye el motor de análisis y sus dependencias, sin ningún fetcher ni dependencias de línea de comandos.
### Dependencias Opcionales
1. Si vas a usar alguna de las características adicionales a continuación, los fetchers, o sus clases, necesitarás instalar las dependencias de los fetchers y sus dependencias del navegador de la siguiente manera:
```bash
pip install "scrapling[fetchers]"
-
+
scrapling install
```
- Esto descarga todos los navegadores, junto con sus dependencias del sistema y dependencias de manipulación de huellas digitales.
+ Esto descarga todos los navegadores, junto con sus dependencias del sistema y dependencias de manipulación de fingerprint.
2. Características adicionales:
- Instalar la característica del servidor MCP:
```bash
pip install "scrapling[ai]"
```
- - Instalar características del shell (shell de Web Scraping y el comando `extract`):
+ - Instalar características del Shell (Shell de Web Scraping y el comando `extract`):
```bash
pip install "scrapling[shell]"
```
- - Instalar todo:
+ - Instalar todo:
```bash
pip install "scrapling[all]"
```
@@ -323,12 +403,5 @@ Este trabajo está licenciado bajo la Licencia BSD-3-Clause.
Este proyecto incluye código adaptado de:
- Parsel (Licencia BSD)—Usado para el submódulo [translator](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/translator.py)
-## Agradecimientos y Referencias
-
-- El brillante trabajo de [Daijro](https://github.com/daijro) en [BrowserForge](https://github.com/daijro/browserforge) y [Camoufox](https://github.com/daijro/camoufox)
-- El brillante trabajo de [Vinyzu](https://github.com/Vinyzu) en [Botright](https://github.com/Vinyzu/Botright) y [PatchRight](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)
-- [brotector](https://github.com/kaliiiiiiiiii/brotector) por técnicas de evasión de detección de navegador
-- [fakebrowser](https://github.com/kkoooqq/fakebrowser) y [BotBrowser](https://github.com/botswin/BotBrowser) por investigación de huellas digitales
-
---
-
-
-
-
- 簡単で効率的なウェブスクレイピング、あるべき姿！
-
+
@@ -24,46 +29,47 @@
- - 選択メソッド - - · - - フェッチャーの選択 - - · - - CLI - - · - - MCPモード - - · - - Beautifulsoupからの移行 - + 選択メソッド + · + Fetcherの選び方 + · + CLI + · + MCPモード + · + Beautifulsoupからの移行
-**アンチボットシステムとの戦いをやめましょう。ウェブサイトが更新されるたびにセレクタを書き直すのをやめましょう。** +Scraplingは、単一のリクエストから本格的なクロールまですべてを処理する適応型Web Scrapingフレームワークです。 -Scraplingは単なるウェブスクレイピングライブラリではありません。ウェブサイトの変更から学習し、それとともに進化する最初の**適応型**スクレイピングライブラリです。他のライブラリがウェブサイトの構造が更新されると壊れる一方で、Scraplingは自動的に要素を再配置し、スクレイパーを稼働し続けます。 +そのパーサーはウェブサイトの変更から学習し、ページが更新されたときに要素を自動的に再配置します。Fetcherはすぐに使えるCloudflare Turnstileなどのアンチボットシステムを回避します。そしてSpiderフレームワークにより、Pause & Resumeや自動Proxy回転機能を備えた並行マルチSessionクロールへとスケールアップできます — すべてわずか数行のPythonで。1つのライブラリ、妥協なし。 -モダンウェブ向けに構築されたScraplingは、**独自の高速パースエンジン**とフェッチャーを備えており、あなたが直面する、または直面するであろうすべてのウェブスクレイピングの課題に対応します。ウェブスクレイパーによってウェブスクレイパーと一般ユーザーのために構築され、誰にでも何かがあります。 +リアルタイム統計とStreamingによる超高速クロール。Web Scraperによって、Web Scraperと一般ユーザーのために構築され、誰にでも何かがあります。 ```python ->> from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher ->> StealthyFetcher.adaptive = True -# レーダーの下でウェブサイトのソースを取得！ ->> page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) ->> print(page.status) -200 ->> products = page.css('.product', auto_save=True) # ウェブサイトのデザイン変更に耐えるデータをスクレイプ！ ->> # 後でウェブサイトの構造が変わったら、`adaptive=True`を渡す ->> products = page.css('.product', adaptive=True) # そしてScraplingはまだそれらを見つけます！ +from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher +StealthyFetcher.adaptive = True +page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) # レーダーの下でウェブサイトを取得！ +products = page.css('.product', auto_save=True) # ウェブサイトのデザイン変更に耐えるデータをスクレイプ！ +products = page.css('.product', adaptive=True) # 後でウェブサイトの構造が変わったら、`adaptive=True`を渡して見つける！ +``` +または本格的なクロールへスケールアップ +```python +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() ``` -# スポンサー + +# スポンサー @@ -74,6 +80,7 @@ Scraplingは単なるウェブスクレイピングライブラリではあり
+
@@ -86,138 +93,211 @@ Scraplingは単なるウェブスクレイピングライブラリではあり
## 主な機能
-### セッションサポート付き高度なウェブサイト取得
-- **HTTPリクエスト**：`Fetcher`クラスで高速でステルスなHTTPリクエスト。ブラウザのTLSフィンガープリント、ヘッダーを模倣し、HTTP3を使用できます。
-- **動的読み込み**：Playwright's ChromiumとGoogle Chromeをサポートする`DynamicFetcher`クラスを通じた完全なブラウザ自動化で動的ウェブサイトを取得。
-- **アンチボット回避**：`StealthyFetcher`とフィンガープリント偽装による高度なステルス機能。自動化でCloudflareのTurnstile/Interstitialのすべてのタイプを簡単に回避できます。
-- **セッション管理**：リクエスト間でCookieと状態を管理するための`FetcherSession`、`StealthySession`、`DynamicSession`クラスによる永続的なセッションサポート。
-- **非同期サポート**：すべてのフェッチャーと専用非同期セッションクラス全体での完全な非同期サポート。
+### 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および専用asyncSessionクラス全体での完全なasyncサポート。
### 適応型スクレイピングとAI統合
- 🔄 **スマート要素追跡**：インテリジェントな類似性アルゴリズムを使用してウェブサイトの変更後に要素を再配置。
- 🎯 **スマート柔軟選択**：CSSセレクタ、XPathセレクタ、フィルタベース検索、テキスト検索、正規表現検索など。
-- 🔍 **類似要素を見つける**：見つかった要素に類似した要素を自動的に特定。
-- 🤖 **AIと使用するMCPサーバー**：AI支援ウェブスクレイピングとデータ抽出のための組み込みMCPサーバー。MCPサーバーは、AI（Claude/Cursorなど）に渡す前にScraplingを活用してターゲットコンテンツを抽出する強力でカスタムな機能を備えており、操作を高速化し、トークン使用量を最小限に抑えることでコストを削減します。（[デモビデオ](https://www.youtube.com/watch?v=qyFk3ZNwOxE)）
+- 🔍 **類似要素の検出**：見つかった要素に類似した要素を自動的に特定。
+- 🤖 **AIと使用するMCPサーバー**：AI支援Web Scrapingとデータ抽出のための組み込みMCPサーバー。MCPサーバーは、AI（Claude/Cursorなど）に渡す前にScraplingを活用してターゲットコンテンツを抽出する強力でカスタムな機能を備えており、操作を高速化し、トークン使用量を最小限に抑えることでコストを削減します。（[デモ動画](https://www.youtube.com/watch?v=qyFk3ZNwOxE)）
### 高性能で実戦テスト済みのアーキテクチャ
-- 🚀 **高速**：ほとんどのPythonスクレイピングライブラリを上回る最適化されたパフォーマンス。
+- 🚀 **超高速**：ほとんどのPythonスクレイピングライブラリを上回る最適化されたパフォーマンス。
- 🔋 **メモリ効率**：最小のメモリフットプリントのための最適化されたデータ構造と遅延読み込み。
- ⚡ **高速JSONシリアル化**：標準ライブラリの10倍の速度。
-- 🏗️ **実戦テスト済み**：Scraplingは92%のテストカバレッジと完全な型ヒントカバレッジを備えているだけでなく、過去1年間に数百人のウェブスクレイパーによって毎日使用されてきました。
+- 🏗️ **実戦テスト済み**：Scraplingは92%のテストカバレッジと完全な型ヒントカバレッジを備えているだけでなく、過去1年間に数百人のWeb Scraperによって毎日使用されてきました。
-### 開発者/ウェブスクレイパーにやさしい体験
-- 🎯 **インタラクティブウェブスクレイピングシェル**：Scraping統合、ショートカット、curlリクエストをScraplingリクエストに変換したり、ブラウザでリクエスト結果を表示したりするなどの新しいツールを備えたオプションの組み込みIPythonシェルで、ウェブスクレイピングスクリプトの開発を加速します。
+### 開発者/Web Scraperにやさしい体験
+- 🎯 **インタラクティブWeb Scraping Shell**：Scrapling統合、ショートカット、curlリクエストをScraplingリクエストに変換したり、ブラウザでリクエスト結果を表示したりするなどの新しいツールを備えたオプションの組み込みIPython Shellで、Web Scrapingスクリプトの開発を加速。
- 🚀 **ターミナルから直接使用**：オプションで、コードを一行も書かずにScraplingを使用してURLをスクレイプできます！
- 🛠️ **豊富なナビゲーションAPI**：親、兄弟、子のナビゲーションメソッドによる高度なDOMトラバーサル。
- 🧬 **強化されたテキスト処理**：組み込みの正規表現、クリーニングメソッド、最適化された文字列操作。
- 📝 **自動セレクタ生成**：任意の要素に対して堅牢なCSS/XPathセレクタを生成。
-- 🔌 **馴染みのあるAPI**：Scrapy/Parselで使用されている同じ疑似要素を持つScrapy/BeautifulSoupに似ています。
-- 📘 **完全な型カバレッジ**：優れたIDEサポートとコード補完のための完全な型ヒント。
+- 🔌 **馴染みのあるAPI**：Scrapy/Parselで使用されている同じ疑似要素を持つScrapy/BeautifulSoupに似た設計。
+- 📘 **完全な型カバレッジ**：優れたIDEサポートとコード補完のための完全な型ヒント。コードベース全体が変更のたびに**PyRight**と**MyPy**で自動的にスキャンされます。
- 🔋 **すぐに使えるDockerイメージ**：各リリースで、すべてのブラウザを含むDockerイメージが自動的にビルドおよびプッシュされます。
## はじめに
-### 基本的な使い方
-```python
-from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher
-from scrapling.fetchers import FetcherSession, StealthySession, DynamicSession
+深く掘り下げずに、Scraplingにできることの簡単な概要をお見せしましょう。
-# セッションサポート付きHTTPリクエスト
-with FetcherSession(impersonate='chrome') as session: # ChromeのTLSフィンガープリントの最新バージョンを使用
+### 基本的な使い方
+Sessionサポート付きHTTPリクエスト
+```python
+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')
+ quotes = page.css('.quote .text::text').getall()
# または一回限りのリクエストを使用
page = Fetcher.get('https://quotes.toscrape.com/')
-quotes = page.css('.quote .text::text')
+quotes = page.css('.quote .text::text').getall()
+```
+高度なステルスモード
+```python
+from scrapling.fetchers import StealthyFetcher, StealthySession
-# 高度なステルスモード（完了するまでブラウザを開いたままにする）
-with StealthySession(headless=True, solve_cloudflare=True) as session:
+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')
+ data = page.css('#padded_content a').getall()
-# または一回限りのリクエストスタイルを使用、このリクエストのためにブラウザを開き、完了後に閉じる
+# または一回限りのリクエストスタイル、このリクエストのためにブラウザを開き、完了後に閉じる
page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')
-data = page.css('#padded_content a')
-
-# 完全なブラウザ自動化（完了するまでブラウザを開いたままにする）
-with DynamicSession(headless=True) as session:
- page = session.fetch('https://quotes.toscrape.com/', network_idle=True)
- quotes = page.css('.quote .text::text')
+data = page.css('#padded_content a').getall()
+```
+完全なブラウザ自動化
+```python
+from scrapling.fetchers import DynamicFetcher, DynamicSession
-# または一回限りのリクエストスタイルを使用
-page = DynamicFetcher.fetch('https://quotes.toscrape.com/', network_idle=True)
-quotes = page.css('.quote .text::text')
+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を備えた本格的なクローラーを構築：
```python
-# CSSセレクタ
-page.css('a::text') # テキストを抽出
-page.css('a::attr(href)') # 属性を抽出
-page.css('a', recursive=False) # 直接の要素のみ
-page.css('a', auto_save=True) # 要素の位置を自動保存
+from scrapling.spiders import Spider, Request, Response
-# XPath
-page.xpath('//a/text()')
+class QuotesSpider(Spider):
+ name = "quotes"
+ start_urls = ["https://quotes.toscrape.com/"]
+ concurrent_requests = 10
-# 柔軟な検索
-page.find_by_text('Python', first_match=True) # テキストで検索
-page.find_by_regex(r'\d{4}') # 正規表現パターンで検索
-page.find('div', {'class': 'container'}) # 属性で検索
+ 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(),
+ }
-# ナビゲーション
-element.parent # 親要素を取得
-element.next_sibling # 次の兄弟を取得
-element.children # 子要素を取得
+ next_page = response.css('.next a')
+ if next_page:
+ yield response.follow(next_page[0].attrib['href'])
-# 類似要素
-similar = page.get_similar(element) # 類似要素を見つける
-
-# 適応型スクレイピング
-saved_elements = page.css('.product', auto_save=True)
-# 後でウェブサイトが変更されたとき：
-page.css('.product', adaptive=True) # 保存された位置を使用して要素を見つける
+result = QuotesSpider().start()
+print(f"{len(result.items)}件の引用をスクレイプしました")
+result.items.to_json("quotes.json")
```
-
-### セッションの使用
+単一のSpiderで複数のSessionタイプを使用：
```python
-from scrapling.fetchers import FetcherSession, AsyncFetcherSession
+from scrapling.spiders import Spider, Request, Response
+from scrapling.fetchers import FetcherSession, AsyncStealthySession
-# 同期セッション
-with FetcherSession() as session:
- # Cookieは自動的に維持されます
- page1 = session.get('https://quotes.toscrape.com/login')
- page2 = session.post('https://quotes.toscrape.com/login', data={'username': 'admin', 'password': 'admin'})
-
- # 必要に応じてブラウザのフィンガープリントを切り替え
+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：
+```python
+QuotesSpider(crawldir="./crawl_data").start()
+```
+Ctrl+Cを押すと正常に一時停止し、進捗は自動的に保存されます。後でSpiderを再度起動する際に同じ`crawldir`を渡すと、中断したところから再開します。
+
+### 高度なパースとナビゲーション
+```python
+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()
+```
+ウェブサイトを取得せずにパーサーをすぐに使用することもできます：
+```python
+from scrapling.parser import Selector
+
+page = Selector("...")
+```
+まったく同じ方法で動作します！
+
+### 非同期Session管理の例
+```python
+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とインタラクティブシェル
+## CLIとインタラクティブShell
-Scrapling v0.3には強力なコマンドラインインターフェースが含まれています：
+Scraplingには強力なコマンドラインインターフェースが含まれています：
[](https://asciinema.org/a/736339)
-インタラクティブウェブスクレイピングシェルを起動
+インタラクティブWeb Scraping Shellを起動
```bash
scrapling shell
```
-プログラミングせずに直接ページをファイルに抽出（デフォルトで`body`タグ内のコンテンツを抽出）。出力ファイルが`.txt`で終わる場合、ターゲットのテキストコンテンツが抽出されます。`.md`で終わる場合、HTMLコンテンツのMarkdown表現になります；`.html`で終わる場合、HTMLコンテンツそのものになります。
+プログラミングせずに直接ページをファイルに抽出（デフォルトで`body`タグ内のコンテンツを抽出）。出力ファイルが`.txt`で終わる場合、ターゲットのテキストコンテンツが抽出されます。`.md`で終わる場合、HTMLコンテンツのMarkdown表現になります。`.html`で終わる場合、HTMLコンテンツそのものになります。
```bash
scrapling extract get 'https://example.com' content.md
scrapling extract get 'https://example.com' content.txt --css-selector '#fromSkipToProducts' --impersonate 'chrome' # CSSセレクタ'#fromSkipToProducts'に一致するすべての要素
@@ -226,34 +306,34 @@ scrapling extract stealthy-fetch 'https://nopecha.com/demo/cloudflare' captchas.
```
> [!NOTE]
-> MCPサーバーやインタラクティブウェブスクレイピングシェルなど、他にも多くの追加機能がありますが、このページは簡潔に保ちたいと思います。完全なドキュメントは[こちら](https://scrapling.readthedocs.io/en/latest/)をご覧ください
+> MCPサーバーやインタラクティブWeb Scraping Shellなど、他にも多くの追加機能がありますが、このページは簡潔に保ちたいと思います。完全なドキュメントは[こちら](https://scrapling.readthedocs.io/en/latest/)をご覧ください
## パフォーマンスベンチマーク
-Scraplingは強力であるだけでなく、驚くほど高速で、バージョン0.3以降のアップデートはすべての操作で優れたパフォーマンス向上を実現しています。以下のベンチマークは、Scraplingのパーサーを他の人気のあるライブラリと比較しています。
+Scraplingは強力であるだけでなく、超高速です。以下のベンチマークは、Scraplingのパーサーを他の人気ライブラリの最新バージョンと比較しています。
### テキスト抽出速度テスト（5000個のネストされた要素）
-| # | ライブラリ | 時間(ms) | vs Scrapling |
-|---|:-----------------:|:-------:|:------------:|
-| 1 | Scrapling | 1.99 | 1.0x |
-| 2 | Parsel/Scrapy | 2.01 | 1.01x |
-| 3 | Raw Lxml | 2.5 | 1.256x |
-| 4 | PyQuery | 22.93 | ~11.5x |
-| 5 | Selectolax | 80.57 | ~40.5x |
-| 6 | BS4 with Lxml | 1541.37 | ~774.6x |
-| 7 | MechanicalSoup | 1547.35 | ~777.6x |
-| 8 | BS4 with html5lib | 3410.58 | ~1713.9x |
+| # | ライブラリ | 時間(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.46 | 1.0x |
-| AutoScraper | 13.3 | 5.407x |
+| ライブラリ | 時間(ms) | vs Scrapling |
+|-------------|:---------:|:------------:|
+| Scrapling | 2.39 | 1.0x |
+| AutoScraper | 12.45 | 5.209x |
> すべてのベンチマークは100回以上の実行の平均を表します。方法論については[benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py)を参照してください。
@@ -266,25 +346,25 @@ ScraplingにはPython 3.10以上が必要です：
pip install scrapling
```
-v0.3.2以降、このインストールにはパーサーエンジンとその依存関係のみが含まれており、フェッチャーやコマンドライン依存関係は含まれていません。
+このインストールにはパーサーエンジンとその依存関係のみが含まれており、Fetcherやコマンドライン依存関係は含まれていません。
### オプションの依存関係
-1. 以下の追加機能、フェッチャー、またはそれらのクラスのいずれかを使用する場合は、フェッチャーの依存関係とブラウザの依存関係を次のようにインストールする必要があります：
+1. 以下の追加機能、Fetcher、またはそれらのクラスのいずれかを使用する場合は、Fetcherの依存関係とブラウザの依存関係を次のようにインストールする必要があります：
```bash
pip install "scrapling[fetchers]"
-
+
scrapling install
```
- これにより、すべてのブラウザ、およびそれらのシステム依存関係とフィンガープリント操作依存関係がダウンロードされます。
+ これにより、すべてのブラウザ、およびそれらのシステム依存関係とfingerprint操作依存関係がダウンロードされます。
2. 追加機能：
- MCPサーバー機能をインストール：
```bash
pip install "scrapling[ai]"
```
- - シェル機能（ウェブスクレイピングシェルと`extract`コマンド）をインストール：
+ - Shell機能（Web Scraping Shellと`extract`コマンド）をインストール：
```bash
pip install "scrapling[shell]"
```
@@ -323,12 +403,5 @@ docker pull ghcr.io/d4vinci/scrapling:latest
このプロジェクトには次から適応されたコードが含まれています：
- Parsel（BSDライセンス）— [translator](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/translator.py)サブモジュールに使用
-## 感謝と参考文献
-
-- [Daijro](https://github.com/daijro)の[BrowserForge](https://github.com/daijro/browserforge)と[Camoufox](https://github.com/daijro/camoufox)における素晴らしい仕事
-- [Vinyzu](https://github.com/Vinyzu)の[Botright](https://github.com/Vinyzu/Botright)と[PatchRight](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)における素晴らしい仕事
-- ブラウザ検出回避技術を提供する[brotector](https://github.com/kaliiiiiiiiii/brotector)
-- フィンガープリント研究を提供する[fakebrowser](https://github.com/kkoooqq/fakebrowser)と[BotBrowser](https://github.com/botswin/BotBrowser)
-
---
-
-
-
-
- Простой, легкий веб-скрапинг, каким он и должен быть!
-
+
@@ -24,46 +29,47 @@
- - Методы выбора - - · - - Выбор фетчера - - · - - CLI - - · - - Режим MCP - - · - - Миграция с Beautifulsoup - + Методы выбора + · + Выбор Fetcher + · + CLI + · + Режим MCP + · + Миграция с Beautifulsoup
-**Прекратите бороться с анти-ботовыми системами. Прекратите переписывать селекторы после каждого обновления сайта.** +Scrapling — это адаптивный фреймворк для Web Scraping, который берёт на себя всё: от одного запроса до полномасштабного обхода сайтов. -Scrapling - это не просто очередная библиотека для веб-скрапинга. Это первая **адаптивная** библиотека для скрапинга, которая учится на изменениях сайтов и развивается вместе с ними. В то время как другие библиотеки ломаются, когда сайты обновляют свою структуру, Scrapling автоматически перемещает ваши элементы и поддерживает работу ваших скраперов. +Его парсер учится на изменениях сайтов и автоматически перемещает ваши элементы при обновлении страниц. Его Fetcher'ы обходят анти-бот системы вроде Cloudflare Turnstile прямо из коробки. А его Spider-фреймворк позволяет масштабироваться до параллельных, многосессионных обходов с Pause & Resume и автоматической ротацией Proxy — и всё это в нескольких строках Python. Одна библиотека, без компромиссов. -Созданный для современного веба, Scrapling имеет **собственный быстрый движок парсинга** и фетчеры для решения всех задач веб-скрапинга, с которыми вы сталкиваетесь или столкнетесь. Созданный веб-скраперами для веб-скраперов и обычных пользователей, здесь есть что-то для каждого. +Молниеносно быстрые обходы с отслеживанием статистики в реальном времени и Streaming. Создано веб-скраперами для веб-скраперов и обычных пользователей — здесь есть что-то для каждого. ```python ->> from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher ->> StealthyFetcher.adaptive = True -# Получайте исходный код сайтов незаметно! ->> page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) ->> print(page.status) -200 ->> products = page.css('.product', auto_save=True) # Скрапьте данные, которые переживут изменения дизайна сайта! ->> # Позже, если структура сайта изменится, передайте `adaptive=True` ->> products = page.css('.product', adaptive=True) # и Scrapling все равно их найдет! +from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher, DynamicFetcher +StealthyFetcher.adaptive = True +page = StealthyFetcher.fetch('https://example.com', headless=True, network_idle=True) # Загрузите сайт незаметно! +products = page.css('.product', auto_save=True) # Скрапьте данные, которые переживут изменения дизайна сайта! +products = page.css('.product', adaptive=True) # Позже, если структура сайта изменится, передайте `adaptive=True`, чтобы найти их! +``` +Или масштабируйте до полного обхода +```python +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() ``` -# Спонсоры + +# Спонсоры @@ -74,6 +80,7 @@ Scrapling - это не просто очередная библиотека д
+
@@ -86,138 +93,211 @@ Scrapling - это не просто очередная библиотека д
## Ключевые особенности
-### Продвинутая загрузка сайтов с поддержкой сессий
-- **HTTP-запросы**: Быстрые и скрытные HTTP-запросы с классом `Fetcher`. Может имитировать TLS-отпечаток браузера, заголовки и использовать HTTP3.
+### 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, конвейеров и длительных обходов.
+- 🛡️ **Обнаружение заблокированных запросов**: Автоматическое обнаружение и повторная отправка заблокированных запросов с настраиваемой логикой.
+- 📦 **Встроенный экспорт**: Экспортируйте результаты через хуки и собственный конвейер или встроенный JSON/JSONL с `result.items.to_json()` / `result.items.to_jsonl()` соответственно.
+
+### Продвинутая загрузка сайтов с поддержкой Session
+- **HTTP-запросы**: Быстрые и скрытные HTTP-запросы с классом `Fetcher`. Может имитировать TLS fingerprint браузера, заголовки и использовать HTTP/3.
- **Динамическая загрузка**: Загрузка динамических сайтов с полной автоматизацией браузера через класс `DynamicFetcher`, поддерживающий Chromium от Playwright и Google Chrome.
-- **Обход анти-ботов**: Расширенные возможности скрытности с `StealthyFetcher` и подмену отпечатков. Может легко обойти все типы Turnstile/Interstitial от Cloudflare с помощью автоматизации.
+- **Обход анти-ботов**: Расширенные возможности скрытности с `StealthyFetcher` и подмену fingerprint'ов. Может легко обойти все типы Cloudflare Turnstile/Interstitial с помощью автоматизации.
- **Управление сессиями**: Поддержка постоянных сессий с классами `FetcherSession`, `StealthySession` и `DynamicSession` для управления cookie и состоянием между запросами.
-- **Поддержка асинхронности**: Полная асинхронная поддержка во всех фетчерах и выделенных асинхронных классах сессий.
+- **Ротация Proxy**: Встроенный `ProxyRotator` с round-robin или пользовательскими стратегиями для всех типов сессий, а также переопределение Proxy для каждого запроса.
+- **Блокировка доменов**: Блокируйте запросы к определённым доменам (и их поддоменам) в браузерных Fetcher'ах.
+- **Поддержка async**: Полная async-поддержка во всех Fetcher'ах и выделенных async-классах сессий.
### Адаптивный скрапинг и интеграция с ИИ
- 🔄 **Умное отслеживание элементов**: Перемещайте элементы после изменений сайта с помощью интеллектуальных алгоритмов подобия.
- 🎯 **Умный гибкий выбор**: CSS-селекторы, XPath-селекторы, поиск на основе фильтров, текстовый поиск, поиск по регулярным выражениям и многое другое.
-- 🔍 **Поиск похожих элементов**: Автоматически находите элементы, похожие на найденные элементы.
-- 🤖 **MCP-сервер для использования с ИИ**: Встроенный MCP-сервер для веб-скрапинга с помощью ИИ и извлечения данных. MCP-сервер обладает мощными, пользовательскими возможностями, которые используют Scrapling для извлечения целевого контента перед передачей его ИИ (Claude/Cursor/и т.д.), тем самым ускоряя операции и снижая затраты за счет минимизации использования токенов. ([демо-видео](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
+- 🔍 **Поиск похожих элементов**: Автоматически находите элементы, похожие на найденные.
+- 🤖 **MCP-сервер для использования с ИИ**: Встроенный MCP-сервер для Web Scraping с помощью ИИ и извлечения данных. MCP-сервер обладает мощными пользовательскими возможностями, которые используют Scrapling для извлечения целевого контента перед передачей его ИИ (Claude/Cursor/и т.д.), тем самым ускоряя операции и снижая затраты за счёт минимизации использования токенов. ([демо-видео](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
### Высокопроизводительная и проверенная в боях архитектура
-- 🚀 **Молниеносно быстро**: Оптимизированная производительность превосходит большинство библиотек скрапинга Python.
+- 🚀 **Молниеносная скорость**: Оптимизированная производительность, превосходящая большинство Python-библиотек для скрапинга.
- 🔋 **Эффективное использование памяти**: Оптимизированные структуры данных и ленивая загрузка для минимального потребления памяти.
-- ⚡ **Быстрая сериализация JSON**: В 10 раз быстрее, чем стандартная библиотека.
+- ⚡ **Быстрая сериализация JSON**: В 10 раз быстрее стандартной библиотеки.
- 🏗️ **Проверено в боях**: Scrapling имеет не только 92% покрытия тестами и полное покрытие type hints, но и ежедневно использовался сотнями веб-скраперов в течение последнего года.
### Удобный для разработчиков/веб-скраперов опыт
-- 🎯 **Интерактивная оболочка веб-скрапинга**: Опциональная встроенная оболочка IPython с интеграцией Scrapling, ярлыками и новыми инструментами для ускорения разработки скриптов веб-скрапинга, такими как преобразование curl-запросов в Scrapling-запросы и просмотр результатов запросов в вашем браузере.
+- 🎯 **Интерактивная Web Scraping Shell**: Опциональная встроенная IPython-оболочка с интеграцией Scrapling, ярлыками и новыми инструментами для ускорения разработки скриптов Web Scraping, такими как преобразование curl-запросов в запросы Scrapling и просмотр результатов запросов в браузере.
- 🚀 **Используйте прямо из терминала**: При желании вы можете использовать Scrapling для скрапинга URL без написания ни одной строки кода!
- 🛠️ **Богатый API навигации**: Расширенный обход DOM с методами навигации по родителям, братьям и детям.
- 🧬 **Улучшенная обработка текста**: Встроенные регулярные выражения, методы очистки и оптимизированные операции со строками.
-- 📝 **Автоматическая генерация селекторов**: Генерация надежных CSS/XPath селекторов для любого элемента.
+- 📝 **Автоматическая генерация селекторов**: Генерация надёжных CSS/XPath-селекторов для любого элемента.
- 🔌 **Знакомый API**: Похож на Scrapy/BeautifulSoup с теми же псевдоэлементами, используемыми в Scrapy/Parsel.
-- 📘 **Полное покрытие типами**: Полные подсказки типов для отличной поддержки IDE и автодополнения кода.
-- 🔋 **Готовый Docker-образ**: С каждым релизом автоматически создается и отправляется Docker-образ, содержащий все браузеры.
+- 📘 **Полное покрытие типами**: Полные type hints для отличной поддержки IDE и автодополнения кода. Вся кодовая база автоматически проверяется **PyRight** и **MyPy** при каждом изменении.
+- 🔋 **Готовый Docker-образ**: С каждым релизом автоматически создаётся и публикуется Docker-образ, содержащий все браузеры.
## Начало работы
-### Базовое использование
-```python
-from scrapling.fetchers import Fetcher, StealthyFetcher, DynamicFetcher
-from scrapling.fetchers import FetcherSession, StealthySession, DynamicSession
+Давайте кратко покажем, на что способен Scrapling, без глубокого погружения.
-# HTTP-запросы с поддержкой сессий
-with FetcherSession(impersonate='chrome') as session: # Используйте последнюю версию TLS-отпечатка Chrome
+### Базовое использование
+HTTP-запросы с поддержкой Session
+```python
+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')
+ quotes = page.css('.quote .text::text').getall()
# Или используйте одноразовые запросы
page = Fetcher.get('https://quotes.toscrape.com/')
-quotes = page.css('.quote .text::text')
+quotes = page.css('.quote .text::text').getall()
+```
+Расширенный режим скрытности
+```python
+from scrapling.fetchers import StealthyFetcher, StealthySession
-# Расширенный режим скрытности (Держите браузер открытым до завершения)
-with StealthySession(headless=True, solve_cloudflare=True) as session:
+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')
+ data = page.css('#padded_content a').getall()
-# Или используйте стиль одноразового запроса, открывает браузер для этого запроса, затем закрывает его после завершения
+# Или используйте стиль одноразового запроса — открывает браузер для этого запроса, затем закрывает его после завершения
page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare')
-data = page.css('#padded_content a')
-
-# Полная автоматизация браузера (Держите браузер открытым до завершения)
-with DynamicSession(headless=True) as session:
- page = session.fetch('https://quotes.toscrape.com/', network_idle=True)
- quotes = page.css('.quote .text::text')
+data = page.css('#padded_content a').getall()
+```
+Полная автоматизация браузера
+```python
+from scrapling.fetchers import DynamicFetcher, DynamicSession
-# Или используйте стиль одноразового запроса
-page = DynamicFetcher.fetch('https://quotes.toscrape.com/', network_idle=True)
-quotes = page.css('.quote .text::text')
+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:
```python
-# CSS-селекторы
-page.css('a::text') # Извлечь текст
-page.css('a::attr(href)') # Извлечь атрибуты
-page.css('a', recursive=False) # Только прямые элементы
-page.css('a', auto_save=True) # Автоматически сохранять позиции элементов
+from scrapling.spiders import Spider, Request, Response
-# XPath
-page.xpath('//a/text()')
+class QuotesSpider(Spider):
+ name = "quotes"
+ start_urls = ["https://quotes.toscrape.com/"]
+ concurrent_requests = 10
-# Гибкий поиск
-page.find_by_text('Python', first_match=True) # Найти по тексту
-page.find_by_regex(r'\d{4}') # Найти по паттерну regex
-page.find('div', {'class': 'container'}) # Найти по атрибутам
+ 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(),
+ }
-# Навигация
-element.parent # Получить родительский элемент
-element.next_sibling # Получить следующего брата
-element.children # Получить дочерние элементы
+ next_page = response.css('.next a')
+ if next_page:
+ yield response.follow(next_page[0].attrib['href'])
-# Похожие элементы
-similar = page.get_similar(element) # Найти похожие элементы
-
-# Адаптивный скрапинг
-saved_elements = page.css('.product', auto_save=True)
-# Позже, когда сайт изменится:
-page.css('.product', adaptive=True) # Найти элементы используя сохраненные позиции
+result = QuotesSpider().start()
+print(f"Извлечено {len(result.items)} цитат")
+result.items.to_json("quotes.json")
```
-
-### Использование сессий
+Используйте несколько типов сессий в одном Spider:
```python
-from scrapling.fetchers import FetcherSession, AsyncFetcherSession
+from scrapling.spiders import Spider, Request, Response
+from scrapling.fetchers import FetcherSession, AsyncStealthySession
-# Синхронная сессия
-with FetcherSession() as session:
- # Cookie автоматически сохраняются
- page1 = session.get('https://quotes.toscrape.com/login')
- page2 = session.post('https://quotes.toscrape.com/login', data={'username': 'admin', 'password': 'admin'})
-
- # При необходимости переключите отпечаток браузера
+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 следующим образом:
+```python
+QuotesSpider(crawldir="./crawl_data").start()
+```
+Нажмите Ctrl+C для мягкой остановки — прогресс сохраняется автоматически. Позже, когда вы снова запустите Spider, передайте тот же `crawldir`, и он продолжит с того места, где остановился.
+
+### Продвинутый парсинг и навигация
+```python
+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()
+```
+Вы можете использовать парсер напрямую, если не хотите загружать сайты, как показано ниже:
+```python
+from scrapling.parser import Selector
+
+page = Selector("...")
+```
+И он работает точно так же!
+
+### Примеры async Session
+```python
+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()) # Опционально - Статус пула вкладок браузера (занят/свободен/ошибка)
+
+ print(session.get_pool_stats()) # Опционально — статус пула вкладок браузера (занят/свободен/ошибка)
results = await asyncio.gather(*tasks)
print(session.get_pool_stats())
```
-## CLI и интерактивная оболочка
+## CLI и интерактивная Shell
-Scrapling v0.3 включает мощный интерфейс командной строки:
+Scrapling включает мощный интерфейс командной строки:
[](https://asciinema.org/a/736339)
-Запустить интерактивную оболочку веб-скрапинга
+Запустить интерактивную Web Scraping Shell
```bash
scrapling shell
```
-Извлечь страницы в файл напрямую без программирования (Извлекает содержимое внутри тега `body` по умолчанию). Если выходной файл заканчивается на `.txt`, то будет извлечено текстовое содержимое цели. Если заканчивается на `.md`, это будет Markdown-представление HTML-содержимого; если заканчивается на `.html`, это будет само HTML-содержимое.
+Извлечь страницы в файл напрямую без программирования (по умолчанию извлекает содержимое внутри тега `body`). Если выходной файл заканчивается на `.txt`, будет извлечено текстовое содержимое цели. Если заканчивается на `.md`, это будет Markdown-представление HTML-содержимого; если заканчивается на `.html`, это будет само HTML-содержимое.
```bash
scrapling extract get 'https://example.com' content.md
scrapling extract get 'https://example.com' content.txt --css-selector '#fromSkipToProducts' --impersonate 'chrome' # Все элементы, соответствующие CSS-селектору '#fromSkipToProducts'
@@ -226,24 +306,24 @@ scrapling extract stealthy-fetch 'https://nopecha.com/demo/cloudflare' captchas.
```
> [!NOTE]
-> Есть много дополнительных функций, но мы хотим сохранить эту страницу краткой, например, MCP-сервер и интерактивная оболочка веб-скрапинга. Ознакомьтесь с полной документацией [здесь](https://scrapling.readthedocs.io/en/latest/)
+> Есть множество дополнительных возможностей, но мы хотим сохранить эту страницу краткой, включая MCP-сервер и интерактивную Web Scraping Shell. Ознакомьтесь с полной документацией [здесь](https://scrapling.readthedocs.io/en/latest/)
## Тесты производительности
-Scrapling не только мощный - он также невероятно быстрый, и обновления с версии 0.3 обеспечили исключительные улучшения производительности во всех операциях. Следующие тесты производительности сравнивают парсер Scrapling с другими популярными библиотеками.
+Scrapling не только мощный — он ещё и невероятно быстрый. Следующие тесты производительности сравнивают парсер Scrapling с последними версиями других популярных библиотек.
### Тест скорости извлечения текста (5000 вложенных элементов)
-| # | Библиотека | Время (мс) | vs Scrapling |
+| # | Библиотека | Время (мс) | vs Scrapling |
|---|:-----------------:|:----------:|:------------:|
-| 1 | Scrapling | 1.99 | 1.0x |
-| 2 | Parsel/Scrapy | 2.01 | 1.01x |
-| 3 | Raw Lxml | 2.5 | 1.256x |
-| 4 | PyQuery | 22.93 | ~11.5x |
-| 5 | Selectolax | 80.57 | ~40.5x |
-| 6 | BS4 with Lxml | 1541.37 | ~774.6x |
-| 7 | MechanicalSoup | 1547.35 | ~777.6x |
-| 8 | BS4 with html5lib | 3410.58 | ~1713.9x |
+| 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 |
### Производительность подобия элементов и текстового поиска
@@ -252,8 +332,8 @@ Scrapling не только мощный - он также невероятно
| Библиотека | Время (мс) | vs Scrapling |
|-------------|:----------:|:------------:|
-| Scrapling | 2.46 | 1.0x |
-| AutoScraper | 13.3 | 5.407x |
+| Scrapling | 2.39 | 1.0x |
+| AutoScraper | 12.45 | 5.209x |
> Все тесты производительности представляют собой средние значения более 100 запусков. См. [benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py) для методологии.
@@ -266,33 +346,33 @@ Scrapling требует Python 3.10 или выше:
pip install scrapling
```
-Начиная с v0.3.2, эта установка включает только движок парсера и его зависимости, без каких-либо фетчеров или зависимостей командной строки.
+Эта установка включает только движок парсера и его зависимости, без каких-либо Fetcher'ов или зависимостей командной строки.
### Опциональные зависимости
-1. Если вы собираетесь использовать какие-либо из дополнительных функций ниже, фетчеры или их классы, вам необходимо установить зависимости фетчеров и их зависимости браузера следующим образом:
+1. Если вы собираетесь использовать какие-либо из дополнительных возможностей ниже, Fetcher'ы или их классы, вам необходимо установить зависимости Fetcher'ов и браузеров следующим образом:
```bash
pip install "scrapling[fetchers]"
-
+
scrapling install
```
- Это загрузит все браузеры вместе с их системными зависимостями и зависимостями манипуляции отпечатками.
+ Это загрузит все браузеры вместе с их системными зависимостями и зависимостями для манипуляции fingerprint'ами.
-2. Дополнительные функции:
+2. Дополнительные возможности:
- Установить функцию MCP-сервера:
```bash
pip install "scrapling[ai]"
```
- - Установить функции оболочки (оболочка веб-скрапинга и команда `extract`):
+ - Установить функции Shell (Web Scraping Shell и команда `extract`):
```bash
pip install "scrapling[shell]"
```
- - Установить все:
+ - Установить всё:
```bash
pip install "scrapling[all]"
```
- Помните, что вам нужно установить зависимости браузера с помощью `scrapling install` после любого из этих дополнений (если вы еще этого не сделали)
+ Помните, что вам нужно установить зависимости браузеров с помощью `scrapling install` после любого из этих дополнений (если вы ещё этого не сделали)
### Docker
Вы также можете установить Docker-образ со всеми дополнениями и браузерами с помощью следующей команды из DockerHub:
@@ -303,11 +383,11 @@ docker pull pyd4vinci/scrapling
```bash
docker pull ghcr.io/d4vinci/scrapling:latest
```
-Этот образ автоматически создается и отправляется с использованием GitHub Actions и основной ветки репозитория.
+Этот образ автоматически создаётся и публикуется с помощью GitHub Actions и основной ветки репозитория.
-## Вклад
+## Участие в разработке
-Мы приветствуем вклад! Пожалуйста, прочитайте наши [руководства по внесению вклада](https://github.com/D4Vinci/Scrapling/blob/main/CONTRIBUTING.md) перед началом работы.
+Мы приветствуем участие! Пожалуйста, прочитайте наши [руководства по участию в разработке](https://github.com/D4Vinci/Scrapling/blob/main/CONTRIBUTING.md) перед началом работы.
## Отказ от ответственности
@@ -323,12 +403,5 @@ docker pull ghcr.io/d4vinci/scrapling:latest
Этот проект включает код, адаптированный из:
- Parsel (лицензия BSD) — Используется для подмодуля [translator](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/translator.py)
-## Благодарности и ссылки
-
-- Блестящая работа [Daijro](https://github.com/daijro) над [BrowserForge](https://github.com/daijro/browserforge) и [Camoufox](https://github.com/daijro/camoufox)
-- Блестящая работа [Vinyzu](https://github.com/Vinyzu) над [Botright](https://github.com/Vinyzu/Botright) и [PatchRight](https://github.com/Kaliiiiiiiiii-Vinyzu/patchright)
-- [brotector](https://github.com/kaliiiiiiiiii/brotector) за техники обхода обнаружения браузера
-- [fakebrowser](https://github.com/kkoooqq/fakebrowser) и [BotBrowser](https://github.com/botswin/BotBrowser) за исследование отпечатков
-
---
-
+ 
+
Easy, effortless Web Scraping as it should be!
-
+
@@ -50,16 +63,27 @@ Built for the modern Web, Scrapling features **its own rapid parsing engine** an
## Key Features
+### Spiders — A Full Crawling Framework
+- 🕷️ **Scrapy-like Spider API**: Define spiders with `start_urls`, async `parse` callbacks, and `Request`/`Response` objects.
+- ⚡ **Concurrent Crawling**: Configurable concurrency limits, per-domain throttling, and download delays.
+- 🔄 **Multi-Session Support**: Unified interface for HTTP requests, and stealthy headless browsers in a single spider — route requests to different sessions by ID.
+- 💾 **Pause & Resume**: Checkpoint-based crawl persistence. Press Ctrl+C for a graceful shutdown; restart to resume from where you left off.
+- 📡 **Streaming Mode**: Stream scraped items as they arrive via `async for item in spider.stream()` with real-time stats — ideal for UI, pipelines, and long-running crawls.
+- 🛡️ **Blocked Request Detection**: Automatic detection and retry of blocked requests with customizable logic.
+- 📦 **Built-in Export**: Export results through hooks and your own pipeline or the built-in JSON/JSONL with `result.items.to_json()` / `result.items.to_jsonl()` respectively.
+
### Advanced Websites Fetching with Session Support
- **HTTP Requests**: Fast and stealthy HTTP requests with the `Fetcher` class. Can impersonate browsers' TLS fingerprint, headers, and use HTTP/3.
-- **Dynamic Loading**: Fetch dynamic websites with full browser automation through the `DynamicFetcher` class supporting Playwright's Chromium, and Google's Chrome.
-- **Anti-bot Bypass**: Advanced stealth capabilities with `StealthyFetcher` and fingerprint spoofing. Can bypass all types of Cloudflare's Turnstile/Interstitial with automation easily.
+- **Dynamic Loading**: Fetch dynamic websites with full browser automation through the `DynamicFetcher` class supporting Playwright's Chromium and Google's Chrome.
+- **Anti-bot Bypass**: Advanced stealth capabilities with `StealthyFetcher` and fingerprint spoofing. Can easily bypass all types of Cloudflare's Turnstile/Interstitial with automation.
- **Session Management**: Persistent session support with `FetcherSession`, `StealthySession`, and `DynamicSession` classes for cookie and state management across requests.
+- **Proxy Rotation**: Built-in `ProxyRotator` with round-robin or custom strategies across all session types, plus per-request proxy overrides.
+- **Domain Blocking**: Block requests to specific domains (and their subdomains) in browser-based fetchers.
- **Async Support**: Complete async support across all fetchers and dedicated async session classes.
### Adaptive Scraping & AI Integration
- 🔄 **Smart Element Tracking**: Relocate elements after website changes using intelligent similarity algorithms.
-- 🎯 **Smart Flexible Selection**: CSS selectors, XPath selectors, filter-based search, text search, regex search, and more.
+- 🎯 **Smart Flexible Selection**: CSS selectors, XPath selectors, filter-based search, text search, regex search, and more.
- 🔍 **Find Similar Elements**: Automatically locate elements similar to found elements.
- 🤖 **MCP Server to be used with AI**: Built-in MCP server for AI-assisted Web Scraping and data extraction. The MCP server features powerful, custom capabilities that leverage Scrapling to extract targeted content before passing it to the AI (Claude/Cursor/etc), thereby speeding up operations and reducing costs by minimizing token usage. ([demo video](https://www.youtube.com/watch?v=qyFk3ZNwOxE))
@@ -71,12 +95,12 @@ Built for the modern Web, Scrapling features **its own rapid parsing engine** an
### Developer/Web Scraper Friendly Experience
- 🎯 **Interactive Web Scraping Shell**: Optional built-in IPython shell with Scrapling integration, shortcuts, and new tools to speed up Web Scraping scripts development, like converting curl requests to Scrapling requests and viewing requests results in your browser.
-- 🚀 **Use it directly from the Terminal**: Optionally, you can use Scrapling to scrape a URL without writing a single code!
+- 🚀 **Use it directly from the Terminal**: Optionally, you can use Scrapling to scrape a URL without writing a single line of code!
- 🛠️ **Rich Navigation API**: Advanced DOM traversal with parent, sibling, and child navigation methods.
- 🧬 **Enhanced Text Processing**: Built-in regex, cleaning methods, and optimized string operations.
- 📝 **Auto Selector Generation**: Generate robust CSS/XPath selectors for any element.
- 🔌 **Familiar API**: Similar to Scrapy/BeautifulSoup with the same pseudo-elements used in Scrapy/Parsel.
-- 📘 **Complete Type Coverage**: Full type hints for excellent IDE support and code completion.
+- 📘 **Complete Type Coverage**: Full type hints for excellent IDE support and code completion. The entire codebase is automatically scanned with **PyRight** and **MyPy** with each change.
- 🔋 **Ready Docker image**: With each release, a Docker image containing all browsers is automatically built and pushed.
@@ -85,10 +109,34 @@ Scrapling’s GitHub stars have grown steadily since its release (see chart belo
+
+
## Installation
Scrapling requires Python 3.10 or higher:
@@ -97,7 +145,7 @@ Scrapling requires Python 3.10 or higher:
pip install scrapling
```
-Starting with v0.3.2, this installation only includes the parser engine and its dependencies, without any fetchers or commandline dependencies.
+This installation only includes the parser engine and its dependencies, without any fetchers or commandline dependencies.
### Optional Dependencies
diff --git a/docs/parsing/main_classes.md b/docs/parsing/main_classes.md
index ac8af75..40a66f3 100644
--- a/docs/parsing/main_classes.md
+++ b/docs/parsing/main_classes.md
@@ -1,9 +1,8 @@
## Introduction
-> 💡 **Prerequisites:**
->
-> - You’ve completed or read the [Querying elements](../parsing/selection.md) page to understand how to find/extract elements from the [Selector](../parsing/main_classes.md#selector) object.
->