🕷️ The BEST Web Scraping framework that handles everything from a single request to a full-scale crawl! Don't be shy, join here: https://discord.gg/EMgGbDceNQ and follow here for daily tips and tricks: https://x.com/Scrapling_dev
Python aiai-scrapingautomationcrawlercrawlingcrawling-pythondatadata-extractionmcpmcp-serverplaywrightpythonscrapingselectorsstealthweb-scraperweb-scrapingweb-scraping-pythonwebscrapingxpath
docs: Add Arabic docs for the website
Karim shoair5bc85cf7682d
diff --git a/.readthedocs.yaml b/.readthedocs.yamlindex 8d5a8d5..9409358 100644--- a/.readthedocs.yaml+++ b/.readthedocs.yaml@@ -15,7 +15,7 @@ build:- pip install ".[all]"build:html:- - zensical build+ - for config in zensical.yml zensical.*.yml; do zensical build --config-file "$config" || exit 1; donepost_build:- mkdir -p $READTHEDOCS_OUTPUT/html/- cp --recursive site/* $READTHEDOCS_OUTPUT/html/diff --git a/CONTRIBUTING.md b/CONTRIBUTING.mdindex 2684042..a50a8ec 100644--- a/CONTRIBUTING.md+++ b/CONTRIBUTING.md@@ -148,6 +148,8 @@ Documentation is built using [Zensical](https://zensical.org/). You can build it```bashpip install zensicalpip install -r docs/requirements.txt-zensical build --clean # Build the static site-zensical serve # Local preview+for config in zensical.yml zensical.*.yml; do+ zensical build --clean --config-file "$config" || exit 1+done+zensical serve --config-file zensical.yml```diff --git a/docs/README_AR.md b/docs/README_AR.mdindex 28544b9..2ee63cf 100644--- a/docs/README_AR.md+++ b/docs/README_AR.md@@ -1,7 +1,7 @@<!-- mcp-name: io.github.D4Vinci/Scrapling --><h1 align="center">- <a href="https://scrapling.readthedocs.io">+ <a href="https://scrapling.readthedocs.io/en/latest/ar/"><picture><source media="(prefers-color-scheme: dark)" srcset="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/docs/assets/cover_dark.svg?sanitize=true"><img alt="Scrapling Poster" src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/docs/assets/cover_light.svg?sanitize=true">@@ -19,8 +19,8 @@<a href="https://hub.docker.com/r/pyd4vinci/scrapling" target="_blank"><img alt="Docker Pulls" src="https://img.shields.io/docker/pulls/pyd4vinci/scrapling?labelColor=%20%23FDB062&logo=Docker&labelColor=%20%23528bff"></a><a href="https://clickpy.clickhouse.com/dashboard/scrapling" rel="nofollow"><img src="https://img.shields.io/pypi/dm/scrapling" alt="PyPI package downloads"></a>- <a href="https://scrapling.readthedocs.io/en/latest/ai/agent-skill.html" alt="AI Agent Skill">- <img alt="Static Badge" src="https://img.shields.io/badge/Skill-black?style=flat&label=Agent&link=https%3A%2F%2Fscrapling.readthedocs.io%2Fen%2Flatest%2Fai%2Fagent-skill.html"></a>+ <a href="https://scrapling.readthedocs.io/en/latest/ar/ai/agent-skill.html" alt="AI Agent Skill">+ <img alt="Static Badge" src="https://img.shields.io/badge/Skill-black?style=flat&label=Agent&link=https%3A%2F%2Fscrapling.readthedocs.io%2Fen%2Flatest%2Far%2Fai%2Fagent-skill.html"></a><a href="https://clawhub.ai/D4Vinci/scrapling-official" alt="OpenClaw Skill"><img alt="OpenClaw Skill" src="https://img.shields.io/badge/Clawhub-darkred?style=flat&label=OpenClaw&link=https%3A%2F%2Fclawhub.ai%2FD4Vinci%2Fscrapling-official"></a><br/>@@ -36,17 +36,17 @@</p><p align="center">- <a href="https://scrapling.readthedocs.io/en/latest/parsing/selection.html"><strong>طرق الاختيار</strong></a>+ <a href="https://scrapling.readthedocs.io/en/latest/ar/parsing/selection.html"><strong>طرق الاختيار</strong></a>·- <a href="https://scrapling.readthedocs.io/en/latest/fetching/choosing.html"><strong>اختيار Fetcher</strong></a>+ <a href="https://scrapling.readthedocs.io/en/latest/ar/fetching/choosing.html"><strong>اختيار Fetcher</strong></a>·- <a href="https://scrapling.readthedocs.io/en/latest/spiders/architecture.html"><strong>العناكب</strong></a>+ <a href="https://scrapling.readthedocs.io/en/latest/ar/spiders/architecture.html"><strong>العناكب</strong></a>·- <a href="https://scrapling.readthedocs.io/en/latest/spiders/proxy-blocking.html"><strong>تدوير البروكسي</strong></a>+ <a href="https://scrapling.readthedocs.io/en/latest/ar/spiders/proxy-blocking.html"><strong>تدوير البروكسي</strong></a>·- <a href="https://scrapling.readthedocs.io/en/latest/cli/overview.html"><strong>واجهة سطر الأوامر</strong></a>+ <a href="https://scrapling.readthedocs.io/en/latest/ar/cli/overview.html"><strong>واجهة سطر الأوامر</strong></a>·- <a href="https://scrapling.readthedocs.io/en/latest/ai/mcp-server.html"><strong>وضع MCP</strong></a>+ <a href="https://scrapling.readthedocs.io/en/latest/ar/ai/mcp-server.html"><strong>وضع MCP</strong></a></p>Scrapling هو إطار عمل لـ Web Scraping بلغة Python يجمع طلبات HTTP السريعة، والمتصفحات الخفية، وأدوات التحليل القوية، والزحف المتزامن في مكتبة واحدة.@@ -57,10 +57,10 @@ Scrapling هو إطار عمل لـ Web Scraping بلغة Python يجمع طلب## ماذا يمكنك أن تفعل باستخدام Scrapling-- **[الجلب والتفاعل](https://scrapling.readthedocs.io/en/latest/fetching/choosing.html)**: طلبات HTTP سريعة، ومتصفحات خفية، وتشغيل JavaScript، والتعامل مع Cloudflare Turnstile/Interstitial، وجلسات مستمرة، وتسجيل طلبات API في الخلفية.-- **[التحليل والاستخراج](https://scrapling.readthedocs.io/en/latest/parsing/selection.html)**: CSS وXPath، والبحث بالنص والتعبيرات النمطية، وتتبع العناصر التكيفي، ومطابقة العناصر المتشابهة، وإخراج Markdown نظيف.-- **[الزحف والتصدير](https://scrapling.readthedocs.io/en/latest/spiders/getting-started.html)**: عناكب متزامنة، وتدوير للبروكسي، وإعادة محاولات، وAutoThrottle، وإيقاف مؤقت واستئناف، وStreaming، وقوالب جاهزة، وتصدير بصيغ JSON/JSONL/CSV/XML.-- **[استخراج البيانات بالذكاء الاصطناعي أو من الطرفية](https://scrapling.readthedocs.io/en/latest/ai/mcp-server.html)**: خادم MCP لوكلاء الذكاء الاصطناعي لتصفح المواقع واستخراج البيانات، وAgent Skill، وأوامر CLI، وShell تفاعلي.+- **[الجلب والتفاعل](https://scrapling.readthedocs.io/en/latest/ar/fetching/choosing.html)**: طلبات HTTP سريعة، ومتصفحات خفية، وتشغيل JavaScript، والتعامل مع Cloudflare Turnstile/Interstitial، وجلسات مستمرة، وتسجيل طلبات API في الخلفية.+- **[التحليل والاستخراج](https://scrapling.readthedocs.io/en/latest/ar/parsing/selection.html)**: CSS وXPath، والبحث بالنص والتعبيرات النمطية، وتتبع العناصر التكيفي، ومطابقة العناصر المتشابهة، وإخراج Markdown نظيف.+- **[الزحف والتصدير](https://scrapling.readthedocs.io/en/latest/ar/spiders/getting-started.html)**: عناكب متزامنة، وتدوير للبروكسي، وإعادة محاولات، وAutoThrottle، وإيقاف مؤقت واستئناف، وStreaming، وقوالب جاهزة، وتصدير بصيغ JSON/JSONL/CSV/XML.+- **[استخراج البيانات بالذكاء الاصطناعي أو من الطرفية](https://scrapling.readthedocs.io/en/latest/ar/ai/mcp-server.html)**: خادم MCP لوكلاء الذكاء الاصطناعي لتصفح المواقع واستخراج البيانات، وAgent Skill، وأوامر CLI، وShell تفاعلي.ابدأ بصفحة واحدة:@@ -265,8 +265,8 @@ result.items.to_json("quotes.json")### ميزات الذكاء الاصطناعي- 🤖 **خادم MCP**: دع روبوتات المحادثة ووكلاء الذكاء الاصطناعي (Claude/Cursor وغيرها) يستخرجون البيانات عبر Scrapling باستخدام طلبات HTTP، والتفاعل مع المتصفح، ولقطات الشاشة، وحالة تسجيل الدخول المحفوظة، واستجابات API في الخلفية. يستخدم متصفحنا الخفي مع الأدوات المناسبة لتمكين نماذج الذكاء الاصطناعي المناسبة من تجاوز أي اختبار CAPTCHA تواجهه أثناء العمل (ناهيك عن أداة حل تحديات Cloudflare الخاصة بنا). يستخدم طرقاً متعددة لتقليل المحتوى المرسل للنموذج، وحظر الإعلانات، وحمايته من حقن التعليمات (Prompt-Injection). يشمل متصفحات بعيدة عبر CDP ونقل HTTP مع خيارات مصادقة. ([فيديو توضيحي](https://www.youtube.com/watch?v=qyFk3ZNwOxE))-- 🧠 **Agent Skill**: [مهارة جاهزة للتثبيت](https://scrapling.readthedocs.io/en/latest/ai/agent-skill.html) تُعلّم وكلاء البرمجة المكتبة بالكامل، حتى يكون الكود الذي يكتبونه بـ Scrapling مطابقاً للواجهة الحالية بدلاً من التخمين.-- 📚 **Markdown جاهز لأنظمة RAG**: حوّل أي صفحة إلى Markdown نظيف ومعقّم وجاهز لنماذج اللغة بسطر واحد (`page.markdown()`)، أو ازحف موقعاً كاملاً إلى مجموعة ملفات Markdown باستخدام القالب `ContentSpider`، كل ذلك بدون استخدام أي نموذج لغوي في العملية. ([الوثائق](https://scrapling.readthedocs.io/en/latest/ai/building-rag-systems.html))+- 🧠 **Agent Skill**: [مهارة جاهزة للتثبيت](https://scrapling.readthedocs.io/en/latest/ar/ai/agent-skill.html) تُعلّم وكلاء البرمجة المكتبة بالكامل، حتى يكون الكود الذي يكتبونه بـ Scrapling مطابقاً للواجهة الحالية بدلاً من التخمين.+- 📚 **Markdown جاهز لأنظمة RAG**: حوّل أي صفحة إلى Markdown نظيف ومعقّم وجاهز لنماذج اللغة بسطر واحد (`page.markdown()`)، أو ازحف موقعاً كاملاً إلى مجموعة ملفات Markdown باستخدام القالب `ContentSpider`، كل ذلك بدون استخدام أي نموذج لغوي في العملية. ([الوثائق](https://scrapling.readthedocs.io/en/latest/ar/ai/building-rag-systems.html))### بنية عالية الأداء ومختبرة ميدانياً- 🚀 **سريع كالبرق**: أداء محسّن يتفوق على معظم مكتبات Web Scraping في Python.@@ -467,7 +467,7 @@ scrapling extract fetch 'https://nopecha.com/demo/cloudflare' captchas.html --cs```> [!NOTE]-> هناك العديد من الميزات الإضافية، لكننا نريد إبقاء هذه الصفحة موجزة، بما في ذلك خادم MCP والـ Shell التفاعلي لـ Web Scraping. تحقق من الوثائق الكاملة [هنا](https://scrapling.readthedocs.io/en/latest/)+> هناك العديد من الميزات الإضافية، لكننا نريد إبقاء هذه الصفحة موجزة، بما في ذلك خادم MCP والـ Shell التفاعلي لـ Web Scraping. تحقق من الوثائق الكاملة [هنا](https://scrapling.readthedocs.io/en/latest/ar/)## معايير الأداء@@ -535,7 +535,7 @@ pip install scrapling```bashpip install "scrapling[ai]"```- - تثبيت اعتماديات ([بناء أنظمة RAG](https://scrapling.readthedocs.io/en/latest/ai/building-rag-systems.html)):+ - تثبيت اعتماديات ([بناء أنظمة RAG](https://scrapling.readthedocs.io/en/latest/ar/ai/building-rag-systems.html)):```bashpip install "scrapling[rag]"```diff --git a/docs/assets/javascripts/language-links.js b/docs/assets/javascripts/language-links.jsnew file mode 100644index 0000000..5578aea--- /dev/null+++ b/docs/assets/javascripts/language-links.js@@ -0,0 +1,13 @@+(() => {+ const base = new URL(JSON.parse(document.getElementById("__config").textContent).base, location);+ if (!base.pathname.endsWith("/")) base.pathname += "/";+ const links = [...document.querySelectorAll(".md-select a[hreflang]")].map(link => [link, link.href]);+ const update = () => links.forEach(([link, root]) => {+ link.href = new URL(location.pathname.slice(base.pathname.length) + location.search + location.hash, root).href;+ link.target = "_self";+ });+ update();+ location$.subscribe(update);+ addEventListener("hashchange", update);+ for (const event of ["click", "auxclick", "contextmenu"]) addEventListener(event, update, true);+})();diff --git a/docs/index.md b/docs/index.mdindex 4818a01..502b06f 100644--- a/docs/index.md+++ b/docs/index.md@@ -69,52 +69,7 @@ This prints `10` and saves the quotes and authors to `quotes.json`.## Top Sponsors-<style>-.ad {- width:240px;- height:100px;-}--</style>--<!-- sponsors -->-<div style="text-align: center;">- <a href="https://go.nodemaven.com/scraplingseptember" target="_blank" title="Proxies with the Highest IP Scores">- <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/NodeMaven.jpg" class="ad">- </a>- <a href="https://hypersolutions.co/?utm_source=github&utm_medium=readme&utm_campaign=scrapling" target="_blank" title="Bot Protection Bypass API for Akamai, DataDome, Incapsula & Kasada">- <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/HyperSolutions.png" class="ad">- </a>- <a href="https://evomi.com?utm_source=github&utm_medium=banner&utm_campaign=d4vinci-scrapling" target="_blank" title="Evomi is your Swiss Quality Proxy Provider, starting at $0.49/GB">- <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/evomi.png" class="ad">- </a>- <a href="https://tikhub.io/?utm_source=github.com/D4Vinci/Scrapling&utm_medium=marketing_social&utm_campaign=retargeting&utm_content=carousel_ad" target="_blank" title="Unlock the Power of Social Media Data & AI">- <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/TikHub.jpg" class="ad">- </a>- <a href="https://substack.thewebscraping.club/p/scrapling-hands-on-guide?utm_source=github&utm_medium=repo&utm_campaign=scrapling" target="_blank" title="The #1 newsletter dedicated to Web Scraping">- <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/TWSC.png" class="ad">- </a>- <a href="https://www.swiftproxy.net/?ref=D4Vinci" target="_blank" title="Scalable Solutions for Web Data Access">- <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/SwiftProxy.png" class="ad">- </a>- <a href="https://byteful.com/?utm_source=scrapling_website&utm_medium=github-sponsor&utm_campaign=scrapling_github_sponsor" target="_blank" title="Ethically sourced residential proxy infrastructure powering web scraping and AI agents">- <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/byteful.png" class="ad">- </a>- <a href="https://proxylane.dev/?utm_source=scrapling&utm_medium=partnership&utm_campaign=scrapling_platinum_202609&utm_content=github_readme" target="_blank" title="28M+ clean residential IPs for browser automation. No Blocks. No CAPTCHAs. Pay-as-you-Go.">- <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/proxylane.png" class="ad">- </a>- <a href="https://www.lundproxy.com/unlimited-residential-bandwidth.html?utm_source=github&utm_medium=sponsorship&utm_campaign=scrapling&utm_content=banner" target="_blank" title="Unlimited residential traffic, sized only by bandwidth.">- <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/lundproxy.png" class="ad">- </a>- <a href="https://dataimpulse.com/?utm_source=website&utm_medium=github_readme&utm_campaign=scrapling_platinum" target="_blank" title="Buy Pay-as-you-go proxies from $1/GB">- <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/DataImpulse_Platinum.png" class="ad">- </a>- <br />- <br />- <a href="https://cloro.dev/?utm_source=referral&utm_medium=scrapling" target="_blank" title="The search API for the AI era"><img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/cloro.jpg"></a>-</div>--<!-- /sponsors -->+--8<-- "sponsors.html"<i><sub>Do you want to show your ad here? Click [here](https://github.com/sponsors/D4Vinci), choose a plan, and enjoy the rest of the perks!</sub></i>diff --git a/docs/locales/ar/ai/agent-skill.md b/docs/locales/ar/ai/agent-skill.mdnew file mode 100644index 0000000..12b1f4b--- /dev/null+++ b/docs/locales/ar/ai/agent-skill.md@@ -0,0 +1,46 @@+---+title: "مهارة Scrapling لوكلاء البرمجة: التثبيت والاستخدام"+description: "ثبّت مهارة Scrapling لوكيل البرمجة. وفّر له أمثلة ومراجع حديثة عن جلب الصفحات وتحليلها والزحف إلى المواقع."+---++# مهارة Scrapling لوكلاء البرمجة {#scrapling-agent-skill}++يمنح [خادم MCP](mcp-server.md) مساعد الذكاء الاصطناعي أدوات لاستخراج بيانات المواقع نيابة عنك. أما **مهارة Scrapling لوكلاء البرمجة** فتعلّم الوكيل استخدام المكتبة نفسها، ليكتب كودًا يطابق الـ API الحالي بدلًا من التخمين اعتمادًا على بيانات تدريب قديمة.++تتبع المهارة مواصفات [AgentSkills](https://agentskills.io/specification)، لذلك يستطيع [Claude Code](https://claude.com/product/claude-code) و[OpenClaw](https://github.com/openclaw/openclaw) وغيرهما من أدوات الوكلاء قراءتها. تجمع إرشادات الجلب والتحليل والزحف وMCP وRAG في مراجع Markdown يحمّلها الوكيل عند الحاجة، مع أمثلة جاهزة للتشغيل. وهكذا يستطيع الإجابة عن معظم أسئلة Scrapling وكتابة كود صحيح لاستخراج البيانات دون مغادرة المحرر.++توجد المهارة في مجلد [agent-skill](https://github.com/D4Vinci/Scrapling/tree/main/agent-skill) داخل المستودع باسم `scrapling-official`، ويتبع إصدارها دائمًا إصدار المكتبة.++## التثبيت {#installation}++### Skills.sh {#skillssh}++ثبّت المهارة من المستودع باستخدام أداة [skills.sh](https://skills.sh) لسطر الأوامر:++```bash+npx skills add D4Vinci/Scrapling --skill scrapling-official+```++تكتشف الأداة الوكلاء المثبّتين لديك وتضيف المهارة إليهم.++### Clawhub {#clawhub}++إذا كنت تستخدم OpenClaw، يمكنك تثبيت المهارة عبر [Clawhub](https://docs.openclaw.ai/tools/clawhub):++```bash+clawhub install scrapling-official+```++أو ثبّتها من [صفحتها على Clawhub](https://clawhub.ai/D4Vinci/scrapling-official).++### التنزيل اليدوي {#manual-download}++نزّل ملف ZIP الخاص بالمهارة [مباشرة من المستودع](https://github.com/D4Vinci/Scrapling/raw/refs/heads/main/agent-skill/Scrapling-Skill.zip)، ثم فكّه داخل مجلد مهارات الوكيل. في Claude Code، هذا المجلد هو `~/.claude/skills/`.++## محتويات المهارة {#whats-inside}++- **`SKILL.md`**: نقطة البداية التي يقرأها الوكيل أولًا. تشرح الإعداد، واختيار أداة الجلب، وقواعد الأمان التي يجب أن يتبعها، مثل تمرير `--ai-targeted` دائمًا إلى أوامر CLI للحماية من حقن التعليمات.+- **`references/`**: نسخ Markdown من صفحات التوثيق، تشمل التحليل والجلب والعناكب وخادم MCP والتكاملات. تُحمّل عند الحاجة فقط، فلا تستهلك مساحة سياق الوكيل قبل أن يحتاج إليها.+- **`examples/`**: سكربتات جاهزة للتشغيل يستطيع الوكيل نسخ الكود منها.++اختبرنا المهارة مع OpenClaw وClaude Code. إذا واجهت مشكلة، افتح [بلاغًا](https://github.com/D4Vinci/Scrapling/issues/new/choose) أو تواصل معنا على [خادم Discord](https://discord.gg/EMgGbDceNQ).diff --git a/docs/locales/ar/ai/building-rag-systems.md b/docs/locales/ar/ai/building-rag-systems.mdnew file mode 100644index 0000000..ac478cf--- /dev/null+++ b/docs/locales/ar/ai/building-rag-systems.md@@ -0,0 +1,109 @@+---+title: "حوّل المواقع إلى Markdown لأنظمة RAG باستخدام Scrapling"+description: "حوّل استجابات الصفحات إلى Markdown أو استخدم ContentSpider لجمع موقع كامل. جهّز النصوص للتقسيم والفهرسة في نظام RAG."+---++# بناء أنظمة RAG باستخدام Scrapling {#building-rag-systems-with-scrapling}++جودة أنظمة RAG تعتمد على جودة النصوص التي تدخل إليها. يستهلك HTML الخام الرموز في الوسوم وقوائم التنقل والسكربتات وعناصر التتبع غير المفيدة. وقد يحمل أيضًا محتوى مخفيًا لحقن التعليمات في النموذج اللغوي. تحوّل Scrapling الصفحات والمواقع الكاملة إلى Markdown نظيف، وتزيل المحتوى المخفي دون استخدام نموذج لغوي. بذلك تكون عملية جمع النصوص سريعة، ولا تدفع تكلفة نموذج لكل صفحة.++## التثبيت {#installation}++```bash+pip install "scrapling[rag]"++scrapling install+```++تثبّت مجموعة `rag` أدوات الجلب مع دعم التحويل إلى Markdown. وتشمل مجموعات `ai` و`shell` و`all` هذا الدعم أيضًا. ينزّل أمر `scrapling install` متطلبات المتصفح، وهي مطلوبة فقط لأدوات الجلب التي تستخدم المتصفح.++## تحويل صفحة واحدة إلى Markdown {#one-page-to-markdown}++يحتوي كل كائن [Response](../fetching/choosing.md#response-object) على الدالة `markdown()`:++```python+from scrapling.fetchers import Fetcher++markdown = Fetcher.get("https://example.com").markdown(main_content_only=True)+```++تعمل مع جميع أدوات الجلب، لذا يمكنك تحويل الصفحات المحمية بـ Cloudflare بسطر واحد أيضًا:++```python+from scrapling.fetchers import StealthyFetcher++markdown = StealthyFetcher.fetch("https://protected.example.com", solve_cloudflare=True).markdown(main_content_only=True)+```++يتحكم معاملان في الناتج:++- `main_content_only`: يحوّل المحتوى الموجود داخل وسم `<body>` فقط.+- `css_selector`: يحوّل العناصر المطابقة لمحدد CSS فقط، ويجمع جميع النتائج المطابقة معًا. استخدمه لاستخراج الجزء الذي تحتاج إليه بالضبط وتقليل استهلاك الرموز:++```python+markdown = Fetcher.get("https://example.com/docs/page").markdown(css_selector="article")+```++بغض النظر عن المعاملات التي تمرّرها، تُزال السكربتات والأنماط والمحتوى المخفي دائمًا قبل التحويل. هذا هو التنظيف نفسه الذي يستخدمه [خادم MCP](mcp-server.md) لحماية وكلاء الذكاء الاصطناعي من حقن التعليمات: يزيل العناصر المخفية بأنماط مباشرة، وعناصر `aria-hidden="true"`، وعناصر slot المخفية، ووسوم `<template>`، وتعليقات HTML، والمحارف عديمة العرض. يستخدم خادم MCP هذا التنظيف مع `main_content_only=True`.++## تحويل موقع كامل إلى مجموعة ملفات Markdown {#a-whole-website-to-a-markdown-corpus}++يزحف قالب `ContentSpider` إلى الموقع ويحوّل كل صفحة باستخدام [إطار العناكب](../spiders/architecture.md). بذلك تحصل على التزامن، وضبط السرعة تلقائيًا، واحترام robots.txt، والإيقاف والاستكمال دون إعداد هذه الميزات بنفسك:++```python+from scrapling.spiders import ContentSpider++class DocsSpider(ContentSpider):+ name = "docs"+ start_urls = ["https://example.com/docs/"]+ allowed_domains = {"example.com"}+ output_dir = "docs_markdown"+ max_pages = 200++result = DocsSpider().start()+result.items.to_jsonl("docs.jsonl")+```++تنتج كل صفحة عنصرًا واحدًا يحتوي على المفاتيح `url` و`title` و`markdown`. وعند تعيين `output_dir`، تُحفظ كل صفحة أيضًا في ملف Markdown اسمه مشتق من رابطها. لذا ينتج المثال أعلاه مجلدًا من ملفات `.md` وملف `docs.jsonl` جاهزًا للمعالجة.++يتطلب القالب تعيين `allowed_domains` ليبقى الزحف داخل الموقع المطلوب. الخيارات هي:++- `css_selector` / `main_content_only`: يُمرّران إلى `markdown()` لكل صفحة. ويكون `main_content_only` مفعّلًا افتراضيًا.+- `output_dir`: عند تعيينه، يُكتب ملف Markdown لكل صفحة.+- `max_pages`: أقصى عدد صفحات للتحويل. قد تُجلب الطلبات الموجودة بالفعل في قائمة الانتظار عند بلوغ الحد، لكنها لن تُحوّل. القيمة `0`، وهي الافتراضية، تلغي هذا الحد.++يتبع القالب افتراضيًا كل رابط صفحة داخل `allowed_domains`. ولأنه مبني على [CrawlSpider](../spiders/generic-templates.md#crawlspider)، يمكنك تعريف `rules()` مع [LinkExtractor](../spiders/generic-templates.md#linkextractor-reference) الخاص بك للتحكم في الزحف: يحدد `allow` أنماط الروابط المطلوبة، ويستبعد `deny` الأنماط غير المطلوبة، مثل صفحات تسجيل الدخول وقوائم الوسوم ونسخ الطباعة:++```python+from scrapling.spiders import CrawlRule, LinkExtractor, ContentSpider++class DocsSpider(ContentSpider):+ name = "docs"+ start_urls = ["https://example.com/"]+ allowed_domains = {"example.com"}++ def rules(self):+ return [CrawlRule(LinkExtractor(allow=r"/docs/", deny=[r"/docs/changelog/", r"\?print="]))]+```++تكون الأولوية لـ `deny` على `allow`. ويمكن أن تتضمن القاعدة `priority` أو دالة `process_request` كما في أي **CrawlSpider**.++## إدخال البيانات إلى مخزن المتجهات {#feeding-a-vector-store}++يمكن استخدام ملف JSONL الناتج مع أي مسار عمل لإنشاء embeddings، أي تمثيلات رقمية للنصوص. مثال بسيط:++```python+import json++with open("docs.jsonl", encoding="utf-8") as f:+ for line in f:+ page = json.loads(line)+ for chunk in split_into_chunks(page["markdown"]):+ vector_store.add(text=chunk, metadata={"url": page["url"], "title": page["title"]})+```++استخدم `css_selector` في العنكبوت لإزالة المحتوى المتكرر قبل تقسيم النص، بدلًا من تنظيفه لاحقًا. كلما قل المحتوى غير المفيد في البيانات التي تحوّلها إلى متجهات، تحسّنت نتائج الاسترجاع.++## بدائل تفاعلية {#interactive-alternatives}++إذا كنت تفضّل استخراج البيانات عبر المحادثة بدلًا من مسارات المعالجة، فإن [خادم MCP](mcp-server.md) يتيح لمساعد الذكاء الاصطناعي أدوات استخراج Markdown نفسها. كما تعلّم [مهارة الوكيل](agent-skill.md) وكلاء البرمجة كتابة هذا الكود بأنفسهم.diff --git a/docs/locales/ar/ai/mcp-server.md b/docs/locales/ar/ai/mcp-server.mdnew file mode 100644index 0000000..3157900--- /dev/null+++ b/docs/locales/ar/ai/mcp-server.md@@ -0,0 +1,556 @@+---+title: "خادم Scrapling MCP: الإعداد وطرق استخراج البيانات"+description: "اربط عميل ذكاء اصطناعي بـ Scrapling للجلب عبر HTTP والمتصفح. استخدم الجلسات وحالة تسجيل الدخول المحفوظة والإجراءات والاستخراج المحدد وسجل API."+---++# دليل خادم Scrapling MCP {#scrapling-mcp-server-guide}++<iframe width="560" height="315" src="https://www.youtube.com/embed/qyFk3ZNwOxE?si=3FHzgcYCb66iJ6e3" title="مشغّل فيديو YouTube" frameborder="0" allow="accelerometer; autoplay; clipboard-write; encrypted-media; gyroscope; picture-in-picture; web-share" referrerpolicy="strict-origin-when-cross-origin" allowfullscreen></iframe>++**خادم Scrapling MCP** ميزة جديدة توفر قدرات Scrapling القوية لاستخراج بيانات الويب مباشرة داخل مساعد الذكاء الاصطناعي أو الوكيل الذي تفضّله. يتيح هذا التكامل جلب المواقع واستخراج بياناتها وتجاوز الحماية من البوتات بالمحادثة، عبر واجهة Claude أو أي واجهة تدعم MCP.++## الميزات {#features}++يوفر خادم Scrapling MCP ست عشرة أداة لاستخراج بيانات الويب والتفاعل مع المتصفح. تجلب أدوات الاستخدام الواحد رابطًا واحدًا، ثم تغلق المتصفح أو العميل الذي فتحته. أما أدوات الجلسات فتحتفظ بـ cookies والإعدادات بين الاستدعاءات، ليواصل الذكاء الاصطناعي إجراءات المتصفح في التبويب نفسه ويفحص سجل الشبكة.++### أدوات الاستخدام الواحد {#one-shot-tools}++#### 🚀 استخراج سريع عبر HTTP {#basic-http-scraping}++- **`make_request`**: طلبات HTTP سريعة بأي طريقة، مثل GET وPOST وPUT وDELETE، مع محاكاة بصمة المتصفح وتوليد ترويسات متصفح حقيقية تطابق إصدار TLS، ودعم HTTP/3، وغير ذلك!++#### 🔒 استخراج بمتصفح Stealthy {#stealth-browser-scraping}++- **`browser_fetch_once`**: شغّل JavaScript واستخرج بيانات الصفحات الديناميكية باستخدام متصفح Stealthy. يدعم تعديل البصمة وتجاوز Cloudflare Turnstile وInterstitial، والتحكم في المتصفح والطلب!++### أدوات الجلسات {#session-tools}++#### 🔌 إدارة الجلسات {#session-management}++- **`browser_open`**: ينشئ جلسة متصفح Stealthy مستمرة تظل مفتوحة عبر عدة استدعاءات لـ `browser_fetch`، لتجنب تكلفة تشغيل متصفح جديد كل مرة. تحفظ إعدادات المتصفح وتُرجع `session_id` و`session_type` فقط. استخدم `list_sessions` للاطلاع على `settings` الفعلية، وهي فارغة في جلسات CDP.+- **`open_request_session`**: ينشئ جلسة HTTP مستمرة دون متصفح، لاستخدامها مع `session_make_request`. تحتفظ بـ cookies والاتصالات وبصمة المتصفح `impersonate` بين الطلبات. تُرجع `session_id` و`session_type` فقط، ويكون النوع `static`. استخدم `list_sessions` للاطلاع على `settings` الفعلية.+- **`close_session`**: يغلق جلسة مستمرة، سواء للمتصفح أو للطلبات، ويحرر مواردها.+- **`list_sessions`**: يعرض كل الجلسات النشطة مع تفاصيلها و`settings`.++#### حالة المتصفح {#browser-state}++- **`browser_save_state`**: يحفظ cookies وlocal storage وIndexedDB في ملف JSON متوافق مع Playwright، لتتمكن من إعادة استخدام حالة تسجيل الدخول بعد انتهاء جلسة المتصفح. يحل الحفظ محل الملف إذا كان موجودًا.+- **`browser_load_state`**: يستعيد ملفًا محفوظًا داخل جلسة متصفح مفتوحة، حتى قبل أول تحميل لصفحة. يستبدل الحالة المخزنة الحالية دون إغلاق التبويبات الموجودة أو تغيير صفحاتها. اجلب الصفحة أو أعد تحميلها لاستخدام تسجيل الدخول المستعاد.++تُحفظ ملفات الحالة على الجهاز الذي يشغّل خادم MCP. ولا تشمل `sessionStorage` أو التبويبات المفتوحة أو إعدادات المتصفح.++#### 🎯 الجلب عبر جلسة {#fetching-through-a-session}++- **`browser_fetch`**: يشغّل JavaScript ويستخرج بيانات رابط واحد عبر جلسة متصفح Stealthy مفتوحة، مع تعديل البصمة وتجاوز Cloudflare Turnstile وInterstitial. ويمكنه أيضًا أخذ وصف منظم للصفحة يشمل مراجع العناصر ومواضعها وأحجامها، لمساعدة الذكاء الاصطناعي على تحديد عناصر التحكم وتخطيط حركة الفأرة.+- **`session_make_request`**: يرسل طلبات HTTP سريعة بأي طريقة، مثل GET وPOST وPUT وDELETE، مع محاكاة بصمة المتصفح والترويسات المطابقة ودعم HTTP/3. يعيد استخدام cookies والاتصالات وبصمة المتصفح عبر جلسة مفتوحة باستخدام `open_request_session`.++#### 📸 لقطات الشاشة {#screenshots}++- **`browser_screenshot`**: يلتقط الصفحة الحالية أو عنصرًا محددًا بصيغة PNG أو JPEG دون إعادة تحميلها. افحص الحقول المملوءة والقوائم المفتوحة والرسوم وبطاقات النتائج، مع تقليل المحتوى غير المرتبط عند تصوير عنصر واحد. يدعم الجزء المرئي والصفحة الكاملة والعنصر الواحد، مع إمكانية ضبط جودة JPEG. تُرجع اللقطة ككتلة صورة فعلية يستطيع النموذج رؤيتها مباشرة.++#### محتوى الصفحة الحالية {#current-page-content}++- **`browser_extract`**: يقرأ الصفحة الحالية أو عنصرًا واحدًا كوصف منظم للذكاء الاصطناعي، أو HTML أو Markdown أو نص، دون إعادة تحميل الصفحة. استخرج النتائج بعد ملء النماذج أو تحميل مزيد من المحتوى. يتضمن الوصف أدوار العناصر وأسماءها ومراجعها ومواضعها وأحجامها لاستخدامها في إجراءات لاحقة. ويُرجع البحث باستخدام regex أسطر الوصف المطابقة مع السياق القريب والعناصر الآباء.++#### إجراءات المتصفح {#browser-actions}++- **`browser_actions`**: يجمع حركات الفأرة وملء الحقول واختصارات لوحة المفاتيح والرد على مربعات الحوار والانتظار في استدعاء واحد. اقبل تنبيهات المتصفح ورسائل التأكيد أو ارفضها، أو أدخل نصًا في مربعات الطلب. مثلًا: املأ مربع بحث، وأرسل البحث، وانتظر النتائج، ثم افتح نتيجة. يستطيع الذكاء الاصطناعي جمع الخطوات المعروفة، وأخذ وصف الصفحة بشكل منفصل عندما يحتاج إلى فحص تغيير فيها.++ أظهر القوائم والتلميحات التي تظهر عند مرور الفأرة، وانقر الأزرار والروابط، أو حرّك الفأرة فوق لوحة داخلية ومرّرها رأسيًا أو أفقيًا. تدعم الحركة والنقر المحددات ومراجع وصف الصفحة والإحداثيات، مع الانتظار التلقائي وتمرير العنصر إلى الجزء المرئي عند استهداف عنصر. كما تدعم الحركة بالإحداثيات على عدة خطوات، والنقر بالزر الأيسر والأيمن والأوسط، والنقر المزدوج.++ استهدف الحقول في أي مكان باستخدام المحددات أو مراجع وصف الصفحة. املأ النصوص، وحدّد مربعات الاختيار أو ألغِها، واختر أزرار radio، وحدّد خيارًا أو أكثر من القوائم المنسدلة الأصلية حسب النص الظاهر. يمكن للنص أن يستبدل المحتوى الحالي أو يمسحه أو يُضاف عند موضع المؤشر. تستطيع اختصارات لوحة المفاتيح تحديد النص وحذفه ونقل التركيز وإرسال النماذج وإغلاق القوائم. يكتب الوضع البطيء حرفًا واحدًا في كل مرة، مع فترات توقف عشوائية بين الأحرف وكل الإجراءات.++ انتظر ظهور النتائج أو اختفاء طبقات التحميل أو وقوع أحداث تحميل الصفحة قبل الإجراء التالي. تدعم الأداة أيضًا فترات انتظار ثابتة وانتظار استقرار نشاط الشبكة.++#### JavaScript {#javascript}++- **`browser_evaluate`**: يشغّل JavaScript في الصفحة الحالية لاستخراج بيانات مخصصة، وإجراء حسابات، وتنفيذ مهام خاصة بالصفحة. يستطيع الذكاء الاصطناعي جمع بيانات عدة عناصر أو قراءة حالة التطبيق أو تحديث محتوى الصفحة. يدعم السكربتات غير المتزامنة ويُرجع نتائجها بصيغة JSON.++#### سجل الشبكة {#network-history}++- **`browser_network_requests`**: يبحث عن الطلبات المكتملة عبر التبويبات وتحميلات الصفحات وإجراءات المتصفح. اكتشف استدعاءات API التي توفر بيانات الصفحة، وافحص أخطاء HTTP، وتتبّع عمليات إعادة التوجيه المحفوظة. تُخفى الموارد الثابتة افتراضيًا لتقليل حجم النتائج. تُرجع تفاصيل الطلبات بصيغة JSON، مع تقسيم السجلات الطويلة إلى صفحات.+- **`browser_network_request`**: يفحص ملخص طلب مسجل واحد أو ترويساته أو بياناته المُرسلة أو نص استجابته بصيغة JSON منظمة. يُرجع الجزء المحدد كاملًا دون تحميل الصفحة أو إرسال الطلب مجددًا. تبقى الاستجابات المحفوظة متاحة بعد تغير الصفحة. تحدّ حدود الحجم من حجم السجل، وتوضح ملاحظة سبب عدم حفظ المحتوى غير النصي أو الكبير أو غير القابل للقراءة. اقرأ التفاصيل التي تحتاجها قبل إغلاق جلسة MCP.++تُقرأ أجسام الاستجابات وتُحفظ فقط عندما تكون قيمة `Content-Type` من الأنواع النصية المدعومة، مثل HTML وJSON وXML وJavaScript. أما الأنواع الثنائية أو المفقودة أو غير المعروفة، فتُحفظ بيانات الطلب وترويساته دون قراءة جسم الاستجابة أو حفظه. ويواصل المتصفح تحميل الموارد كالمعتاد.++تُحفظ الطلبات المكتملة فقط، بما فيها استجابات HTTP من فئتي 4xx و5xx. تُستبعد الطلبات الفاشلة وغير المكتملة. تظهر السجلات بعد انتهاء التقاطها، ولا تنتظر قراءة السجل أو إغلاق الجلسة اكتمال الالتقاط. قد تُستبعد عمليات الالتقاط التي ما زالت جارية عند الانتقال أو الإغلاق. تأتي البايتات المحفوظة من المتصفح، وقد تختلف عن بايتات الخادم. يتبع النص المسجل فك ترميز UTF-8 في Playwright عندما يكون صالحًا، ويستخدم الترميز المعلن كبديل.++### Shadow DOM {#shadow-dom}++اضبط `pierce_shadow=true` في `browser_fetch_once` أو في كل استدعاء لـ `browser_fetch` لتضمين محتوى Shadow DOM المفتوح. قيمته الافتراضية `false`. راجع [Shadow DOM](../fetching/stealthy.md#shadow-dom) لأمثلة المحددات وحدود الدعم.++### القدرات الرئيسية {#key-capabilities}++- **استخراج المحتوى بذكاء**: حوّل الصفحات والعناصر إلى Markdown أو HTML، أو استخرج نسخة نظيفة من النص.+- **دعم محددات CSS**: استخدم محرك Scrapling لاستهداف عناصر معينة بدقة قبل إرسال المحتوى إلى الذكاء الاصطناعي.+- **تجاوز الحماية من البوتات**: تعامل مع Cloudflare Turnstile وInterstitial وغيرها من وسائل الحماية.+- **دعم proxies**: استخدمها لإخفاء هويتك أو استهداف موقع جغرافي.+- **محاكاة المتصفح**: حاكِ المتصفحات الحقيقية عبر بصمة TLS وترويسات حقيقية تطابق الإصدار، وغير ذلك.+- **استمرار الجلسات**: أعد استخدام جلسات المتصفح عبر عدة طلبات لتحسين الأداء.+- **حظر الإعلانات**: تحظر جميع أدوات المتصفح تلقائيًا الطلبات إلى نحو 3,500 نطاق معروف للإعلانات والتتبع، لتوفير الرموز وتسريع تحميل الصفحات.+- **الحماية من حقن التعليمات**: يزيل المحتوى المخفي تلقائيًا، مثل العناصر المخفية بأنماط مباشرة وaria-hidden وعناصر slot المخفية والمحارف عديمة العرض وتعليقات HTML ووسوم template، التي قد تُستخدم لحقن تعليمات ضارة.++#### لماذا تستخدم خادم Scrapling MCP بدلًا من الأدوات الأخرى؟ {#but-why-use-scrapling-mcp-server-instead-of-other-available-tools}++إلى جانب قدراته على التخفي وتجاوز Cloudflare Turnstile وInterstitial، فإن خادم Scrapling هو الوحيد الذي يتيح اختيار عناصر معينة لإرسالها إلى الذكاء الاصطناعي، لتوفير الكثير من الوقت والرموز!++تستخرج الخوادم الأخرى المحتوى ثم ترسله كله إلى الذكاء الاصطناعي ليستخرج الحقول المطلوبة. وهذا يستهلك رموزًا أكثر بكثير من اللازم بسبب المحتوى غير المرتبط بالمهمة. تحل Scrapling هذه المشكلة بالسماح بتمرير محدد CSS لتضييق المحتوى المطلوب قبل إرساله إلى النموذج، فتكون العملية أسرع وأكثر كفاءة.++إذا كنت لا تعرف كتابة محددات CSS أو استخدامها، فلا تقلق. اطلب من الذكاء الاصطناعي كتابة محددات للحقول المحتملة، وسيجرّب تراكيب مختلفة حتى يجد المناسب، كما سنوضح في قسم الأمثلة.++## التثبيت {#installation}++ثبّت Scrapling مع دعم MCP، ثم تأكد من تثبيت متطلبات المتصفح.++```bash+# Install Scrapling with MCP server dependencies+pip install "scrapling[ai]"++# Install browser dependencies+scrapling install+```++أو استخدم صورة Docker مباشرة من سجل Docker:++```bash+docker pull pyd4vinci/scrapling+```++أو نزّلها من سجل GitHub:++```bash+docker pull ghcr.io/d4vinci/scrapling:latest+```++## إعداد خادم MCP {#setting-up-the-mcp-server}++نشرح هنا إضافة خادم Scrapling MCP إلى [Claude Desktop](https://claude.ai/download) و[Claude Code](https://www.anthropic.com/claude-code)، لكن الفكرة نفسها تنطبق على أي مساعد يدعم MCP:++!!! note "ملاحظة:"++ أُضيف أمر `scrapling-mcp` المستخدم أدناه في الإصدار 0.4.13 كاختصار مباشر لـ `scrapling mcp`، لتسهيل إضافة Scrapling إلى سجلات MCP والعملاء الذين يتوقعون أمرًا واحدًا. إذا كنت تستخدم إصدارًا أقدم، فاستخدم `scrapling` مع `mcp` كأول معامل.++### Claude Desktop {#claude-desktop}++1. افتح Claude Desktop.+2. انقر قائمة ☰ في أعلى اليسار، ثم Settings، ثم Developer، ثم Edit Config.+3. أضف إعداد خادم Scrapling MCP:++```json+"ScraplingServer": {+ "command": "scrapling-mcp"+}+```++إذا كان هذا أول خادم MCP تضيفه، فاجعل محتوى الملف كما يلي:++```json+{+ "mcpServers": {+ "ScraplingServer": {+ "command": "scrapling-mcp"+ }+ }+}+```++وفقًا لـ [المقال الرسمي](https://modelcontextprotocol.io/quickstart/user)، تُنشئ هذه الخطوة ملف إعداد جديدًا إذا لم يكن موجودًا، أو تفتح الملف الحالي. يوجد الملف في:++1. **MacOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`+2. **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`++للتأكد من عمل الإعداد، استخدم المسار الكامل للملف التنفيذي `scrapling-mcp`:++1. **MacOS**: `which scrapling-mcp`+2. **Windows**: `where scrapling-mcp`++على جهاز Mac الخاص بي، كانت النتيجة `/Users/<MyUsername>/.venv/bin/scrapling-mcp`، لذا استخدمت الإعداد التالي:++```json+{+ "mcpServers": {+ "ScraplingServer": {+ "command": "/Users/<MyUsername>/.venv/bin/scrapling-mcp"+ }+ }+}+```++#### Docker {#docker}++إذا كنت تستخدم صورة Docker، فسيكون الإعداد مثل هذا:++```json+{+ "mcpServers": {+ "ScraplingServer": {+ "command": "docker",+ "args": [+ "run", "-i", "--rm", "pyd4vinci/scrapling", "mcp"+ ]+ }+ }+}+```++تنطبق الفكرة نفسها على [Cursor](https://cursor.com/docs/context/mcp) و[WindSurf](https://windsurf.com/university/tutorials/configuring-first-mcp-server) وغيرهما.++### Claude Code {#claude-code}++الإعداد هنا أبسط بكثير. مع [Claude Code](https://www.anthropic.com/claude-code):++```bash+claude mcp add ScraplingServer "/Users/<MyUsername>/.venv/bin/scrapling-mcp"+```++للحصول على مسار الملف التنفيذي لـ Scrapling:++1. **MacOS**: `which scrapling-mcp`+2. **Windows**: `where scrapling-mcp`++للتفاصيل، راجع مقال Anthropic الرئيسي عن [إضافة خوادم MCP إلى Claude Code](https://docs.anthropic.com/en/docs/claude-code/mcp#option-1%3A-add-a-local-stdio-server).++بعد إضافة الخادم، أغلق التطبيق الذي استخدمته بالكامل وأعد تشغيله. في Claude Desktop، يفترض أن يظهر مؤشر خادم MCP، وهو 🔧، أسفل يمين مربع المحادثة، أو يظهر `ScraplingServer` في قائمة `Search and tools` داخل مربع الإدخال.++### استخدام ملف متصفح تنفيذي مخصص {#custom-browser-executable}++تستطيع أداتا `browser_fetch_once` و`browser_open` استخدام ملف تنفيذي لمتصفح متوافق مع Chromium بدلًا من Chromium المرفق. يفيد ذلك مع نسخ المتصفحات المخصصة أو محركات المتصفح الخفيفة.++لإعداده مرة واحدة لخادم MCP كله، مرّر مسار الملف التنفيذي عند بدء الخادم:++```bash+scrapling-mcp --executable-path "/path/to/chromium"+```++في إعداد Claude Desktop، أضف الخيار إلى معاملات الخادم:++```json+{+ "mcpServers": {+ "ScraplingServer": {+ "command": "/Users/<MyUsername>/.venv/bin/scrapling-mcp",+ "args": [+ "--executable-path",+ "/path/to/chromium"+ ]+ }+ }+}+```++يمكنك أيضًا تعيين متغير البيئة `SCRAPLING_EXECUTABLE_PATH` قبل بدء الخادم. ويستطيع الذكاء الاصطناعي اختيار ملف متصفح مختلف لجلب واحد باستخدام `browser_fetch_once` أو عند فتح جلسة باستخدام `browser_open`.++### الاتصال بمتصفحات بعيدة {#connecting-to-remote-browsers}++لا يحتاج `browser_open` إلى تشغيل متصفح محلي. مرّر رابط CDP ليتصل بمتصفح يعمل بالفعل عبر [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/)، سواء كان على الجهاز نفسه أو جهاز آخر أو لدى مزوّد متصفحات مُدارة:++```+Open a stealthy browser session on wss://cdp.provider.example/session/abc123, then use it to scrape the product details from https://shop.example.com. Close the session when you're done.+```++تستخدم `session_id` الناتج كالمعتاد مع `browser_fetch` و`browser_extract` و`browser_actions` و`browser_evaluate` و`browser_screenshot` و`browser_network_requests` و`browser_network_request` و`browser_save_state` و`browser_load_state`.++يمكن أن يكون الرابط عنوان WebSocket يبدأ بـ `ws://` أو `wss://`، كما يوفره مزوّدو المتصفحات المُدارة، أو عنوان HTTP لمتصفح شغّلته بنفسك مع تفعيل منفذ تصحيح الأخطاء عن بعد:++```commandline+chrome --remote-debugging-port=9222+```++يمكن الوصول إلى هذا المتصفح باستخدام `cdp_url="http://localhost:9222"`، أو عنوان الجهاز إذا كان المتصفح يعمل على جهاز آخر.++!!! note "ملاحظات:"++ * المتصفح يعمل بالفعل، لذلك تُتجاهل الخيارات الخاصة بالتشغيل فقط في جلسات CDP: وهي `headless` و`real_chrome` و`executable_path`، بما فيها القيمة الافتراضية للخادم الموضحة أعلاه.<br/>+ * تظل بقية الخيارات فعالة، مثل `locale` و`useragent` و`proxy` و`cookies` و`timezone_id`، لأن كل جلسة تنشئ سياق متصفح خاصًا بها على المتصفح البعيد.++### Streamable HTTP {#streamable-http}++منذ الإصدار 0.3.6، يمكن تشغيل خادم MCP بوضع النقل Streamable HTTP بدلًا من وضع stdio التقليدي.++بدلًا من الأمر التالي الذي يستخدم stdio:++```bash+scrapling-mcp+```++استخدم هذا الأمر لتفعيل Streamable HTTP:++```bash+scrapling-mcp --http+```++العنوان الافتراضي الذي يستمع إليه الخادم هو `127.0.0.1`، والمنفذ هو 8000. ويمكن تغييرهما كما يلي:++```bash+scrapling-mcp --http --host '0.0.0.0' --port 8000+```++الإعداد الافتراضي يقبل الاتصالات من الجهاز نفسه فقط. مرّر `--host '0.0.0.0'` عندما تريد إتاحة الخادم عبر الشبكة. هذا قرار منفصل عن إعداد المصادقة أدناه.++إذا شغّلت Streamable HTTP داخل Docker، فيجب الاستماع على `0.0.0.0` وتعيين token، وإلا فلن يصل المنفذ المنشور إلى الخادم، لأن `127.0.0.1` داخل الحاوية لا يظهر إلا لها:++```bash+docker run -p 8000:8000 -e SCRAPLING_MCP_AUTH_TOKEN="<your-token>" pyd4vinci/scrapling mcp --http --host '0.0.0.0'+```++### المصادقة {#authentication}++لا يستطيع الوصول إلى وضع stdio إلا البرنامج الذي بدأه. لكن عند الانتقال إلى Streamable HTTP، يستطيع أي شخص يصل إلى المنفذ استدعاء كل الأدوات، بما فيها جلب أي رابط من الجهاز الذي يشغّل الخادم. لذلك يتطلب Streamable HTTP المصادقة، ويرفض `--http` وحده بدء التشغيل ويطلب token:++```bash+scrapling-mcp --http --auth-token "$(openssl rand -hex 32)"+```++يجب أن يرسل العميل هذا token في ترويسة `Authorization`. ويُرفض أي طلب لا يحتوي عليه برمز `401`:++```json+{+ "mcpServers": {+ "ScraplingServer": {+ "url": "https://your-server.example.com/mcp",+ "headers": {+ "Authorization": "Bearer <your-token>"+ }+ }+ }+}+```++تمرير token في سطر الأوامر يتركه في سجل الطرفية وقائمة العمليات، لذا يُفضّل استخدام متغير البيئة `SCRAPLING_MCP_AUTH_TOKEN`:++```bash+export SCRAPLING_MCP_AUTH_TOKEN="<your-token>"+scrapling-mcp --http+```++إذا أردت خادمًا دون مصادقة، مثل الاختبار محليًا على العنوان الافتراضي `127.0.0.1`، فاطلب ذلك صراحة باستخدام `--no-auth`:++```bash+scrapling-mcp --http --no-auth+```++الجمع بين `--no-auth` و`--host '0.0.0.0'` يتيح كل الأدوات لأي شخص يصل إلى المنفذ، لذا تجنّب هذا الجمع خارج شبكة موثوقة.++عندما يستمع الخادم على عنوان عام، حدّد أيضًا أسماء المضيفين التي يقبلها. هذا يفعّل الحماية من هجمات DNS rebinding، حيث يحاول موقع تزوره الاتصال بخادمك عبر المتصفح. ويمكن تكرار الخيار:++```bash+scrapling-mcp --http --allowed-host 'your-server.example.com:8000'+```++!!! note "ملاحظات:"++ * تنطبق المصادقة على Streamable HTTP فقط. تُتجاهل مع stdio، ويسجل الخادم تحذيرًا بذلك.<br/>+ * يرسل HTTP العادي token دون تشفير، لذا ضع الخادم خلف reverse proxy يتولى اتصال TLS قبل إتاحته على الإنترنت.<br/>+ * يُستخدم مفتاح واحد مشترك، وليس بيانات دخول منفصلة لكل عميل. لذا تستخدم كل التطبيقات token نفسه، ويتطلب تغييره إعادة تشغيل الخادم.<br/>+ * يسجل الخادم تحذيرًا عند تشغيله باستخدام `--http --no-auth` لإبلاغك بأن المصادقة غير مفعّلة.<br/>+ * عند تمرير `--auth-token` و`--no-auth` معًا، يبقى token فعالًا وتستمر المصادقة بدلًا من إلغائها دون تنبيه.++## أمثلة {#examples}++نعرض هنا بعض prompts التي استخدمناها عند اختبار خادم MCP. وربما تكون أكثر إبداعًا منا في كتابة الطلبات :)++سنبدأ بطلبات بسيطة ثم ننتقل تدريجيًا إلى طلبات أكثر تعقيدًا. نستخدم Claude Desktop في الأمثلة، لكن الفكرة نفسها تنطبق على بقية التطبيقات.++1. **استخراج بيانات بسيط**++ استخرج المحتوى الرئيسي من صفحة بصيغة Markdown:++ ```+ Scrape the main content from https://example.com and convert it to markdown format.+ ```++ يستطيع Claude استخدام `make_request` لجلب الصفحة وإرجاع محتوى نظيف وسهل القراءة. تستخدم طلبات HTTP ثلاث محاولات افتراضيًا، مع ثانية واحدة بين المحاولات. وإذا كانت الصفحة تحتاج إلى JavaScript أو تمنع طلبات HTTP، يمكن استخدام `browser_fetch_once`. تغلق الأداتان مواردهما بعد الاستدعاء.++ ويمكن تحسين الطلب نفسه كما يلي:++ ```+ Use regular requests to scrape the main content from https://example.com and convert it to markdown format.+ ```++ يوضح هذا لـ Claude الأداة المطلوبة، فلا يحتاج إلى التخمين. أحيانًا يبدأ بطلبات HTTP العادية بنفسه، وأحيانًا يفترض أن المتصفح أنسب للموقع دون سبب واضح. كقاعدة عامة، حدّد له الأداة دائمًا لتوفير الوقت والتكلفة والحصول على نتائج متسقة.++2. **استخراج بيانات محددة**++ استخرج عناصر معينة باستخدام محددات CSS:++ ```+ Get all product titles from https://shop.example.com using the CSS selector '.product-title'. If the request fails, retry up to 5 times every 10 seconds.+ ```++ يستخرج الخادم العناصر المطابقة للمحدد فقط ويُرجعها في قائمة منظمة. لاحظ أنني طلبت ضبط الأداة على خمس محاولات عند وجود مشاكل اتصال بالموقع، لكن الإعداد الافتراضي مناسب لمعظم الحالات.++3. **جمع بيانات المتاجر الإلكترونية**++ مثال آخر لطلب أكثر تعقيدًا قليلًا:++ ```+ Open a stealthy browser session and visit these e-commerce URLs one at a time:+ - https://shop1.com/product-a+ - https://shop2.com/product-b+ - https://shop3.com/product-c++ Get the product names, prices, and descriptions from each page. Close the session when done.+ ```++ يستطيع Claude إعادة استخدام جلسة متصفح واحدة، واستدعاء `browser_fetch` لكل رابط بالترتيب، ثم تحليل البيانات المستخرجة.++4. **خطوات عمل أكثر تقدمًا**++ لنفترض أنني أريد كل ألعاب الأكشن الموجودة الآن في الصفحة الأولى من متجر PlayStation. يمكنني استخدام الطلب التالي:++ ```+ Extract the URLs of all games on this page, then visit each game in order and return a list of all action games: https://store.playstation.com/en-us/pages/browse+ ```++ اطلب من الذكاء الاصطناعي إعادة استخدام جلسة HTTP لتجنب تشغيل متصفح عندما تكون البيانات متاحة بالطلبات العادية:++ ```+ Open an HTTP session, extract the URLs of all games on this page, then fetch each game in order and return a list of all action games. Close the session when done: https://store.playstation.com/en-us/pages/browse+ ```++ وإذا كنت تعرف كتابة محددات CSS، فيمكنك تقليل المحتوى قبل أن يقرأه النموذج:++ ```+ Use an HTTP session to extract the URLs of all games on the page below, then fetch each game in order and return a list of all action games.+ The selector for games in the first page is `[href*="/concept/"]` and the selector for the genre in each game page is `[data-qa="gameInfo#releaseInformation#genre-value"]`.+ Close the session when done.++ URL: https://store.playstation.com/en-us/pages/browse+ ```++5. **استخراج بيانات موقع محمي بـ Cloudflare**++ إذا كنت تعتقد أن الموقع يستخدم حماية Cloudflare، فأخبر Claude بدلًا من تركه يكتشف ذلك بنفسه.++ ```+ What's the price of this product? Be cautious, as it utilizes Cloudflare's Turnstile protection. Make the browser visible while you work.++ https://ao.com/product/oo101uk-ninja-woodfire-outdoor-pizza-oven-brown-99357-685.aspx+ ```++6. **خطوات عمل طويلة**++ يمكنك مثلًا استخدام طلب كهذا:++ ```+ Extract all product URLs for the following category, then return the prices and details for the first 3 products.++ https://www.arnotts.ie/furniture/bedroom/bed-frames/+ ```++ لكن الطلب التالي أفضل:++ ```+ Go to the following category URL and extract all product URLs using the CSS selector "a". Then, reuse the session to fetch the first 3 product pages in order and extract each product’s price and details. Close the session when done.++ Keep the output in markdown format to reduce irrelevant content.++ Category URL:+ https://www.arnotts.ie/furniture/bedroom/bed-frames/+ ```++7. **استخدام الجلسات المستمرة**++ عند استخراج بيانات عدة صفحات من الموقع نفسه، استخدم جلسة متصفح مستمرة لتجنب تشغيل متصفح جديد لكل طلب:++ ```+ Open a stealthy browser session, then use it to scrape the main details from the first 5 product pages on https://shop.example.com. Close the session when you're done.+ ```++ يستخدم Claude أداة `browser_open` لإنشاء متصفح مستمر، ثم `browser_fetch` لكل صفحة منتج عبر الجلسة نفسها، وأخيرًا `close_session`. هذا أسرع بكثير من تشغيل متصفح جديد لكل صفحة.++ !!! danger "تنبيه"++ عند استخدام الجلسات المستمرة، تذكّر إغلاق الجلسة بعد الانتهاء، وإلا ستظل مفتوحة!++8. **استخدام جلسة مستمرة في مهمة طويلة**++ مثال اختبار طويل آخر يتطلب من Claude التفكير:++ ```+ Use Scrapling MCP to do the following in this order:++ 1. Open a stealthy browser session with headless mode off.+ 2. Go to this page and collect the number of stars: https://github.com/D4Vinci/Scrapling+ 3. From the README, get the URL that shows the number of downloads and go to it.+ 4. Get the number of downloads and the top 3 countries from the graph.+ 5. Prepare a report with the results.+ 6. Close the browser.+ ```++وهكذا. إبداعك هو الأساس هنا.++## أفضل الممارسات {#best-practices}++إليك بعض النصائح التقنية.++### 1. اختر الأداة المناسبة {#1-choose-the-right-tool}++- **`make_request`**: طلبات HTTP سريعة لصفحة واحدة أو استدعاء API.+- **`browser_fetch_once`**: صفحة JavaScript واحدة أو صفحة ديناميكية أو موقع محمي، بما في ذلك Cloudflare.+- **أدوات الجلسات**: طلبات مترابطة، وإجراءات المتصفح، ولقطات الشاشة، وسجل الشبكة.++### 2. حسّن الأداء {#2-optimize-performance}++- أعد استخدام جلسة واحدة واجلب الروابط بالترتيب.+- عطّل الموارد غير المطلوبة.+- اضبط مهل انتظار مناسبة.+- استخدم محددات CSS لاستخراج المحتوى المطلوب فقط.++### 3. تعامل مع المحتوى الديناميكي {#3-handle-dynamic-content}++- استخدم `network_idle` مع تطبيقات الصفحة الواحدة، أو SPA.+- اضبط `wait_selector` لانتظار عناصر معينة.+- زِد مهلة الانتظار للمواقع بطيئة التحميل.++### 4. جودة البيانات {#4-data-quality}++- استخدم `main_content_only=true` لاختيار محتوى body وتنظيفه.+- اختر قيمة `extraction_type` المناسبة لمهمتك.++### 5. الحماية من حقن التعليمات {#5-prompt-injection-protection}++ينظّف خادم MCP المحتوى المستخرج تلقائيًا عند تفعيل `main_content_only`، وهو الإعداد الافتراضي. يزيل هذا المحتوى المخفي الذي قد تستخدمه مواقع ضارة لإدخال تعليمات إلى سياق الذكاء الاصطناعي:++- **أنماط الإخفاء المباشرة**: مثل `display:none` و`visibility:hidden`، والقيم الصفرية للشفافية وحجم الخط والارتفاع والعرض وmax-height وmax-width.+- **عناصر مخفية عن أدوات تسهيل الوصول**: `aria-hidden="true"`.+- **وسوم template وعناصر slot المخفية**: عناصر `<template>` و`<slot hidden>`.+- **تعليقات HTML**: `<!-- ... -->`.+- **محارف عديمة العرض**: محارف Unicode غير المرئية، مثل المسافات عديمة العرض.++تعمل هذه الحماية تلقائيًا مع استخراج HTML وMarkdown والنص. أبقِ `main_content_only=true`، وهو الإعداد الافتراضي، للحصول على أقصى حماية.++### 6. إدارة الجلسات {#6-manage-sessions}++- استخدم `make_request` أو `browser_fetch_once` للجلب المنفرد. تغلقان مواردهما ولا تتركان جلسة للاستدعاءات اللاحقة.+- استخدم `browser_open` لإنشاء جلسة متصفح مستمرة عند جلب عدة صفحات، ثم استدعِ `browser_fetch` لكل صفحة عبر هذه الجلسة.+- لطلبات HTTP العادية المتعددة، استخدم `open_request_session` ثم `session_make_request` لكل طلب. تحتفظ الجلسة بـ cookies والاتصالات وبصمة المتصفح `impersonate` بين الاستدعاءات دون متصفح.+- تحتفظ الجلسات بإعدادات مستوى الجلسة التي عُيّنت عند فتحها، مثل headless وlocale وcookies وخيارات التخفي للمتصفح، و`impersonate` و`proxy` لجلسات الطلبات. أما خيارات كل طلب، مثل timeout وwait_selector وnetwork_idle وsolve_cloudflare، فتُمرّر إلى `browser_fetch` أو `session_make_request` في كل استدعاء. تظهر قيمها الافتراضية في مخططات الأدوات.+- يستطيع `browser_fetch` حل تحديات Cloudflare عبر جلسة متصفح Stealthy المفتوحة.+- أغلق الجلسات دائمًا باستخدام `close_session` بعد الانتهاء لتحرير الموارد.+- استخدم `list_sessions` لمعرفة الجلسات التي ما زالت نشطة، والاطلاع على `settings` التي أُنشئت بها كل جلسة. تُرجع الإعدادات لوكيل الذكاء الاصطناعي، وتكون فارغة لجلسات CDP.+- مرّر `session_id` مخصصًا إلى أدوات فتح الجلسات لإعطائها أسماء واضحة، مثل `"search"` أو `"checkout"`، بدلًا من المعرّف السداسي العشري العشوائي. تُرجع الأدوات خطأ إذا كان المعرّف مستخدمًا، لتكتشف التعارض مبكرًا.++### 7. التقاط صور الشاشة {#7-capturing-screenshots}++- تلتقط `browser_screenshot` الصفحة المفتوحة بالفعل عبر `browser_fetch` في جلسة متصفح Stealthy. لا تعيد تحميل الصفحة، ليستطيع الذكاء الاصطناعي فحص الحقول المملوءة والقوائم المفتوحة ونتائج إجراءاته.+- تُرجع الصورة في كتلة `ImageContent` فعلية، ليراها النموذج مباشرة.+- التقط الجزء المرئي أو الصفحة كاملة، بما فيها المحتوى أسفل الجزء الظاهر.+- التقط حقلًا أو رسمًا أو بطاقة أو نتيجة واحدة لفحصها دون محتوى كثير حولها. قد تمرّر لقطة العنصر الصفحة لإظهاره.+- اختر PNG لصور دون فقدان جودة، أو JPEG بجودة قابلة للضبط لتقليل حجم البيانات.+- يستطيع الذكاء الاصطناعي استخدام `browser_actions` لانتظار المحتوى أو إكمال التفاعل قبل التصوير.++## اعتبارات قانونية وأخلاقية {#legal-and-ethical-considerations}++⚠️ **إرشادات مهمة:**++- **افحص robots.txt**: افتح `https://website.com/robots.txt` لمعرفة قواعد استخراج البيانات.+- **احترم حدود الطلبات**: لا تُثقل الخوادم بكثرة الطلبات.+- **شروط الخدمة**: اقرأ شروط الموقع والتزم بها.+- **حقوق النشر**: احترم حقوق الملكية الفكرية.+- **الخصوصية**: راعِ قوانين حماية البيانات الشخصية.+- **الاستخدام التجاري**: تأكد من امتلاك الإذن المطلوب لأغراض العمل.++---++*صُنع بحب ❤️ بواسطة فريق Scrapling. نتمنى لك تجربة موفقة في استخراج البيانات!*diff --git a/docs/locales/ar/api-reference/custom-types.md b/docs/locales/ar/api-reference/custom-types.mdnew file mode 100644index 0000000..7521a73--- /dev/null+++ b/docs/locales/ar/api-reference/custom-types.md@@ -0,0 +1,26 @@+---+title: "مرجع API للفئتين TextHandler وAttributesHandler"+description: "تعرّف على أدوات النصوص وقوائم النصوص والخصائص في Scrapling، مع الاستخراج باستخدام regex والتحويل إلى JSON والبحث عن القيم."+---++# مرجع API للأنواع المخصصة {#custom-types-api-reference}++هذا مرجع لكل الأنواع المخصصة في Scrapling، مع جميع معاملاتها وخصائصها وطرقها.++يمكنك استيرادها كلها كما يلي:++```python+from scrapling.core.custom_types import TextHandler, TextHandlers, AttributesHandler+```++## ::: scrapling.core.custom_types.TextHandler+ handler: python+ :docstring:++## ::: scrapling.core.custom_types.TextHandlers+ handler: python+ :docstring:++## ::: scrapling.core.custom_types.AttributesHandler+ handler: python+ :docstring:diff --git a/docs/locales/ar/api-reference/fetchers.md b/docs/locales/ar/api-reference/fetchers.mdnew file mode 100644index 0000000..98ced12--- /dev/null+++ b/docs/locales/ar/api-reference/fetchers.md@@ -0,0 +1,48 @@+---+title: "مرجع API لجلب الصفحات عبر HTTP والمتصفح"+description: "تعرّف على API للفئات Fetcher وAsyncFetcher وStealthyFetcher والجلسات، مع خيارات الطلبات وإعدادات المتصفح وأنواع القيم المعادة."+---++# فئات Fetchers {#fetchers-classes}++هذا مرجع لكل معاملات فئات Fetchers وخصائصها وطرقها.++يمكنك استيرادها كلها كما يلي:++```python+from scrapling.fetchers import (+ Fetcher, AsyncFetcher, StealthyFetcher,+ FetcherSession, AsyncStealthySession, StealthySession+)+```++## ::: scrapling.fetchers.Fetcher+ handler: python+ :docstring:++## ::: scrapling.fetchers.AsyncFetcher+ handler: python+ :docstring:++## ::: scrapling.fetchers.StealthyFetcher+ handler: python+ :docstring:+++## فئات الجلسات {#session-classes}++### جلسات HTTP {#http-sessions}++## ::: scrapling.fetchers.FetcherSession+ handler: python+ :docstring:++### جلسات التخفي {#stealth-sessions}++## ::: scrapling.fetchers.StealthySession+ handler: python+ :docstring:++## ::: scrapling.fetchers.AsyncStealthySession+ handler: python+ :docstring:diff --git a/docs/locales/ar/api-reference/mcp-server.md b/docs/locales/ar/api-reference/mcp-server.mdnew file mode 100644index 0000000..8858469--- /dev/null+++ b/docs/locales/ar/api-reference/mcp-server.md@@ -0,0 +1,96 @@+---+title: "مرجع API لخادم MCP في Scrapling"+description: "تعرّف على أدوات خادم MCP ونماذج الطلبات والاستجابات وعمليات الجلسات لجمع البيانات عبر HTTP والمتصفح."+---++# مرجع API لخادم MCP {#mcp-server-api-reference}++يوفر **خادم MCP في Scrapling** ست عشرة أداة لجمع بيانات الويب والتفاعل مع المتصفح عبر Model Context Protocol (MCP). يربط الخادم إمكانات Scrapling مباشرة بمساعدي AI، لتجمع البيانات من خلال المحادثة مع ميزات متقدمة لتجاوز أنظمة منع الروبوتات.++يمكنك تشغيل خادم MCP بالأمر التالي:++```bash+scrapling mcp+```++أو استيراد فئة الخادم مباشرة:++```python+from scrapling.core.ai import ScraplingMCPServer++server = ScraplingMCPServer()+server.serve(http=False, host="127.0.0.1", port=8000)+```++لتحديد ملف تشغيل متصفح متوافق مع Chromium لأدوات MCP التي تستخدم المتصفح، مرّر `executable_path`:++```python+server = ScraplingMCPServer(executable_path="/path/to/chromium")+```++## نموذج الاستجابة {#response-model}++تعيد أدوات الجلب وطلبات HTTP استجابة بالشكل الموحد التالي، باستجابة واحدة لكل استدعاء. تستخدم أدوات إدارة الجلسات النماذج الموضحة أدناه. تعيد `browser_screenshot` صورة للصفحة الحالية أو لعنصر واحد، مع رابط الصفحة، في كتلتي محتوى للصورة والنص. تعيد `browser_extract` و`browser_actions` نصًا عاديًا. تعيد أداتا الشبكة بيانات JSON منظمة باستخدام النماذج أدناه. تعيد `browser_evaluate` نتيجتها بصيغة JSON داخل كتلة نص عادي.++## ::: scrapling.core.ai.server.ResponseModel+ handler: python+ :docstring:++## نماذج طلبات الشبكة {#network-request-models}++تعيد `browser_network_requests` نموذج `NetworkRequestsModel` بالحقول `requests` و`next_cursor` و`has_more` و`dropped_count`. يحتوي كل `NetworkRequestInfo` على `id` و`url` و`method` و`resource_type` و`status`. مرّر `next_cursor` إلى `after_id` للمتابعة. تشير `has_more` إلى وجود نتائج مطابقة أخرى حاليًا.++تعيد `browser_network_request` نموذج `NetworkRequestModel` بالحقول `request_id` و`part` و`data` و`note`. تُعاد الملخصات والترويسات ككائنات، بينما يُعاد نص المحتوى المحفوظ كاملًا كسلسلة نصية، بما فيه نص استجابات JSON. يوضح `note` سبب غياب المحتوى أو عدم اكتمال الترويسات.++## ::: scrapling.core.ai._network_formatting.NetworkRequestInfo+ handler: python+ :docstring:++## ::: scrapling.core.ai.server.NetworkRequestsModel+ handler: python+ :docstring:++## ::: scrapling.core.ai._network_formatting.NetworkRequestModel+ handler: python+ :docstring:++## نماذج الجلسات {#session-models}++فئات النماذج المستخدمة لإدارة الجلسات:++## ::: scrapling.core.ai.server.SessionInfo+ handler: python+ :docstring:++## ::: scrapling.core.ai.server.SessionCreatedModel+ handler: python+ :docstring:++## ::: scrapling.core.ai.server.SessionClosedModel+ handler: python+ :docstring:++## فئة خادم MCP {#mcp-server-class}++فئة خادم MCP الأساسية التي توفر كل أدوات جمع بيانات الويب:++- **`make_request`**: تجلب رابطًا واحدًا عبر HTTP مع محاكاة المتصفح وإغلاق العميل تلقائيًا. تدعم GET وPOST وPUT وDELETE.+- **`browser_fetch_once`**: تجلب رابطًا واحدًا عبر متصفح متخفٍ يشغّل JavaScript ويتعامل مع Cloudflare، ثم تغلق المتصفح. استخدم جلسة مستمرة إذا أردت تنفيذ خطوات لاحقة أو قراءة سجل الشبكة.++- **`browser_extract`**: تقرأ الصفحة الحالية أو عنصرًا واحدًا بصيغة AI snapshot أو HTML أو Markdown أو نص، دون إعادة تحميل الصفحة. تحتفظ بنتائج النماذج والخطوات المنفذة على الصفحة. تتضمن snapshots أدوار العناصر وأسماءها ومراجعها ومواقعها وأحجامها. يعيد البحث باستخدام regex الأسطر المطابقة مع النص القريب والعناصر الأب.+- **`browser_actions`**: تنفذ سلسلة خطوات في استدعاء واحد: تحريك الماوس، والمرور فوق العناصر، والنقر، والتمرير، وملء الحقول، واختصارات لوحة المفاتيح، والرد على نوافذ الحوار، والانتظار. يمكنك قبول التنبيهات والتأكيدات أو رفضها، وإدخال نص في نوافذ الطلب. املأ حقل بحث وأرسله وانتظر النتائج وافتح نتيجة دون استدعاء مستقل لكل خطوة.++ تحدد أهداف الحركة والنقر باستخدام selectors أو مراجع snapshot أو الإحداثيات. عند استهداف عنصر، تنتظر الأداة ظهوره وتمرر الصفحة حتى يصبح مرئيًا. تدعم الحركة على عدة خطوات، والنقر بالأزرار الأيسر والأيمن والأوسط، والنقر المزدوج، وتمرير اللوحات المتداخلة.++ استهدف الحقول في أي مكان بالصفحة باستخدام selectors أو مراجع snapshot. أدخل نصًا، وحدد مربعات الاختيار أو ألغِ تحديدها، وحدد أزرار الاختيار، واختر خيارًا أو أكثر من القوائم الأصلية باستخدام نص الخيار. استبدل النص أو امسحه، أو اكتب عند موضع المؤشر الحالي. تعمل اختصارات لوحة المفاتيح على العنصر الذي يملك التركيز حاليًا. يضيف الوضع البطيء فترات توقف عشوائية بين الأحرف المكتوبة وبين كل الخطوات.++ انتظر ظهور المحتوى أو اختفاء طبقات التحميل باستخدام selectors أو مراجع snapshot. يمكنك أيضًا انتظار أحداث تحميل الصفحة أو استقرار نشاط الشبكة، أو إضافة فترة انتظار ثابتة قبل المتابعة.++- **`browser_evaluate`**: تشغّل JavaScript على الصفحة الحالية لاستخراج بيانات مخصصة أو حساب نتائج أو قراءة حالة التطبيق أو تحديث محتوى الصفحة. تدعم البرامج غير المتزامنة وتعيد نتائجها بصيغة JSON.+- **`browser_network_requests`**: تبحث في طلبات المتصفح المكتملة عبر علامات التبويب والتنقل والخطوات المنفذة. اعثر على استدعاءات API وأخطاء HTTP وعمليات إعادة التوجيه المحفوظة. تُخفى الموارد الثابتة افتراضيًا لتقليل حجم النتائج، ولا تُدرج الطلبات الفاشلة أو غير المكتملة. تعيد تفاصيل منظمة للطلبات مع تقسيم النتائج إلى صفحات.+- **`browser_network_request`**: تقرأ ملخص طلب مسجل أو ترويساته أو بياناته المرسلة أو نص استجابته بصيغة JSON منظمة، دون تكرار الطلب. تعيد الجزء المحدد كاملًا، بما فيه نص المحتوى المحفوظ. تبقى الاستجابات المحفوظة متاحة بعد تغير الصفحة، بما فيها استجابات HTTP من الفئتين 4xx و5xx. تظهر السجلات بعد اكتمال الحفظ. قراءة السجل وإغلاق الجلسة لا ينتظران اكتماله، وقد لا تُدرج عمليات الحفظ التي ما زالت تعمل عند التنقل أو الإغلاق. تأتي البايتات المحفوظة من Playwright وقد تختلف عن بايتات الخادم. يستخدم النص المسجل فك ترميز UTF-8 من Playwright عندما يكون صالحًا، وإلا يستخدم الترميز المعلن. تُقرأ وتُحفظ فقط أجسام الاستجابات ذات `Content-Type` النصي المدعوم. تحتفظ الأنواع الثنائية أو المفقودة أو غير المعروفة بالبيانات الوصفية والترويسات دون قراءة الجسم، ويستمر تحميل المتصفح كالمعتاد. تحد حدود الحجم من السجل المحفوظ. وقد توضح ملاحظة سبب عدم حفظ محتوى غير نصي أو كبير أو غير قابل للقراءة. اقرأ التفاصيل التي تحتاجها قبل إغلاق جلسة MCP.+- **`browser_fetch`**: تجلب صفحة عبر جلسة متصفح متخفٍ مفتوحة، وتستخرج HTML أو Markdown أو نصًا أو snapshot منظمة. يمكن أن تشمل snapshot الصفحة كلها أو عنصرًا محددًا، وتضم مراجع العناصر ومواقعها وأحجامها لاستخدامها في خطوات لاحقة.++## ::: scrapling.core.ai.server.ScraplingMCPServer+ handler: python+ :docstring:diff --git a/docs/locales/ar/api-reference/proxy-rotation.md b/docs/locales/ar/api-reference/proxy-rotation.mdnew file mode 100644index 0000000..f3cfa7b--- /dev/null+++ b/docs/locales/ar/api-reference/proxy-rotation.md@@ -0,0 +1,18 @@+---+title: "مرجع API للفئة ProxyRotator"+description: "تعرّف على ProxyRotator وطرق اختيار Proxy وتبديله. اضبط عناوين Proxy لجلسات HTTP والمتصفح."+---++# تبديل Proxy {#proxy-rotation}++تتيح الفئة `ProxyRotator` تبديل عناوين Proxy لأي Fetcher أو جلسة، مع دعم آمن لاستخدامها من عدة threads.++يمكنك استيرادها كما يلي:++```python+from scrapling.fetchers import ProxyRotator+```++## ::: scrapling.engines.toolbelt.proxy_rotation.ProxyRotator+ handler: python+ :docstring:diff --git a/docs/locales/ar/api-reference/response.md b/docs/locales/ar/api-reference/response.mdnew file mode 100644index 0000000..29e415f--- /dev/null+++ b/docs/locales/ar/api-reference/response.md@@ -0,0 +1,18 @@+---+title: "مرجع API للفئة Response في Scrapling"+description: "تعرّف على حالة الاستجابة وترويساتها ومحتواها وبياناتها الوصفية والتحويل إلى Markdown وطريقة follow. استخدم طرق Selector الموروثة لاستخراج البيانات."+---++# الفئة Response {#response-class}++تجمع الفئة `Response` استجابات HTTP من كل Fetchers في شكل واحد. تتيح قراءة الحالة والترويسات والمحتوى وملفات تعريف الارتباط، مع `Selector` لتحليل المحتوى.++يمكنك استيراد الفئة `Response` كما يلي:++```python+from scrapling.engines.toolbelt.custom import Response+```++## ::: scrapling.engines.toolbelt.custom.Response+ handler: python+ :docstring:diff --git a/docs/locales/ar/api-reference/selector.md b/docs/locales/ar/api-reference/selector.mdnew file mode 100644index 0000000..7f5950d--- /dev/null+++ b/docs/locales/ar/api-reference/selector.md@@ -0,0 +1,24 @@+---+title: "مرجع API للفئتين Selector وSelectors"+description: "تعرّف على طرق تحليل HTML واختيار العناصر واستخراج البيانات والتنقل والتتبع المتكيف في Selector وSelectors."+---++# الفئة Selector {#selector-class}++الفئة `Selector` هي أساس تحليل HTML واختيار العناصر في Scrapling.++هذا مرجع لكل المعاملات والخصائص والطرق في الفئة `Selector`.++يمكنك استيراد الفئة `Selector` كما يلي:++```python+from scrapling.parser import Selector+```++## ::: scrapling.parser.Selector+ handler: python+ :docstring:++## ::: scrapling.parser.Selectors+ handler: python+ :docstring:diff --git a/docs/locales/ar/api-reference/spiders.md b/docs/locales/ar/api-reference/spiders.mdnew file mode 100644index 0000000..2ac6959--- /dev/null+++ b/docs/locales/ar/api-reference/spiders.md@@ -0,0 +1,42 @@+---+title: "مرجع API لفئات Spiders والطلبات ونتائج الجمع"+description: "تعرّف على hooks لمراحل عمل Spider وخيارات الطلبات وإدارة الجلسات وإحصاءات الجمع وطرق تصدير العناصر."+---++# فئات Spider {#spider-classes}++هذا مرجع لكل معاملات فئات إطار Spiders وخصائصها وطرقها.++يمكنك استيرادها كما يلي:++```python+from scrapling.spiders import Spider, Request, CrawlResult, SessionManager, Response+```++## ::: scrapling.spiders.Spider+ handler: python+ :docstring:++## ::: scrapling.spiders.Request+ handler: python+ :docstring:++## فئات النتائج {#result-classes}++## ::: scrapling.spiders.result.CrawlResult+ handler: python+ :docstring:++## ::: scrapling.spiders.result.CrawlStats+ handler: python+ :docstring:++## ::: scrapling.spiders.result.ItemList+ handler: python+ :docstring:++## إدارة الجلسات {#session-management}++## ::: scrapling.spiders.session.SessionManager+ handler: python+ :docstring:diff --git a/docs/locales/ar/assets b/docs/locales/ar/assetsnew file mode 120000index 0000000..41aef43--- /dev/null+++ b/docs/locales/ar/assets@@ -0,0 +1 @@+../../assets\ No newline at end of filediff --git a/docs/locales/ar/benchmarks.md b/docs/locales/ar/benchmarks.mdnew file mode 100644index 0000000..c2a0c4d--- /dev/null+++ b/docs/locales/ar/benchmarks.md@@ -0,0 +1,33 @@+---+title: "اختبارات أداء محلّلات HTML في Python: Scrapling ومكتبات أخرى"+description: "قارن أداء Scrapling مع مكتبات Python الشائعة في تحليل HTML واستخراج النص والبحث عن العناصر المتشابهة."+---++# اختبارات الأداء {#performance-benchmarks}++إلى جانب قدراته، يتميز Scrapling بسرعته العالية. تقارن الاختبارات التالية محلّل Scrapling بمكتبات أخرى شائعة.++### اختبار سرعة استخراج النص من 5000 عنصر متداخل {#text-extraction-speed-test-5000-nested-elements}++| # | المكتبة | الوقت (ms) | مقارنة بـScrapling |+|---|:-----------------:|:---------:|:------------:|+| 1 | Scrapling | 1.99 | 1.0x |+| 2 | Parsel/Scrapy | 2.06 | 1.035 |+| 3 | Raw Lxml | 2.56 | 1.286 |+| 4 | PyQuery | 23.98 | ~12x |+| 5 | Selectolax | 197.02 | ~99x |+| 6 | MechanicalSoup | 1545.15 | ~776.5x |+| 7 | BS4 with Lxml | 1562.1 | ~785.0x |+| 8 | BS4 with html5lib | 3412.73 | ~1714.9x |+++### أداء البحث عن النص والعناصر المتشابهة {#element-similarity-text-search-performance}++تتفوق قدرة Scrapling على العثور على العناصر بعد تغيّر الصفحة على البدائل بفارق واضح:++| المكتبة | الوقت (ms) | مقارنة بـScrapling |+|-------------|:---------:|:------------:|+| Scrapling | 2.3 | 1.0x |+| AutoScraper | 12.58 | 5.47x |++> تمثل النتائج متوسط 100 تشغيل مع قياس الوقت. راجع [benchmarks.py](https://github.com/D4Vinci/Scrapling/blob/main/benchmarks.py) لمعرفة طريقة الاختبار.diff --git a/docs/locales/ar/cli/extract-commands.md b/docs/locales/ar/cli/extract-commands.mdnew file mode 100644index 0000000..48ac9ca--- /dev/null+++ b/docs/locales/ar/cli/extract-commands.md@@ -0,0 +1,342 @@+---+title: "احفظ صفحات الويب بصيغة Markdown أو HTML أو نص من سطر الأوامر"+description: "استخدم scrapling extract لحفظ نتائج HTTP أو المتصفح. حدّد المحتوى باستخدام CSS، واضبط خيارات الطلب، واختر صيغة إخراج مدعومة."+---++# دليل أمر الاستخراج في Scrapling {#scrapling-extract-command-guide}++**استخرج بيانات الويب من الطرفية دون الحاجة إلى البرمجة!**++يتيح أمر `scrapling extract` تنزيل محتوى المواقع واستخراجه من الطرفية مباشرة دون كتابة كود. وهو مناسب للمبتدئين والباحثين وكل من يحتاج إلى استخراج بيانات الويب بسرعة.++!!! success "قبل البدء"++ 1. اقرأ صفحة [أساسيات أدوات الجلب](../fetching/choosing.md) لتفهم [كائن Response](../fetching/choosing.md#response-object) وتعرف أداة الجلب المناسبة.+ 2. اقرأ صفحة [البحث عن العناصر](../parsing/selection.md) لتعرف كيفية العثور على العناصر واستخراجها من كائن [Selector](../parsing/main_classes.md#selector) أو [Response](../fetching/choosing.md#response-object).+ 3. اقرأ صفحة [الأصناف الرئيسية](../parsing/main_classes.md) لتعرف الخصائص والدوال التي يرثها [Response](../fetching/choosing.md#response-object) من [Selector](../parsing/main_classes.md#selector).+ 4. اقرأ صفحة واحدة على الأقل من قسم أدوات الجلب لاستخدامها هنا: [طلبات HTTP](../fetching/static.md) أو [الجلب بالمتصفح](../fetching/stealthy.md).++## ما مجموعة أوامر Extract؟ {#what-is-the-extract-command-group}++أوامر extract أدوات بسيطة للطرفية توفر ما يلي:++- **تنزيل صفحات الويب** وحفظ محتواها في ملفات.+- **تحويل HTML إلى صيغ سهلة القراءة** مثل Markdown، أو الاحتفاظ به بصيغة HTML، أو استخراج نص الصفحة فقط.+- **دعم محددات CSS** لاستخراج أجزاء معينة من الصفحة.+- **التعامل مع طلبات HTTP والجلب بالمتصفح**.+- **خيارات تخصيص كثيرة** للترويسات وcookies وproxies وبقية الإعدادات. تتوفر تقريبًا كل خيارات الكود من سطر الأوامر أيضًا.++!!! tip "الوضع المخصص للذكاء الاصطناعي"++ تدعم كل أوامر extract الخيار `--ai-targeted`. عند تفعيله، يستخرج محتوى body الأساسي فقط، ويزيل الوسوم غير المفيدة، وهي script وstyle وnoscript وsvg. كما يزيل العناصر المخفية التي قد تُستخدم لحقن التعليمات، ومنها العناصر المخفية بأنماط مباشرة وaria-hidden وعناصر slot المخفية ووسوم template، ويزيل محارف Unicode عديمة العرض وتعليقات HTML. ومع أمر المتصفح `fetch`، يفعّل حظر الإعلانات تلقائيًا أيضًا. هذا مناسب عندما ستُرسل النتيجة إلى نموذج ذكاء اصطناعي.++## بداية سريعة {#quick-start}++- **تنزيل محتوى موقع**++ نزّل محتوى الموقع كنص نظيف وسهل القراءة:++ ```bash+ scrapling extract get "https://example.com" page_content.txt+ ```++ يرسل هذا طلب HTTP GET ويحفظ نص الصفحة في `page_content.txt`.++- **الحفظ بصيغ مختلفة**++ اختر صيغة الإخراج بتغيير امتداد الملف:++ ```bash+ # Convert the HTML content to Markdown, then save it to the file (great for documentation)+ scrapling extract get "https://blog.example.com" article.md++ # Save the HTML content as it is to the file+ scrapling extract get "https://example.com" page.html++ # Save a clean version of the text content of the webpage to the file+ scrapling extract get "https://example.com" content.txt++ # Or use the Docker image with something like this:+ docker run -v $(pwd)/output:/output pyd4vinci/scrapling extract get "https://blog.example.com" /output/article.md+ ```++- **استخراج محتوى محدد**++ تستطيع جميع الأوامر استخدام محددات CSS لاستخراج أجزاء معينة من الصفحة عبر `--css-selector` أو `-s`، كما في الأمثلة التالية.++## الأوامر المتاحة {#available-commands}++اعرض الأوامر باستخدام `scrapling extract --help` لتحصل على القائمة التالية:++```bash+Usage: scrapling extract [OPTIONS] COMMAND [ARGS]...++ Fetch web pages using various fetchers and extract full/selected HTML content as HTML, Markdown, or extract text content.++Options:+ --help Show this message and exit.++Commands:+ get Perform a GET request and save the content to a file.+ post Perform a POST request and save the content to a file.+ put Perform a PUT request and save the content to a file.+ delete Perform a DELETE request and save the content to a file.+ fetch Use StealthyFetcher to fetch content with advanced stealth features.+```++سنشرح كل أمر بالتفصيل فيما يلي.++### طلبات HTTP {#http-requests}++1. **طلب GET**++ الأمر الأكثر استخدامًا لتنزيل محتوى المواقع:++ ```bash+ scrapling extract get [URL] [OUTPUT_FILE] [OPTIONS]+ ```++ **أمثلة:**++ ```bash+ # Basic download+ scrapling extract get "https://news.site.com" news.md++ # Download with custom timeout+ scrapling extract get "https://example.com" content.txt --timeout 60++ # Extract only specific content using CSS selectors+ scrapling extract get "https://blog.example.com" articles.md --css-selector "article"++ # Send a request with cookies+ scrapling extract get "https://scrapling.requestcatcher.com" content.md --cookies "session=abc123; user=john"++ # Add user agent+ scrapling extract get "https://api.site.com" data.txt -H "User-Agent: MyBot 1.0"++ # Add multiple headers+ scrapling extract get "https://site.com" page.html -H "Accept: text/html" -H "Accept-Language: en-US"+ ```++ اعرض خيارات الأمر باستخدام `scrapling extract get --help` كما يلي:++ ```bash+ Usage: scrapling extract get [OPTIONS] URL OUTPUT_FILE++ Perform a GET request and save the content to a file.++ The output file path can be an HTML file, a Markdown file of the HTML content, or the text content itself. Use file extensions (`.html`/`.md`/`.txt`) respectively.++ Options:+ -H, --headers TEXT HTTP headers in format "Key: Value" (can be used multiple times)+ --cookies TEXT Cookies string in format "name1=value1;name2=value2"+ --timeout INTEGER Request timeout in seconds (default: 30)+ --proxy TEXT Proxy URL in format "http://username:password@host:port"+ -s, --css-selector TEXT CSS selector to extract specific content from the page. It returns all matches.+ -p, --params TEXT Query parameters in format "key=value" (can be used multiple times)+ --follow-redirects / --no-follow-redirects Whether to follow redirects (default: True)+ --verify / --no-verify Whether to verify SSL certificates (default: True)+ --impersonate TEXT Browser to impersonate (e.g., chrome, firefox).+ --stealthy-headers / --no-stealthy-headers Use stealthy browser headers (default: True)+ --ai-targeted Extract only main content and sanitize hidden elements for AI consumption (default: False)+ --help Show this message and exit.++ ```++ تعمل هذه الخيارات بالطريقة نفسها في بقية أوامر الطلبات، لذلك لا حاجة إلى تكرار شرحها.++2. **طلب POST**++ ```bash+ scrapling extract post [URL] [OUTPUT_FILE] [OPTIONS]+ ```++ **أمثلة:**++ ```bash+ # Submit form data+ scrapling extract post "https://api.site.com/search" results.html --data "query=python&type=tutorial"++ # Send JSON data+ scrapling extract post "https://api.site.com" response.txt --json '{"username": "test", "action": "search"}'+ ```++ اعرض خيارات الأمر باستخدام `scrapling extract post --help` كما يلي:++ ```bash+ Usage: scrapling extract post [OPTIONS] URL OUTPUT_FILE++ Perform a POST request and save the content to a file.++ The output file path can be an HTML file, a Markdown file of the HTML content, or the text content itself. Use file extensions (`.html`/`.md`/`.txt`) respectively.++ Options:+ -d, --data TEXT Form data to include in the request body (as string, ex: "param1=value1¶m2=value2")+ -j, --json TEXT JSON data to include in the request body (as string)+ -H, --headers TEXT HTTP headers in format "Key: Value" (can be used multiple times)+ --cookies TEXT Cookies string in format "name1=value1;name2=value2"+ --timeout INTEGER Request timeout in seconds (default: 30)+ --proxy TEXT Proxy URL in format "http://username:password@host:port"+ -s, --css-selector TEXT CSS selector to extract specific content from the page. It returns all matches.+ -p, --params TEXT Query parameters in format "key=value" (can be used multiple times)+ --follow-redirects / --no-follow-redirects Whether to follow redirects (default: True)+ --verify / --no-verify Whether to verify SSL certificates (default: True)+ --impersonate TEXT Browser to impersonate (e.g., chrome, firefox).+ --stealthy-headers / --no-stealthy-headers Use stealthy browser headers (default: True)+ --ai-targeted Extract only main content and sanitize hidden elements for AI consumption (default: False)+ --help Show this message and exit.++ ```++3. **طلب PUT**++ ```bash+ scrapling extract put [URL] [OUTPUT_FILE] [OPTIONS]+ ```++ **أمثلة:**++ ```bash+ # Send data+ scrapling extract put "https://scrapling.requestcatcher.com/put" results.html --data "update=info" --impersonate "firefox"++ # Send JSON data+ scrapling extract put "https://scrapling.requestcatcher.com/put" response.txt --json '{"username": "test", "action": "search"}'+ ```++ اعرض خيارات الأمر باستخدام `scrapling extract put --help` كما يلي:++ ```bash+ Usage: scrapling extract put [OPTIONS] URL OUTPUT_FILE++ Perform a PUT request and save the content to a file.++ The output file path can be an HTML file, a Markdown file of the HTML content, or the text content itself. Use file extensions (`.html`/`.md`/`.txt`) respectively.++ Options:+ -d, --data TEXT Form data to include in the request body+ -j, --json TEXT JSON data to include in the request body (as string)+ -H, --headers TEXT HTTP headers in format "Key: Value" (can be used multiple times)+ --cookies TEXT Cookies string in format "name1=value1;name2=value2"+ --timeout INTEGER Request timeout in seconds (default: 30)+ --proxy TEXT Proxy URL in format "http://username:password@host:port"+ -s, --css-selector TEXT CSS selector to extract specific content from the page. It returns all matches.+ -p, --params TEXT Query parameters in format "key=value" (can be used multiple times)+ --follow-redirects / --no-follow-redirects Whether to follow redirects (default: True)+ --verify / --no-verify Whether to verify SSL certificates (default: True)+ --impersonate TEXT Browser to impersonate (e.g., chrome, firefox).+ --stealthy-headers / --no-stealthy-headers Use stealthy browser headers (default: True)+ --ai-targeted Extract only main content and sanitize hidden elements for AI consumption (default: False)+ --help Show this message and exit.+ ```++4. **طلب DELETE**++ ```bash+ scrapling extract delete [URL] [OUTPUT_FILE] [OPTIONS]+ ```++ **أمثلة:**++ ```bash+ # Send data+ scrapling extract delete "https://scrapling.requestcatcher.com/delete" results.html++ # Send JSON data+ scrapling extract delete "https://scrapling.requestcatcher.com/" response.txt --impersonate "chrome"+ ```++ اعرض خيارات الأمر باستخدام `scrapling extract delete --help` كما يلي:++ ```bash+ Usage: scrapling extract delete [OPTIONS] URL OUTPUT_FILE++ Perform a DELETE request and save the content to a file.++ The output file path can be an HTML file, a Markdown file of the HTML content, or the text content itself. Use file extensions (`.html`/`.md`/`.txt`) respectively.++ Options:+ -H, --headers TEXT HTTP headers in format "Key: Value" (can be used multiple times)+ --cookies TEXT Cookies string in format "name1=value1;name2=value2"+ --timeout INTEGER Request timeout in seconds (default: 30)+ --proxy TEXT Proxy URL in format "http://username:password@host:port"+ -s, --css-selector TEXT CSS selector to extract specific content from the page. It returns all matches.+ -p, --params TEXT Query parameters in format "key=value" (can be used multiple times)+ --follow-redirects / --no-follow-redirects Whether to follow redirects (default: True)+ --verify / --no-verify Whether to verify SSL certificates (default: True)+ --impersonate TEXT Browser to impersonate (e.g., chrome, firefox).+ --stealthy-headers / --no-stealthy-headers Use stealthy browser headers (default: True)+ --ai-targeted Extract only main content and sanitize hidden elements for AI consumption (default: False)+ --help Show this message and exit.+ ```++### الجلب بالمتصفح {#browser-fetching}++استخدم `fetch` لصفحات JavaScript وأتمتة المتصفح والمواقع المحمية. يشغّل `StealthyFetcher` مع جميع خيارات التخفي المتاحة.++```bash+scrapling extract fetch "https://scrapling.requestcatcher.com/" content.md --network-idle+scrapling extract fetch "https://scrapling.requestcatcher.com/" data.txt --wait-selector ".content-loaded"+scrapling extract fetch "https://scrapling.requestcatcher.com/" page.html --no-headless --disable-resources+scrapling extract fetch "https://nopecha.com/demo/cloudflare" data.txt --solve-cloudflare --css-selector "#padded_content a"+scrapling extract fetch "https://site.com" content.md --proxy "http://proxy-server:8080"+```++استخدم `--pierce-shadow` لتضمين محتوى Shadow DOM المفتوح. هذا الخيار غير مفعّل افتراضيًا، ويمكن تعطيله صراحة باستخدام `--no-pierce-shadow`. راجع [Shadow DOM](../fetching/stealthy.md#shadow-dom) لأمثلة المحددات وحدود الدعم.++```bash+scrapling extract fetch "https://example.com" content.md --pierce-shadow+```++شغّل `scrapling extract fetch --help` لعرض كل الخيارات:++```text+Usage: scrapling extract fetch [OPTIONS] URL OUTPUT_FILE++ Use StealthyFetcher to fetch content with advanced stealth features.++Options:+ --headless / --no-headless Run browser in headless mode (default: True)+ --disable-resources / --enable-resources Drop unnecessary resources for speed boost (default: False)+ --block-webrtc / --allow-webrtc Block WebRTC entirely (default: False)+ --solve-cloudflare / --no-solve-cloudflare Solve Cloudflare challenges (default: False)+ --allow-webgl / --block-webgl Allow WebGL (default: True)+ --pierce-shadow / --no-pierce-shadow Include open Shadow DOM content (default: False)+ --network-idle / --no-network-idle Wait for network idle (default: False)+ --real-chrome/--no-real-chrome If you have a Chrome browser installed on your device, enable this, and the Fetcher will launch an instance of your browser and use it. (default: False)+ --timeout INTEGER Timeout in milliseconds (default: 30000)+ --wait INTEGER Additional wait time in milliseconds after page load (default: 0)+ -s, --css-selector TEXT CSS selector to extract specific content from the page. It returns all matches.+ --wait-selector TEXT CSS selector to wait for before proceeding+ --hide-canvas / --show-canvas Add noise to canvas operations (default: False)+ --locale TEXT Specify user locale. Defaults to the system default locale.+ --proxy TEXT Proxy URL in format "http://username:password@host:port"+ -H, --extra-headers TEXT Extra headers in format "Key: Value" (can be used multiple times)+ --dns-over-https / --no-dns-over-https Route DNS through Cloudflare's DoH to prevent DNS leaks when using proxies (default: False)+ --block-ads / --no-block-ads Block requests to known ad and tracker domains (default: False)+ --executable-path TEXT Path to a custom Chromium-compatible browser executable. Falls back to the SCRAPLING_EXECUTABLE_PATH environment variable when not set.+ --ai-targeted Extract only main content and sanitize hidden elements for AI consumption (default: False)+ --help Show this message and exit.+```++## متى تستخدم كل أمر؟ {#when-to-use-each-command}++إذا لم تكن خبيرًا في استخراج بيانات الويب ولم تعرف ماذا تختار، فاستخدم هذه القاعدة البسيطة:++- استخدم **`get`** مع المواقع البسيطة والمدونات والمقالات الإخبارية.+- استخدم **`fetch`** مع صفحات JavaScript وأتمتة المتصفح والمواقع المحمية، ومنها Cloudflare.++## اعتبارات قانونية وأخلاقية {#legal-and-ethical-considerations}++⚠️ **إرشادات مهمة:**++- **افحص robots.txt**: افتح `https://website.com/robots.txt` لمعرفة قواعد استخراج البيانات.+- **احترم حدود الطلبات**: لا تُثقل الخوادم بكثرة الطلبات.+- **شروط الخدمة**: اقرأ شروط الموقع والتزم بها.+- **حقوق النشر**: احترم حقوق الملكية الفكرية.+- **الخصوصية**: راعِ قوانين حماية البيانات الشخصية.+- **الاستخدام التجاري**: تأكد من امتلاك الإذن المطلوب لأغراض العمل.++---++*نتمنى لك تجربة موفقة في استخراج البيانات! تذكّر احترام سياسات المواقع والالتزام بكل القوانين واللوائح المعمول بها.*diff --git a/docs/locales/ar/cli/interactive-shell.md b/docs/locales/ar/cli/interactive-shell.mdnew file mode 100644index 0000000..bd12c12--- /dev/null+++ b/docs/locales/ar/cli/interactive-shell.md@@ -0,0 +1,236 @@+---+title: "جرّب استخراج بيانات الويب في بيئة Scrapling التفاعلية"+description: "اجلب الصفحات وجرّب المحددات وافحص النتائج في بيئة IPython. حوّل أوامر curl، وأعد استخدام الاستجابات الأخيرة، واختبر كود استخراج البيانات."+---++# دليل بيئة Scrapling التفاعلية {#scrapling-interactive-shell-guide}++<script src="https://asciinema.org/a/736339.js" id="asciicast-736339" async data-autoplay="1" data-loop="1" data-cols="225" data-rows="40" data-start-at="00:06" data-speed="1.5" data-theme="tango"></script>++**بيئة REPL قوية لاستخراج بيانات الويب للمطورين وعلماء البيانات**++بيئة Scrapling التفاعلية مبنية على IPython ومطوّرة خصيصًا لمهام استخراج بيانات الويب. تتيح الوصول الفوري إلى كل ميزات Scrapling، واختصارات مفيدة، وإدارة تلقائية للصفحات، وأدوات متقدمة مثل تحويل أوامر curl.++!!! success "قبل البدء"++ 1. اقرأ صفحة [أساسيات أدوات الجلب](../fetching/choosing.md) لتفهم [كائن Response](../fetching/choosing.md#response-object) وتعرف أداة الجلب المناسبة.+ 2. اقرأ صفحة [البحث عن العناصر](../parsing/selection.md) لتعرف كيفية العثور على العناصر واستخراجها من كائن [Selector](../parsing/main_classes.md#selector) أو [Response](../fetching/choosing.md#response-object).+ 3. اقرأ صفحة [الأصناف الرئيسية](../parsing/main_classes.md) لتعرف الخصائص والدوال التي يرثها [Response](../fetching/choosing.md#response-object) من [Selector](../parsing/main_classes.md#selector).+ 4. اقرأ صفحة واحدة على الأقل من قسم أدوات الجلب لاستخدامها هنا: [طلبات HTTP](../fetching/static.md) أو [الجلب بالمتصفح](../fetching/stealthy.md).++## لماذا تستخدم البيئة التفاعلية؟ {#why-use-the-interactive-shell}++تحوّل البيئة التفاعلية استخراج البيانات من دورة بطيئة لكتابة السكربت وتشغيله إلى تجربة سريعة للاستكشاف. وهي مناسبة لـ:++- **إنشاء نماذج أولية بسرعة**: جرّب طرق استخراج البيانات فورًا.+- **استكشاف البيانات**: تنقّل في المواقع واستخرج البيانات بشكل تفاعلي.+- **تعلّم Scrapling**: جرّب الميزات وشاهد النتائج فورًا.+- **تصحيح أدوات الاستخراج**: نفّذ الطلبات خطوة بخطوة وافحص النتائج.+- **تحويل طريقة العمل**: حوّل أمر curl من أدوات المطور في المتصفح إلى طلب Fetcher في سطر واحد.++## البدء {#getting-started}++### تشغيل البيئة التفاعلية {#launch-the-shell}++```bash+# Start the interactive shell+scrapling shell++# Execute code and exit (useful for scripting)+scrapling shell -c "get('https://quotes.toscrape.com'); print(len(page.css('.quote')))"++# Set logging level+scrapling shell --loglevel info+```++بعد التشغيل، تظهر لافتة Scrapling ويمكنك البدء مباشرة، كما يوضح الفيديو أعلاه:++```python+# No imports needed - everything is ready!+get('https://news.ycombinator.com')++# Explore the page structure+page.css('a')[:5] # Look at first 5 links++# Refine your selectors+stories = page.css('.titleline>a')+len(stories) # 30++# Extract specific data+for story in stories[:3]:+ title = story.text+ url = story['href']+ print(f"{title}: {url}")++# Try different approaches+titles = page.css('.titleline>a::text') # Direct text extraction+urls = page.css('.titleline>a::attr(href)') # Direct attribute extraction+```++## الاختصارات المدمجة {#built-in-shortcuts}++توفر البيئة اختصارات مريحة لتقليل الكود المتكرر:++- **`get(url, **kwargs)`**: طلب HTTP GET بدلًا من `Fetcher.get`.+- **`post(url, **kwargs)`**: طلب HTTP POST بدلًا من `Fetcher.post`.+- **`put(url, **kwargs)`**: طلب HTTP PUT بدلًا من `Fetcher.put`.+- **`delete(url, **kwargs)`**: طلب HTTP DELETE بدلًا من `Fetcher.delete`.+- **`fetch(url, **kwargs)`**: جلب بمتصفح Stealthy بدلًا من `StealthyFetcher.fetch`.++تتوفر الأصناف الأكثر استخدامًا تلقائيًا دون استيراد، ومنها `Fetcher` و`AsyncFetcher` و`StealthyFetcher` و`Selector`.++### إدارة الصفحات تلقائيًا {#smart-page-management}++تتابع البيئة طلباتك وصفحاتك تلقائيًا:++- **الوصول إلى الصفحة الحالية**++ تُحدّث قيمتا `page` و`response` تلقائيًا لتشيرا إلى آخر صفحة جُلبت:++ ```python+ get('https://quotes.toscrape.com')+ # 'page' and 'response' both refer to the last fetched page+ page.url # 'https://quotes.toscrape.com'+ response.status # Prints 200; Same as page.status+ ```++- **سجل الصفحات**++ تحتفظ `pages` بآخر خمس صفحات، وهي كائن من نوع `Selectors`:++ ```python+ get('https://site1.com')+ get('https://site2.com')+ get('https://site3.com')++ # Access last 5 pages+ len(pages) # `Selectors` object with `page` history -> 3+ pages[0].url # First page in history -> 'https://site1.com'+ pages[-1].url # Most recent page -> 'https://site3.com'++ # Work with historical pages+ for i, old_page in enumerate(pages):+ print(f"Page {i}: {old_page.url} - {old_page.status}")+ ```++## أوامر مفيدة أخرى {#additional-helpful-commands}++### عرض الصفحة {#page-visualization}++اعرض الصفحات التي جلبتها داخل المتصفح:++```python+get('https://quotes.toscrape.com')+view(page) # Opens the page HTML in your default browser+```++### التكامل مع أوامر curl {#curl-command-integration}++توفر البيئة دالتين لتحويل أوامر curl من أدوات المطور في المتصفح إلى طلبات `Fetcher`: وهما `uncurl` و`curl2fetcher`.++أولًا، انسخ طلبًا على هيئة أمر curl كما يلي:++<img src="../assets/scrapling_shell_curl.png" title="نسخ طلب من Chrome على هيئة أمر curl" alt="نسخ طلب من Chrome على هيئة أمر curl" style="width: 70%;"/>++- **تحويل أمر curl إلى كائن Request**++ ```python+ curl_cmd = '''curl 'https://scrapling.requestcatcher.com/post' \+ -X POST \+ -H 'Content-Type: application/json' \+ -d '{"name": "test", "value": 123}' '''++ request = uncurl(curl_cmd)+ request.method # -> 'post'+ request.url # -> 'https://scrapling.requestcatcher.com/post'+ request.headers # -> {'Content-Type': 'application/json'}+ ```++- **تنفيذ أمر curl مباشرة**++ ```python+ # Convert and execute in one step+ curl2fetcher(curl_cmd)+ page.status # -> 200+ ```++### ميزات IPython {#ipython-features}++ترث البيئة كل قدرات IPython:++```python+# Magic commands+%time page = get('https://example.com') # Time execution+%history # Show command history+%save filename.py 1-10 # Save commands 1-10 to file++# Tab completion works everywhere+page.c<TAB> # Shows: css, cookies, headers, etc.+Fetcher.<TAB> # Shows all Fetcher methods++# Object inspection+get? # Show get documentation+```++## أمثلة {#examples}++إليك بعض الأمثلة التي أنشأها الذكاء الاصطناعي:++#### جمع بيانات المتاجر الإلكترونية {#e-commerce-data-collection}++```python+# Start with product listing page+catalog = get('https://shop.example.com/products')++# Find product links+product_links = catalog.css('.product-link::attr(href)').getall()+print(f"Found {len(product_links)} products")++# Sample a few products first+for link in product_links[:3]:+ product = get(catalog.urljoin(link))+ name = product.css('.product-name::text').get('')+ price = product.css('.price::text').get('')+ print(f"{name}: {price}")++# Scale up with sessions for efficiency+from scrapling.fetchers import FetcherSession+with FetcherSession() as session:+ products = []+ for link in product_links:+ product = session.get(catalog.urljoin(link))+ products.append({+ 'name': product.css('.product-name::text').get(''),+ 'price': product.css('.price::text').get(''),+ 'url': link+ })+```++#### التكامل مع API واختبارها {#api-integration-and-testing}++```python+>>> # Test API endpoints interactively+>>> response = get('https://jsonplaceholder.typicode.com/posts/1')+>>> response.json()+{'userId': 1, 'id': 1, 'title': 'sunt aut...', 'body': 'quia et...'}++>>> # Test POST requests+>>> new_post = post('https://jsonplaceholder.typicode.com/posts',+... json={'title': 'Test Post', 'body': 'Test content', 'userId': 1})+>>> new_post.json()['id']+101++>>> # Test with different data+>>> updated = put('https://jsonplaceholder.typicode.com/posts/1',+... json={'title': 'Updated Title'})+```++## الحصول على المساعدة {#getting-help}++إذا احتجت إلى مساعدة إضافية غير الموجودة في الطرفية، يمكنك الرجوع إلى:++- [توثيق Scrapling](../index.md)+- [مجتمع Discord](https://discord.gg/EMgGbDceNQ)+- [بلاغات GitHub](https://github.com/D4Vinci/Scrapling/issues)++هذا كل شيء! نتمنى لك تجربة موفقة. تجعل البيئة التفاعلية استخراج بيانات الويب سهلًا مثل المحادثة.diff --git a/docs/locales/ar/cli/overview.md b/docs/locales/ar/cli/overview.mdnew file mode 100644index 0000000..4f3b200--- /dev/null+++ b/docs/locales/ar/cli/overview.md@@ -0,0 +1,40 @@+---+title: "واجهة Scrapling لسطر الأوامر: استخرج البيانات من الطرفية"+description: "ثبّت أدوات Scrapling للطرفية، واختر بين أوامر extract والبيئة التفاعلية وخادم MCP. اتبع الدليل المناسب لمهمتك."+---++# واجهة سطر الأوامر {#command-line-interface}++منذ الإصدار 0.3، تشمل Scrapling واجهة قوية لسطر الأوامر توفر ثلاث إمكانات رئيسية:++1. **البيئة التفاعلية**: بيئة لاستخراج بيانات الويب مبنية على IPython، وتوفر اختصارات وأدوات مفيدة كثيرة.+2. **أوامر الاستخراج**: استخرج بيانات المواقع من الطرفية دون كتابة كود.+3. **الأوامر المساعدة**: أدوات التثبيت والإدارة.++```bash+# Launch interactive shell+scrapling shell++# Convert the content of a page to markdown and save it to a file+scrapling extract get "https://example.com" content.md++# Get help for any command+scrapling --help+scrapling extract --help+```++## المتطلبات {#requirements}++يتطلب هذا القسم تثبيت مجموعة المتطلبات الإضافية `shell` كما يلي:++```bash+pip install "scrapling[shell]"+```++للجلب باستخدام المتصفح، ثبّت متطلبات المتصفح أيضًا:++```bash+scrapling install+```++ينزّل هذا الأمر Chromium ومتطلبات النظام اللازمة له، ويحدّث قائمة TLD. لا تحتاج طلبات HTTP إلى هذه الخطوة.diff --git a/docs/locales/ar/development/adaptive_storage_system.md b/docs/locales/ar/development/adaptive_storage_system.mdnew file mode 100644index 0000000..bb3465b--- /dev/null+++ b/docs/locales/ar/development/adaptive_storage_system.md@@ -0,0 +1,72 @@+---+title: "اكتب نظام تخزين خاصًا للتحليل التكيفي"+description: "نفّذ save وretrieve لميزة التحليل التكيفي في Scrapling. اكتب نظام تخزين باستخدام Redis لحفظ خصائص العناصر واسترجاعها."+---++# كتابة نظام الاسترجاع الخاص بك {#writing-your-retrieval-system}++تستخدم Scrapling قاعدة SQLite افتراضيًا. يشرح هذا الدليل كيفية كتابة نظام التخزين الخاص بك لحفظ خصائص العناصر التي تستخدمها ميزة `adaptive`.++قد ترغب مثلًا في استخدام Firebase ومشاركة قاعدة البيانات بين عدة عناكب على أجهزة مختلفة. هذه فكرة مفيدة، لأن قاعدة البيانات المتاحة عبر الإنترنت تسمح للعناكب بمشاركة بيانات التحليل التكيفي.++لكي يعمل صنف التخزين الخاص بك، يجب أن يحقق هذه المتطلبات الثلاثة:++1. أن يرث من الصنف المجرد `scrapling.core.storage.StorageSystemMixin`، وأن يقبل معاملًا نصيًا باسم `url` للحفاظ على طريقة عمل المكتبة.+2. أن يستخدم decorator باسم `functools.lru_cache` فوق الصنف، ليتبع نمط Singleton مثل الأصناف الأخرى.+3. أن ينفّذ الدالتين `save` و`retrieve` وفقًا لتلميحات الأنواع:+ - لا تُرجع دالة `save` قيمة، وتستقبل معاملين من المكتبة:+ * الأول من نوع `lxml.html.HtmlElement`، وهو العنصر نفسه. يجب تحويله إلى قاموس باستخدام الدالة `element_to_dict` في `scrapling.core.utils._StorageTools` للحفاظ على التنسيق نفسه، ثم حفظه في قاعدة البيانات بالطريقة التي تريدها.+ * الثاني نص يمثل المعرّف المستخدم للاسترجاع. يجب أن يكون الجمع بين هذا المعرّف ومعامل `url` الممرّر عند الإنشاء فريدًا لكل سجل، وإلا ستختلط بيانات `adaptive`.+ - تستقبل دالة `retrieve` نصًا يمثل المعرّف. تستخدمه مع `url` الممرّر عند الإنشاء لاسترجاع قاموس العنصر من قاعدة البيانات. إذا كان موجودًا تُرجعه، وإلا تُرجع `None`.++> إذا احتجت إلى مثال أوضح، يمكنك مراجعة تنفيذي باستخدام SQLite3 في ملف [storage_adaptors](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/storage.py).++إذا استوفى الصنف هذه الشروط، فبقية الخطوات بسيطة. وإذا كنت ستستخدم المكتبة في تطبيق متعدد threads، فتأكد أن الصنف يدعم ذلك بأمان. الصنف الافتراضي آمن للاستخدام مع threads متعددة.++أضفنا بعض الدوال المساعدة إلى الصنف المجرد لتستخدمها عند الحاجة. يمكنك الاطلاع عليها في [الكود](https://github.com/D4Vinci/Scrapling/blob/main/scrapling/core/storage.py)، حيث توجد تعليقات كثيرة تشرحها :)++## مثال عملي: التخزين باستخدام Redis {#real-world-example-redis-storage}++إليك مثالًا عمليًا أكثر باستخدام Redis، أنشأه الذكاء الاصطناعي:++```python+import redis+import orjson+from functools import lru_cache+from scrapling.core.storage import StorageSystemMixin+from scrapling.core.utils import _StorageTools++@lru_cache(None)+class RedisStorage(StorageSystemMixin):+ def __init__(self, host='localhost', port=6379, db=0, url=None):+ super().__init__(url)+ self.redis = redis.Redis(+ host=host,+ port=port,+ db=db,+ decode_responses=False+ )++ def save(self, element, identifier: str) -> None:+ # Convert element to dictionary+ element_dict = _StorageTools.element_to_dict(element)++ # Create key+ key = f"scrapling:{self._get_base_url()}:{identifier}"++ # Store as JSON+ self.redis.set(+ key,+ orjson.dumps(element_dict)+ )++ def retrieve(self, identifier: str) -> dict | None:+ # Get data+ key = f"scrapling:{self._get_base_url()}:{identifier}"+ data = self.redis.get(key)++ # Parse JSON if exists+ if data:+ return orjson.loads(data)+ return None+```diff --git a/docs/locales/ar/development/scrapling_custom_types.md b/docs/locales/ar/development/scrapling_custom_types.mdnew file mode 100644index 0000000..95a1f99--- /dev/null+++ b/docs/locales/ar/development/scrapling_custom_types.md@@ -0,0 +1,28 @@+---+title: "استخدم أنواع النصوص والخصائص من Scrapling في الكود"+description: "استخدم TextHandler وTextHandlers وAttributesHandler خارج المحلل. تعرّف على أنواع Python التي ترث منها، ودوال JSON المساعدة، والخصائص للقراءة فقط."+---++# استخدام الأنواع الخاصة بـ Scrapling {#using-scraplings-custom-types}++> يمكنك استخدام الأنواع التي أُنشئت لـ Scrapling خارج المكتبة أيضًا. وهذا أفضل من نسخ كودها :)++### يمكن استيراد جميع الأنواع الحالية منفردة كما يلي {#all-current-types-can-be-imported-alone-like-below}++```python+from scrapling.core.custom_types import TextHandler, AttributesHandler++somestring = TextHandler('{}')+parsed = somestring.json()+somedict_1 = AttributesHandler({'a': 1})+somedict_2 = AttributesHandler(a=1)+```++يرث `TextHandler` من النوع `str` في Python، لذا تعمل معه جميع العمليات والدوال القياسية التي تعمل مع النصوص في Python.+قيمة `parsed` هي القاموس `{}`، وليست النص `'{}'`. للتحقق من كائن، استخدم `isinstance(somestring, TextHandler)`. وللتحقق من صنف، استخدم `issubclass(TextHandler, str)`.++يرث الصنف `AttributesHandler` من `collections.abc.Mapping`، لذلك لا يمكن تعديل بياناته، أي إنه للقراءة فقط، ويرث عملياته منه. يمكنك الوصول إلى البيانات التي مرّرتها لاحقًا عبر الخاصية `_data`، لكن انتبه: نوعها هو `types.MappingProxyType`، وهي أيضًا للقراءة فقط، وأسرع من `collections.abc.Mapping` بأجزاء من الثانية.++ببساطة، إذا كنت جديدًا في Python، فإن عمليات ودوال النوع القياسي `dict` تعمل مع `AttributesHandler`، باستثناء العمليات التي تحاول تعديل البيانات نفسها.++إذا أردت تعديل بيانات `AttributesHandler`، فحوّلها أولًا إلى قاموس باستخدام الدالة `dict` مثلًا، ثم عدّل القاموس خارج الكائن.diff --git a/docs/locales/ar/donate.md b/docs/locales/ar/donate.mdnew file mode 100644index 0000000..1c5d9c5--- /dev/null+++ b/docs/locales/ar/donate.md@@ -0,0 +1,37 @@+---+title: "ادعم Scrapling وساهم في تطويره"+description: "ادعم Scrapling عبر GitHub Sponsors أو Buy Me a Coffee. تعرّف على باقات الإعلان ومزايا رعاية المشروع."+---++# الدعم والإعلانات {#support-and-advertisement}++أطوّر هذه المشاريع في وقت فراغي، وقد بذلت كثيرًا من الجهد والموارد لتقديمها مجانًا للمجتمع. عندما تصبح داعمًا، تساهم مباشرة في مخزون قهوتي، وتساعدني على الوفاء بمسؤولياتي، وتتيح لي مواصلة تحديث المشاريع الحالية وربما إنشاء مشاريع جديدة.++يمكنك دعمي مباشرة عبر [GitHub Sponsors](https://github.com/sponsors/D4Vinci) أو [Buy Me a Coffee](https://buymeacoffee.com/d4vinci).++شكرًا لك. واصل الفضول والتجربة، واترك أثرك في العالم! ❤️++## الإعلانات {#advertisement}+إذا أردت **الإعلان** عن نشاطك لجمهورنا، اطّلع على [الباقات المتاحة](https://github.com/sponsors/D4Vinci):++### 1. [الباقة الفضية](https://github.com/sponsors/D4Vinci/sponsorships?tier_id=435495) (100 دولار شهريًا) {#1-the-silver-tier-100month}+المزايا:++1. يظهر شعارك في [أعلى صفحة مشروع Scrapling](https://github.com/D4Vinci/Scrapling?tab=readme-ov-file#sponsors).+2. يظهر الشعار نفسه في [أعلى صفحة Scrapling على PyPI](https://pypi.org/project/scrapling/) و[أعلى صفحة صورة Docker](https://hub.docker.com/r/pyd4vinci/scrapling)، بالطريقة نفسها التي يظهر بها في صفحة المشروع.++### 2. [الباقة الذهبية](https://github.com/sponsors/D4Vinci/sponsorships?tier_id=591422) (200 دولار شهريًا) {#2-the-gold-tier-200month}+المزايا:++1. يظهر شعارك في [أعلى صفحة مشروع Scrapling](https://github.com/D4Vinci/Scrapling?tab=readme-ov-file#sponsors).+2. يظهر الشعار نفسه في [أعلى صفحة Scrapling على PyPI](https://pypi.org/project/scrapling/) و[أعلى صفحة صورة Docker](https://hub.docker.com/r/pyd4vinci/scrapling)، بالطريقة نفسها التي يظهر بها في صفحة المشروع.+3. يظهر شعارك ضمن كبار الداعمين في الصفحة الرئيسية لـ[موقع Scrapling](index.md).++### 3. [الباقة البلاتينية](https://github.com/sponsors/D4Vinci/sponsorships?tier_id=586646) (300 دولار شهريًا) {#3-the-platinum-tier-300month}+المزايا:++1. يظهر شعارك في مكان مميز [بأعلى صفحة مشروع Scrapling](https://github.com/D4Vinci/Scrapling?tab=readme-ov-file#platinum-sponsors)، مع فقرة لا تتجاوز 25 كلمة.+2. يظهر الشعار نفسه في [صفحة PyPI](https://pypi.org/project/scrapling/) و[صفحة Docker](https://hub.docker.com/r/pyd4vinci/scrapling)، بالطريقة نفسها التي يظهر بها في صفحة المشروع.+3. مكان مميز لشعارك ضمن كبار الداعمين في الصفحة الرئيسية لـ[موقع Scrapling](index.md).+4. رتبة شريك في خادم Discord، وإعلان على صفحة Twitter وخادم Discord.+5. ذكر اسمك في نهاية ملاحظات كل إصدار.diff --git a/docs/locales/ar/fetching/choosing.md b/docs/locales/ar/fetching/choosing.mdnew file mode 100644index 0000000..1586b1d--- /dev/null+++ b/docs/locales/ar/fetching/choosing.md@@ -0,0 +1,95 @@+---+title: "اختر طلبات HTTP أو المتصفح لجمع بيانات الويب"+description: "اختر Fetcher أو StealthyFetcher حسب مهمتك. تعرّف على وقت استخدام HTTP المباشر وتشغيل JavaScript والجلسات القابلة لإعادة الاستخدام."+---++# أساسيات أدوات الجلب {#fetchers-basics}++## مقدمة {#introduction}+أدوات الجلب Fetchers هي فئات ترسل الطلبات أو تجلب الصفحات بسطر واحد، مع ميزات كثيرة، ثم تعيد كائن [Response](#response-object). منذ الإصدار v0.3، لكل أداة جلب فئة جلسة مستقلة تُبقي الجلسة مفتوحة. مثلًا، تبقي أداة جلب المتصفح المتصفح مفتوحًا حتى تنتهي من كل طلباتك، بدلًا من فتح عدة متصفحات. اختر حسب حاجتك.++أُضيفت هذه الميزة لأن Scrapling كان قبل الإصدار v0.2 محلّل صفحات فقط. الهدف هو أن يغطي تدريجيًا كل احتياجات جمع بيانات الويب.++> أدوات الجلب ليست مجرد أغلفة لمكتبات أخرى. هي تستخدم هذه المكتبات كمحركات لإرسال الطلبات وجلب الصفحات، وتضيف ميزات لا توفرها المحركات نفسها، مع الاستفادة من قدراتها وتحسينها لجمع بيانات الويب.++## نظرة على أدوات الجلب {#fetchers-overview}++يوفر Scrapling أداتي HTTP، وهما `Fetcher` و`AsyncFetcher`، وأداة متصفح هي `StealthyFetcher`، مع فئات جلسات للطلبات المتكررة.++يساعدك الجدول التالي على المقارنة والاختيار بسرعة.+++| الميزة | Fetcher | StealthyFetcher |+|--------------------|---------------------------------------------------|--------------------------------------------------------------------------------------------|+| السرعة النسبية | 🐇🐇🐇🐇🐇 | 🐇🐇🐇 |+| التخفي | ⭐⭐ | ⭐⭐⭐⭐⭐ |+| خيارات تجاوز كشف البوتات | ⭐⭐ | ⭐⭐⭐⭐⭐ |+| تشغيل JavaScript | ❌ | ✅ |+| استهلاك الذاكرة | ⭐ | ⭐⭐⭐ |+| الاستخدام الأنسب | جمع البيانات البسيط عندما تكفي طلبات HTTP | مواقع تُحمّل ديناميكيًا <br/> أتمتة محدودة <br/> حمايات بسيطة أو معقدة |+| المتصفحات | ❌ | Chromium وGoogle Chrome |+| واجهة المتصفح المستخدمة | ❌ | Playwright |+| صعوبة الإعداد | بسيط | بسيط |++سنشرح كل أداة بالتفصيل في الصفحات التالية.++## إعداد محلّل الصفحات في كل أدوات الجلب {#parser-configuration-in-all-fetchers}+تُستورد كل أدوات الجلب بالطريقة نفسها، كما سترى في الصفحات التالية:+```python+from scrapling.fetchers import Fetcher, AsyncFetcher, StealthyFetcher+```+ثم استخدمها مباشرة دون إنشاء كائن. ستستخدم إعدادات المحلّل الافتراضية:+```python+page = StealthyFetcher.fetch('https://example.com')+```+إذا أردت إعداد المحلّل، أي [فئة Selector](../parsing/main_classes.md#selector)، الذي سيُستخدم على الرد قبل إعادته، نفّذ هذا أولًا:+```python+from scrapling.fetchers import Fetcher+Fetcher.configure(adaptive=True, keep_comments=False) # and the rest+```+أو:+```python+from scrapling.fetchers import Fetcher+Fetcher.adaptive=True+Fetcher.keep_comments=False+```+ثم أكمل الكود كالمعتاد.++خيارات الإعداد المتاحة هي `adaptive` و`adaptive_domain` و`huge_tree` و`keep_comments` و`storage` و`storage_args`. وهي الخيارات نفسها التي تمرّرها إلى [Selector](../parsing/main_classes.md#selector). اعرض الإعدادات الحالية في أي وقت باستخدام `<fetcher_class>.display_config()`.++!!! info "معلومة"++ خيار `adaptive` معطّل افتراضيًا. يجب تفعيله لاستخدام هذه الميزة.++### إعداد المحلّل لكل طلب {#set-parser-config-per-request}+تُطبّق الإعدادات السابقة على كل الطلبات التي ترسلها الفئة نفسها، وذلك لتبسيط الاستخدام.++إذا احتجت إلى إعدادات مختلفة لكل طلب، مرّر قاموسًا إلى الخيار `selector_config` في دالة الطلب، مثل `fetch` أو `get` أو `post` وغيرها.++## كائن Response {#response-object}+كائن `Response` يشبه فئة [Selector](../parsing/main_classes.md#selector)، مع تفاصيل إضافية عن الرد مثل الترويسات ورمز الحالة وملفات تعريف الارتباط، كما يلي:+```python+from scrapling.fetchers import Fetcher+page = Fetcher.get('https://example.com')++page.status # HTTP status code+page.reason # Status message+page.cookies # Response cookies as a dictionary+page.headers # Response headers+page.request_headers # Request headers+page.history # Response history of redirections, if any+page.body # Raw response body as bytes+page.encoding # Response encoding+page.meta # Response metadata dictionary (e.g., proxy used). Mainly helpful with the spiders system.+```+تعيد كل أدوات الجلب كائن `Response`. وتعيد جلسات المتصفح التي تفعّل `record_requests=True` كائنات `Response` محفوظة أيضًا عبر `session.network.search(limit=None)` و`session.network.get(request_id)`. راجع [سجل الشبكة](stealthy.md#network-history) لمعرفة كيفية قراءة ردود API المحفوظة والانتقال إلى v5.++يمكن لكائن `Response` تحويل الصفحة إلى Markdown نظيف وجاهز لنماذج اللغة بسطر واحد:+```python+markdown = Fetcher.get('https://example.com').markdown(main_content_only=True)+```+تُزال دائمًا السكربتات والأنماط والمحتوى المخفي ومحتوى حقن التعليمات قبل التحويل. ويمكنك تمرير `css_selector` لتحويل عناصر محددة فقط. تتطلب هذه الميزة إضافة `rag`، وهي موجودة أيضًا ضمن `ai` و`shell` و`all`. تشرحها صفحة [بناء أنظمة RAG](../ai/building-rag-systems.md) بالتفصيل.++!!! note "ملاحظة"++ منذ الإصدار v0.4، يكون محتوى `body` في فئة `Response` دائمًا من نوع bytes، بخلاف فئة [Selector](../parsing/main_classes.md#selector).diff --git a/docs/locales/ar/fetching/static.md b/docs/locales/ar/fetching/static.mdnew file mode 100644index 0000000..e2d7606--- /dev/null+++ b/docs/locales/ar/fetching/static.md@@ -0,0 +1,449 @@+---+title: "جمع البيانات عبر HTTP في Python باستخدام Fetcher وFetcherSession"+description: "أرسل طلبات HTTP متزامنة أو غير متزامنة مع محاكاة المتصفحات وملفات تعريف الارتباط والبروكسي والجلسات القابلة لإعادة الاستخدام، واستخرج البيانات من الرد باستخدام Scrapling."+---++# طلبات HTTP {#http-requests}++توفر فئة `Fetcher` طلبات HTTP سريعة وخفيفة باستخدام مكتبة `curl_cffi` عالية الأداء، مع كثير من ميزات التخفي.++!!! success "قبل البدء"++ 1. اقرأ [أساسيات أدوات الجلب](../fetching/choosing.md) لتفهم [كائن Response](../fetching/choosing.md#response-object) وتختار أداة الجلب المناسبة.+ 2. اقرأ [البحث عن العناصر](../parsing/selection.md) لتعرف كيف تجد العناصر وتستخرجها من كائن [Selector](../parsing/main_classes.md#selector) أو [Response](../fetching/choosing.md#response-object).+ 3. اقرأ [الفئات الأساسية](../parsing/main_classes.md) لتعرف الخصائص والدوال التي ترثها [Response](../fetching/choosing.md#response-object) من [Selector](../parsing/main_classes.md#selector).++## الاستخدام الأساسي {#basic-usage}+هذه طريقة الاستيراد الأساسية، وهي نفسها لكل أدوات الجلب:++```python+from scrapling.fetchers import Fetcher+```+تعرّف على إعداد خيارات التحليل [هنا](choosing.md#parser-configuration-in-all-fetchers).++### الخيارات المشتركة {#shared-arguments}+تشترك كل دوال إرسال الطلبات هنا في بعض الخيارات، فلنشرحها أولًا.++- **url**: الرابط المطلوب.+- **stealthy_headers**: ينشئ ترويسات متصفح حقيقية ويضيفها عند تفعيله، وهو مفعّل افتراضيًا. يضيف أيضًا ترويسة referer من Google.+- **follow_redirects**: يتحكم في إعادة التوجيه. **القيمة الافتراضية `"safe"`** تتبع إعادة التوجيه، لكنها ترفض الوجهات ذات عناوين IP الداخلية أو الخاصة للحماية من SSRF. استخدم `True` لتتبعها بلا قيود، أو `False` لتعطيلها تمامًا.+- **timeout**: أقصى مدة انتظار اكتمال كل طلب بالثواني. **القيمة الافتراضية 30 ثانية**.+- **retries**: أقصى عدد لمحاولات الطلب الفاشل، بما فيها المحاولة الأولى. **القيمة الافتراضية 3**.+- **retry_delay**: مدة الانتظار بالثواني بين المحاولات. **القيمة الافتراضية ثانية واحدة**.+- **impersonate**: يحاكي بصمات TLS لمتصفحات محددة. يقبل اسم متصفح أو قائمة أسماء، مثل `"chrome110"` أو `"firefox102"` أو `"safari15_5"` لإصدارات محددة، أو `"chrome"` و`"firefox"` و`"safari"` و`"edge"` لاستخدام أحدث إصدار متاح تلقائيًا. تبدو الطلبات بذلك كطلبات متصفح حقيقي على مستوى TLS. عند تمرير قائمة، يختار اسمًا عشوائيًا لكل طلب. **الافتراضي هو أحدث إصدار Chrome متاح.**+- **http3**: يستخدم HTTP/3 للطلبات. **القيمة الافتراضية False**. قد يسبب مشكلات عند استخدامه مع `impersonate`.+- **cookies**: ملفات تعريف الارتباط المستخدمة في الطلب. يقبل قاموسًا من `name→value` أو قائمة قواميس.+- **proxy**: البروكسي الذي تمر عبره حركة HTTP وHTTPS لهذا الطلب. الصيغة المقبولة هي `http://username:password@localhost:8030`.+- **proxy_auth**: بيانات HTTP Basic Auth للبروكسي، كزوج من اسم المستخدم وكلمة المرور.+- **proxies**: قاموس البروكسيات بالصيغة `{"http": proxy_url, "https": proxy_url}`.+- **proxy_rotator**: كائن `ProxyRotator` لتبديل البروكسي تلقائيًا. لا يمكن جمعه مع `proxy` أو `proxies`.+- **headers**: ترويسات إضافية للطلب. يمكنها استبدال أي ترويسة ينشئها `stealthy_headers`.+- **max_redirects**: أقصى عدد لعمليات إعادة التوجيه. **القيمة الافتراضية 30**. استخدم -1 لإزالة الحد.+- **verify**: هل تُفحص شهادات HTTPS؟ **القيمة الافتراضية True**.+- **cert**: زوج من اسمَي ملف الشهادة والمفتاح لشهادة العميل.+- **selector_config**: قاموس خيارات تحليل مخصصة يُستخدم عند إنشاء كائن `Selector` أو `Response` النهائي.++!!! note "ملاحظات:"++ 1. المتصفحات المتاحة حاليًا للمحاكاة هي (`"edge"`, `"chrome"`, `"chrome_android"`, `"safari"`, `"safari_beta"`, `"safari_ios"`, `"safari_ios_beta"`, `"firefox"`, `"tor"`).<br/>+ 2. تظهر المتصفحات المتاحة وإصداراتها تلقائيًا في الإكمال التلقائي للخيارات، وتتحدث مع كل تحديث لـ`curl_cffi`.<br/>+ 3. عند تفعيل `impersonate` أو `stealthy_headers`، تنشئ أدوات الجلب تلقائيًا ترويسات حقيقية تطابق إصدار المتصفح المستخدم.++للمزيد من التخصيص، يمكنك تمرير أي خيار تدعمه `curl_cffi` إلى أي دالة لا تدعمه بالفعل.++### ترميز النص {#text-encoding}++إذا ظهر النص مشوّهًا في صفحة لا تستخدم UTF-8، مرّر `default_encoding="shift_jis"`، أو ترميز الصفحة، مع الطلب. يحدد هذا الترميز البديل عندما لا تحتوي ترويسة `Content-Type` على charset. ولا يستبدل ترميزًا حدده الخادم.++إذا أرسل الخادم charset غير صحيح، افرض الترميز الصحيح باستخدام `selector_config={"encoding": "shift_jis"}`.++### طرق HTTP {#http-methods}+توجد خيارات إضافية حسب طريقة الطلب، مثل `params` لطلبات GET، و`data` أو `json` لطلبات POST وPUT وDELETE.++الأمثلة أفضل طريقة للتوضيح:++> ملاحظة: الطريقتان `OPTIONS` و`HEAD` غير مدعومتين.+#### GET {#get}+```python+from scrapling.fetchers import Fetcher+# Basic GET+page = Fetcher.get('https://example.com')+page = Fetcher.get('https://scrapling.requestcatcher.com/get', stealthy_headers=True)+page = Fetcher.get('https://scrapling.requestcatcher.com/get', proxy='http://username:password@localhost:8030')+# With parameters+page = Fetcher.get('https://example.com/search', params={'q': 'query'})++# With headers+page = Fetcher.get('https://example.com', headers={'User-Agent': 'Custom/1.0'})+# Basic HTTP authentication+page = Fetcher.get("https://example.com", auth=("my_user", "password123"))+# Browser impersonation+page = Fetcher.get('https://example.com', impersonate='chrome')+# HTTP/3 support+page = Fetcher.get('https://example.com', http3=True)+```+للطلبات غير المتزامنة، يكفي تعديل بسيط:+```python+from scrapling.fetchers import AsyncFetcher+# Basic GET+page = await AsyncFetcher.get('https://example.com')+page = await AsyncFetcher.get('https://scrapling.requestcatcher.com/get', stealthy_headers=True)+page = await AsyncFetcher.get('https://scrapling.requestcatcher.com/get', proxy='http://username:password@localhost:8030')+# With parameters+page = await AsyncFetcher.get('https://example.com/search', params={'q': 'query'})+# With headers+page = await AsyncFetcher.get('https://example.com', headers={'User-Agent': 'Custom/1.0'})+# Basic HTTP authentication+page = await AsyncFetcher.get("https://example.com", auth=("my_user", "password123"))+# Browser impersonation+page = await AsyncFetcher.get('https://example.com', impersonate='chrome110')+# HTTP/3 support+page = await AsyncFetcher.get('https://example.com', http3=True)+```+في كل الحالات، يكون `page` كائن [Response](choosing.md#response-object)، وهو أيضًا [Selector](../parsing/main_classes.md#selector) كما ذكرنا، لذلك يمكنك استخدامه مباشرة:+```python+page.css('.something.something')++page = Fetcher.get('https://api.github.com/events')+>>> page.json()+[{'id': '<redacted>',+ 'type': 'PushEvent',+ 'actor': {'id': '<redacted>',+ 'login': '<redacted>',+ 'display_login': '<redacted>',+ 'gravatar_id': '',+ 'url': 'https://api.github.com/users/<redacted>',+ 'avatar_url': 'https://avatars.githubusercontent.com/u/<redacted>'},+ 'repo': {'id': '<redacted>',+...+```+#### POST {#post}+```python+from scrapling.fetchers import Fetcher+# Basic POST+page = Fetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, params={'q': 'query'})+page = Fetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, stealthy_headers=True)+page = Fetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, proxy='http://username:password@localhost:8030', impersonate="chrome")+# Another example of form-encoded data+page = Fetcher.post('https://example.com/submit', data={'username': 'user', 'password': 'pass'}, http3=True)+# JSON data+page = Fetcher.post('https://example.com/api', json={'key': 'value'})+```+للطلبات غير المتزامنة، يكفي تعديل بسيط:+```python+from scrapling.fetchers import AsyncFetcher+# Basic POST+page = await AsyncFetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'})+page = await AsyncFetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, stealthy_headers=True)+page = await AsyncFetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, proxy='http://username:password@localhost:8030', impersonate="chrome")+# Another example of form-encoded data+page = await AsyncFetcher.post('https://example.com/submit', data={'username': 'user', 'password': 'pass'}, http3=True)+# JSON data+page = await AsyncFetcher.post('https://example.com/api', json={'key': 'value'})+```+#### PUT {#put}+```python+from scrapling.fetchers import Fetcher+# Basic PUT+page = Fetcher.put('https://example.com/update', data={'status': 'updated'})+page = Fetcher.put('https://example.com/update', data={'status': 'updated'}, stealthy_headers=True, impersonate="chrome")+page = Fetcher.put('https://example.com/update', data={'status': 'updated'}, proxy='http://username:password@localhost:8030')+# Another example of form-encoded data+page = Fetcher.put("https://scrapling.requestcatcher.com/put", data={'key': ['value1', 'value2']})+```+للطلبات غير المتزامنة، يكفي تعديل بسيط:+```python+from scrapling.fetchers import AsyncFetcher+# Basic PUT+page = await AsyncFetcher.put('https://example.com/update', data={'status': 'updated'})+page = await AsyncFetcher.put('https://example.com/update', data={'status': 'updated'}, stealthy_headers=True, impersonate="chrome")+page = await AsyncFetcher.put('https://example.com/update', data={'status': 'updated'}, proxy='http://username:password@localhost:8030')+# Another example of form-encoded data+page = await AsyncFetcher.put("https://scrapling.requestcatcher.com/put", data={'key': ['value1', 'value2']})+```++#### DELETE {#delete}+```python+from scrapling.fetchers import Fetcher+page = Fetcher.delete('https://example.com/resource/123')+page = Fetcher.delete('https://example.com/resource/123', stealthy_headers=True, impersonate="chrome")+page = Fetcher.delete('https://example.com/resource/123', proxy='http://username:password@localhost:8030')+```+للطلبات غير المتزامنة، يكفي تعديل بسيط:+```python+from scrapling.fetchers import AsyncFetcher+page = await AsyncFetcher.delete('https://example.com/resource/123')+page = await AsyncFetcher.delete('https://example.com/resource/123', stealthy_headers=True, impersonate="chrome")+page = await AsyncFetcher.delete('https://example.com/resource/123', proxy='http://username:password@localhost:8030')+```++## إدارة الجلسات {#session-management}++لإرسال عدة طلبات بالإعدادات نفسها، استخدم `FetcherSession`. تعمل الفئة مع الكود المتزامن وغير المتزامن، وتحدد نوع الجلسة وتغيره تلقائيًا دون الحاجة إلى استيراد مختلف.++تقبل `FetcherSession` معظم خيارات دوال الطلبات. يمكنك تحديد إعدادات للجلسة كلها، ثم تغييرها لطلب معين بسهولة، كما في الأمثلة التالية.++```python+from scrapling.fetchers import FetcherSession++# Create a session with default configuration+with FetcherSession(+ impersonate='chrome',+ http3=True,+ stealthy_headers=True,+ timeout=30,+ retries=3+) as session:+ # Make multiple requests with the same settings and the same cookies+ page1 = session.get('https://scrapling.requestcatcher.com/get')+ page2 = session.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'})+ page3 = session.get('https://api.github.com/events')++ # All requests share the same session and connection pool+```++يمكنك أيضًا استخدام `ProxyRotator` مع `FetcherSession` لتبديل البروكسي تلقائيًا بين الطلبات:++```python+from scrapling.fetchers import FetcherSession, ProxyRotator++rotator = ProxyRotator([+ 'http://proxy1:8080',+ 'http://proxy2:8080',+ 'http://proxy3:8080',+])++with FetcherSession(proxy_rotator=rotator, impersonate='chrome') as session:+ # Each request automatically uses the next proxy in rotation+ page1 = session.get('https://example.com/page1')+ page2 = session.get('https://example.com/page2')++ # You can check which proxy was used via the response metadata+ print(page1.meta['proxy'])+```++ويمكنك استبدال بروكسي الجلسة أو أداة التبديل لطلب معين بتمرير `proxy=` مباشرة إلى دالة الطلب:++```python+with FetcherSession(proxy='http://default-proxy:8080') as session:+ # Uses the session proxy+ page1 = session.get('https://example.com/page1')++ # Override the proxy for this specific request+ page2 = session.get('https://example.com/page2', proxy='http://special-proxy:9090')+```++وهذا مثال غير متزامن:++```python+async with FetcherSession(impersonate='firefox', http3=True) as session:+ # All standard HTTP methods available+ response = await session.get('https://example.com')+ response = await session.post('https://scrapling.requestcatcher.com/post', json={'data': 'value'})+ response = await session.put('https://scrapling.requestcatcher.com/put', data={'update': 'info'})+ response = await session.delete('https://scrapling.requestcatcher.com/delete')+```+أو بشكل أفضل:+```python+import asyncio+from scrapling.fetchers import FetcherSession++# Async session usage+async with FetcherSession(impersonate="safari") as session:+ urls = ['https://example.com/page1', 'https://example.com/page2']++ tasks = [+ session.get(url) for url in urls+ ]++ pages = await asyncio.gather(*tasks)+```++تستخدم فئة `Fetcher` فئة `FetcherSession` لإنشاء جلسة مؤقتة لكل طلب.++### فوائد الجلسات {#session-benefits}++- **سرعة أكبر**: أسرع بعشر مرات من إنشاء جلسة مستقلة لكل طلب.+- **الاحتفاظ بملفات تعريف الارتباط**: إدارة تلقائية لها بين الطلبات.+- **استخدام أفضل للموارد**: تقليل استهلاك الذاكرة والمعالج عند إرسال عدة طلبات.+- **إعدادات مركزية**: مكان واحد لإدارة إعدادات الطلبات.++## أمثلة {#examples}+أمثلة متكاملة لمساعدة من يبدأ في جمع بيانات الويب.++### طلب HTTP بسيط {#basic-http-request}++```python+from scrapling.fetchers import Fetcher++# Make a request+page = Fetcher.get('https://example.com')++# Check the status+if page.status == 200:+ # Extract title+ title = page.css('title::text').get()+ print(f"Page title: {title}")++ # Extract all links+ links = page.css('a::attr(href)').getall()+ print(f"Found {len(links)} links")+```++### جمع بيانات المنتجات {#product-scraping}++```python+from scrapling.fetchers import Fetcher++def scrape_products():+ page = Fetcher.get('https://example.com/products')++ # Find all product elements+ products = page.css('.product')++ results = []+ for product in products:+ results.append({+ 'title': product.css('.title::text').get(),+ 'price': product.css('.price::text').re_first(r'\d+\.\d{2}'),+ 'description': product.css('.description::text').get(),+ 'in_stock': product.has_class('in-stock')+ })++ return results+```++### تنزيل الملفات {#downloading-files}++```python+from scrapling.fetchers import Fetcher++page = Fetcher.get('https://raw.githubusercontent.com/D4Vinci/Scrapling/main/docs/assets/main_cover.png')+with open(file='main_cover.png', mode='wb') as f:+ f.write(page.body)+```++### التنقل بين صفحات النتائج {#pagination-handling}++```python+from scrapling.fetchers import Fetcher++def scrape_all_pages():+ base_url = 'https://example.com/products?page={}'+ page_num = 1+ all_products = []++ while True:+ # Get current page+ page = Fetcher.get(base_url.format(page_num))++ # Find products+ products = page.css('.product')+ if not products:+ break++ # Process products+ for product in products:+ all_products.append({+ 'name': product.css('.name::text').get(),+ 'price': product.css('.price::text').get()+ })++ # Next page+ page_num += 1++ return all_products+```++### إرسال نموذج {#form-submission}++```python+from scrapling.fetchers import Fetcher++# Submit login form+response = Fetcher.post(+ 'https://example.com/login',+ data={+ 'username': '[email protected]',+ 'password': 'password123'+ }+)++# Check login success+if response.status == 200:+ # Extract user info+ user_name = response.css('.user-name::text').get()+ print(f"Logged in as: {user_name}")+```++### استخراج جدول {#table-extraction}++```python+from scrapling.fetchers import Fetcher++def extract_table():+ page = Fetcher.get('https://example.com/data')++ # Find table+ table = page.css('table')[0]++ # Extract headers+ headers = [+ th.text for th in table.css('thead th')+ ]++ # Extract rows+ rows = []+ for row in table.css('tbody tr'):+ cells = [td.text for td in row.css('td')]+ rows.append(dict(zip(headers, cells)))++ return rows+```++### قائمة التنقل {#navigation-menu}++```python+from scrapling.fetchers import Fetcher++def extract_menu():+ page = Fetcher.get('https://example.com')++ # Find navigation+ nav = page.css('nav')[0]++ menu = {}+ for item in nav.css('li'):+ links = item.css('a')+ if links:+ link = links[0]+ menu[link.text] = {+ 'url': link['href'],+ 'has_submenu': bool(item.css('.submenu'))+ }++ return menu+```++## متى تستخدم كل أداة؟ {#when-to-use}++استخدم `Fetcher` عندما:++- تحتاج إلى طلبات HTTP سريعة.+- تريد أقل استهلاك إضافي للموارد.+- لا تحتاج إلى تشغيل JavaScript، ويمكن جمع بيانات الموقع بالطلبات فقط.+- تحتاج إلى بعض ميزات التخفي، مثل التعامل مع موقع يستخدم حماية دون اختبارات JavaScript.++استخدم `FetcherSession` عندما:++- ترسل عدة طلبات إلى الموقع نفسه أو مواقع مختلفة.+- تحتاج إلى حفظ ملفات تعريف الارتباط أو المصادقة بين الطلبات.+- تريد إعادة استخدام الاتصالات لتحسين الأداء.+- تحتاج إلى إعدادات ثابتة بين الطلبات.+- تتعامل مع APIs تتطلب الاحتفاظ بحالة الجلسة.++استخدم أدوات جلب أخرى عندما:++- تحتاج إلى أتمتة المتصفح.+- تحتاج إلى ميزات متقدمة للتخفي أو تجاوز كشف البوتات.+- تحتاج إلى تشغيل JavaScript أو التفاعل مع المحتوى الديناميكي.diff --git a/docs/locales/ar/fetching/stealthy.md b/docs/locales/ar/fetching/stealthy.mdnew file mode 100644index 0000000..6082b4b--- /dev/null+++ b/docs/locales/ar/fetching/stealthy.md@@ -0,0 +1,536 @@+---+title: "جمع بيانات مواقع JavaScript باستخدام StealthyFetcher"+description: "حمّل الصفحات وانتظر البيانات وأعد استخدام تسجيل الدخول واقرأ ردود API في الخلفية عبر جلسات متصفح Scrapling، مع إعداد البروكسي والتعامل مع اختبارات الحماية."+---++# جلب الصفحات بالمتصفح باستخدام StealthyFetcher {#browser-fetching-with-stealthyfetcher}++تحمّل فئة `StealthyFetcher` صفحات JavaScript وتؤتمت Chromium أو Google Chrome مع ميزات لتجاوز كشف البوتات. تستخدم [واجهة Playwright](https://playwright.dev/python/docs/intro) مع تعديلات للتخفي.++كما سنوضح لاحقًا، تحتاج إلى بعض المعرفة بـ[واجهة Page في Playwright](https://playwright.dev/python/docs/api/class-page) لأتمتة الصفحة.++!!! success "قبل البدء"++ 1. اقرأ [أساسيات أدوات الجلب](../fetching/choosing.md) لتفهم [كائن Response](../fetching/choosing.md#response-object) وتختار أداة الجلب المناسبة.+ 2. اقرأ [البحث عن العناصر](../parsing/selection.md) لتعرف كيف تجد العناصر وتستخرجها من كائن [Selector](../parsing/main_classes.md#selector) أو [Response](../fetching/choosing.md#response-object).+ 3. اقرأ [الفئات الأساسية](../parsing/main_classes.md) لتعرف الخصائص والدوال التي ترثها [Response](../fetching/choosing.md#response-object) من [Selector](../parsing/main_classes.md#selector).++## الاستخدام الأساسي {#basic-usage}+هذه طريقة الاستيراد الأساسية، وهي نفسها لكل أدوات الجلب:++```python+from scrapling.fetchers import StealthyFetcher+```+تعرّف على إعداد خيارات التحليل [هنا](choosing.md#parser-configuration-in-all-fetchers).++سنراجع معظم الخيارات واحدًا تلو الآخر مع أمثلة. للوصول مباشرة إلى جدول كل الخيارات، [اضغط هنا](#full-list-of-arguments).++!!! abstract "معلومة سريعة"++ النسخة غير المتزامنة من دالة `fetch` هي `async_fetch`.+++توفر أداة الجلب حاليًا ثلاثة خيارات أساسية للتشغيل، ويمكن الجمع بين الخيارات حسب الحاجة.++وهي:++### 1. Chromium المرفق {#1-bundled-chromium}+```python+StealthyFetcher.fetch('https://example.com')+```+يفتح هذا Chromium المرفق بإعدادات التخفي الافتراضية، ثم يحمّل الصفحة.++### 2. Chrome الحقيقي {#2-real-chrome}+```python+StealthyFetcher.fetch('https://example.com', real_chrome=True)+```+استخدم هذا الخيار إذا كان Google Chrome مثبّتًا لديك. يعمل مثل الخيار الأول، لكنه يستخدم Chrome المثبّت على جهازك بدلًا من Chromium. بذلك تبدو الطلبات أقرب إلى استخدام متصفح حقيقي، فيصعب كشفها وتحصل على نتائج أفضل.++إذا لم يكن Chrome مثبّتًا وتريد هذا الخيار، يمكنك تثبيته للمكتبة من الطرفية بدلًا من تثبيته يدويًا:+```commandline+playwright install chrome+```++### 3. الاتصال عبر CDP {#3-cdp-connection}+```python+StealthyFetcher.fetch('https://example.com', cdp_url='ws://localhost:9222')+```+بدلًا من تشغيل Chromium أو Chrome محليًا، يمكنك الاتصال بمتصفح بعيد عبر [Chrome DevTools Protocol](https://chromedevtools.github.io/devtools-protocol/).++يمكن أن يكون الرابط عنوان WebSocket يبدأ بـ`ws://` أو `wss://`، وهو ما يقدمه مزودو المتصفحات، أو عنوان HTTP للمتصفح مثل `http://localhost:9222`.+++## ما الذي توفره الأداة؟ {#what-does-it-do}++يدعم StealthyFetcher الميزات التالية لتجاوز كشف البوتات:++1. تجاوز أنواع Cloudflare Turnstile وInterstitial تلقائيًا باستخدام `solve_cloudflare=True`.+2. منع تسريبات بيئة تشغيل CDP وتسريبات WebRTC.+3. عزل تنفيذ JavaScript، وإزالة كثير من بصمات Playwright، وتجنب بعض سلوكيات البوتات المعروفة.+4. إضافة تشويش إلى canvas لمنع استخدامه في تكوين بصمة للمتصفح.+5. تعديل الطرق المعروفة لكشف وضع المتصفح بلا واجهة تلقائيًا، مع خيار لتجنب الكشف بسبب اختلاف المنطقة الزمنية.+6. وخيارات أخرى لتجاوز الحماية...++## قائمة الخيارات الكاملة {#full-list-of-arguments}+يوفر Scrapling خيارات كثيرة لهذه الأداة وفئات جلساتها. قبل الانتقال إلى [الأمثلة](#examples)، هذه قائمة الخيارات كاملة:+++| الخيار | الوصف | اختياري |+|:---------------------:|-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------:|+| url | الرابط المطلوب. | ❌ |+| headless | استخدم `True` لتشغيل المتصفح بلا واجهة ظاهرة، وهو **الافتراضي**، أو `False` لعرضه. | ✔️ |+| disable_resources | يمنع تحميل الموارد غير الضرورية لزيادة السرعة. الأنواع المحظورة هي `font` و`image` و`media` و`beacon` و`object` و`imageset` و`texttrack` و`websocket` و`csp_report` و`stylesheet`. | ✔️ |+| cookies | يحدد ملفات تعريف الارتباط للطلب التالي. | ✔️ |+| useragent | نص User-Agent المطلوب. **دون تحديده، تنشئ الأداة User-Agent حقيقيًا للمتصفح نفسه وإصداره وتستخدمه.** | ✔️ |+| network_idle | ينتظر حتى تخلو الصفحة من اتصالات الشبكة لمدة 500 ms على الأقل. | ✔️ |+| load_dom | مفعّل افتراضيًا. ينتظر تحميل JavaScript في الصفحات وتنفيذه، أي حالة `domcontentloaded`. | ✔️ |+| pierce_shadow | يضم محتوى Shadow DOM المفتوح إلى HTML الرد. الافتراضي `False`. يمكن ضبطه للجلسة أو تغييره لكل طلب. | ✔️ |+| timeout | المهلة بالميلي ثانية لكل العمليات والانتظار في الصفحة. الافتراضي 30,000 ms، أي 30 ثانية. | ✔️ |+| wait | مدة انتظار إضافية بالميلي ثانية بعد اكتمال كل شيء، قبل إغلاق الصفحة وإعادة كائن `Response`. | ✔️ |+| page_action | لأتمتة الصفحة. مرّر دالة تستقبل كائن `page` وتعمل بعد الانتقال لتنفيذ الخطوات المطلوبة. | ✔️ |+| page_setup | دالة تستقبل كائن `page` وتعمل قبل الانتقال. استخدمها لتسجيل مستمعي الأحداث أو routes التي يجب إعدادها قبل تحميل الصفحة. | ✔️ |+| wait_selector | ينتظر وصول عنصر يطابق محدد CSS إلى حالة معينة. | ✔️ |+| init_script | مسار مطلق لملف JavaScript يُنفّذ عند إنشاء كل صفحة في الجلسة. | ✔️ |+| wait_selector_state | الحالة التي ينتظرها Scrapling للمحدد الممرّر عبر `wait_selector`. _الافتراضي `attached`._ | ✔️ |+| google_search | مفعّل افتراضيًا. يضيف ترويسة referer من Google. | ✔️ |+| extra_headers | قاموس ترويسات إضافية للطلب. _إذا استُخدم مع `google_search`، تكون الأولوية لقيمة referer التي يحددها `google_search`._ | ✔️ |+| proxy | البروكسي المستخدم للطلبات. يقبل نصًا أو قاموسًا بالمفاتيح 'server' و'username' و'password' فقط. | ✔️ |+| real_chrome | فعّله إذا كان Chrome مثبّتًا على جهازك، لتشغّل أداة الجلب نسخة منه وتستخدمها. | ✔️ |+| locale | لغة المستخدم وإعداداته المحلية، مثل `en-GB` أو `de-DE`. يؤثر في `navigator.language` وترويسة `Accept-Language` وقواعد تنسيق الأرقام والتواريخ. يستخدم إعداد النظام افتراضيًا. | ✔️ |+| timezone_id | يغيّر المنطقة الزمنية للمتصفح. الافتراضي هو منطقة النظام الزمنية. | ✔️ |+| cdp_url | يتصل بهذا الرابط للتحكم بمتصفح عبر CDP بدلًا من تشغيل متصفح جديد. | ✔️ |+| user_data_dir | مسار مجلد بيانات المستخدم، الذي يحفظ ملفات تعريف الارتباط والتخزين المحلي. ينشئ مجلدًا مؤقتًا افتراضيًا. **يعمل مع الجلسات فقط.** | ✔️ |+| extra_flags | قائمة خيارات إضافية تُمرّر إلى المتصفح عند تشغيله. | ✔️ |+| solve_cloudflare | يحل كل أنواع اختبارات Cloudflare Turnstile وInterstitial قبل إعادة الرد. الافتراضي `False`. | ✔️ |+| block_webrtc | يُلزم WebRTC باتباع إعدادات البروكسي لمنع تسريب عنوان IP المحلي. | ✔️ |+| hide_canvas | يضيف تشويشًا عشوائيًا إلى عمليات canvas لمنع تكوين بصمة. | ✔️ |+| allow_webgl | مفعّل افتراضيًا. تعطيله يوقف WebGL وWebGL 2.0 تمامًا. لا يُنصح بذلك، لأن كثيرًا من أنظمة WAF تتحقق الآن من تفعيل WebGL. | ✔️ |+| additional_args | إعدادات إضافية تُمرّر إلى سياق Playwright، ولها أولوية أعلى من إعدادات Scrapling. | ✔️ |+| selector_config | قاموس خيارات تحليل مخصصة يُستخدم عند إنشاء كائن `Selector` أو `Response` النهائي. | ✔️ |+| blocked_domains | مجموعة أسماء نطاقات لحظر الطلبات إليها، بما فيها النطاقات الفرعية. مثلًا، يحظر `"example.com"` النطاق `"sub.example.com"` أيضًا. | ✔️ |+| block_ads | يحظر الطلبات إلى نحو 3,500 نطاق إعلانات وتتبع معروف. يمكن جمعه مع `blocked_domains`. | ✔️ |+| dns_over_https | يوجّه استعلامات DNS عبر DNS-over-HTTPS من Cloudflare لمنع تسريب DNS عند استخدام البروكسي. | ✔️ |+| proxy_rotator | كائن `ProxyRotator` لتبديل البروكسي تلقائيًا. لا يمكن جمعه مع `proxy`. | ✔️ |+| retries | عدد محاولات الطلبات الفاشلة. الافتراضي 3. | ✔️ |+| retry_delay | مدة الانتظار بالثواني بين المحاولات. الافتراضي ثانية واحدة. | ✔️ |+| record_requests | يحتفظ بالطلبات المكتملة والردود المحفوظة في `session.network`. للجلسات فقط، والافتراضي `False`. | ✔️ |+| max_recorded_requests | أقصى عدد طلبات محفوظة لكل جلسة. الافتراضي 1,000. توجد أيضًا حدود ثابتة لحجم محتوى الردود المحفوظ. | ✔️ |+| executable_path | مسار مطلق لملف متصفح تنفيذي مخصص بدلًا من Chromium المرفق. يفيد في التثبيتات غير المعتادة أو نسخ المتصفح المخصصة. | ✔️ |++يمكن ضبط كل هذه الخيارات للجلسة كاملة. ويمكن أيضًا ضبط كل طلب وحده بتمرير الخيارات التي تعمل على مستوى علامة تبويب المتصفح، مثل `google_search` و`timeout` و`wait` و`page_action` و`page_setup` و`extra_headers` و`disable_resources` و`wait_selector` و`wait_selector_state` و`network_idle` و`load_dom` و`pierce_shadow` و`solve_cloudflare` و`blocked_domains` و`proxy` و`selector_config`.++!!! note "ملاحظات:"++ 1. زاد `disable_resources` سرعة الطلبات بنحو 25% في اختباراتي لبعض المواقع، وقد يقلل استخدام البروكسي. لكن استخدمه بحذر، لأنه قد يمنع بعض المواقع من إكمال التحميل.+ 2. الخيار `google_search` مفعّل افتراضيًا لكل الطلبات، ويضبط referer على `https://www.google.com/`. وله أولوية على قيمة referer في `extra_headers` عند استخدامهما معًا.+ 3. إذا لم تحدد User-Agent وفعّلت وضع headless، تنشئ الأداة User-Agent حقيقيًا لإصدار المتصفح نفسه. وإذا لم تحدده ولم تفعّل headless، تستخدم User-Agent الافتراضي للمتصفح، وهو نفسه المستخدم في المتصفحات المعتادة في الإصدارات الحديثة.+ 4. يُسجّل `init_script` مع سياق المتصفح ليعمل عند إنشاء الصفحات. يستخدم وضع التخفي سياق التنفيذ المعزول في Patchright افتراضيًا. إذا احتاجت `page_action` إلى قراءة متغيرات عامة يضعها السكربت على `window`، استدعِ `page.evaluate(..., isolated_context=False)` داخل الدالة.++## إدارة الجلسات {#session-management}++لإبقاء المتصفح مفتوحًا أثناء إرسال عدة طلبات بالإعدادات نفسها، استخدم `StealthySession` أو `AsyncStealthySession`. تقبل الفئتان كل خيارات `fetch`، فتستطيع تحديد إعدادات للجلسة كلها.++```python+from scrapling.fetchers import StealthySession+++with StealthySession(+ headless=True,+ disable_resources=True,+ real_chrome=True+) as session:++ page1 = session.fetch('https://example1.com')+ page2 = session.fetch('https://example2.com')+ page3 = session.fetch('https://dynamic-site.com')+++```++### استخدام جلسة غير متزامنة {#async-session-usage}++```python+import asyncio+from scrapling.fetchers import AsyncStealthySession++async def scrape_multiple_sites():+ async with AsyncStealthySession(+ network_idle=True,+ timeout=30000,+ max_pages=3+ ) as session:++ pages = await asyncio.gather(+ session.fetch('https://spa-app1.com'),+ session.fetch('https://spa-app2.com'),+ session.fetch('https://dynamic-content.com')+ )+ return pages+```++ربما لاحظت `max_pages`. يتيح الاحتفاظ **بمجموعة علامات تبويب للمتصفح**، وتحدد به أقصى عدد مفتوح في الوقت نفسه. تبقى علامات التبويب مفتوحة بعد انتهاء طلباتها. مع كل طلب، تفعل المكتبة التالي:++1. تعيد استخدام علامة تبويب متاحة إن وجدت. يطبّق كل طلب إعداداته الخاصة، مثل `timeout` و`extra_headers` و`disable_resources` و`blocked_domains`، فلا تنتقل إعدادات الطلب السابق إليه.+2. أو تفتح علامة تبويب جديدة إذا كان العدد الحالي أقل من `max_pages`.+3. وإلا تتحقق على فترات تقل عن ثانية من توفر علامة تبويب، لمدة 60 ثانية، ثم ترفع `TimeoutError`. قد يحدث ذلك إذا توقف الموقع عن الاستجابة.++تُغلق علامات التبويب التي يحدث فيها خطأ وتُستبدل. ويمكنك إغلاقها كلها في أي وقت باستخدام `session.close_pages()`، وسيفتح الطلب التالي علامة جديدة.++يسمح هذا بجلب عدة روابط في الوقت نفسه داخل المتصفح نفسه، فيوفر الموارد ويزيد السرعة كثيرًا :)++بقاء علامات التبويب مفتوحة يعني أيضًا أن الصفحة السابقة تبقى متاحة للطلب التالي. تعمل `page_setup` في الطلب التالي عليها قبل الانتقال إلى صفحة أخرى. هذا أساس ربط خطوات الأتمتة بين الطلبات.++كانت الإصدارات من 0.3.2 إلى 0.4.14 تغلق كل علامة تبويب بعد الطلب، لأن إعادة استخدامها كانت تنقل الإعدادات بين الطلبات. منذ 0.4.15، تُعاد تهيئة الإعدادات عند كل استخدام، ولذلك تبقى العلامات مفتوحة.++### حفظ حالة الجلسة واستعادتها {#save-and-load-session-state}++استخدم `save_state(path)` لحفظ ملفات تعريف الارتباط والتخزين المحلي وIndexedDB في ملف JSON. واستخدم `load_state(path)` لاستعادته في جلسة أخرى أو استبدال الحالة المخزنة للجلسة الحالية. تقبل الدالتان نصًا أو `pathlib.Path` وتعيدان `None`. الصيغة متوافقة مع ملفات حالة التخزين في Playwright.++```python+from scrapling.fetchers import StealthySession++with StealthySession() as session:+ session.fetch('https://example.com')+ session.save_state('state.json')++with StealthySession() as session:+ session.load_state('state.json')+ page = session.fetch('https://example.com')+```++احفظ الحالة بعد انتهاء تسجيل الدخول أو خطوات المتصفح الأخرى. استدعِ الدالتين داخل جلسة بدأت بالفعل، وبعد اكتمال طلبات الجلب المعلقة. تحل الحالة المحمّلة محل ملفات تعريف الارتباط والتخزين المحلي وIndexedDB الحالية. اجلب الصفحة أو أعد تحميلها لاستخدام تسجيل الدخول المستعاد، لأن تحميل الحالة لا ينقل علامات التبويب المفتوحة.++استخدم `await` مع `AsyncStealthySession`:++```python+from scrapling.fetchers import AsyncStealthySession++async def restore_session():+ async with AsyncStealthySession() as session:+ await session.load_state('state.json')+ page = await session.fetch('https://example.com')+ await session.save_state('state.json')+ return page+```++تحفظ هذه الدوال سياق المتصفح المشترك وتستعيده فقط. لا تؤثر في سياقات البروكسي المؤقتة لكل طلب. جلسات `proxy_rotator` ليس لها سياق مشترك، لذلك ترفع الدوال فيها `RuntimeError`. أما `proxy` الثابت للجلسة فيعمل كالمعتاد.++لا يحتوي الملف على `sessionStorage` أو علامات التبويب المفتوحة أو إعدادات المتصفح. يستبدل الحفظ الملف الموجود، ويجب أن يكون المجلد الأب موجودًا. تُمرّر أخطاء الملفات وJSON إلى المستدعي.++### فوائد الجلسات {#session-benefits}++- **إعادة استخدام المتصفح**: طلبات لاحقة أسرع بكثير باستخدام المتصفح نفسه.+- **حفظ ملفات تعريف الارتباط**: إدارة تلقائية لها ولحالة الجلسة، كما يفعل أي متصفح.+- **بصمة ثابتة**: بصمة المتصفح نفسها في كل الطلبات.+- **استخدام أفضل للذاكرة**: استهلاك أقل للموارد مقارنة بتشغيل متصفح جديد لكل طلب.+++## أمثلة {#examples}+الأمثلة تجعل الشرح أوضح، فلنرَ بعضها.++### التحكم في الموارد {#resource-control}++```python++page = StealthyFetcher.fetch('https://example.com', disable_resources=True)+```++### Shadow DOM {#shadow-dom}++تحتفظ بعض الصفحات بمحتوى داخل shadow roots مفتوحة لا تظهر في HTML المعتاد للصفحة. فعّل `pierce_shadow` لضم هذا المحتوى إلى الرد، ثم استخدم CSS أو XPath كالمعتاد:++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch('https://example.com', pierce_shadow=True)+titles = page.css('product-card .title::text').getall()+```++الافتراضي `False`. يمكنك تفعيله للجلسة وتعطيله لطلب معين:++```python+from scrapling.fetchers import StealthySession++with StealthySession(pierce_shadow=True) as session:+ page = session.fetch('https://example.com')+ plain_page = session.fetch('https://example.com', pierce_shadow=False)+```++يعمل الخيار نفسه مع `async_fetch` والجلسات غير المتزامنة.++تُضم الجذور المفتوحة فقط. لا يجري المرور على الجذور المغلقة أو مستندات iframe. استخدم `wait_selector` عندما يُحمّل مكوّن بعد الصفحة.++يتحول كل جذر مفتوح إلى غلاف `<shadow-root>` في الرد. تحتفظ عناصر slot بوسومها وخصائصها، وتحتوي العقد المخصصة لها أو المحتوى البديل عند عدم تخصيص شيء. تُحذف عناصر light DOM التابعة غير المخصصة. لا تتغير الصفحة الفعلية في المتصفح.++```html+<product-card>+ <shadow-root>+ <div class="title">Product name</div>+ <slot name="price"><span class="price">20</span></slot>+ </shadow-root>+</product-card>+```++تعمل محددات العناصر المتداخلة عبر هذه العناصر. أما محددات الابن المباشر، فيجب أن تتضمن الأغلفة وعناصر slot:++```python+titles = page.css('product-card .title::text').getall()+titles = page.css('product-card > shadow-root > .title::text').getall()+prices = page.css('product-card > shadow-root > slot[name="price"] > .price::text').getall()+```++تظهر الأغلفة وعناصر slot في مسارات XPath و`.children` و`response.body` وتصدير HTML. يعيد استخراج Markdown والنص محتواها دون طباعة الوسوم. وتظل خصائص إخفاء slot متاحة لأدوات تنظيف المحتوى.++تتبع النسخة المحفوظة ترتيب المحتوى، لكنها لا تحسب ظهور العناصر أو تخطيطها وفق CSS. المحددات التي تحتوي `<shadow-root>` تعمل على رد Scrapling، وليس صفحة المتصفح الفعلية. وقد تتعامل محلّلات HTML الأخرى مع التداخل غير المعتاد بصورة مختلفة.++### حظر النطاقات {#domain-blocking}++```python++page = StealthyFetcher.fetch('https://example.com', blocked_domains={"ads.example.com", "tracker.net"})+```++### التحكم في الشبكة {#network-control}++```python++page = StealthyFetcher.fetch('https://example.com', network_idle=True)+++page = StealthyFetcher.fetch('https://example.com', timeout=30000)+++page = StealthyFetcher.fetch('https://example.com', proxy='http://username:password@host:port')+```++### تنزيل الملفات {#downloading-files}++```python+page = StealthyFetcher.fetch('https://raw.githubusercontent.com/D4Vinci/Scrapling/main/docs/assets/main_cover.png')++with open(file='main_cover.png', mode='wb') as f:+ f.write(page.body)+```++تعيد خاصية `body` في كائن `Response` قيمة من نوع `bytes` دائمًا.++### الإعداد قبل الانتقال {#pre-navigation-setup}+لإعداد مستمعي الأحداث أو routes أو السكربتات التي يجب تسجيلها قبل انتقال الصفحة، استخدم `page_setup`. تستقبل الدالة كائن `page` وتعمل قبل استدعاء `page.goto()`.++```python+from patchright.sync_api import Page++def capture_websockets(page: Page):+ page.on("websocket", lambda ws: print(f"WebSocket opened: {ws.url}"))++page = StealthyFetcher.fetch('https://example.com', page_setup=capture_websockets)+```+النسخة غير المتزامنة:+```python+from patchright.async_api import Page++async def capture_websockets(page: Page):+ page.on("websocket", lambda ws: print(f"WebSocket opened: {ws.url}"))++page = await StealthyFetcher.async_fetch('https://example.com', page_setup=capture_websockets)+```++يمكنك جمعها مع `page_action`. تعمل `page_setup` قبل الانتقال، وتعمل `page_action` بعده.++### خيارات Cloudflare والتخفي {#cloudflare-and-stealth-options}++```python++page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare', solve_cloudflare=True)+++page = StealthyFetcher.fetch(+ 'https://protected-site.com',+ solve_cloudflare=True,+ block_webrtc=True,+ real_chrome=True,+ hide_canvas=True,+ google_search=True,+ proxy='http://username:password@host:port', # It can also be a dictionary with only the keys 'server', 'username', and 'password'.+)+```++يفعّل `solve_cloudflare` الكشف التلقائي وحل كل أنواع اختبارات Cloudflare Turnstile وInterstitial:++- اختبارات JavaScript المُدارة.+- الاختبارات التفاعلية، مثل النقر على مربعات التحقق.+- الاختبارات غير المرئية، أي التحقق التلقائي في الخلفية.++ويحل أيضًا الصفحات المخصصة التي تحتوي CAPTCHA مدمجة.++!!! notes "**ملاحظات مهمة:**"++ 1. في بعض المواقع ذات الإعدادات المخصصة، قد تحتاج إلى `wait_selector` لضمان انتظار المحتوى الحقيقي بعد حل CAPTCHA. بعض المواقع حالات خاصة جدًا، بينما نحاول جعل الحل عامًا قدر الإمكان.+ 2. يجب أن تكون المهلة 60 ثانية على الأقل عند استخدام أداة حل Cloudflare، لتوفير وقت كافٍ للحل.+ 3. تعمل هذه الميزة مع البروكسي وخيارات التخفي الأخرى.++### أتمتة المتصفح {#browser-automation}+هنا تستخدم معرفتك بـ[واجهة Page في Playwright](https://playwright.dev/python/docs/api/class-page). تستقبل الدالة التي تمرّرها كائن الصفحة من Playwright، وتنفّذ الإجراء المطلوب، ثم تواصل أداة الجلب عملها.++تُنفّذ هذه الدالة مباشرة بعد انتظار `network_idle` إن كان مفعّلًا، وقبل انتظار `wait_selector`. لذلك يمكن استخدامها لأغراض أخرى غير الأتمتة، ويمكنك تعديل الصفحة كما تريد.++في المثال التالي، استخدمت [أحداث الفأرة](https://playwright.dev/python/docs/api/class-mouse) لتمرير الصفحة بعجلة الفأرة، ثم تحريك المؤشر:+```python+from patchright.sync_api import Page++def scroll_page(page: Page):+ page.mouse.wheel(10, 0)+ page.mouse.move(100, 400)+ page.mouse.up()++page = StealthyFetcher.fetch('https://example.com', page_action=scroll_page)+```+إذا استخدمت نسخة الجلب غير المتزامنة، يجب أن تكون الدالة غير متزامنة أيضًا.+```python+from patchright.async_api import Page++async def scroll_page(page: Page):+ await page.mouse.wheel(10, 0)+ await page.mouse.move(100, 400)+ await page.mouse.up()++page = await StealthyFetcher.async_fetch('https://example.com', page_action=scroll_page)+```++### شروط الانتظار {#wait-conditions}++```python++page = StealthyFetcher.fetch(+ 'https://quotes.toscrape.com/js-delayed/',+ wait_selector='.quote',+ wait_selector_state='visible'+)+```+هذا آخر شرط انتظار للعنصر قبل إعادة الرد إذا فعّلته. مرّر محدد CSS عبر `wait_selector`، وستنتظر الأداة تحقق الحالة المحددة في `wait_selector_state`. الافتراضي `attached`، أي وجود العنصر في DOM.++بعد ذلك، إذا كان `load_dom` مفعّلًا، وهو الافتراضي، تتحقق الأداة مجددًا من تحميل JavaScript وتنفيذه، أي حالة `domcontentloaded`، أو تواصل الانتظار. وإذا فعّلت `network_idle`، تنتظر تحققه مجددًا كما شرحنا سابقًا.++يمكن الانتظار لأي من الحالات التالية ([المصدر](https://playwright.dev/python/docs/api/class-page#page-wait-for-selector)):++- `attached`: انتظار وجود العنصر في DOM.+- `detached`: انتظار غياب العنصر عن DOM.+- `visible`: انتظار مساحة عرض غير فارغة للعنصر، وعدم وجود `visibility:hidden`. العنصر بلا محتوى أو ذو `display:none` تكون مساحة عرضه فارغة، ولا يُعد ظاهرًا.+- `hidden`: انتظار انفصال العنصر عن DOM، أو فراغ مساحة عرضه، أو وجود `visibility:hidden`. هذا عكس `'visible'`.++### سجل الشبكة {#network-history}++فعّل `record_requests` في جلسة المتصفح لفحص الطلبات المكتملة عبر تحميل الصفحات والإجراءات وعلامات التبويب. يغطي السجل سياقات الجلسة، بما فيها سياقات البروكسي المؤقتة، ويحفظ الردود ككائنات `Response` من Scrapling. ابحث عن طلبات API وأخطاء HTTP وإعادة التوجيه دون إعادة إرسال الطلبات، واقرأ الترويسات والمحتوى حتى بعد إغلاق الجلسة. لا تُحفظ الطلبات الفاشلة أو غير المكتملة، لكن تُحفظ ردود HTTP المكتملة ذات الرموز 4xx و5xx.++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True, max_recorded_requests=1000) as session:+ session.fetch('https://example.com', network_idle=True)++for response in session.network.search(resource_type='document', limit=None):+ print(response.meta['network_id'], response.url, response.status)+ if note := response.meta.get('body_note'):+ print(note)+ else:+ print(response.body)+ print(response.css('title::text').get())++session.network.clear()+```++تعمل الواجهة نفسها مع `AsyncStealthySession`. التسجيل معطّل افتراضيًا. حدد `record_requests=True`، ومعه `max_recorded_requests` عند الحاجة، أثناء إنشاء الجلسة.++- تعيد `session.network.search(url_pattern=None, method=None, resource_type=None, status=None, after_id=0, limit=100, include_static=True)` كائنات `Response` المحفوظة بترتيب معرّف الشبكة. تعيد `limit=None` كل النتائج المطابقة المحتفظ بها. يقبل `url_pattern` تعبيرًا منتظمًا يُطبّق عند البحث، ويُرفع خطأ حينها إذا كان غير صالح. يختار `after_id` الردود ذات المعرّفات الأكبر منه. تحتفظ `include_static=False` بطلبات XHR وfetch وأخطاء HTTP في النتائج. استخدم `True` لكل أنواع الموارد وإعادة التوجيه المحفوظة.+- تعيد `session.network.get(request_id)` ردًا محفوظًا واحدًا من نوع `Response`، أو `None` إذا لم يعد موجودًا في السجل.+- تحذف `session.network.clear()` السجل. تستمر معرّفات الطلبات في الزيادة ولا تُستخدم مرة أخرى.++يوفر كل `Response` محفوظ خصائص `.url` و`.method` و`.status` و`.headers` و`.request_headers` و`.body` من نوع bytes، ودالة `.json()` ودوال CSS وXPath مباشرة. يحتوي `.meta` على `network_id` و`resource_type` و`request_body`، والأخير bytes أو `None`. قد تكون الترويسات جزئية إذا فشلت قراءتها كاملة. هذه قراءات محلية حتى في الجلسات غير المتزامنة، فلا تستخدم await معها ولا تستدعِ `.body()`. إذا تعذر تحليل المحتوى المحفوظ، تبقى البايتات محفوظة، لكن دوال CSS وXPath تستخدم مستندًا فارغًا.++للبحث عن طلبات API حسب الرابط، استخدم `session.network.search(url_pattern=r'https://api\.example\.com/.*', limit=None)`. أضف `resource_type='fetch'` أو `resource_type='xhr'` عندما تحتاج إلى نوع واحد من الطلبات.++يقرأ المسجّل محتوى الرد ويحفظه للقيم النصية المدعومة من `Content-Type` فقط: `text/*`، والأنواع المنتهية بـ`+json` أو `+xml` بما فيها SVG، وJSON وXML وJavaScript وGraphQL وبيانات النماذج بترميز URL. تحتفظ الأنواع الثنائية وغير المعروفة والردود بلا `Content-Type` ببياناتها الوصفية دون محتوى الرد. يستمر المتصفح في تحميل الموارد كالمعتاد.++تأتي البايتات المحفوظة من Playwright، وقد تختلف عن البايتات الأصلية للخادم. يستخدم النص المسجّل UTF-8 إذا كانت البايتات صالحة بهذا الترميز، بما يطابق Playwright، وإلا يستخدم charset المعلن. لا تتغير ترويسات الرد.++المحتوى المتجاهَل أو الأكبر من الحد أو الذي تعذر قراءته يعيد `b''`، مع السبب في `response.meta.get('body_note')`. للمحتوى غير النصي تكون الرسالة `Non-text body; not saved.`. تبقى البيانات الوصفية والترويسات المتاحة محفوظة. لا توجد ملاحظة للنص المحفوظ، حتى لو كان فارغًا. وتبقى ردود HEAD والرموز 204 و205 و304 فارغة بلا ملاحظة.++دوال `search` و`get` و`clear` محلية ومتزامنة حتى في الجلسات غير المتزامنة. لا يظهر الإدخال إلا بعد تحويل الرد وحفظه. تعمل أحداث المتصفح أثناء نشاط Playwright، ويحتاج الحفظ غير المتزامن أيضًا إلى عمل حلقة الأحداث. قراءة السجل لا تنتظر اكتمال عمليات الحفظ.++إغلاق الجلسة لا ينتظر اكتمال الحفظ. قد تُفقد العمليات التي ما زالت جارية عند انتقال الصفحة أو إغلاق سياق المتصفح. تظل الردود التي حُفظت بالفعل قابلة للقراءة بعد الإغلاق.++يحتفظ السجل افتراضيًا بما يصل إلى 1,000 طلب. الحد الأقصى لمحتوى كل رد محفوظ هو 1 MiB، وللمجموع 20 MiB. تُحذف السجلات القديمة عند بلوغ الحدود. حدود المحتوى ثابتة وليست إعدادات للجلسة. تشمل هذه الحدود الإدخالات والبايتات المحتفظ بها فقط، ولا تشمل ذاكرة المتصفح الكلية، أو عمليات الحفظ المتزامنة، أو القراءة المؤقتة للمحتوى الكامل، أو HTML المحلّل، أو محتوى الطلبات.++#### الانتقال إلى v5 {#migrating-in-v5}++أُزيل `capture_xhr` و`response.captured_xhr` في v5. استخدم جلسة متصفح صريحة مع `record_requests=True`، ثم اقرأ `session.network.search(url_pattern=..., limit=None)`. يحل هذا أيضًا محل حفظ API عبر أدوات الجلب ذات الطلب الواحد، لذلك احتفظ بكائن الجلسة. تُطبّق المرشحات على السجل المحفوظ للجلسة كلها، وليس على عملية الحفظ أو طلب جلب واحد. يُحفظ محتوى الردود النصية المدعومة فقط. تعيد `search()` حتى 100 نتيجة افتراضيًا، وتعيد `limit=None` كل النتائج المطابقة المحتفظ بها دون تغيير حدود السجل.++### ترويسات المتصفح والإعدادات المحلية {#browser-headers-and-locale}++```python+page = StealthyFetcher.fetch(+ 'https://example.com',+ google_search=True,+ useragent='Mozilla/5.0...',+ locale='en-US',+)+```++### مثال عام {#general-example}+```python+from scrapling.fetchers import StealthyFetcher++def scrape_dynamic_content():++ page = StealthyFetcher.fetch(+ 'https://example.com/dynamic',+ network_idle=True,+ wait_selector='.content'+ )+++ content = page.css('.content')++ return {+ 'title': content.css('h1::text').get(),+ 'items': [+ item.text for item in content.css('.item')+ ]+ }+```++### تبديل البروكسي {#proxy-rotation}++```python+from scrapling.fetchers import StealthySession, ProxyRotator+++rotator = ProxyRotator([+ "http://proxy1:8080",+ "http://proxy2:8080",+ "http://proxy3:8080",+])+++with StealthySession(proxy_rotator=rotator, headless=True) as session:+ page1 = session.fetch('https://example1.com')+ page2 = session.fetch('https://example2.com')+++ page3 = session.fetch('https://example3.com', proxy='http://specific-proxy:8080')+```++!!! warning "تنبيه"++ تستخدم كل أدوات جلب المتصفح وجلساتها افتراضيًا سياق متصفح مستمرًا مع مجموعة علامات تبويب. لكن المتصفحات لا تسمح ببروكسي مستقل لكل علامة. لذلك عند استخدام `ProxyRotator`، تفتح الأداة تلقائيًا سياقًا مستقلًا لكل بروكسي، بعلامة تبويب واحدة لكل سياق. وعند انتهاء المهمة، تُغلق العلامة وسياقها معًا.++## متى تستخدم الأداة؟ {#when-to-use}++استخدم StealthyFetcher عندما:++- تريد تجاوز حماية كشف البوتات.+- تحتاج إلى بصمة متصفح موثوقة.+- تحتاج إلى دعم JavaScript كامل.+- تريد ميزات تخفٍّ تلقائية.+- تحتاج إلى أتمتة المتصفح.+- تتعامل مع حماية Cloudflare.diff --git a/docs/locales/ar/index.md b/docs/locales/ar/index.mdnew file mode 100644index 0000000..b81271d--- /dev/null+++ b/docs/locales/ar/index.md@@ -0,0 +1,243 @@+---+title: "Scrapling: إطار عمل لجمع بيانات الويب باستخدام Python"+description: "Scrapling: اجمع بيانات الويب الحديث بسهولة!"+---++<style>+.md-typeset h1 {+ display: none;+}+[data-md-color-scheme="default"] .only-dark { display: none; }+[data-md-color-scheme="slate"] .only-light { display: none; }+</style>++<br/>+<div align="center">+ <a href="index.html" alt="الغلاف">+ <img alt="Scrapling" src="assets/cover_light.svg" class="only-light">+ <img alt="Scrapling" src="assets/cover_dark.svg" class="only-dark">+ </a>+</div>++<h2 align="center"><i>اجمع بيانات الويب الحديث بسهولة</i></h2><br>++Scrapling إطار عمل بلغة Python لجمع بيانات الويب. يجمع طلبات HTTP السريعة، والمتصفحات الخفية، وتحليل الصفحات، والزحف المتزامن في مكتبة واحدة.++اجمع بيانات الصفحات الثابتة، وشغّل JavaScript، وتفاعل مع المواقع، واستخرج البيانات من طلبات API التي تعمل خلفها. أنشئ برامج زحف بجلسات قابلة لإعادة الاستخدام، وتبديل البروكسي، وإعادة المحاولة تلقائيًا، والإيقاف والاستئناف، وتصدير البيانات بأدوات مدمجة.++استخدمه من Python أو الطرفية أو وكيل الذكاء الاصطناعي عبر خادم MCP وAgent Skill. يغطي Scrapling خطوات جمع البيانات كاملة، من استخراج بضعة حقول إلى جمع موقع كامل في ملفات Markdown نظيفة.++## ما الذي يمكنك فعله باستخدام Scrapling؟ {#what-you-can-do-with-scrapling}++- **[الجلب والتفاعل](fetching/choosing.md)**: طلبات HTTP سريعة، ومتصفحات خفية، وتشغيل JavaScript، والتعامل مع Cloudflare Turnstile وInterstitial، وجلسات مستمرة، وحفظ ردود API التي تعمل في الخلفية.+- **[التحليل والاستخراج](parsing/selection.md)**: البحث باستخدام CSS وXPath والنص والتعبيرات المنتظمة، وتتبع العناصر عند تغير الصفحة، والعثور على العناصر المتشابهة، وإخراج Markdown نظيف.+- **[الزحف والتصدير](spiders/getting-started.md)**: برامج Spider متزامنة، وتبديل البروكسي، وإعادة المحاولة، وAutoThrottle، والإيقاف والاستئناف، وبث النتائج، وقوالب جاهزة، وتصدير JSON وJSONL وCSV وXML.+- **[جمع البيانات بالذكاء الاصطناعي أو من الطرفية](ai/mcp-server.md)**: خادم MCP لوكلاء الذكاء الاصطناعي لتصفح المواقع واستخراج البيانات، وAgent Skill، وأوامر CLI، وواجهة تفاعلية.++ابدأ بصفحة واحدة:++```python+from scrapling.fetchers import Fetcher++page = Fetcher.get('https://quotes.toscrape.com/')+quotes = page.css('.quote .text::text').getall()+print(quotes)+```++أو وسّع العمل باستخدام Spider:++```python+from scrapling.spiders import Spider, Response++class QuotesSpider(Spider):+ name = "quotes"+ start_urls = ["https://quotes.toscrape.com/"]++ 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(),+ }++result = QuotesSpider().start()+print(len(result.items))+result.items.to_json("quotes.json")+```++يطبع هذا المثال `10` ويحفظ الاقتباسات وأسماء أصحابها في `quotes.json`.++## كبار الداعمين {#top-sponsors}++--8<-- "sponsors.html"++<i><sub>هل تريد عرض إعلانك هنا؟ اضغط [هنا](https://github.com/sponsors/D4Vinci)، واختر خطة، واستفد من بقية المزايا!</sub></i>++## الميزات الأساسية {#key-features}++### Spiders: إطار عمل كامل للزحف {#spiders-a-full-crawling-framework}+- 🕷️ **واجهة Spider تشبه Scrapy**: عرّف برامج Spider باستخدام `start_urls`، ودوال `parse` غير المتزامنة، وكائنات `Request` و`Response`.+- ⚡ **زحف متزامن**: اضبط عدد الطلبات المتزامنة، وحدود كل نطاق، ومدة الانتظار بين التنزيلات.+- 🔄 **دعم عدة جلسات**: واجهة واحدة لطلبات HTTP والمتصفحات الخفية بلا واجهة ضمن Spider واحد. وجّه الطلبات إلى جلسات مختلفة باستخدام المعرّف.+- 💾 **الإيقاف والاستئناف**: احفظ الطلبات المعلقة والروابط التي زرتها باستخدام `crawldir`. اضغط Ctrl+C للإيقاف الآمن، ثم أعد التشغيل مع المجلد نفسه.+- 📡 **بث النتائج**: استقبل العناصر فور جمعها عبر `async for item in spider.stream()`، مع إحصاءات مباشرة. يناسب الواجهات وخطوات معالجة البيانات وعمليات الزحف الطويلة.+- 🛡️ **كشف الطلبات المحظورة**: كشف الطلبات المحظورة وإعادة محاولتها تلقائيًا، مع إمكانية تخصيص السلوك.+- 🚦 **AutoThrottle**: لا تحتاج إلى تخمين مدة الانتظار. يضبط Spider المدة لكل نطاق حسب سرعة رد الموقع، ثم يضاعفها، أو ينتظر المدة التي يطلبها `Retry-After`، عندما يبدأ الموقع في الحظر أو تقييد معدل الطلبات. ويعود إلى السرعة الأعلى عند توقف ذلك.+- 🤖 **الالتزام بملف robots.txt**: خيار `robots_txt_obey` يحترم تعليمات `Disallow` و`Crawl-delay` و`Request-rate`، مع تخزين مؤقت لكل نطاق.+- 🧪 **وضع التطوير**: احفظ الردود على القرص في أول تشغيل، ثم أعد استخدامها في التشغيلات التالية. عدّل دالة `parse()` دون إرسال طلبات جديدة إلى الخوادم.+- 🧩 **قوالب Spider جاهزة**: استخدم `CrawlSpider` لتتبع الروابط وفق قواعد، و`SitemapSpider` للزحف من خرائط الموقع أو robots.txt، و`XMLFeedSpider` و`CSVFeedSpider` لقراءة خلاصات XML وRSS وCSV، و`ShopifySpider` لجمع منتجات متاجر Shopify العامة، بعنصر مستقل لكل نوع من المنتج.+- 🔗 **استخراج الروابط**: أداة `LinkExtractor` مستقلة تدعم أنماط السماح والمنع، وتصفية النطاقات والامتدادات، وحصر البحث باستخدام CSS وXPath، وتوحيد صيغة الروابط. استخدمها داخل القوالب أو وحدها.+- 📦 **تصدير مدمج**: صدّر النتائج عبر hooks وخط معالجة خاص بك، أو استخدم أدوات JSON وJSONL وCSV وXML المدمجة: `result.items.to_json()` و`to_jsonl()` و`to_csv()` و`to_xml()`.++### جلب متقدم للمواقع مع دعم الجلسات {#advanced-websites-fetching-with-session-support}+- **طلبات HTTP**: طلبات HTTP سريعة وخفية باستخدام `Fetcher`. تدعم محاكاة بصمة TLS وترويسات المتصفح واستخدام HTTP/3.+- **التحميل الديناميكي**: اجلب المواقع الديناميكية مع أتمتة كاملة للمتصفح عبر `StealthyFetcher`، الذي يدعم Chromium الخاص بـPlaywright وGoogle Chrome.+- **تجاوز كشف البوتات**: إخفاء متقدم للأتمتة ومحاكاة البصمات باستخدام `StealthyFetcher`. يمكنه تجاوز أنواع Cloudflare Turnstile وInterstitial تلقائيًا.+- **إدارة الجلسات**: تدعم `FetcherSession` و`StealthySession` الجلسات المستمرة لإدارة ملفات تعريف الارتباط وحالة المتصفح بين الطلبات.+- **تبديل البروكسي**: أداة `ProxyRotator` مدمجة تدعم التبديل الدوري أو المخصص في كل أنواع الجلسات، مع إمكانية تحديد بروكسي مستقل لكل طلب.+- **حظر النطاقات والإعلانات**: امنع الطلبات إلى نطاقات محددة ونطاقاتها الفرعية، أو فعّل حظر الإعلانات المدمج في أدوات جلب المتصفح، الذي يشمل نحو 3,500 نطاق إعلانات وتتبع معروف.+- **منع تسريب DNS**: دعم اختياري لـDNS-over-HTTPS لتوجيه استعلامات DNS عبر DoH من Cloudflare، ومنع تسريبها عند استخدام البروكسي.+- **متصفحات بعيدة**: اتصل بمتصفح يعمل بالفعل عبر CDP باستخدام `cdp_url`، سواء كان على جهازك أو جهاز آخر أو لدى مزود متصفحات، بدلًا من تشغيل متصفح محلي. ويمكنك استخدام نسخة Chromium الخاصة بك مع أي أداة جلب متصفح عبر `executable_path`.+- **حفظ ردود API في الخلفية**: فعّل `record_requests=True` في جلسة المتصفح، ثم ابحث في الردود المحفوظة عبر `session.network.search(limit=None)`. اقرأ بيانات API وأخطاء HTTP عبر عمليات تحميل الصفحات دون إعادة الطلبات. للسجل حد أقصى، ويحفظ محتوى الردود النصية.+- **الدعم غير المتزامن**: دعم كامل في كل أدوات الجلب، مع فئات جلسات مخصصة للعمل غير المتزامن.++### تحليل الصفحات واستخراج البيانات {#parsing-and-data-extraction}+- 🔄 **تتبع ذكي للعناصر**: اعثر على العناصر بعد تغير الموقع باستخدام خوارزميات مقارنة التشابه.+- 🎯 **اختيار مرن للعناصر**: محددات CSS وXPath، والبحث بالشروط أو بالنص أو بالتعبيرات المنتظمة، والمزيد.+- 🔍 **العثور على العناصر المتشابهة**: ابحث تلقائيًا عن عناصر تشبه العناصر التي وجدتها.++### ميزات الذكاء الاصطناعي {#ai-features}+- 🤖 **خادم MCP**: يتيح لوكلاء ومساعدي الذكاء الاصطناعي، مثل Claude وCursor، جمع البيانات عبر Scrapling باستخدام طلبات HTTP، والتفاعل مع المتصفح، ولقطات الشاشة، وحالة تسجيل دخول محفوظة، وردود API في الخلفية. يستخدم متصفحنا الخفي مع أدوات تساعد النماذج المناسبة على تجاوز CAPTCHA أثناء العمل، إلى جانب أداة حل Cloudflare. ويقلل المحتوى المرسل إلى النموذج، ويحظر الإعلانات، ويحميه من حقن التعليمات Prompt Injection. يدعم أيضًا المتصفحات البعيدة عبر CDP والاتصال عبر HTTP مع خيارات المصادقة. ([فيديو توضيحي](https://www.youtube.com/watch?v=qyFk3ZNwOxE))+- 🧠 **Agent Skill**: [مهارة جاهزة للتثبيت](ai/agent-skill.md) تعرّف وكلاء البرمجة على المكتبة كاملة، ليكتبوا كودًا يطابق واجهتها الحالية بدلًا من التخمين.+- 📚 **Markdown جاهز لأنظمة RAG**: حوّل أي صفحة إلى Markdown نظيف ومنقّى وجاهز لنماذج اللغة بسطر واحد (`page.markdown()`)، أو اجمع موقعًا كاملًا في مجموعة ملفات Markdown باستخدام قالب `ContentSpider`، دون الحاجة إلى نموذج لغة أثناء العملية. ([التوثيق](ai/building-rag-systems.md))++### أداء عالٍ وتصميم مجرّب {#high-performance-battle-tested-architecture}+- 🚀 **سرعة عالية**: أداء محسّن يتفوق على معظم مكتبات جمع بيانات الويب في Python.+- 🔋 **استهلاك قليل للذاكرة**: هياكل بيانات محسّنة وتحميل عند الحاجة لتقليل استخدام الذاكرة.+- ⚡ **تحويل سريع إلى JSON**: أسرع بعشر مرات من المكتبة القياسية.+- 🏗️ **مجرّب عمليًا**: تغطي الاختبارات 92% من Scrapling، وتوجد تلميحات أنواع للكود كله. كما استخدمه مئات العاملين في جمع بيانات الويب يوميًا خلال العام الماضي.++### تجربة مناسبة للمطورين وجمع البيانات {#developerweb-scraper-friendly-experience}+- 🎯 **واجهة تفاعلية لجمع البيانات**: واجهة IPython اختيارية مدمجة مع Scrapling، واختصارات وأدوات تسرّع كتابة البرامج، مثل تحويل طلبات curl إلى طلبات Scrapling وعرض نتائج الطلبات في المتصفح.+- 🚀 **استخدام مباشر من الطرفية**: يمكنك جمع بيانات رابط دون كتابة أي كود.+- 🛠️ **طرق كثيرة للتنقل**: تنقل في شجرة DOM بين الآباء والأشقاء والأبناء.+- 🧬 **معالجة نصوص محسّنة**: تعبيرات منتظمة وطرق لتنظيف النص وعمليات نصية محسّنة مدمجة.+- 📝 **إنشاء محددات تلقائيًا**: أنشئ محددات CSS وXPath موثوقة لأي عنصر.+- 🔌 **واجهة مألوفة**: تشبه Scrapy وBeautifulSoup، وتستخدم pseudo-elements نفسها الموجودة في Scrapy وParsel.+- 🤝 **تكامل مباشر مع Scrapy**: إذا كنت تستخدم Scrapy، أضف decorator باسم `scrapling_response` إلى أي callback لتحليل الردود التي تجلبها بالفعل بمحلّل Scrapling، دون إعادة كتابة البرنامج.+- 📘 **تلميحات أنواع كاملة**: دعم جيد لمحرر الكود والإكمال التلقائي. يُفحص الكود كله تلقائيًا باستخدام **PyRight** و**MyPy** مع كل تغيير.+- 🔋 **صورة Docker جاهزة**: تُبنى صورة Docker تحتوي كل المتصفحات وتُنشر تلقائيًا مع كل إصدار.+++## تاريخ النجوم {#star-history}+زاد عدد نجوم Scrapling على GitHub باستمرار منذ إصداره، كما يوضح الرسم التالي.++<div id="chartContainer">+ <a href="https://github.com/D4Vinci/Scrapling">+ <img id="chartImage" alt="رسم تاريخ النجوم" loading="lazy" src="https://api.star-history.com/svg?repos=D4Vinci/Scrapling&type=Date" height="400"/>+ </a>+</div>++<script>+const observer = new MutationObserver((mutations) => {+ mutations.forEach((mutation) => {+ if (mutation.attributeName === 'data-md-color-media') {+ const colorMedia = document.body.getAttribute('data-md-color-media');+ const isDarkScheme = document.body.getAttribute('data-md-color-scheme') === 'slate';+ const chartImg = document.querySelector('#chartImage');+ const baseUrl = 'https://api.star-history.com/svg?repos=D4Vinci/Scrapling&type=Date';++ if (colorMedia === '(prefers-color-scheme)' ? isDarkScheme : colorMedia.includes('dark')) {+ chartImg.src = `${baseUrl}&theme=dark`;+ } else {+ chartImg.src = baseUrl;+ }+ }+ });+});++observer.observe(document.body, {+ attributes: true,+ attributeFilter: ['data-md-color-media', 'data-md-color-scheme']+});+</script>+++## التثبيت {#installation}+يتطلب Scrapling إصدار Python 3.10 أو أحدث:++```bash+pip install scrapling+```++!!! warning "تنبيه"++ يثبّت هذا الأمر محلّل الصفحات ومتطلباته فقط، دون أدوات الجلب أو متطلبات سطر الأوامر. لذلك فإن استيراد أي شيء من `scrapling.fetchers` أو `scrapling.spiders`، كما في الأمثلة السابقة، سيؤدي إلى `ModuleNotFoundError` إذا اكتفيت بهذا التثبيت. لاستخدام أدوات الجلب أو Spiders، ثبّت متطلبات أدوات الجلب أولًا كما يلي.++### المتطلبات الاختيارية {#optional-dependencies}++1. إذا أردت استخدام أي من الميزات الإضافية التالية أو أدوات الجلب أو فئاتها، ثبّت متطلبات أدوات الجلب والمتصفحات كما يلي:+ ```bash+ pip install "scrapling[fetchers]"++ scrapling install # normal install+ scrapling install --force # force reinstall+ ```++ ينزّل هذا كل المتصفحات، ومتطلبات النظام، ومتطلبات تعديل بصمات المتصفح.++ ويمكنك تثبيتها من الكود بدلًا من تشغيل أمر:+ ```python+ from scrapling.cli import install++ install([], standalone_mode=False) # normal install+ install(["--force"], standalone_mode=False) # force reinstall+ ```++2. الميزات الإضافية:+++ - تثبيت خادم MCP:+ ```bash+ pip install "scrapling[ai]"+ ```+ - تثبيت متطلبات [بناء أنظمة RAG](ai/building-rag-systems.md):+ ```bash+ pip install "scrapling[rag]"+ ```+ - تثبيت أدوات الطرفية، أي الواجهة التفاعلية وأمر `extract`:+ ```bash+ pip install "scrapling[shell]"+ ```+ - تثبيت كل الميزات:+ ```bash+ pip install "scrapling[all]"+ ```+ شغّل `scrapling install` عندما تحتاج إلى أدوات جلب المتصفح. لا تتطلب طلبات HTTP تثبيت متصفح.++### Docker {#docker}+يمكنك أيضًا تنزيل صورة Docker تحتوي كل الإضافات والمتصفحات من DockerHub بالأمر التالي:+```bash+docker pull pyd4vinci/scrapling+```+أو تنزيلها من سجل GitHub:+```bash+docker pull ghcr.io/d4vinci/scrapling:latest+```+تُبنى هذه الصورة وتُنشر تلقائيًا باستخدام GitHub Actions والفرع الرئيسي للمستودع.++## تنظيم التوثيق {#how-the-documentation-is-organized}+توثيق Scrapling واسع، لذلك نحاول اتباع [إطار Diátaxis للتوثيق](https://diataxis.fr/).++## الدعم {#support}++إذا أعجبك Scrapling وتريد دعم تطويره:++- ⭐ أضف نجمة إلى [مستودع GitHub](https://github.com/D4Vinci/Scrapling).+- 🚀 تابعنا على [Twitter](https://x.com/Scrapling_dev) وانضم إلى [خادم Discord](https://discord.gg/EMgGbDceNQ).+- 💝 يمكنك [رعاية المشروع أو شراء قهوة لي](donate.md). :wink:+- 🐛 أبلغ عن الأخطاء واقترح ميزات عبر [GitHub Issues](https://github.com/D4Vinci/Scrapling/issues).++## الترخيص {#license}++هذا المشروع مرخّص برخصة BSD-3. راجع ملف [LICENSE](https://github.com/D4Vinci/Scrapling/blob/main/LICENSE) للتفاصيل.diff --git a/docs/locales/ar/integrations/scrapy.md b/docs/locales/ar/integrations/scrapy.mdnew file mode 100644index 0000000..8fbdc03--- /dev/null+++ b/docs/locales/ar/integrations/scrapy.md@@ -0,0 +1,64 @@+---+title: "استخدم تحليل Scrapling داخل عنكبوت Scrapy"+description: "حوّل استجابات Scrapy إلى Scrapling أو أضف decorator إلى دالة callback. احتفظ بزاحف Scrapy واستخدم محددات Scrapling والتحليل التكيفي."+---++# دمج Scrapling مع Scrapy {#integrating-scrapling-into-scrapy}++إذا كان لديك مشروع Scrapy، فلا تحتاج إلى إعادة كتابته للاستفادة من API التحليل في Scrapling. يحوّل تكامل Scrapy الاستجابات إلى كائنات [Response](../fetching/choosing.md#response-object) من Scrapling مباشرة داخل دوال callback في العنكبوت. بذلك يستمر Scrapy في إدارة الزحف، بينما تتولى Scrapling التحليل.++!!! note "التثبيت"++ يعمل هذا التكامل مع التثبيت الأساسي لـ Scrapling، أي `pip install scrapling`، دون متطلبات إضافية. يحتاج فقط إلى تثبيت Scrapy، وهو موجود بالفعل في مشروع Scrapy.++## الاستخدام {#usage}++أضف decorator باسم `scrapling_response` إلى أي دالة callback في العنكبوت، وسيصبح المعامل `response` الذي تستقبله كائن `Response` من Scrapling:++```python+import scrapy+from scrapling.integrations.scrapy import scrapling_response+++class QuotesSpider(scrapy.Spider):+ name = "quotes"+ start_urls = ["https://quotes.toscrape.com"]++ @scrapling_response+ def parse(self, response): # `response` is now a Scrapling Response+ first_quote = response.find_by_text("The world as we have created it", partial=True)+ for quote in [first_quote, *first_quote.find_similar()]:+ card = quote.parent+ yield {+ "text": quote.get_all_text(strip=True),+ "author": card.find("small", class_="author").text,+ "tags": [tag.text for tag in card.find_all("a", class_="tag")],+ }+ next_page = response.css("li.next a::attr(href)").get()+ if next_page:+ yield scrapy.Request(response.urljoin(next_page), callback=self.parse)+```++يعمل هذا الـ decorator مع جميع أنواع callback التي يدعمها Scrapy: الدوال العادية، والمولّدات، وcoroutines، والمولّدات غير المتزامنة. ويحتفظ الغلاف بنوع الدالة واسمها وdocstring الخاصة بها، فتظل آليات فحص دوال callback وعقود اختبارها في Scrapy تعمل.++يمكنك أيضًا تمرير إعدادات [Selector](../parsing/main_classes.md#selector) إلى الـ decorator، وستُمرّر إلى كائن `Response` الناتج:++```python+ @scrapling_response(adaptive=True, keep_comments=True)+ def parse_product(self, response):+ ...+```++إذا كان لديك كائن استجابة من Scrapy خارج دالة callback، مثل middleware أو pipeline، فاستخدم دالة التحويل مباشرة:++```python+from scrapling.integrations.scrapy import convert_response++scrapling_response = convert_response(scrapy_response, keep_comments=False)+```++## ملاحظات {#notes}++- أرجع طلبات الصفحات التالية باستخدام yield مع `scrapy.Request(response.urljoin(href))` كما في المثال أعلاه. تنشئ دالة `Response.follow()` في Scrapling طلبات خاصة بـ [نظام عناكب Scrapling](../spiders/getting-started.md)، ولا يفهمها Scrapy.+- يُنسخ قاموس `meta` في الاستجابة نسخًا سطحيًا، لذلك تظل الكائنات التي خزّنها middleware آخر متاحة. مثلًا، عند استخدام `scrapy-playwright`، تظل الصفحة موجودة في `response.meta["playwright_page"]`.+- تُقرأ cookies من ترويسات `Set-Cookie` الخام وتُضاف إلى قاموس `cookies` في الاستجابة.diff --git a/docs/locales/ar/overview.md b/docs/locales/ar/overview.mdnew file mode 100644index 0000000..17c1f65--- /dev/null+++ b/docs/locales/ar/overview.md@@ -0,0 +1,341 @@+---+title: "نظرة على Scrapling: تحليل الصفحات وطلبات HTTP والمتصفحات الخفية"+description: "تعرّف على تحليل الصفحات وجلبها في Scrapling، مع أمثلة على CSS وXPath والبحث في النص وطلبات HTTP والمتصفحات الخفية."+---++# ابدأ مع Scrapling {#get-started-with-scrapling}++## اختر نقطة البداية {#pick-your-path}++لا تعرف من أين تبدأ؟ اختر ما يناسب ما تريد عمله:++| أريد أن... | ابدأ هنا |+|---:|---:|+| **أحلّل HTML** موجودًا لدي | [البحث عن العناصر](parsing/selection.md): الاختيار باستخدام CSS وXPath والنص |+| **أجمع بيانات صفحة بسرعة** وأجرّب فكرة | اختر [أداة جلب](fetching/choosing.md) وابدأ التجربة، أو شغّل [الواجهة التفاعلية](cli/interactive-shell.md) |+| **أبني برنامج زحف** يمكن توسيعه | [Spiders](spiders/getting-started.md): زحف متزامن بعدة جلسات، مع الإيقاف والاستئناف |+| **أجمع البيانات دون كتابة كود** | [أوامر الاستخراج من الطرفية](cli/extract-commands.md)، أو اربط [خادم MCP](ai/mcp-server.md) بأداة الذكاء الاصطناعي المفضلة لديك |+| **أنتقل** من مكتبة أخرى | [الانتقال من BeautifulSoup](tutorials/migrating_from_beautifulsoup.md) أو [المقارنة مع Scrapy](spiders/architecture.md#comparison-with-scrapy) |++---++سنبدأ بنظرة سريعة على أدوات تحليل الصفحات. ثم سنجلب المواقع باستخدام متصفحات مخصصة، ونرسل الطلبات، ونحلّل الردود.++سنستخدم مستند HTML التالي، الذي أنشأه ChatGPT، في أمثلة هذه الصفحة:+```python+html_doc = """<html>+ <head>+ <title>Complex Web Page</title>+ <style>+ .hidden { display: none; }+ </style>+ </head>+ <body>+ <header>+ <nav>+ <ul>+ <li> <a href="#home">Home</a> </li>+ <li> <a href="#about">About</a> </li>+ <li> <a href="#contact">Contact</a> </li>+ </ul>+ </nav>+ </header>+ <main>+ <section id="products" schema='{"jsonable": "data"}'>+ <h2>Products</h2>+ <div class="product-list">+ <article class="product" data-id="1">+ <h3>Product 1</h3>+ <p class="description">This is product 1</p>+ <span class="price">$10.99</span>+ <div class="hidden stock">In stock: 5</div>+ </article>++ <article class="product" data-id="2">+ <h3>Product 2</h3>+ <p class="description">This is product 2</p>+ <span class="price">$20.99</span>+ <div class="hidden stock">In stock: 3</div>+ </article>++ <article class="product" data-id="3">+ <h3>Product 3</h3>+ <p class="description">This is product 3</p>+ <span class="price">$15.99</span>+ <div class="hidden stock">Out of stock</div>+ </article>+ </div>+ </section>++ <section id="reviews">+ <h2>Customer Reviews</h2>+ <div class="review-list">+ <div class="review" data-rating="5">+ <p class="review-text">Great product!</p>+ <span class="reviewer">John Doe</span>+ </div>+ <div class="review" data-rating="4">+ <p class="review-text">Good value for money.</p>+ <span class="reviewer">Jane Smith</span>+ </div>+ </div>+ </section>+ </main>+ <script id="page-data" type="application/json">+ {+ "lastUpdated": "2024-09-22T10:30:00Z",+ "totalProducts": 3+ }+ </script>+ </body>+</html>"""+```+ابدأ بتحميل HTML السابق بهذه الطريقة:+```python+import re+from scrapling.parser import Selector+page = Selector(html_doc)+page # <data='<html><head><title>Complex Web Page</tit...'>+```+احصل على كل النص في الصفحة، بما فيه نص العناصر المتداخلة:+```python+page.get_all_text(ignore_tags=('script', 'style'))+# 'Complex Web Page\nHome\nAbout\nContact\nProducts\nProduct 1\nThis is product 1\n$10.99\nIn stock: 5\nProduct 2\nThis is product 2\n$20.99\nIn stock: 3\nProduct 3\nThis is product 3\n$15.99\nOut of stock\nCustomer Reviews\nGreat product!\nJohn Doe\nGood value for money.\nJane Smith'+```++## البحث عن العناصر {#finding-elements}+إذا أردت الوصول إلى عنصر في الصفحة، فستجد طريقة للوصول إليه. يمكنك الجمع بين طرق البحث كما تحتاج.++ابحث عن أول عنصر HTML من نوع `section`:+```python+section_element = page.find('section')+# <data='<section id="products" schema='{"jsonabl...' parent='<main><section id="products" schema='{"j...'>+```+ابحث عن كل عناصر `section`:+```python+section_elements = page.find_all('section')+# [<data='<section id="products" schema='{"jsonabl...' parent='<main><section id="products" schema='{"j...'>, <data='<section id="reviews"><h2>Customer Revie...' parent='<main><section id="products" schema='{"j...'>]+```+ابحث عن كل عناصر `section` التي تساوي فيها قيمة الخاصية `id` النص `products`:+```python+section_elements = page.find_all('section', {'id':"products"})+# Same as+section_elements = page.find_all('section', id="products")+# [<data='<section id="products" schema='{"jsonabl...' parent='<main><section id="products" schema='{"j...'>]+```+ابحث عن كل عناصر `section` التي تحتوي فيها قيمة الخاصية `id` على النص `product`:+```python+section_elements = page.find_all('section', {'id*':"product"})+```+ابحث عن كل عناصر `h3` التي يطابق نصها التعبير المنتظم `Product \d`:+```python+page.find_all('h3', re.compile(r'Product \d'))+# [<data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>, <data='<h3>Product 2</h3>' parent='<article class="product" data-id="2"><h3...'>, <data='<h3>Product 3</h3>' parent='<article class="product" data-id="3"><h3...'>]+```+ابحث عن كل عناصر `h3` و`h2` التي يطابق نصها التعبير المنتظم `Product` فقط:+```python+page.find_all(['h3', 'h2'], re.compile(r'Product'))+# [<data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>, <data='<h3>Product 2</h3>' parent='<article class="product" data-id="2"><h3...'>, <data='<h3>Product 3</h3>' parent='<article class="product" data-id="3"><h3...'>, <data='<h2>Products</h2>' parent='<section id="products" schema='{"jsonabl...'>]+```+ابحث عن كل العناصر التي يساوي نصها `Products` بالضبط، دون احتساب المسافات البيضاء:+```python+page.find_by_text('Products', first_match=False)+# [<data='<h2>Products</h2>' parent='<section id="products" schema='{"jsonabl...'>]+```+أو ابحث عن كل العناصر التي يطابق نصها التعبير المنتظم `Product \d`:+```python+page.find_by_regex(r'Product \d', first_match=False)+# [<data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>, <data='<h3>Product 2</h3>' parent='<article class="product" data-id="2"><h3...'>, <data='<h3>Product 3</h3>' parent='<article class="product" data-id="3"><h3...'>]+```+ابحث عن كل العناصر المشابهة للعنصر الذي تريده:+```python+target_element = page.find_by_regex(r'Product \d', first_match=True)+# <data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>+target_element.find_similar()+# [<data='<h3>Product 2</h3>' parent='<article class="product" data-id="2"><h3...'>, <data='<h3>Product 3</h3>' parent='<article class="product" data-id="3"><h3...'>]+```+ابحث عن أول عنصر يطابق محدد CSS:+```python+page.css('.product-list [data-id="1"]')[0]+# <data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>+```+ابحث عن كل العناصر التي تطابق محدد CSS:+```python+page.css('.product-list article')+# [<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>, <data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>, <data='<article class="product" data-id="3"><h3...' parent='<div class="product-list"> <article clas...'>]+```+ابحث عن أول عنصر يطابق محدد XPath:+```python+page.xpath("//*[@id='products']/div/article")[0]+# <data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>+```+ابحث عن كل العناصر التي تطابق محدد XPath:+```python+page.xpath("//*[@id='products']/div/article")+# [<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>, <data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>, <data='<article class="product" data-id="3"><h3...' parent='<div class="product-list"> <article clas...'>]+```++هذه بداية بسيطة فقط. سنعرض لاحقًا خيارات أكثر تقدمًا لطرق البحث هذه.+## الوصول إلى بيانات العناصر {#accessing-elements-data}+الأمر بهذه البساطة:+```pycon+>>> section_element.tag+'section'+>>> print(section_element.attrib)+{'id': 'products', 'schema': '{"jsonable": "data"}'}+>>> section_element.attrib['schema'].json() # If an attribute value can be converted to json, then use `.json()` to convert it+{'jsonable': 'data'}+>>> section_element.text # Direct text content+''+>>> section_element.get_all_text() # All text content recursively+'Products\nProduct 1\nThis is product 1\n$10.99\nIn stock: 5\nProduct 2\nThis is product 2\n$20.99\nIn stock: 3\nProduct 3\nThis is product 3\n$15.99\nOut of stock'+>>> section_element.html_content # The HTML content of the element+'<section id="products" schema=\'{"jsonable": "data"}\'><h2>Products</h2>\n <div class="product-list">\n <article class="product" data-id="1"><h3>Product 1</h3>\n <p class="description">This is product 1</p>\n <span class="price">$10.99</span>\n <div class="hidden stock">In stock: 5</div>\n </article><article class="product" data-id="2"><h3>Product 2</h3>\n <p class="description">This is product 2</p>\n <span class="price">$20.99</span>\n <div class="hidden stock">In stock: 3</div>\n </article><article class="product" data-id="3"><h3>Product 3</h3>\n <p class="description">This is product 3</p>\n <span class="price">$15.99</span>\n <div class="hidden stock">Out of stock</div>\n </article></div>\n </section>'+>>> print(section_element.prettify()) # The prettified version+'''+<section id="products" schema='{"jsonable": "data"}'><h2>Products</h2>+ <div class="product-list">+ <article class="product" data-id="1"><h3>Product 1</h3>+ <p class="description">This is product 1</p>+ <span class="price">$10.99</span>+ <div class="hidden stock">In stock: 5</div>+ </article><article class="product" data-id="2"><h3>Product 2</h3>+ <p class="description">This is product 2</p>+ <span class="price">$20.99</span>+ <div class="hidden stock">In stock: 3</div>+ </article><article class="product" data-id="3"><h3>Product 3</h3>+ <p class="description">This is product 3</p>+ <span class="price">$15.99</span>+ <div class="hidden stock">Out of stock</div>+ </article>+ </div>+</section>+'''+>>> section_element.path # All the ancestors in the DOM tree of this element+[<data='<main><section id="products" schema='{"j...' parent='<body> <header><nav><ul><li> <a href="#h...'>,+ <data='<body> <header><nav><ul><li> <a href="#h...' parent='<html><head><title>Complex Web Page</tit...'>,+ <data='<html><head><title>Complex Web Page</tit...'>]+>>> section_element.generate_css_selector+'#products'+>>> section_element.generate_full_css_selector+'body > main > #products'+>>> section_element.generate_xpath_selector+"//*[@id='products']"+>>> section_element.generate_full_xpath_selector+"//body/main/*[@id='products']"+```++## التنقل بين العناصر {#navigation}+نستخدم هنا العناصر التي وجدناها في الأمثلة السابقة:++```pycon+>>> section_element.parent+<data='<main><section id="products" schema='{"j...' parent='<body> <header><nav><ul><li> <a href="#h...'>+>>> section_element.parent.tag+'main'+>>> section_element.parent.parent.tag+'body'+>>> section_element.children+[<data='<h2>Products</h2>' parent='<section id="products" schema='{"jsonabl...'>,+ <data='<div class="product-list"> <article clas...' parent='<section id="products" schema='{"jsonabl...'>]+>>> section_element.siblings+[<data='<section id="reviews"><h2>Customer Revie...' parent='<main><section id="products" schema='{"j...'>]+>>> section_element.next # gets the next element, the same logic applies to `quote.previous`.+<data='<section id="reviews"><h2>Customer Revie...' parent='<main><section id="products" schema='{"j...'>+>>> section_element.children.css('h2::text').getall()+['Products']+>>> page.css('[data-id="1"]')[0].has_class('product')+True+```+إذا احتجت إلى أكثر من العنصر الأب المباشر، يمكنك المرور على كل أسلاف العنصر في شجرة DOM، كما يلي:+```python+for ancestor in section_element.iterancestors():+ print(ancestor.tag)+```+يمكنك البحث عن سلف محدد يحقق شرطًا. مرّر دالة تستقبل كائن `Selector` وتعيد `True` عند تحقق الشرط، أو `False` خلاف ذلك:+```pycon+>>> section_element.find_ancestor(lambda ancestor: ancestor.css('nav'))+<data='<body> <header><nav><ul><li> <a href="#h...' parent='<html><head><title>Complex Web Page</tit...'>+```++## جلب المواقع {#fetching-websites}+بدلًا من تمرير HTML مباشرة إلى Scrapling، يمكنك جلب رد الموقع عبر طلب HTTP أو تحميله في متصفح.++توجد أداة جلب تناسب كل حالة استخدام.++### طلبات HTTP {#http-requests}+لإرسال طلبات HTTP بسيطة، استورد فئة `Fetcher` واستخدمها كما يلي:+```python+from scrapling.fetchers import Fetcher+page = Fetcher.get('https://scrapling.requestcatcher.com/get', impersonate="chrome")+```+وهكذا تستخدم طرق HTTP المختلفة:+```python+from scrapling.fetchers import Fetcher+page = Fetcher.get('https://scrapling.requestcatcher.com/get', stealthy_headers=True)+page = Fetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, proxy='http://username:password@localhost:8030')+page = Fetcher.put('https://scrapling.requestcatcher.com/put', data={'key': 'value'})+page = Fetcher.delete('https://scrapling.requestcatcher.com/delete')+```+للطلبات غير المتزامنة، استبدل الاستيراد كما يلي:+```python+from scrapling.fetchers import AsyncFetcher+page = await AsyncFetcher.get('https://scrapling.requestcatcher.com/get', stealthy_headers=True)+page = await AsyncFetcher.post('https://scrapling.requestcatcher.com/post', data={'key': 'value'}, proxy='http://username:password@localhost:8030')+page = await AsyncFetcher.put('https://scrapling.requestcatcher.com/put', data={'key': 'value'})+page = await AsyncFetcher.delete('https://scrapling.requestcatcher.com/delete')+```++!!! note "ملاحظات:"++ 1. عند تفعيل `stealthy_headers`، تُنشأ ترويسات متصفح حقيقية وتُستخدم في الطلبات، بما فيها ترويسة referer من Google. هذا الخيار مفعّل افتراضيًا.+ 2. يتيح لك `impersonate` محاكاة بصمة TLS لإصدار محدد من المتصفح.+ 3. عند تفعيل `http3`، تستخدم أداة الجلب HTTP/3 في الطلبات، فتبدو الطلبات أقرب إلى طلبات المتصفح الحقيقي.++هذه بعض قدرات أداة الجلب فقط. اقرأ بقية التفاصيل [هنا](fetching/static.md).++### التحميل الديناميكي {#dynamic-loading}+يمكنك أيضًا التعامل مع المواقع الديناميكية، وهي شائعة اليوم.++توفر فئة `StealthyFetcher` خيارات كثيرة لجلب صفحات الويب وتحميلها باستخدام متصفحات مبنية على Chromium.+```python+from scrapling.fetchers import StealthyFetcher+page = StealthyFetcher.fetch('https://quotes.toscrape.com/js/', disable_resources=True, block_ads=True, wait_selector='.quote')+print(len(page.css(".quote"))) # -> 10++# The async version of fetch+page = await StealthyFetcher.async_fetch('https://quotes.toscrape.com/js/', disable_resources=True, block_ads=True, wait_selector='.quote')+print(len(page.css(".quote"))) # -> 10+```+تعتمد على [Playwright](https://playwright.dev/python/) مع تعديلات لإخفاء الأتمتة. استخدم Chromium المرفق، أو Google Chrome المثبّت لديك مع `real_chrome=True`، أو متصفحًا يعمل بالفعل عبر `cdp_url`.++### تجاوز أنظمة كشف البوتات {#anti-bot-features}++من بين ما توفره:++1. تجاوز أنواع Cloudflare Turnstile وInterstitial تلقائيًا باستخدام `solve_cloudflare=True`.+2. منع تسريبات بيئة تشغيل CDP وتسريبات WebRTC.+3. عزل تنفيذ JavaScript، وإزالة كثير من بصمات Playwright، وتجنب بعض السلوكيات المعروفة التي تكشف البوتات.+4. إضافة تشويش إلى canvas لمنع استخدامه في تكوين بصمة للمتصفح.+5. تعديل الطرق المعروفة لكشف وضع المتصفح بلا واجهة تلقائيًا، مع خيار لتجنب الكشف بسبب اختلاف المنطقة الزمنية.+6. وخيارات أخرى لتجاوز أنظمة الحماية...++```python+from scrapling.fetchers import StealthyFetcher+page = StealthyFetcher.fetch('https://www.browserscan.net/bot-detection') # Running headless by default+page.status == 200 # -> True++page = StealthyFetcher.fetch('https://nopecha.com/demo/cloudflare', solve_cloudflare=True) # Solve Cloudflare captcha automatically if presented+page.status == 200 # -> True++page = StealthyFetcher.fetch('https://www.browserscan.net/bot-detection', block_webrtc=True, hide_canvas=True, dns_over_https=True) # and the rest of arguments...+# The async version of fetch+page = await StealthyFetcher.async_fetch('https://www.browserscan.net/bot-detection')+page.status == 200 # -> True+```++هذه أيضًا بعض القدرات فقط. اقرأ [هذه الصفحة](fetching/stealthy.md) لكل التفاصيل والقائمة الكاملة للخيارات.++---++هذه نظرة سريعة على Scrapling. تابع إلى القسم التالي لمعرفة المزيد.diff --git a/docs/locales/ar/parsing/adaptive.md b/docs/locales/ar/parsing/adaptive.mdnew file mode 100644index 0000000..7a70720--- /dev/null+++ b/docs/locales/ar/parsing/adaptive.md@@ -0,0 +1,232 @@+---+title: "تتبع عناصر HTML والعثور عليها بعد تغير الصفحة"+description: "احفظ تفاصيل العناصر واعثر عليها بعد تغير HTML. تعرّف على تفعيل التحليل التكيفي واستخدام save وretrieve وrelocate."+---++# جمع البيانات مع تغيّر الصفحة {#adaptive-scraping}++!!! success "قبل البدء"++ 1. اقرأ صفحة [البحث عن العناصر](../parsing/selection.md) لتعرف كيف تجد العناصر وتستخرجها من كائن [Selector](../parsing/main_classes.md#selector).+ 2. اقرأ صفحة [الفئات الأساسية](../parsing/main_classes.md) لتفهم فئة [Selector](../parsing/main_classes.md#selector).++التحليل التكيفي Adaptive scraping، المعروف سابقًا باسم automatch، من أقوى ميزات Scrapling. يساعد برنامجك على الاستمرار بعد تغيّر الموقع، بتتبع العناصر والعثور على أماكنها الجديدة.++لنفترض أنك تجمع بيانات صفحة بهذا الشكل:+```html+<div class="container">+ <section class="products">+ <article class="product" id="p1">+ <h3>Product 1</h3>+ <p class="description">Description 1</p>+ </article>+ <article class="product" id="p2">+ <h3>Product 2</h3>+ <p class="description">Description 2</p>+ </article>+ </section>+</div>+```+وتريد جمع بيانات المنتج الأول، الذي يحمل المعرّف `p1`. غالبًا ستكتب محددًا مثل هذا:+```python+page.css('#p1')+```+إذا غيّر أصحاب الموقع بنية الصفحة إلى الشكل التالي:+```html+<div class="new-container">+ <div class="product-wrapper">+ <section class="products">+ <article class="product new-class" data-id="p1">+ <div class="product-info">+ <h3>Product 1</h3>+ <p class="new-description">Description 1</p>+ </div>+ </article>+ <article class="product new-class" data-id="p2">+ <div class="product-info">+ <h3>Product 2</h3>+ <p class="new-description">Description 2</p>+ </div>+ </article>+ </section>+ </div>+</div>+```+فلن يعمل المحدد بعد ذلك، وسيحتاج الكود إلى تعديل. هنا تأتي فائدة `adaptive` في Scrapling.++فعّل `adaptive` عند اختيار العنصر أول مرة. وعندما تبحث عنه لاحقًا ولا تجده، يتذكر Scrapling خصائصه ويبحث في الموقع عن العنصر الأعلى تشابهًا معه، دون ذكاء اصطناعي :)++```python+from scrapling import Selector, Fetcher+# Before the change+page = Selector(page_source, adaptive=True, url='example.com')+# or+Fetcher.adaptive = True+page = Fetcher.get('https://example.com')+# then+element = page.css('#p1', auto_save=True)+if not element: # One day website changes?+ element = page.css('#p1', adaptive=True) # Scrapling still finds it!+# the rest of your code...+```+سأعرض مثالًا أولًا، ثم أشرح طريقة الاستخدام والتفاصيل. تعمل هذه الميزة مع كل طرق اختيار العناصر، وليس CSS وXPath فقط.++## مثال من موقع حقيقي {#real-world-scenario}+لنستخدم موقعًا حقيقيًا ونجلب مصدره بأحد أدوات الجلب. نحتاج إلى موقع سيتغير تصميمه أو بنيته قريبًا، لننسخ المصدر ثم ننتظر التغيير. يصعب معرفة ذلك ما لم أكن أعرف صاحب الموقع، لكن هذا سيجعل الاختبار مُعدًّا مسبقًا، ههه.++لحل ذلك سأستخدم [Wayback Machine](https://web.archive.org/) من [The Web Archive](https://archive.org/). هذه نسخة من [موقع StackOverflow في 2010](https://web.archive.org/web/20100102003420/http://stackoverflow.com/)، قديمة فعلًا!<br/>لنرَ هل تستطيع ميزة adaptive استخراج الزر نفسه من تصميم 2010 والتصميم الحالي بالمحدد نفسه :)++لاستخراج زر Questions من التصميم القديم، يمكنني استخدام `#hmenus > div:nth-child(1) > ul > li:nth-child(1) > a`. هذا المحدد شديد التحديد لأن Google Chrome أنشأه.+++لنجرّب المحدد نفسه مع النسختين:+```python+from scrapling import Fetcher+selector = '#hmenus > div:nth-child(1) > ul > li:nth-child(1) > a'+old_url = "https://web.archive.org/web/20100102003420/http://stackoverflow.com/"+new_url = "https://stackoverflow.com/"+Fetcher.configure(adaptive = True, adaptive_domain='stackoverflow.com')+page = Fetcher.get(old_url, timeout=30)+element1 = page.css(selector, auto_save=True)[0]+# Same selector but used in the updated website+page = Fetcher.get(new_url)+element2 = page.css(selector, adaptive=True)[0]++if element1.text == element2.text:+ print('Scrapling found the same element in the old and new designs!') # Spoiler alert: it does!+```+لاحظ الخيار الجديد `adaptive_domain`. يرى Scrapling أن `archive.org` و`stackoverflow.com` نطاقان مختلفان، ولذلك يفصل بيانات `adaptive` بينهما. لنعلمه أنهما الموقع نفسه، نمرّر نطاقًا مخصصًا يُستخدم عند حفظ بيانات الاثنين، فلا يفصلها.++في الاستخدام الفعلي، سيكون الكود نفسه لكن الطلبين يستخدمان الرابط نفسه، فلن تحتاج إلى `adaptive_domain`. هذا أقرب مثال عملي يمكنني تقديمه، وأتمنى أن يكون واضحًا :)++استخدمت `Selector` و`Fetcher` في المثالين السابقين لتوضيح أن طريقة عمل adaptive واحدة في الحالتين.++!!! info "معلومة"++ السبب الأساسي لإضافة `adaptive_domain` هو التعامل مع تغيّر رابط الموقع عند تغيّر تصميمه أو بنيته. يمكنك عندها متابعة استخدام بيانات adaptive المحفوظة مع الرابط الجديد. دون ذلك، سيعتبره Scrapling موقعًا جديدًا ولن يستخدم البيانات القديمة.++## كيف تعمل ميزة adaptive؟ {#how-the-adaptive-scraping-feature-works}+تعمل على مرحلتين:++1. **الحفظ**: تخزين الخصائص المميزة للعناصر.+2. **المطابقة**: البحث لاحقًا عن عناصر ذات خصائص مشابهة.++لنفترض أنك اخترت عنصرًا بأي طريقة، وتريد أن تعثر عليه المكتبة في المرة التالية، حتى لو تغير تصميم الموقع أو بنيته.++بأقل قدر من التفاصيل التقنية، تعمل الميزة كما يلي:++ 1. تطلب من Scrapling حفظ خصائص العنصر المميزة بإحدى الطرق التي سنعرضها لاحقًا.+ 2. يحفظ Scrapling هذه الخصائص في قاعدة البيانات المحددة، وهي SQLite افتراضيًا.+ 3. لأن صاحب الموقع قد يغير أو يزيل أي خاصية، فلا تصلح أي منها كمعرّف ثابت في قاعدة البيانات. لذلك يعتمد نظام التخزين على شيئين:+ 1. نطاق الموقع الحالي. مرّره عند إنشاء `Selector`، أو دع أداة الجلب تستخرجه من الرابط تلقائيًا.+ 2. معرّف `identifier` لاسترجاع خصائص العنصر من قاعدة البيانات. لا تحتاج دائمًا إلى تحديده بنفسك، وسنشرح ذلك لاحقًا.++ يُستخدم الاثنان معًا لاحقًا لاسترجاع الخصائص المميزة من قاعدة البيانات.++ 4. عندما تتغير بنية الموقع، فعّل `adaptive` واطلب من Scrapling العثور على العنصر. يسترجع خصائصه المحفوظة، ويقارن بها كل عناصر الصفحة، ثم يحسب درجة تشابه لكل عنصر. تأخذ المقارنة كل التفاصيل في الحسبان، كما سنرى.+ 5. تُعاد العناصر التي تحقق أعلى درجة تشابه مع العنصر المطلوب.++### الخصائص المميزة {#the-unique-properties}+قد تتساءل: ما الخصائص المميزة التي نعتمد عليها إذا كان يمكن تغيير كل خصائص العنصر أو إزالتها؟++يعتمد Scrapling على ما يلي:++- اسم وسم العنصر، ونصه، وخصائصه بأسمائها وقيمها، وأشقائه بأسماء وسومهم فقط، ومساره بأسماء الوسوم فقط.+- اسم وسم العنصر الأب، وخصائصه بأسمائها وقيمها، ونصه.++المقارنة لا تشترط التطابق الكامل، بل تقيس مدى التشابه. لذلك تأخذ كل شيء في الحسبان، حتى ترتيب القيم، مثل ترتيب أسماء class في العنصر قبل التغيير وبعده.++## استخدام ميزة adaptive {#how-to-use-adaptive-feature}+يمكن تطبيق الميزة على أي عنصر تجده. وتتوفر أيضًا كخيارات في دوال CSS وXPath كما رأيت، وسنعود إلى ذلك لاحقًا.++أولًا، فعّل الميزة بتمرير `adaptive=True` عند إنشاء [Selector](main_classes.md#selector)، أو فعّلها في أداة الجلب التي تستخدمها كما يلي.++أمثلة:+```python+from scrapling import Selector, Fetcher+page = Selector(html_doc, adaptive=True)+# OR+Fetcher.adaptive = True+page = Fetcher.get('https://example.com')+```+إذا كنت تستخدم [Selector](main_classes.md#selector)، مرّر رابط الموقع عبر `url` حتى يفصل Scrapling الخصائص المحفوظة للعناصر حسب النطاق.++إذا لم تمرّر رابطًا، تُستخدم الكلمة `default` مكانه عند حفظ الخصائص. يسبب ذلك مشكلة فقط إذا استخدمت المعرّف نفسه لاحقًا لموقع آخر، ولم تمرّر `url` عند إنشائه. تحل البيانات الجديدة محل القديمة عند الحفظ، وتستخدم `adaptive` آخر خصائص محفوظة فقط.++توجد أيضًا خيارات `storage` و`storage_args` للاتصال بقاعدة البيانات. تُستخدم فئة SQLite المرفقة بالمكتبة افتراضيًا. غالبًا لن تحتاج إلى تعديلها إلا إذا أردت كتابة نظام تخزين خاص بك، وهو ما نشرحه في [صفحة مستقلة بقسم التطوير](../development/adaptive_storage_system.md).++بعد تفعيل `adaptive` على المستوى العام، توجد طريقتان أساسيتان لاستخدامها.++### باستخدام CSS أو XPath {#the-cssxpath-selection-way}+كما رأيت، استخدم أولًا `auto_save` عند اختيار عنصر موجود في الصفحة:+```python+element = page.css('#p1', auto_save=True)+```+وعندما لا يعود العنصر موجودًا بالمحدد نفسه، استخدم `adaptive` لتبحث المكتبة عنه:+```python+element = page.css('#p1', adaptive=True)+```+بسيط، أليس كذلك؟++لكن هناك عمل يحدث في الخلفية. هل تتذكر المعرّف المطلوب لاسترجاع العنصر؟ في دالتي `css` و`xpath`، يُستخدم المحدد الذي مرّرته كمعرّف تلقائيًا لتسهيل الاستخدام :)++ويمكنك تمرير `identifier` إلى أي من هذه الدوال لتعيين المعرّف بنفسك. يفيد ذلك في بعض الحالات، كما يمكنك استخدامه عند الحفظ مع `auto_save`.++### الطريقة اليدوية {#the-manual-way}+يمكنك حفظ خصائص العنصر واسترجاعها، ثم العثور على مكانه الجديد يدويًا ضمن ميزة `adaptive`. تتيح هذه الطريقة إعادة العثور على أي عنصر، مهما كانت طريقة اختياره.++لنفترض أنك وجدت العنصر بالنص:+```python+element = page.find_by_text('Tipping the Velvet', first_match=True)+```+احفظ خصائصه المميزة باستخدام `save`، لكن يجب أن تحدد المعرّف بنفسك. اخترت هنا `my_special_element`، والأفضل استخدام معرّف واضح المعنى، مثل أسماء المتغيرات الواضحة :)+```python+page.save(element, 'my_special_element')+```+لاحقًا، استرجع الخصائص واعثر على العنصر داخل الصفحة باستخدام `adaptive` كما يلي:+```python+>>> element_dict = page.retrieve('my_special_element')+>>> page.relocate(element_dict, selector_type=True)+[<data='<a href="catalogue/tipping-the-velvet_99...' parent='<h3><a href="catalogue/tipping-the-velve...'>]+>>> page.relocate(element_dict, selector_type=True).css('::text').getall()+['Tipping the Velvet']+```+نستخدم هنا الدالتين `retrieve` و`relocate`.++إذا أردت إبقاء النتيجة ككائن `lxml.etree`، فلا تمرّر `selector_type`:+```python+>>> page.relocate(element_dict)+[<Element a at 0x105a2a7b0>]+```++## حل المشكلات {#troubleshooting}++### لم يُعثر على عناصر مطابقة {#no-matches-found}+```python+# 1. Check if data was saved+element_data = page.retrieve('identifier')+if not element_data:+ print("No data saved for this identifier")++# 2. Try with different identifier+products = page.css('.product', adaptive=True, identifier='old_selector')++# 3. Save again with new identifier+products = page.css('.new-product', auto_save=True, identifier='new_identifier')+```++### العثور على عناصر غير صحيحة {#wrong-elements-matched}+```python+# Use more specific selectors+products = page.css('.product-list .product', auto_save=True)++# Or save with more context+product = page.find_by_text('Product Name').parent+page.save(product, 'specific_product')+```++## مشكلات معروفة {#known-issues}+عند الحفظ باستخدام `adaptive`، تُحفظ خصائص أول عنصر فقط من نتائج الاختيار. لذلك إذا كان المحدد يختار عناصر مختلفة في مواضع أخرى من الصفحة، فقد تعيد `adaptive` العنصر الأول فقط عند البحث عنه لاحقًا. لا يشمل ذلك محددات CSS المجمعة بفواصل، لأن كل محدد منها يُفصل ويُنفّذ وحده.++## ملاحظات أخيرة {#final-thoughts}+شرح هذه الميزة بالتفصيل وببساطة كان صعبًا. إذا بقي شيء غير واضح، اسأل في [قسم النقاشات](https://github.com/D4Vinci/Scrapling/discussions)، وسأرد بأسرع ما يمكن. يمكنك أيضًا استخدام خادم Discord أو التواصل معي مباشرة :)diff --git a/docs/locales/ar/parsing/main_classes.md b/docs/locales/ar/parsing/main_classes.mdnew file mode 100644index 0000000..54c7faf--- /dev/null+++ b/docs/locales/ar/parsing/main_classes.md@@ -0,0 +1,575 @@+---+title: "Selector وSelectors في Scrapling: البيانات والتنقل"+description: "تعرّف على حفظ HTML والنص والخصائص في Selector وSelectors، واستخراج القيم وحل الروابط والتنقل بين الآباء والأبناء والأشقاء."+---++# الفئات الأساسية لتحليل الصفحات {#parsing-main-classes}++!!! success "قبل البدء"++ - اقرأ [البحث عن العناصر](../parsing/selection.md) لتعرف كيف تجد العناصر وتستخرجها من كائن [Selector](../parsing/main_classes.md#selector).++بعد استكشاف طرق اختيار العناصر وميزاتها في Scrapling، لنراجع فئة [Selector](#selector) والكائنات الأخرى لنفهم محلّل الصفحات بصورة أفضل.++فئة [Selector](#selector) هي أساس محلّل Scrapling، وتوفر تحليل HTML واختيار العناصر. يمكنك استيرادها بأي من الطريقتين:+```python+from scrapling import Selector+from scrapling.parser import Selector+```+ثم استخدمها مباشرة كما تعلمت في [النظرة العامة](../overview.md):+```python+page = Selector(+ '<html>...</html>',+ url='https://example.com'+)++# Then select elements as you like+elements = page.css('.product')+```+بعد تمرير HTML أو جلب موقع، يكون الكائن الأساسي الذي تتعامل معه في Scrapling هو [Selector](#selector). وتعيد عمليات الاختيار والتنقل وغيرها كائن [Selector](#selector) أو [Selectors](#selectors)، عندما تكون النتيجة عنصرًا أو مجموعة عناصر من الصفحة، وليست نصًا أو ما شابه.++أي أن الصفحة نفسها كائن [Selector](#selector)، وكذلك عناصرها كائنات [Selector](#selector). أما النص، سواء كان داخل العنصر أو في قيمة خاصية له، فهو كائن [TextHandler](#texthandler). وتُحفظ خصائص العنصر في [AttributesHandler](#attributeshandler). سنعود إليهما لاحقًا، ولنركز الآن على [Selector](#selector).++## Selector {#selector}+### شرح الخيارات {#arguments-explained}+أهم خيار هو `content`، وتمرّر فيه HTML المراد تحليله، كنص `str` أو بايتات `bytes`.++يحدد `url` رابط الصفحة لحل الروابط النسبية وفصل بيانات adaptive المحفوظة حسب النطاق. وتُستخدم `adaptive` و`storage` و`storage_args` مع ميزة [adaptive](adaptive.md)، ولا تؤثر إذا لم تستخدم الميزة.++ثم توجد خيارات لضبط التحليل أو تعديل HTML أثناء تحليله:++- **encoding**: الترميز المستخدم في تحليل HTML. الافتراضي `UTF-8`.+- **keep_comments**: يحدد هل تحتفظ المكتبة بتعليقات HTML أثناء التحليل. معطّل افتراضيًا لأنها قد تسبب مشكلات مختلفة في جمع البيانات.++تركت `huge_tree` و`root` خارج هذا الشرح حتى لا تصبح الصفحة أعقد من اللازم.+قد تلاحظ أنني أفعل ذلك مع ميزات متقدمة لا تحتاج إليها لاستخدام المكتبة. يغطي قسم التطوير هذه التفاصيل إذا أردت التعمق.++تُحمّل معظم خصائص الصفحة وعناصرها عند الحاجة فقط، أي لا تُنشأ حتى تستخدمها، مثل النص داخل الصفحة أو العنصر. هذا أحد أسباب سرعة Scrapling :)++### الخصائص {#properties}+رأيت كثيرًا من هذا في [النظرة العامة](../overview.md)، لكن لا تقلق إن لم تقرأها. سنراجعه بتفصيل أكبر وأمثلة أكثر تقدمًا. وللتوضيح، فصلنا خصائص التنقل في قسم [التنقل](#traversal) أدناه.++للتبسيط، لنفترض أننا نحلّل صفحة HTML التالية:+```html+<html>+ <head>+ <title>Some page</title>+ </head>+ <body>+ <div class="product-list">+ <article class="product" data-id="1">+ <h3>Product 1</h3>+ <p class="description">This is product 1</p>+ <span class="price">$10.99</span>+ <div class="hidden stock">In stock: 5</div>+ </article>++ <article class="product" data-id="2">+ <h3>Product 2</h3>+ <p class="description">This is product 2</p>+ <span class="price">$20.99</span>+ <div class="hidden stock">In stock: 3</div>+ </article>++ <article class="product" data-id="3">+ <h3>Product 3</h3>+ <p class="description">This is product 3</p>+ <span class="price">$15.99</span>+ <div class="hidden stock">Out of stock</div>+ </article>+ </div>++ <script id="page-data" type="application/json">+ {+ "lastUpdated": "2024-09-22T10:30:00Z",+ "totalProducts": 3+ }+ </script>+ </body>+</html>+```+حمّل الصفحة مباشرة كما سبق:+```python+from scrapling import Selector+page = Selector(html_doc)+```+احصل على كل نص الصفحة، بما فيه نص العناصر المتداخلة:+```python+>>> page.get_all_text()+'Some page\n\n \n\n \nProduct 1\nThis is product 1\n$10.99\nIn stock: 5\nProduct 2\nThis is product 2\n$20.99\nIn stock: 3\nProduct 3\nThis is product 3\n$15.99\nOut of stock'+```+احصل على أول عنصر article كما شرحنا. سنستخدمه في المثال:+```python+article = page.find('article')+```+بالطريقة نفسها، احصل على كل نص العنصر، بما فيه العناصر المتداخلة:+```python+>>> article.get_all_text()+'Product 1\nThis is product 1\n$10.99\nIn stock: 5'+```+أما النص المباشر، فسيكون فارغًا لأن العنصر لا يحتوي نصًا مباشرًا في HTML السابق:+```python+>>> article.text+''+```+تقبل `get_all_text` الخيارات الاختيارية التالية:++1. **separator**: الفاصل الذي يربط أجزاء النص المجمّعة. الافتراضي '\n'.+2. **strip**: يزيل المسافات البيضاء من طرفَي النصوص قبل جمعها. معطّل افتراضيًا.+3. **ignore_tags**: tuple بأسماء الوسوم التي تريد تجاهلها مع كل العناصر داخلها. الافتراضي `('script', 'style',)`.+4. **valid_values**: عند تفعيله، تُجمع النصوص ذات القيم الفعلية فقط، وتُتجاهل العناصر ذات النص الفارغ أو المسافات البيضاء فقط. مفعّل افتراضيًا.++النص المعاد هنا كائن [TextHandler](#texthandler)، وليس نصًا عاديًا. سنشرح ذلك لاحقًا. إذا أمكن تحويل المحتوى إلى JSON، استخدم `.json()`:+```python+>>> script = page.find('script')+>>> script.json()+{'lastUpdated': '2024-09-22T10:30:00Z', 'totalProducts': 3}+```+لنحصل الآن على اسم وسم العنصر:+```python+>>> article.tag+'article'+```+إذا استخدمتها على الصفحة مباشرة، فستتعامل مع العنصر الجذري `html`:+```python+>>> page.tag+'html'+```+بهذا اتضحت العلاقة بين `page` و`element`، ولن نكررها.++احصل على خصائص العنصر:+```python+>>> print(article.attrib)+{'class': 'product', 'data-id': '1'}+```+اقرأ خاصية معينة بأي من الطرق التالية:+```python+article.attrib['class']+article.attrib.get('class')+article['class'] # new in v0.3+```+تحقق من وجود خاصية بأي من الطرق التالية:+```python+'class' in article.attrib+'class' in article # new in v0.3+```+احصل على HTML الخاص بالعنصر:+```python+>>> article.html_content+'<article class="product" data-id="1"><h3>Product 1</h3>\n <p class="description">This is product 1</p>\n <span class="price">$10.99</span>\n <div class="hidden stock">In stock: 5</div>\n </article>'+```+احصل على نسخة منسقة من HTML الخاص بالعنصر:+```python+print(article.prettify())+```+```html+<article class="product" data-id="1"><h3>Product 1</h3>+ <p class="description">This is product 1</p>+ <span class="price">$10.99</span>+ <div class="hidden stock">In stock: 5</div>+</article>+```+استخدم `.body` للمحتوى الخام للصفحة. منذ v0.4، تعيد `.body` دائمًا `bytes` إذا كان الكائن `Response` صادرًا من أداة جلب.+```python+>>> page.body+'<html>\n <head>\n <title>Some page</title>\n </head>\n ...'+```+احصل على كل أسلاف العنصر في شجرة DOM:+```python+>>> article.path+[<data='<div class="product-list"> <article clas...' parent='<body> <div class="product-list"> <artic...'>,+ <data='<body> <div class="product-list"> <artic...' parent='<html><head><title>Some page</title></he...'>,+ <data='<html><head><title>Some page</title></he...'>]+```+أنشئ محدد CSS مختصرًا إن أمكن، أو المحدد الكامل:+```python+>>> article.generate_css_selector+'body > div > article'+>>> article.generate_full_css_selector+'body > div > article'+```+وينطبق الأمر نفسه على XPath:+```python+>>> article.generate_xpath_selector+"//body/div/article"+>>> article.generate_full_xpath_selector+"//body/div/article"+```++### التنقل {#traversal}+سنستخدم العناصر السابقة لشرح خصائص ودوال التنقل في الصفحة بالتفصيل.++إذا لم تكن تعرف شجرة DOM أو بنية الشجرة عمومًا، فقد يبدو هذا القسم محيرًا. أنصحك بالبحث عن هذه المفاهيم لفهمها بصورة أفضل.++وإذا أردت شرحًا سريعًا، فهذه الفكرة باختصار.<br/>+العنصر `html` هو جذر شجرة الموقع، لأن كل صفحة تبدأ به.<br/>+يأتي هذا العنصر مباشرة فوق `head` و`body`. وهما «أبناء» له، وهو «الأب» لهما. أما `body` و`head` فهما «شقيقان» لأن لهما الأب نفسه.++الوصول إلى أب العنصر:+```python+>>> article.parent+<data='<div class="product-list"> <article clas...' parent='<body> <div class="product-list"> <artic...'>+>>> article.parent.tag+'div'+```+يمكنك تكرار الوصول بهذه الطريقة، وينطبق ذلك على كل الخصائص والدوال المشابهة التي سنراجعها:+```python+>>> article.parent.parent.tag+'body'+```+احصل على أبناء العنصر:+```python+>>> article.children+[<data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>,+ <data='<p class="description">This is product 1...' parent='<article class="product" data-id="1"><h3...'>,+ <data='<span class="price">$10.99</span>' parent='<article class="product" data-id="1"><h3...'>,+ <data='<div class="hidden stock">In stock: 5</d...' parent='<article class="product" data-id="1"><h3...'>]+```+احصل على كل العناصر الموجودة تحت العنصر. تعمل كنسخة متداخلة من `children`:+```python+>>> article.below_elements+[<data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>,+ <data='<p class="description">This is product 1...' parent='<article class="product" data-id="1"><h3...'>,+ <data='<span class="price">$10.99</span>' parent='<article class="product" data-id="1"><h3...'>,+ <data='<div class="hidden stock">In stock: 5</d...' parent='<article class="product" data-id="1"><h3...'>]+```+تعيد هنا النتيجة نفسها التي تعيدها `children`، لأن أبناء هذا العنصر ليس لهم أبناء.++يوضح المثال التالي، باستخدام العنصر ذي class باسم `product-list`، الفرق بين `children` و`below_elements`:+```python+>>> products_list = page.css('.product-list')[0]+>>> products_list.children+[<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>,+ <data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>,+ <data='<article class="product" data-id="3"><h3...' parent='<div class="product-list"> <article clas...'>]++>>> products_list.below_elements+[<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>,+ <data='<h3>Product 1</h3>' parent='<article class="product" data-id="1"><h3...'>,+ <data='<p class="description">This is product 1...' parent='<article class="product" data-id="1"><h3...'>,+ <data='<span class="price">$10.99</span>' parent='<article class="product" data-id="1"><h3...'>,+ <data='<div class="hidden stock">In stock: 5</d...' parent='<article class="product" data-id="1"><h3...'>,+ <data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>,+...]+```+احصل على أشقاء العنصر:+```python+>>> article.siblings+[<data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>,+ <data='<article class="product" data-id="3"><h3...' parent='<div class="product-list"> <article clas...'>]+```+احصل على العنصر التالي للعنصر الحالي:+```python+>>> article.next+<data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>+```+وينطبق المنطق نفسه على `previous`:+```python+>>> article.previous # It's the first child, so it doesn't have a previous element+>>> second_article = page.css('.product[data-id="2"]')[0]+>>> second_article.previous+<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>+```+تحقق بسهولة وسرعة من وجود اسم class معين:+```python+>>> article.has_class('product')+True+```+إذا احتجت إلى أكثر من الأب المباشر، مرّ على كل أسلاف العنصر كما يلي:+```python+for ancestor in article.iterancestors():+ # do something with it...+```+يمكنك البحث عن سلف يحقق شرطًا. مرّر دالة تستقبل كائن [Selector](#selector) وتعيد `True` عند تحقق الشرط، أو `False` خلاف ذلك:+```python+>>> article.find_ancestor(lambda ancestor: ancestor.has_class('product-list'))+<data='<div class="product-list"> <article clas...' parent='<body> <div class="product-list"> <artic...'>++>>> article.find_ancestor(lambda ancestor: ancestor.css('.product-list')) # Same result, different approach+<data='<div class="product-list"> <article clas...' parent='<body> <div class="product-list"> <artic...'>+```+## Selectors {#selectors}+فئة `Selectors` هي نسخة القائمة من [Selector](#selector). ترث من نوع `List` القياسي في Python، فتشترك معه في الخصائص والدوال، وتضيف طرقًا تسهّل التعامل مع كائنات [Selector](#selector) داخلها.++في فئة [Selector](#selector)، تعيد كل الدوال والخصائص التي تنتج مجموعة عناصر كائنًا من [Selectors](#selectors).++منذ v0.4، تعيد كل طرق الاختيار كائنات [Selector](#selector) أو [Selectors](#selectors) بصورة ثابتة، حتى للعقد النصية وقيم الخصائص. تُغلّف النتائج المختارة عبر `::text` أو `/text()` أو `::attr()` أو `/@attr` في كائنات [Selector](#selector). تكون `tag` فيها `"#text"`، وتعيد خاصية `text` قيمة النص. ويمكنك الوصول إلى القيمة مباشرة، بينما تعيد بقية الخصائص قيمًا فارغة أو افتراضية دون خطأ.++```python+page.css('a::text') # -> Selectors (of text node Selectors)+page.xpath('//a/text()') # -> Selectors+page.css('a::text').get() # -> TextHandler (the first text value)+page.css('a::text').getall() # -> TextHandlers (all text values)+page.css('a::attr(href)') # -> Selectors+page.xpath('//a/@href') # -> Selectors+page.css('.price_color') # -> Selectors+```++### دوال استخراج البيانات {#data-extraction-methods}+منذ v0.4، توفر [Selector](#selector) و[Selectors](#selectors) الدالتين `get()` و`getall()`، والاسمين البديلين `extract_first` و`extract` وفق أسلوب Scrapy. أُزيلت الدالة القديمة `get_all()`.++**في كائن [Selector](#selector):**++- تعيد `get()` كائن `TextHandler`: قيمة النص للعقد النصية، أو HTML الخارجي كاملًا للعناصر.+- تعيد `getall()` قائمة `TextHandlers` تحتوي النص الناتج الواحد.+- `extract_first` اسم بديل لـ`get()`، و`extract` اسم بديل لـ`getall()`.++```python+>>> page.css('h3')[0].get() # Outer HTML of the element+'<h3>Product 1</h3>'++>>> page.css('h3::text')[0].get() # Text value of the text node+'Product 1'+```++**في كائن [Selectors](#selectors):**++- تعيد `get(default=None)` النص الناتج من العنصر **الأول**، أو `default` إذا كانت القائمة فارغة.+- تحوّل `getall()` **كل** العناصر إلى نصوص، وتعيد قائمة `TextHandlers`.+- `extract_first` اسم بديل لـ`get()`، و`extract` اسم بديل لـ`getall()`.++```python+>>> page.css('.price::text').get() # First price text+'$10.99'++>>> page.css('.price::text').getall() # All price texts+['$10.99', '$20.99', '$15.99']++>>> page.css('.price::text').get('') # With default value+'$10.99'+```++تعمل هذه الدوال مع كل طرق الاختيار، مثل CSS وXPath و`find`، وهي الطريقة الموصى بها لاستخراج النص وقيم الخصائص بأسلوب متوافق مع Scrapy.++لنرَ الآن ما تضيفه فئة [Selectors](#selectors).+### الخصائص {#properties_1}+إلى جانب عمليات قوائم Python المعتادة، مثل المرور على العناصر وتقطيع القوائم،++يمكنك فعل ما يلي:++نفّذ محددات CSS وXPath مباشرة على كائنات [Selector](#selector) داخل القائمة. أنواع النتائج هي نفسها في دالتي `css` و`xpath` على [Selector](#selector)، والخيارات متشابهة، لكن `adaptive` غير متاح هنا. يجعل ذلك ربط الدوال ببعضها سهلًا.+```pycon+>>> page.css('.product h3::text').getall()+['Product 1', 'Product 2', 'Product 3']+>>> page.css('.product').css('h3::text').getall()+['Product 1', 'Product 2', 'Product 3']+```+شغّل `re` و`re_first` مباشرة بالخيارات نفسها التي تقبلها [Selector](#selector). سنشرح الدالتين في قسم [TextHandler](#texthandler) أدناه.++لكن `re_first` هنا تعمل بطريقة مختلفة: تشغّل `re` على كل [Selector](#selector) وتعيد أول نتيجة تجدها. أما `re` فتعيد كائن [TextHandlers](#texthandlers) كالمعتاد، وتجمع كل كائنات [TextHandler](#texthandler) الناتجة في كائن [TextHandlers](#texthandlers) واحد.+```pycon+>>> page.css('.price::text').re(r'[\d.]+')+['10.99', '20.99', '15.99']+>>> page.css('.product h3::text').re(r'Product (\d+)')+['1', '2', '3']+```+باستخدام `search`، ابحث بسرعة داخل كائنات [Selector](#selector) الموجودة. يجب أن تستقبل الدالة الممرّرة كائن [Selector](#selector) كأول مُدخل، وتعيد True أو False. تعيد `search` أول كائن [Selector](#selector) يحقق الشرط، أو `None` إذا لم تجده.++```pycon+>>> product = page.css('.product').search(lambda p: p.css('.price::text').get() == '$20.99')+>>> product.css('h3::text').get()+'Product 2'+```+يمكنك استخدام `filter` أيضًا. تستقبل دالة مثل `search`، لكنها تعيد `Selectors` يحتوي **كل** كائنات [Selector](#selector) التي تحقق الشرط:++```pycon+>>> products = page.css('.product').filter(lambda p: float(p.css('.price::text').re_first(r'[\d.]+')) > 15)+>>> products.css('h3::text').getall()+['Product 2', 'Product 3']+```+يمكنك الوصول إلى أول عنصر أو آخر عنصر بأمان دون أخطاء الفهرسة:+```python+>>> page.css('.product').first # First Selector or None+<data='<article class="product" data-id="1"><h3...'>+>>> page.css('.product').last # Last Selector or None+<data='<article class="product" data-id="3"><h3...'>+>>> page.css('.nonexistent').first # Returns None instead of raising IndexError+```++لمعرفة عدد كائنات [Selector](#selector) داخل [Selectors](#selectors) بطريقة مختصرة، استخدم:+```python+page.css('.product').length+```+وهو يساوي:+```python+len(page.css('.product'))+```+نعم، مثل JavaScript :)++## TextHandler {#texthandler}+من المهم فهم هذه الفئة، لأن الدوال والخصائص التي تعيد نصًا ستعيد `TextHandler`، والتي تعيد قائمة نصوص ستعيد [TextHandlers](#texthandlers).++ترث TextHandler من النص القياسي في Python، لذلك يمكنك إجراء كل عمليات نصوص Python عليها. فما الذي يميزها؟++تضيف TextHandler دوال وخصائص غير موجودة في النصوص العادية. سنراجعها الآن. تذكر أن كل دوال وخصائص الفئات التي تعيد نصوصًا تستخدم TextHandler، وهذا يتيح ربط العمليات ويجعل الكود أقصر وأوضح. ويمكنك استيرادها واستخدامها على أي نص، كما سنشرح [لاحقًا](../development/scrapling_custom_types.md).+### الاستخدام {#usage}+قبل شرح الإضافات، اعلم أن عمليات مثل التقطيع والوصول بالفهرس، ودوال مثل `split` و`replace` و`strip`، تعيد `TextHandler` مرة أخرى، فيمكنك ربطها كما تريد. إذا وجدت دالة أو خاصية تعيد نصًا عاديًا بدلًا منها، افتح issue لنعدّلها أيضًا.++نبدأ بـ`re` و`re_first`. هما الدالتان الموجودتان في الفئات الأخرى، أي [Selector](#selector) و[Selectors](#selectors) و[TextHandlers](#texthandlers)، ولذلك تقبلان الخيارات نفسها.++- تستقبل `re` نص التعبير المنتظم أو نمطًا مُجهّزًا كأول مُدخل، وتبحث عن كل النصوص المطابقة وتعيدها في [TextHandlers](#texthandlers). تقبل `re_first` الخيارات نفسها وتعمل بالطريقة نفسها، لكنها تعيد النتيجة الأولى فقط ككائن `TextHandler`.++ وتقبل أيضًا الخيارات المفيدة التالية:++ - **replace_entities**: مفعّل افتراضيًا. يستبدل مراجع كيانات الأحرف بالأحرف التي تمثلها.+ - **clean_match**: معطّل افتراضيًا. ينظف المسافات البيضاء، بما فيها المسافات المتكررة، قبل المطابقة.+ - **case_sensitive**: مفعّل افتراضيًا. عند تعطيله، يتجاهل التعبير المنتظم الفرق بين الأحرف الكبيرة والصغيرة أثناء تجهيزه.++ رأيت هذه الأمثلة من قبل. النتيجة من نوع [TextHandlers](#texthandlers) لأننا استخدمنا `re`.+ ```pycon+ >>> page.css('.price::text').re(r'[\d.]+')+ ['10.99', '20.99', '15.99']+ >>> page.css('.product h3::text').re(r'Product (\d+)')+ ['1', '2', '3']+ ```+ لتوضيح الخيارات الأخرى، سنستخدم نصًا خاصًا في كل مثال:+ ```python+ >>> from scrapling import TextHandler+ >>> test_string = TextHandler('hi there') # Hence the two spaces+ >>> test_string.re('hi there')+ >>> test_string.re('hi there', clean_match=True) # Using `clean_match` will clean the string before matching the regex+ ['hi there']++ >>> test_string2 = TextHandler('Oh, Hi Mark')+ >>> test_string2.re_first('oh, hi Mark')+ >>> test_string2.re_first('oh, hi Mark', case_sensitive=False) # Hence disabling `case_sensitive`+ 'Oh, Hi Mark'++ # Mixing arguments+ >>> test_string.re('hi there', clean_match=True, case_sensitive=False)+ ['hi there']+ ```+ من فوائد استخدام `TextHandler` بدل النصوص أن خاصية مثل `html_content` تعيده أيضًا، فتستطيع البحث بتعبير منتظم في HTML نفسه:+ ```python+ >>> page.html_content.re('div class=".*">(.*)</div')+ ['In stock: 5', 'In stock: 3', 'Out of stock']+ ```++- توجد أيضًا `.json()` التي تحاول تحويل المحتوى إلى كائن JSON بسرعة إن أمكن، وإلا ترفع خطأ:+ ```python+ >>> page.css('#page-data::text').get()+ '\n {\n "lastUpdated": "2024-09-22T10:30:00Z",\n "totalProducts": 3\n }\n '+ >>> page.css('#page-data::text').get().json()+ {'lastUpdated': '2024-09-22T10:30:00Z', 'totalProducts': 3}+ ```+ إذا لم تختَر عقدة نصية عند اختيار العنصر، مثل نصه أو قيمة خاصية، يُستخدم محتواه النصي تلقائيًا:+ ```python+ >>> page.css('#page-data')[0].json()+ {'lastUpdated': '2024-09-22T10:30:00Z', 'totalProducts': 3}+ ```+ تضيف فئة [Selector](#selector) سلوكًا آخر هنا. لنفترض أن هذه هي الصفحة:+ ```html+ <html>+ <body>+ <div>+ <script id="page-data" type="application/json">+ {+ "lastUpdated": "2024-09-22T10:30:00Z",+ "totalProducts": 3+ }+ </script>+ </div>+ </body>+ </html>+ ```+ كما تعرف الآن، توفر [Selector](#selector) دالة `get_all_text` التي تعيد `TextHandler`.<br/><br/>+ إذا كتبت مثلًا:+ ```python+ >>> page.css('div::text').get().json()+ ```+ فستحصل على خطأ، لأن `div` لا يحتوي نصًا مباشرًا يمكن تحويله إلى JSON. في الواقع، لا يحتوي نصًا مباشرًا أصلًا.<br/><br/>+ هنا تساعدك `get_all_text`:+ ```python+ >>> page.css('div')[0].get_all_text(ignore_tags=[]).json()+ {'lastUpdated': '2024-09-22T10:30:00Z', 'totalProducts': 3}+ ```+ استخدمت `ignore_tags` هنا لأن قيمته الافتراضية `('script', 'style',)` كما تعرف.<br/><br/>+ وهناك سلوك مرتبط ستراه عند استخدام أدوات الجلب التي سنشرحها لاحقًا. إذا كان لديك رد JSON مثل هذا:+ ```python+ >>> page = Selector("""{"some_key": "some_value"}""")+ ```+ بما أن [Selector](#selector) مصممة لصفحات HTML، فستتعامل معه كـHTML غير مكتمل وتصلحه. لذلك تعطي `html_content` هذه النتيجة:+ ```python+ >>> page.html_content+ '<html><body><p>{"some_key": "some_value"}</p></body></html>'+ ```+ لكن يمكنك استخدام `json` مباشرة وستعمل:+ ```python+ >>> page.json()+ {'some_key': 'some_value'}+ ```+ قد تتساءل كيف نجح ذلك، مع أن `html` لا يحتوي نصًا مباشرًا.<br/>+ لحالات مثل ردود JSON، تحتفظ [Selector](#selector) بنسخة خام من المحتوى المستلم. عند استخدام `.json()`، تتحقق من هذه النسخة وتحولها إلى JSON. إن لم توجد، كما في العناصر، تتحقق من النص المباشر للعنصر، وإلا تستخدم `get_all_text` مباشرة.<br/>++- دالة مفيدة أخرى هي `.clean()`، وتزيل المسافات البيضاء الزائدة وتجمع المسافات المتكررة في مسافة واحدة، ثم تعيد `TextHandler` جديدًا:+```python+>>> TextHandler('\n wonderful idea, \reh?').clean()+'wonderful idea, eh?'+```+يمكنك أيضًا تمرير `remove_entities` لتستبدل `clean` كيانات HTML بالأحرف التي تمثلها.++- قد تفيدك أيضًا `.sort()` لترتيب أحرف النص، كما تفعل مع القوائم:+```python+>>> TextHandler('acb').sort()+'abc'+```+أو ترتيبها عكسيًا:+```python+>>> TextHandler('acb').sort(reverse=True)+'cba'+```++ستُضاف دوال وخصائص أخرى مع الوقت. تذكر أن هذه الفئة تحل محل النصوص في معظم أجزاء المكتبة.++## TextHandlers {#texthandlers}+كما قد تتوقع، العلاقة هنا تشبه العلاقة بين [Selectors](#selectors) و[Selector](#selector). ترث الفئة سلوك القوائم القياسية ودوالها، وتضيف `re` و`re_first` فقط.++الاختلاف الوحيد أن `re_first` تشغّل `re` على كل [TextHandler](#texthandler) وتعيد أول نتيجة أو `None`. لا يوجد جديد آخر لشرحه، لكن ستُضاف دوال أخرى مع الوقت.++## AttributesHandler {#attributeshandler}+هذه نسخة للقراءة فقط من قاموس Python القياسي `dict`، وتُستخدم لحفظ خصائص كل عنصر أو كائن [Selector](#selector).+```python+>>> print(page.find('script').attrib)+{'id': 'page-data', 'type': 'application/json'}+>>> type(page.find('script').attrib).__name__+'AttributesHandler'+```+لأنها للقراءة فقط، تستخدم موارد أقل من القاموس القياسي. ومع ذلك توفر دوال القاموس وخصائصه نفسها، باستثناء ما يسمح بتعديل البيانات أو استبدالها.++تضيف حاليًا ميزتين بسيطتين:++- دالة `search_values`++ في القاموس العادي، يمكنك استخدام `dict.get("key_name")` للتحقق من وجود مفتاح. لكن البحث بالقيم بدل المفاتيح يحتاج إلى كود إضافي. تفعل هذه الدالة ذلك نيابة عنك، وتبحث في قيم الخصائص الحالية وتعيد قاموسًا لكل عنصر مطابق.++ مثال بسيط:+ ```python+ >>> for i in page.find('script').attrib.search_values('page-data'):+ print(i)+ {'id': 'page-data'}+ ```+ وتوفر الدالة `partial` للبحث بجزء من القيمة:+ ```python+ >>> for i in page.find('script').attrib.search_values('page', partial=True):+ print(i)+ {'id': 'page-data'}+ ```+ المثال الأقرب للاستخدام الفعلي هو دمجها مع `find_all` للعثور على كل العناصر التي تحتوي خصائصها قيمة محددة:+ ```python+ >>> page.find_all(lambda element: list(element.attrib.search_values('product')))+ [<data='<article class="product" data-id="1"><h3...' parent='<div class="product-list"> <article clas...'>,+ <data='<article class="product" data-id="2"><h3...' parent='<div class="product-list"> <article clas...'>,+ <data='<article class="product" data-id="3"><h3...' parent='<div class="product-list"> <article clas...'>]+ ```+ كل هذه العناصر لها القيمة 'product' في الخاصية `class`.++ استخدمت `list` لأن `search_values` تعيد generator، وهو مولّد قيم يُعد True بحد ذاته لكل العناصر حتى إن لم ينتج نتائج.++- خاصية `json_string`++ تحول الخصائص الحالية إلى JSON إذا أمكن، وإلا ترفع خطأ.++ ```python+ >>>page.find('script').attrib.json_string+ b'{"id":"page-data","type":"application/json"}'+ ```diff --git a/docs/locales/ar/parsing/selection.md b/docs/locales/ar/parsing/selection.mdnew file mode 100644index 0000000..fa7d5b5--- /dev/null+++ b/docs/locales/ar/parsing/selection.md@@ -0,0 +1,521 @@+---+title: "استخراج بيانات HTML باستخدام CSS وXPath والنص والتعبيرات المنتظمة"+description: "اختر عناصر HTML باستخدام CSS وXPath والنص والتعبيرات المنتظمة، واعثر على العناصر المتشابهة واستخرج الحقول مع أمثلة Scrapling."+---++# البحث عن العناصر {#querying-elements}+تحلّل فئة `Selector` محتوى HTML. اخترنا ذلك لأن ميزة adaptive لا تعمل مع XML. لخلاصات XML أو RSS أو Atom، استخدم [XMLFeedSpider](../spiders/generic-templates.md#xmlfeedspider)، الذي يستخدم محلّل XML ويعطيك كل عقدة في الخلاصة مباشرة.++توجد خمس طرق أساسية للعثور على العناصر في Scrapling:++1. محددات CSS3.+2. محددات XPath.+3. البحث بالمرشحات أو الشروط.+4. البحث عن عناصر يحتوي نصها على نص محدد.+5. البحث عن عناصر يطابق نصها تعبيرًا منتظمًا.++توجد طرق غير مباشرة أخرى، لكننا سنشرح الطرق الأساسية هنا بالتفصيل. وسنشرح أيضًا ميزة مهمة في Scrapling: العثور على عناصر تشبه عنصرًا لديك. يمكنك الانتقال إلى ذلك القسم مباشرة [من هنا](#finding-similar-elements).++إذا كنت جديدًا في جمع بيانات الويب وليس لديك خبرة كبيرة في كتابة المحددات، وتريد بداية سريعة، أنصحك بتعلم `find` و`find_all` مباشرة [من هنا](#filters-based-searching).++## محددات CSS وXPath {#cssxpath-selectors}++### ما محددات CSS؟ {#what-are-css-selectors}+لغة [CSS](https://en.wikipedia.org/wiki/CSS) تُستخدم لتنسيق مستندات HTML. وتعرّف محددات تربط هذه التنسيقات بعناصر HTML معينة.++يدعم Scrapling محددات CSS3 كما تصفها [مواصفات W3C](http://www.w3.org/TR/2011/REC-css3-selectors-20110929/). يأتي هذا الدعم من `cssselect`، لذلك من الأفضل قراءة [المحددات التي تدعمها cssselect](https://cssselect.readthedocs.io/en/latest/#supported-selectors)، بما فيها pseudo-functions وpseudo-elements.++يدعم Scrapling أيضًا بعض pseudo-elements غير القياسية:++* لاختيار العقد النصية، استخدم ``::text``.+* لاختيار قيم الخصائص، استخدم ``::attr(name)``، حيث name اسم الخاصية المطلوبة.++إذا كنت تستخدم Scrapy أو Parsel، فستجد طريقة عمل المحددات نفسها هنا لتسهيل الانتقال. لا حاجة إلى طريقة غريبة عما اعتدنا عليه :)++استخدم `css` للاختيار بمحددات CSS، وهي تعيد `Selectors`. استخدم `[0]` لأول عنصر، أو `.get()` و`.getall()` لاستخراج القيم النصية من محددات النص والخصائص.++### ما محددات XPath؟ {#what-are-xpath-selectors}+لغة [XPath](https://en.wikipedia.org/wiki/XPath) تختار العقد في مستندات XML، ويمكن استخدامها مع HTML أيضًا. هذا [المرجع المختصر](https://devhints.io/xpath) مفيد لتعلم [XPath](https://en.wikipedia.org/wiki/XPath). يوفر Scrapling محددات XPath مباشرة عبر [lxml](https://lxml.de/).++كما في CSS، ستجد طريقة العمل مألوفة إذا كنت تستخدم Scrapy أو Parsel. لكن Scrapling لا يوفر دالة XPath الإضافية `has-class` الموجودة فيهما. بدلًا منها، يوفر `has_class` على العناصر الناتجة للغرض نفسه.++استخدم دالة `xpath` لاختيار العناصر بمحددات XPath. تتبع الطريقة نفسها التي تتبعها دالة CSS السابقة.++> توجد خيارات إضافية في `css` و`xpath` لم نشرحها هنا لأنها تخص ميزة adaptive، التي سنشرحها بالتفصيل في صفحة مستقلة لاحقًا.++### أمثلة على المحددات {#selectors-examples}+لنرَ أمثلة مشتركة على CSS وXPath.++اختر كل العناصر التي لها class باسم `product`:+```python+products = page.css('.product')+products = page.xpath('//*[@class="product"]')+```+!!! info "ملاحظة:"++ لن يكون محدد XPath هنا دقيقًا إذا كان العنصر يحمل class آخر أيضًا. **من الأفضل استخدام CSS للاختيار حسب class.**++اختر أول عنصر له class باسم `product`:+```python+product = page.css('.product')[0]+product = page.xpath('//*[@class="product"]')[0]+```+احصل على نص أول عنصر من نوع `h1`:+```python+title = page.css('h1::text').get()+title = page.xpath('//h1//text()').get()+```+ويمكنك فعل ذلك أيضًا هكذا:+```python+title = page.css('h1')[0].text+title = page.xpath('//h1')[0].text+```+احصل على قيمة `href` لأول عنصر من نوع `a`:+```python+link = page.css('a::attr(href)').get()+link = page.xpath('//a/@href').get()+```+اختر نص أول عنصر `h1` يحتوي `Phone` ويقع داخل عنصر له class باسم `product`:+```python+title = page.css('.product h1:contains("Phone")::text').get()+title = page.xpath('//*[@class="product"]//h1[contains(text(),"Phone")]/text()').get()+```+يمكنك تداخل المحددات وربطها كما تريد ما دامت تعيد نتائج:+```python+page.css('.product')[0].css('h1:contains("Phone")::text').get()+page.xpath('//*[@class="product"]')[0].xpath('.//h1[contains(text(),"Phone")]/text()').get()+page.xpath('//*[@class="product"]')[0].css('h1:contains("Phone")::text').get()+```+استخدم `.//` لجعل XPath نسبيًا للعنصر الحالي. أما البدء بـ`//` فيبحث في المستند كله، حتى بعد اختيار منتج معين.++مثال آخر:++كل الروابط التي تحتوي خاصية 'href' فيها على 'image':+```python+links = page.css('a[href*="image"]')+links = page.xpath('//a[contains(@href, "image")]')+for index, link in enumerate(links):+ link_value = link.attrib['href'] # Cleaner than link.css('::attr(href)').get()+ link_text = link.text+ print(f'Link number {index} points to this url {link_value} with text content as "{link_text}"')+```++## اختيار العناصر بالنص {#text-content-selection}+يتيح Scrapling اختيار العناصر حسب نصها المباشر بطريقتين:++1. عناصر يحتوي نصها المباشر على النص المطلوب، مع خيارات متعددة عبر `find_by_text`.+2. عناصر يطابق نصها المباشر تعبيرًا منتظمًا، مع خيارات متعددة عبر `find_by_regex`.++إذا كنت تتقن التعبيرات المنتظمة regex، يمكنك فعل ما تفعله `find_by_text` باستخدام `find_by_regex`. لكننا نوفر الطريقتين لتسهيل الاستخدام للجميع.++مرّر النص كأول مُدخل إلى `find_by_text`، أو التعبير المنتظم كأول مُدخل إلى `find_by_regex`. تشترك الدالتان في الخيارات التالية:++* **first_match**: إذا كانت `True`، وهي الافتراضية، تعيد الدالة أول نتيجة تجدها.+* **case_sensitive**: إذا كانت `True`، تميز المطابقة بين الأحرف الكبيرة والصغيرة.+* **clean_match**: إذا كانت `True`، تستبدل المسافات البيضاء والمتكررة بمسافة واحدة قبل المطابقة.++تبحث `find_by_text` افتراضيًا عن تطابق كامل، أي يجب أن يساوي نص العنصر النص الذي تمرّره فقط. ولهذا توفر خيارًا إضافيًا:++* **partial**: عند تفعيله، تعيد `find_by_text` العناصر التي تحتوي النص المطلوب ضمن نصها، دون اشتراط التطابق الكامل.++!!! abstract "ملاحظة:"++ تقبل `find_by_regex` نصًا عاديًا أو نمط regex مُجهّزًا كأول مُدخل، كما سترى في الأمثلة.++### العثور على العناصر المتشابهة {#finding-similar-elements}+من أهم ميزات Scrapling القدرة على العثور على عناصر تشبه عنصرًا لديك. جاءت الفكرة من AutoScraper، لكن Scrapling يتيح استخدامها مع عناصر وجدتها بأي طريقة. غالبًا ستستخدمها بعد البحث بالنص، كما في AutoScraper، لذلك نشرحها هنا.++كيف تعمل؟++لنفترض أنك وجدت منتجًا بعنوانه، وتريد استخراج بقية المنتجات في الجدول أو الحاوية نفسها. استدعِ `.find_similar()` على العنصر، وسيفعل Scrapling التالي:++1. يجد كل عناصر الصفحة الموجودة في العمق نفسه في شجرة DOM.+2. يفحصها ويستبعد ما لا يطابق اسم وسم العنصر واسم وسم أبيه واسم وسم جدّه.+3. نكون بذلك واثقين بدرجة كبيرة، نحو 99%، من أن العناصر مناسبة. وكفحص أخير، يستخدم Scrapling المطابقة التقريبية لاستبعاد العناصر التي لا تشبه خصائصها خصائص العنصر الأصلي. توجد نسبة للتحكم في ذلك. أنصح بتركها كما هي ما لم تفشل الإعدادات الافتراضية في الوصول إلى العناصر المطلوبة.++أعرف أن الشرح طويل، لكن التفاصيل مهمة هنا. سنرى أمثلة في القسم التالي. أولًا، هذه الخيارات التي تقبلها الدالة:++* **similarity_threshold**: نسبة التشابه المستخدمة في الخطوة 3 لمقارنة الخصائص. الافتراضي 0.2، أي يجب أن تتشابه خصائص العنصرين بنسبة 20% على الأقل. يمكنك ضبطها على 0 لتعطيل هذا الفحص، لكن أنصح بقراءة بقية الخيارات أولًا.+* **ignore_attributes**: أسماء الخصائص التي تُتجاهل في المقارنة الأخيرة. الافتراضي `('href', 'src',)`، لأن الروابط قد تختلف كثيرًا بين العناصر ولا يُعتمد عليها هنا.+* **match_text**: إذا كانت `True`، يدخل نص العنصر في المقارنة في الخطوة 3. لا يُنصح به في الحالات المعتادة، لكن القرار حسب الحالة.++لنرَ الأمثلة التالية.++### أمثلة {#examples}+أمثلة مشتركة للبحث بالنص والتعبيرات المنتظمة.++سأستخدم فئة `Fetcher` في هذه الأمثلة، وسنشرحها بالتفصيل لاحقًا.+```python+from scrapling.fetchers import Fetcher+page = Fetcher.get('https://books.toscrape.com/index.html')+```+ابحث عن أول عنصر يطابق نصه هذا النص بالكامل:+```python+>>> page.find_by_text('Tipping the Velvet')+<data='<a href="catalogue/tipping-the-velvet_99...' parent='<h3><a href="catalogue/tipping-the-velve...'>+```+ادمجها مع `page.urljoin` لتحويل `href` النسبي إلى رابط كامل:+```python+>>> page.find_by_text('Tipping the Velvet').attrib['href']+'catalogue/tipping-the-velvet_999/index.html'+>>> page.urljoin(page.find_by_text('Tipping the Velvet').attrib['href'])+'https://books.toscrape.com/catalogue/tipping-the-velvet_999/index.html'+```+احصل على كل المطابقات إن وجدت أكثر من واحدة. لاحظ أن النتيجة قائمة:+```python+>>> page.find_by_text('Tipping the Velvet', first_match=False)+[<data='<a href="catalogue/tipping-the-velvet_99...' parent='<h3><a href="catalogue/tipping-the-velve...'>]+```+احصل على كل العناصر التي تحتوي `the`، باستخدام المطابقة الجزئية:+```python+>>> results = page.find_by_text('the', partial=True, first_match=False)+>>> [i.text for i in results]+['A Light in the ...',+ 'Tipping the Velvet',+ 'The Requiem Red',+ 'The Dirty Little Secrets ...',+ 'The Coming Woman: A ...',+ 'The Boys in the ...',+ 'The Black Maria',+ 'Mesaerion: The Best Science ...',+ "It's Only the Himalayas"]+```+البحث لا يميز افتراضيًا بين الأحرف الكبيرة والصغيرة، لذلك تظهر `The` أيضًا. لنحصر النتائج في العناصر التي تحتوي `the` بالأحرف الصغيرة فقط:+```python+>>> results = page.find_by_text('the', partial=True, first_match=False, case_sensitive=True)+>>> [i.text for i in results]+['A Light in the ...',+ 'Tipping the Velvet',+ 'The Boys in the ...',+ "It's Only the Himalayas"]+```+احصل على أول عنصر يطابق نصه تعبير السعر المنتظم:+```python+>>> page.find_by_regex(r'£[\d\.]+')+<data='<p class="price_color">£51.77</p>' parent='<div class="product_price"> <p class="pr...'>+>>> page.find_by_regex(r'£[\d\.]+').text+'£51.77'+```+يمكنك أيضًا تمرير نمط regex مُجهّز. يتعرف Scrapling على نوع المُدخل ويستخدمه:+```python+>>> import re+>>> regex = re.compile(r'£[\d\.]+')+>>> page.find_by_regex(regex)+<data='<p class="price_color">£51.77</p>' parent='<div class="product_price"> <p class="pr...'>+>>> page.find_by_regex(regex).text+'£51.77'+```+احصل على كل العناصر التي تطابق التعبير المنتظم:+```python+>>> page.find_by_regex(r'£[\d\.]+', first_match=False)+[<data='<p class="price_color">£51.77</p>' parent='<div class="product_price"> <p class="pr...'>,+ <data='<p class="price_color">£53.74</p>' parent='<div class="product_price"> <p class="pr...'>,+ <data='<p class="price_color">£50.10</p>' parent='<div class="product_price"> <p class="pr...'>,+ <data='<p class="price_color">£47.82</p>' parent='<div class="product_price"> <p class="pr...'>,+ ...]+```+وهكذا...++ابحث عن كل العناصر التي تشبه العنصر الحالي في الموضع والخصائص. في هذه الحالة نتجاهل 'title' أثناء المطابقة:+```python+>>> element = page.find_by_text('Tipping the Velvet')+>>> element.find_similar(ignore_attributes=['title'])+[<data='<a href="catalogue/a-light-in-the-attic_...' parent='<h3><a href="catalogue/a-light-in-the-at...'>,+ <data='<a href="catalogue/soumission_998/index....' parent='<h3><a href="catalogue/soumission_998/in...'>,+ <data='<a href="catalogue/sharp-objects_997/ind...' parent='<h3><a href="catalogue/sharp-objects_997...'>,+...]+```+لاحظ أن العدد 19 لا 20، لأن العنصر الحالي لا يُضاف إلى النتائج.+```python+>>> len(element.find_similar(ignore_attributes=['title']))+19+```+احصل على `href` من كل العناصر المشابهة:+```python+>>> [+ element.attrib['href']+ for element in element.find_similar(ignore_attributes=['title'])+]+['catalogue/a-light-in-the-attic_1000/index.html',+ 'catalogue/soumission_998/index.html',+ 'catalogue/sharp-objects_997/index.html',+ ...]+```+لنأخذ مثالًا أكثر تقدمًا: نريد بيانات كل الكتب، باستخدام هذا العنصر كنقطة بداية:+```python+>>> first_product = element.parent.parent+>>> for product in [first_product, *first_product.find_similar()]:+ print({+ "name": product.css('h3 a::text').get(),+ "price": product.css('.price_color')[0].re_first(r'[\d\.]+'),+ "stock": product.css('.availability::text').getall()[-1].clean()+ })+{'name': 'Tipping the Velvet', 'price': '53.74', 'stock': 'In stock'}+{'name': 'A Light in the ...', 'price': '51.77', 'stock': 'In stock'}+{'name': 'Soumission', 'price': '50.10', 'stock': 'In stock'}+{'name': 'Sharp Objects', 'price': '47.82', 'stock': 'In stock'}+...+```+### أمثلة متقدمة {#advanced-examples}+أمثلة أكثر تقدمًا وأقرب للاستخدام الفعلي مع `find_similar`.++استخراج منتجات متجر إلكتروني:+```python+def extract_product_grid(page):+ # Find the first product card+ first_product = page.find_by_text('Add to Cart').find_ancestor(+ lambda e: e.has_class('product-card')+ )++ # Find similar product cards+ products = [first_product, *first_product.find_similar()]++ return [+ {+ 'name': p.css('h3::text').get(),+ 'price': p.css('.price::text').re_first(r'\d+\.\d{2}'),+ 'stock': 'In stock' in p.get_all_text(),+ 'rating': p.css('.rating')[0].attrib.get('data-rating')+ }+ for p in products+ ]+```+استخراج صفوف جدول:+```python+def extract_table_data(page):+ # Find the first data row+ first_row = page.css('table tbody tr')[0]++ # Find similar rows+ rows = [first_row, *first_row.find_similar()]++ return [+ {+ 'column1': row.css('td:nth-child(1)::text').get(),+ 'column2': row.css('td:nth-child(2)::text').get(),+ 'column3': row.css('td:nth-child(3)::text').get()+ }+ for row in rows+ ]+```+استخراج حقول نموذج:+```python+def extract_form_fields(page):+ # Find first form field container+ first_field = page.css('input')[0].find_ancestor(+ lambda e: e.has_class('form-field')+ )++ # Find similar field containers+ fields = [first_field, *first_field.find_similar()]++ return [+ {+ 'label': f.css('label::text').get(),+ 'type': f.css('input')[0].attrib.get('type'),+ 'required': 'required' in f.css('input')[0].attrib+ }+ for f in fields+ ]+```+استخراج مراجعات من موقع:+```python+def extract_reviews(page):+ # Find first review+ first_review = page.find_by_text('Great product!')+ review_container = first_review.find_ancestor(+ lambda e: e.has_class('review')+ )++ # Find similar reviews+ all_reviews = [review_container, *review_container.find_similar()]++ return [+ {+ 'text': r.css('.review-text::text').get(),+ 'rating': r.attrib.get('data-rating'),+ 'author': r.css('.reviewer::text').get()+ }+ for r in all_reviews+ ]+```+## البحث بالمرشحات {#filters-based-searching}+قد تكون هذه أفضل طريقة للبحث عن العناصر في Scrapling، لأنها قوية وأسهل للمبتدئ من كتابة المحددات.++استُلهمت `find_all` و`find` من دالة `find_all` في BeautifulSoup. تقبلان عدة مرشحات وتبحثان عن العناصر التي تحققها كلها.++بالتحديد:++* أي نص تمرّره يُعد اسم وسم.+* أي iterable، مثل List أو Tuple أو Set، يُعد مجموعة أسماء وسوم.+* أي قاموس يُعد مجموعة أسماء خصائص HTML وقيمها للعناصر المطلوبة.+* أي نمط regex يُستخدم لتصفية العناصر حسب محتواها، مثل `find_by_regex`.+* أي دالة تمرّرها تُستخدم لتصفية العناصر.+* أي خيار باسم keyword argument يُعد اسم خاصية HTML وقيمتها.++تجمع الطريقة كل المُدخلات والخيارات، ثم يمرّر كل مرشح نتائجه إلى التالي في سلسلة تصفية.++تُصفّى العناصر في الصفحة أو العنصر الحالي بالترتيب التالي:++1. جمع العناصر التي تطابق أسماء الوسوم الممرّرة.+2. جمع العناصر التي تطابق كل الخصائص الممرّرة، أو تصفية نتائج الخطوة السابقة إن استُخدمت.+3. جمع العناصر التي تطابق كل أنماط regex الممرّرة، أو تصفية نتائج الخطوات السابقة إن استُخدمت.+4. جمع العناصر التي تحقق كل الدوال الممرّرة، أو تصفية نتائج الخطوات السابقة إن استُخدمت.++!!! note "ملاحظات:"++ 1. تبدأ التصفية من أول مرشح موجود وفق الترتيب السابق. إذا لم تمرّر أسماء وسوم ومرّرت خصائص، تبدأ من الخطوة 2، وهكذا.+ 2. ترتيب تمرير المُدخلات لا يهم. الترتيب المعتمد هو المذكور أعلاه فقط.++ستوضح الأمثلة الفكرة :)++### أمثلة {#examples_1}+```python+from scrapling.fetchers import Fetcher+page = Fetcher.get('https://quotes.toscrape.com/')+```+ابحث عن كل العناصر ذات الوسم `div`:+```python+>>> page.find_all('div')+[<data='<div class="container"> <div class="row...' parent='<body> <div class="container"> <div clas...'>,+ <data='<div class="row header-box"> <div class=...' parent='<div class="container"> <div class="row...'>,+...]+```+ابحث عن كل عناصر div التي تساوي قيمة class فيها `quote`:+```python+>>> page.find_all('div', class_='quote')+[<data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,+ <data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,+...]+```+النتيجة نفسها بطريقة أخرى:+```python+>>> page.find_all('div', {'class': 'quote'})+[<data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,+ <data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,+...]+```+ابحث عن كل العناصر التي تساوي قيمة class فيها `quote`:+```python+>>> page.find_all({'class': 'quote'})+[<data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,+ <data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,+...]+```+ابحث عن كل عناصر div التي تساوي قيمة class فيها `quote`، وتحتوي عنصرًا يطابق `.text` ويحتوي نصه على 'world':+```python+>>> page.find_all('div', {'class': 'quote'}, lambda e: "world" in e.css('.text::text').get())+[<data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>]+```+ابحث عن كل العناصر التي لها أبناء:+```python+>>> page.find_all(lambda element: len(element.children) > 0)+[<data='<html lang="en"><head><meta charset="UTF...'>,+ <data='<head><meta charset="UTF-8"><title>Quote...' parent='<html lang="en"><head><meta charset="UTF...'>,+ <data='<body> <div class="container"> <div clas...' parent='<html lang="en"><head><meta charset="UTF...'>,+...]+```+ابحث عن كل العناصر التي يحتوي نصها على 'world':+```python+>>> page.find_all(lambda element: "world" in element.text)+[<data='<span class="text" itemprop="text">“The...' parent='<div class="quote" itemscope itemtype="h...'>,+ <data='<a class="tag" href="/tag/world/page/1/"...' parent='<div class="tags"> Tags: <meta class="ke...'>]+```+ابحث عن كل عناصر span التي تطابق التعبير المنتظم:+```python+>>> page.find_all('span', re.compile(r'world'))+[<data='<span class="text" itemprop="text">“The...' parent='<div class="quote" itemscope itemtype="h...'>]+```+ابحث عن كل عناصر div وspan ذات class باسم 'quote'. لا توجد عناصر span مطابقة هنا، فتُعاد div فقط:+```python+>>> page.find_all(['div', 'span'], {'class': 'quote'})+[<data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,+ <data='<div class="quote" itemscope itemtype="h...' parent='<div class="col-md-8"> <div class="quote...'>,+...]+```+اجمع الطرق معًا:+```python+>>> page.find_all({'itemtype':"http://schema.org/CreativeWork"}, 'div').css('.author::text').getall()+['Albert Einstein',+ 'J.K. Rowling',+...]+```+فكرة إضافية: ابحث عن كل العناصر التي تنتهي قيمة `href` فيها بكلمة 'Einstein':+```python+>>> page.find_all({'href$': 'Einstein'})+[<data='<a href="/author/Albert-Einstein">(about...' parent='<span>by <small class="author" itemprop=...'>,+ <data='<a href="/author/Albert-Einstein">(about...' parent='<span>by <small class="author" itemprop=...'>,+ <data='<a href="/author/Albert-Einstein">(about...' parent='<span>by <small class="author" itemprop=...'>]+```+فكرة أخرى: ابحث عن كل العناصر التي تحتوي قيمة `href` فيها على '/author/':+```python+>>> page.find_all({'href*': '/author/'})+[<data='<a href="/author/Albert-Einstein">(about...' parent='<span>by <small class="author" itemprop=...'>,+ <data='<a href="/author/J-K-Rowling">(about)</a...' parent='<span>by <small class="author" itemprop=...'>,+ <data='<a href="/author/Albert-Einstein">(about...' parent='<span>by <small class="author" itemprop=...'>,+...]+```+وهكذا...++## إنشاء المحددات {#generating-selectors}+يمكنك إنشاء محدد CSS أو XPath لأي عنصر، وإعادة استخدامه هنا أو في مكان آخر. ولا يهم بأي طريقة عثرت على العنصر.++أنشئ محدد CSS قصيرًا للعنصر `url_element` إن أمكن، وإلا أنشئ محددًا كاملًا:+```python+>>> url_element = page.find({'href*': '/author/'})+>>> url_element.generate_css_selector+'body > div > div:nth-of-type(2) > div > div > span:nth-of-type(2) > a'+```+أنشئ محدد CSS كاملًا للعنصر `url_element` بدءًا من أول الصفحة:+```python+>>> url_element.generate_full_css_selector+'body > div > div:nth-of-type(2) > div > div > span:nth-of-type(2) > a'+```+أنشئ محدد XPath قصيرًا للعنصر `url_element` إن أمكن، وإلا أنشئ محددًا كاملًا:+```python+>>> url_element.generate_xpath_selector+'//body/div/div[2]/div/div/span[2]/a'+```+أنشئ محدد XPath كاملًا للعنصر `url_element` بدءًا من أول الصفحة:+```python+>>> url_element.generate_full_xpath_selector+'//body/div/div[2]/div/div/span[2]/a'+```+!!! abstract "ملاحظة:"++ عند طلب محدد قصير، يبحث Scrapling عن عنصر مميز ليكون نقطة توقف، مثل عنصر له `id`. لم يوجد عنصر كهذا في مثالنا، لذلك تطابق المحدد القصير والكامل.++## استخدام المحددات مع التعبيرات المنتظمة {#using-selectors-with-regular-expressions}+كما في `parsel` و`scrapy`، توجد `re` و`re_first` لاستخراج البيانات بالتعبيرات المنتظمة. لكنهما هنا متاحتان في معظم الفئات، مثل `Selector` و`Selectors` و`TextHandler` و`TextHandlers`، فتستطيع استخدامهما مباشرة على العنصر دون اختيار عقدة نصية أولًا.++سنشرح ذلك بتفصيل أكبر مع فئة [TextHandler](main_classes.md#texthandler)، لكن هذه أمثلة عامة:+```python+>>> page.css('.price_color')[0].re_first(r'[\d\.]+')+'51.77'++>>> page.css('.price_color').re_first(r'[\d\.]+')+'51.77'++>>> page.css('.price_color').re(r'[\d\.]+')+['51.77',+ '53.74',+ '50.10',+ '47.82',+ '54.23',+...]++>>> page.css('.product_pod h3 a::attr(href)').re(r'catalogue/(.*)/index.html')+['a-light-in-the-attic_1000',+ 'tipping-the-velvet_999',+ 'soumission_998',+ 'sharp-objects_997',+...]++>>> filtering_function = lambda e: e.parent.tag == 'h3' and e.parent.parent.has_class('product_pod') # As above selector+>>> page.find('a', filtering_function).attrib['href'].re(r'catalogue/(.*)/index.html')+['a-light-in-the-attic_1000']++>>> page.find_by_text('Tipping the Velvet').attrib['href'].re(r'catalogue/(.*)/index.html')+['tipping-the-velvet_999']+```+وهكذا. سنشرح المزيد في الصفحة التالية مع فئة [TextHandler](main_classes.md#texthandler).diff --git a/docs/locales/ar/spiders/advanced.md b/docs/locales/ar/spiders/advanced.mdnew file mode 100644index 0000000..752f7ce--- /dev/null+++ b/docs/locales/ar/spiders/advanced.md@@ -0,0 +1,431 @@+---+title: "التحكم في الزحف: AutoThrottle ونقاط الاستكمال والذاكرة المؤقتة واستقبال البيانات"+description: "تحكّم في سرعة الزحف والتزامن. تعرّف على تخزين الردود مؤقتًا والإيقاف المؤقت والاستكمال واستقبال البيانات أثناء الزحف والحالة المحفوظة في نقاط الاستكمال."+---++# استخدامات متقدمة {#advanced-usages}++## مقدمة {#introduction}++!!! success "قبل البدء"++ 1. اقرأ صفحة [البداية](getting-started.md) وتعرّف على إنشاء عنكبوت بسيط وتشغيله.++تشرح هذه الصفحة الميزات المتقدمة في نظام العناكب: التحكم في التزامن، والإيقاف المؤقت والاستكمال، واستقبال البيانات أثناء الزحف، ودوال مراحل التشغيل، والإحصاءات، والسجلات.++## التحكم في التزامن {#concurrency-control}++يستخدم نظام العناكب ثلاث خصائص للكلاس للتحكم في مقدار الضغط الذي تسببه الطلبات:++| الخاصية | القيمة الافتراضية | الوصف |+|---------|-------------------|-------|+| `concurrent_requests` | `4` | أقصى عدد طلبات تُعالج في الوقت نفسه |+| `concurrent_requests_per_domain` | `0` | أقصى عدد طلبات متزامنة لكل نطاق. القيمة 0 تعني عدم وضع حد لكل نطاق |+| `download_delay` | `0.0` | عدد ثواني الانتظار قبل كل طلب |+| `robots_txt_obey` | `False` | الالتزام بقواعد robots.txt، وهي Disallow وCrawl-delay وRequest-rate |++```python+class PoliteSpider(Spider):+ name = "polite"+ start_urls = ["https://example.com"]++ # Be gentle with the server+ concurrent_requests = 4+ concurrent_requests_per_domain = 2+ download_delay = 1.0 # Wait 1 second between requests++ async def parse(self, response: Response):+ yield {"title": response.css("title::text").get("")}+```++عند تحديد `concurrent_requests_per_domain`، يحصل كل نطاق على حد تزامن خاص به، بالإضافة إلى الحد العام. يفيد ذلك عند الزحف إلى عدة نطاقات في الوقت نفسه، إذ يمكنك السماح بتزامن عام مرتفع مع الحد من الضغط على كل نطاق.++!!! tip "نصيحة"++ يضيف `download_delay` انتظارًا ثابتًا قبل كل طلب، بغض النظر عن النطاق. استخدمه للتحكم البسيط في معدل الطلبات.++## AutoThrottle {#autothrottle}++اختيار `download_delay` ثابت يعتمد على التخمين. إذا كان منخفضًا جدًا فقد تُحظر، وإذا كان مرتفعًا جدًا فقد يستغرق الزحف وقتًا طويلًا. يراقب AutoThrottle سرعة رد الموقع الفعلية، ثم يضبط فترة الانتظار لكل نطاق بشكل مستقل. فيسرع مع الخوادم السريعة، ويبطئ مع الخوادم البطيئة أو التي تحظر الطلبات.++| الخاصية | القيمة الافتراضية | الوصف |+|---------|-------------------|-------|+| `autothrottle_enabled` | `False` | تفعيل فترة الانتظار التي تتغير تلقائيًا |+| `autothrottle_start_delay` | `5.0` | فترة الانتظار المستخدمة لأول طلب إلى النطاق |+| `autothrottle_max_delay` | `60.0` | أقصى فترة انتظار مسموح بها |+| `autothrottle_target_concurrency` | `None` | عدد الطلبات المتزامنة المستهدف لكل نطاق، كما سنوضح أدناه |+| `autothrottle_block_backoff` | `True` | مضاعفة فترة انتظار النطاق في كل مرة يحظرك فيها |++```python+class AdaptiveSpider(Spider):+ name = "adaptive"+ start_urls = ["https://example.com"]++ concurrent_requests = 8+ concurrent_requests_per_domain = 1++ autothrottle_enabled = True+ autothrottle_start_delay = 2.0+ autothrottle_max_delay = 30.0++ async def parse(self, response: Response):+ yield {"title": response.css("title::text").get("")}+```++بعد كل رد، تتجه فترة الانتظار نحو الوقت الذي استغرقه الخادم للرد. فالموقع الذي يرد خلال 0.5 ثانية يستقر عادةً قرب انتظار قدره 0.5 ثانية، أي نحو طلب واحد قيد التنفيذ في الوقت نفسه. يُحدد عدد الطلبات المستهدف لكل نطاق بهذا الترتيب: `autothrottle_target_concurrency` إذا حددته، وإلا `concurrent_requests_per_domain`، وإلا 1. لذلك غالبًا لا تحتاج إلى تحديد هدف منفصل، لأن الحد الذي ضبطته لكل نطاق يُستخدم كهدف، وتُقسم فترة الانتظار عليه. إذا زاد وقت الرد فجأة، تُطبّق الزيادة فورًا بدلًا من إدخالها تدريجيًا في المتوسط. وهكذا يبطئ العنكبوت بمجرد أن يبدأ الخادم في مواجهة صعوبة، ولا يزيد سرعته إلا تدريجيًا.++### الإبطاء عند الحظر {#backing-off-when-blocked}++وقت الرد وحده لا يكشف حدود معدل الطلبات. غالبًا يصل رد `429` أو `403` أو صفحة captcha *أسرع* من المحتوى الحقيقي، مما قد يوحي بأن الموقع يسمح بسرعة أعلى إذا اعتمدنا على الوقت فقط. لذلك فإن أي رد غير سليم، أي حالة خارج 2xx أو رد تعتبره `is_blocked()` محظورًا، **يضاعف** فترة انتظار النطاق:++```+0.5s -> 1s -> 2s -> 4s -> 8s ... (up to autothrottle_max_delay)+```++يستمر العنكبوت في الإبطاء ما دام الموقع يرفض الطلبات. وعندما تعود الردود السليمة، يخفض حساب المتوسط فترة الانتظار تدريجيًا نحو سرعة الخادم الفعلية. وهكذا يعود للعمل بصورة طبيعية دون إعادة تشغيل.++إذا حدد الموقع مدة الانتظار في ترويسة `Retry-After` مع رد `429` أو `503`، تُستخدم هذه القيمة بدلًا من المضاعفة. يدعم النظام الصيغة الرقمية، مثل `Retry-After: 120`، وصيغة تاريخ HTTP.++اضبط `autothrottle_block_backoff = False` لتعطيل هذا السلوك والعودة إلى ضبط السرعة حسب وقت الرد فقط. في هذه الحالة، يستطيع الحظر منع العنكبوت من زيادة السرعة، لكنه لا يضاعف فترة الانتظار.++تتوفر فترة الانتظار النهائية لكل نطاق في الإحصاءات:++```python+result = AdaptiveSpider().start()+print(result.stats.autothrottle_delays) # {'example.com': 0.62}+```++!!! note "ملاحظات"++ * تضع `download_delay` وفترات انتظار robots.txt حدًا أدنى، لكن `autothrottle_max_delay` يضع سقفًا لهذا الحد أيضًا. اجعل الحد الأقصى مساويًا على الأقل لفترة الانتظار التي ضبطتها أو التي يطلبها robots.txt.<br/>+ * تؤدي `concurrent_requests_per_domain` دورين: تحدد أقصى عدد طلبات قيد التنفيذ إلى النطاق، وتُستخدم كهدف لـ AutoThrottle. لذلك لا تحتاج غالبًا إلى ضبط هدف منفصل. يُنصح بتحديدها، لأن النطاق الذي ينتظر يحتفظ بموضع من الحد العام للتزامن. وإذا تركت عدد الطلبات لكل نطاق غير محدود، فقد تستنفد هذه الطلبات المنتظرة المواضع المشتركة مع النطاقات الأخرى.<br/>+ * يشمل وقت الرد المقاس عملية الجلب كاملة، بما فيها أي محاولات إعادة داخلية، ووقت عرض الصفحة في جلسات المتصفح.<br/>+ * يضع `autothrottle_max_delay` سقفًا لكل شيء، بما فيه `Retry-After`. إذا طلب الموقع انتظارًا أطول من هذا السقف، فارفع `autothrottle_max_delay` للالتزام به.<br/>+ * لا تُحفظ فترات الانتظار التي تعلّمها النظام في نقاط الاستكمال. بعد الإيقاف المؤقت والاستكمال، يبدأ كل نطاق مجددًا من `autothrottle_start_delay`.++## استخدام uvloop {#using-uvloop}++تقبل `start()` المعامل `use_uvloop` لاستخدام event loop الأسرع [uvloop](https://github.com/MagicStack/uvloop) أو [winloop](https://github.com/nicktimko/winloop)، إذا كان متاحًا:++```python+result = MySpider().start(use_uvloop=True)+```++قد يحسّن ذلك عدد الطلبات التي تُعالج في وقت معين عندما يعتمد الزحف كثيرًا على عمليات الإدخال والإخراج. تحتاج إلى تثبيت `uvloop` على Linux أو macOS، أو `winloop` على Windows، بشكل منفصل.++## الإيقاف المؤقت والاستكمال {#pause-resume}++يدعم العنكبوت الإيقاف المؤقت المنظم والاستكمال باستخدام نقاط محفوظة. لتفعيل ذلك، مرّر مجلد `crawldir` عند إنشاء العنكبوت:++```python+spider = MySpider(crawldir="crawl_data/my_spider")+result = spider.start()++if result.paused:+ print("Crawl was paused. Run again to resume.")+else:+ print("Crawl completed!")+```++### كيف يعمل {#how-it-works}++1. **الإيقاف المؤقت**: اضغط `Ctrl+C` أثناء الزحف. ينتظر العنكبوت اكتمال الطلبات الجارية، ثم يحفظ نقطة استكمال تضم الطلبات المعلّقة ومجموعة بصمات الطلبات التي سبق رصدها، ثم يخرج.+2. **الإيقاف الفوري**: اضغط `Ctrl+C` مرة ثانية للإيقاف فورًا دون انتظار المهام الجارية.+3. **الاستكمال**: شغّل العنكبوت مجددًا بقيمة `crawldir` نفسها. يكتشف النقطة المحفوظة، ويستعيد الطابور ومجموعة البصمات، ويكمل من حيث توقف، دون تشغيل `start_requests()`.+4. **التنظيف**: عند اكتمال الزحف بصورة طبيعية دون إيقاف مؤقت، تُحذف ملفات نقاط الاستكمال تلقائيًا.++**تُحفظ نقاط الاستكمال أيضًا بصورة دورية أثناء الزحف، كل 5 دقائق افتراضيًا.**++يمكنك تغيير الفاصل الزمني كما يلي:++```python+# Save checkpoint every 2 minutes+spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)+```++تتم الكتابة على القرص كعملية واحدة لا تترك ملفًا مكتوبًا جزئيًا، ولذلك تكون آمنة.++!!! tip "نصيحة"++ عند استخدام `start()`، يؤدي ضغط `Ctrl+C` أثناء الزحف إلى إغلاق منظم، حتى لو لم تفعّل نظام نقاط الاستكمال. الضغط مرة ثانية دون انتظار يُغلق العنكبوت فورًا.++### معرفة ما إذا كنت تستكمل زحفًا سابقًا {#knowing-if-youre-resuming}++تستقبل الدالة `on_start()` القيمة `resuming`:++```python+async def on_start(self, resuming: bool = False):+ if resuming:+ self.logger.info("Resuming from checkpoint!")+ else:+ self.logger.info("Starting fresh crawl")+```++## وضع التطوير {#development-mode}++عند تعديل منطق `parse()` وتجربته، تكون إعادة الطلبات إلى خوادم الموقع في كل تشغيل بطيئة وتسبب طلبات كثيرة. يحفظ وضع التطوير كل رد على القرص عند التشغيل الأول، ثم يعيد استخدامه من القرص في مرات التشغيل التالية. لذلك يمكنك تعديل المحددات وإعادة تشغيل العنكبوت كما تريد دون جلب الصفحات نفسها مجددًا.++فعّله بضبط `development_mode = True` في العنكبوت:++```python+class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]+ development_mode = True++ async def parse(self, response: Response):+ yield {"title": response.css("title::text").get("")}+```++يجلب التشغيل الأول الصفحات بالطريقة المعتادة ويحفظ كل رد على القرص. تستخدم مرات التشغيل التالية الذاكرة المؤقتة للطلبات نفسها بدلًا من جلب الصفحات. عند استخدام `robots_txt_obey=True`، تُفحص قواعد robots.txt قبل البحث في الذاكرة المؤقتة.++### مكان الذاكرة المؤقتة {#cache-location}++تُحفظ الردود افتراضيًا في `.scrapling_cache/{spider.name}/` نسبةً إلى مجلد العمل الحالي، أي المجلد الذي شغّلت العنكبوت منه، **وليس** المجلد الذي يحتوي على ملف العنكبوت. يمكنك تغيير المكان باستخدام `development_cache_dir`:++```python+class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]+ development_mode = True+ development_cache_dir = "/tmp/my_spider_cache"+```++### كيف يعمل {#how-it-works_1}++1. **مفتاح التخزين**: تُحفظ كل استجابة تحت بصمة الطلب. لذلك فإن تغيير أي خاصية تؤثر في البصمة، مثل `fp_include_kwargs` أو `fp_include_headers` أو `fp_keep_fragments`، يؤدي إلى جلب جديد.+2. **صيغة التخزين**: ملف JSON لكل رد، باسم `{fingerprint_hex}.json`. يُرمّز المحتوى باستخدام base64 للحفاظ على البيانات الثنائية كما هي تمامًا. تتم الكتابة بإنشاء ملف مؤقت ثم إعادة تسميته.+3. **إعادة الاستخدام**: عند العثور على رد محفوظ، يتجاوز المحرك جلب الصفحة، بما فيه `download_delay` وحدود معدل الطلبات ومسار إعادة المحاولة عبر `is_blocked()`. يصل الرد المحفوظ مباشرة إلى دالة callback.+4. **الإحصاءات**: تظل الطلبات المحفوظة تُحسب ضمن `requests_count` و`response_bytes` وعدادات حالات الرد، فتبدو الإحصاءات مثل الزحف العادي. يوضح العدادان الإضافيان `cache_hits` و`cache_misses` عدد مرات العثور على رد محفوظ وعدد مرات عدم العثور عليه.++### مسح الذاكرة المؤقتة {#clearing-the-cache}++لا تنتهي صلاحية الردود تلقائيًا. لفرض جلب جديد، احذف مجلد الذاكرة المؤقتة أو استدعِ `clear()` مباشرة من مديرها.++!!! warning "تنبيه"++ وضع التطوير مخصّص للتطوير، وليس للتشغيل الفعلي. لا تنتهي صلاحية الردود المحفوظة، وإعادة استخدامها تتجاوز حدود معدل الطلبات وإعادة الطلبات المحظورة. لا تنشر عنكبوتًا مع `development_mode = True`.++## استقبال البيانات أثناء الزحف {#streaming}++للعناكب التي تعمل طويلًا، أو للتطبيقات التي تحتاج إلى البيانات المستخرجة فورًا، استخدم `stream()` بدلًا من `start()`:++```python+import anyio++async def main():+ spider = MySpider()+ async for item in spider.stream():+ print(f"Got item: {item}")+ # Access real-time stats+ print(f"Items so far: {spider.stats.items_scraped}")+ print(f"Requests made: {spider.stats.requests_count}")++anyio.run(main)+```++الفروق الأساسية عن `start()`:++- يجب استدعاء `stream()` من سياق غير متزامن.+- تُخرج البيانات واحدة تلو الأخرى عند استخراجها، بدلًا من جمعها في قائمة.+- يمكنك قراءة `spider.stats` أثناء المرور على البيانات للحصول على إحصاءات مباشرة.++!!! abstract "تفاصيل"++ تجد شرح القائمة الكاملة للإحصاءات المتاحة عبر `spider.stats` [أدناه](#results-statistics).++يمكنك استخدامها مع نقاط الاستكمال أيضًا، مما يسهل إنشاء واجهات تعرض بيانات مباشرة وتدعم الإيقاف المؤقت والاستكمال.++```python+import anyio++async def main():+ spider = MySpider(crawldir="crawl_data/my_spider")+ async for item in spider.stream():+ print(f"Got item: {item}")+ # Access real-time stats+ print(f"Items so far: {spider.stats.items_scraped}")+ print(f"Requests made: {spider.stats.requests_count}")++anyio.run(main)+```++يمكنك أيضًا استخدام `spider.pause()` لإيقاف العنكبوت في الكود السابق. إذا استخدمتها دون تفعيل نظام نقاط الاستكمال، فستغلق عملية الزحف فقط.++## دوال مراحل التشغيل {#lifecycle-hooks}++يوفر العنكبوت عدة دوال يمكنك إعادة تعريفها لإضافة سلوك مخصّص في مراحل الزحف المختلفة:++### on_start {#on_start}++تُستدعى قبل بدء الزحف. استخدمها للإعداد، مثل تحميل البيانات أو تهيئة الموارد:++```python+async def on_start(self, resuming: bool = False):+ self.logger.info("Spider starting up")+ # Load seed URLs from a database, initialize counters, etc.+```++### on_close {#on_close}++تُستدعى بعد انتهاء الزحف، سواء اكتمل أم توقف مؤقتًا. استخدمها للتنظيف والإغلاق:++```python+async def on_close(self):+ self.logger.info("Spider shutting down")+ # Close database connections, flush buffers, etc.+```++### on_error {#on_error}++تُستدعى عند فشل طلب بسبب استثناء. استخدمها لتتبع الأخطاء أو لإضافة طريقة استرداد مخصّصة:++```python+async def on_error(self, request: Request, error: Exception):+ self.logger.error(f"Failed: {request.url} - {error}")+ # Log to error tracker, save failed URL for later, etc.+```++### on_scraped_item {#on_scraped_item}++تُستدعى لكل عنصر بيانات قبل إضافته إلى النتائج. أعد العنصر، مع تعديله أو دونه، للاحتفاظ به، أو أعد `None` لاستبعاده:++```python+async def on_scraped_item(self, item: dict) -> dict | None:+ # Drop items without a title+ if not item.get("title"):+ return None++ # Modify items (e.g., add timestamps)+ item["scraped_at"] = "2026-01-01"+ return item+```++!!! tip "نصيحة"++ يمكنك أيضًا استخدام هذه الدالة لتمرير البيانات إلى مراحل المعالجة الخاصة بك، ثم استبعادها من نتائج العنكبوت.++### start_requests {#start_requests}++أعد تعريف `start_requests()` لإنشاء الطلبات الأولى بطريقة مخصّصة بدلًا من استخدام `start_urls`:++```python+async def start_requests(self):+ # POST request to log in first+ yield Request(+ "https://example.com/login",+ method="POST",+ data={"user": "admin", "pass": "secret"},+ callback=self.after_login,+ )++async def after_login(self, response: Response):+ # Now crawl the authenticated pages+ yield response.follow("/dashboard", callback=self.parse)+```++## النتائج والإحصاءات {#results-statistics}++يحتوي `CrawlResult` الذي تعيده `start()` على البيانات المستخرجة والإحصاءات المفصّلة:++```python+result = MySpider().start()++# Items+print(f"Total items: {len(result.items)}")+result.items.to_json("output.json", indent=True)++# Did the crawl complete?+print(f"Completed: {result.completed}")+print(f"Paused: {result.paused}")++# Statistics+stats = result.stats+print(f"Requests: {stats.requests_count}")+print(f"Failed: {stats.failed_requests_count}")+print(f"Blocked: {stats.blocked_requests_count}")+print(f"Offsite filtered: {stats.offsite_requests_count}")+print(f"Robots.txt disallowed: {stats.robots_disallowed_count}")+print(f"Cache hits: {stats.cache_hits}")+print(f"Cache misses: {stats.cache_misses}")+print(f"Items scraped: {stats.items_scraped}")+print(f"Items dropped: {stats.items_dropped}")+print(f"Response bytes: {stats.response_bytes}")+print(f"Duration: {stats.elapsed_seconds:.1f}s")+print(f"Speed: {stats.requests_per_second:.1f} req/s")+```++### الإحصاءات المفصّلة {#detailed-stats}++يتتبع كائن `CrawlStats` المعلومات التفصيلية التالية:++```python+stats = result.stats++# Status code distribution+print(stats.response_status_count)+# {'status_200': 150, 'status_404': 3, 'status_403': 1}++# Bytes downloaded per domain+print(stats.domains_response_bytes)+# {'example.com': 1234567, 'api.example.com': 45678}++# Requests per session+print(stats.sessions_requests_count)+# {'http': 120, 'stealth': 34}++# Proxies used during the crawl+print(stats.proxies)+# ['http://proxy1:8080', 'http://proxy2:8080']++# Log level counts+print(stats.log_levels_counter)+# {'debug': 200, 'info': 50, 'warning': 3, 'error': 1, 'critical': 0}++# Timing information+print(stats.start_time) # Unix timestamp when crawl started+print(stats.end_time) # Unix timestamp when crawl finished+print(stats.download_delay) # The download delay used (seconds)++# Concurrency settings used+print(stats.concurrent_requests) # Global concurrency limit+print(stats.concurrent_requests_per_domain) # Per-domain concurrency limit++# AutoThrottle+print(stats.autothrottle_enabled) # Whether the adaptive delay was on+print(stats.autothrottle_delays) # Final delay per domain, {'example.com': 0.62}++# Custom stats (set by your spider code)+print(stats.custom_stats)+# {'login_attempts': 3, 'pages_with_errors': 5}++# Export everything as a dict+print(stats.to_dict())+```++## السجلات {#logging}++يحتوي العنكبوت على logger مدمج يمكنك الوصول إليه عبر `self.logger`. يُعدّ مسبقًا باسم العنكبوت، ويدعم الخيارات التالية:++| الخاصية | القيمة الافتراضية | الوصف |+|---------|-------------------|-------|+| `logging_level` | `logging.DEBUG` | أقل مستوى رسائل يُسجّل |+| `logging_format` | `"[%(asctime)s]:({spider_name}) %(levelname)s: %(message)s"` | تنسيق رسالة السجل |+| `logging_date_format` | `"%Y-%m-%d %H:%M:%S"` | تنسيق التاريخ في الرسائل |+| `log_file` | `None` | مسار ملف السجل، بالإضافة إلى الرسائل في الطرفية |++```python+import logging++class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]+ logging_level = logging.INFO+ log_file = "logs/my_spider.log"++ async def parse(self, response: Response):+ self.logger.info(f"Processing {response.url}")+ yield {"title": response.css("title::text").get("")}+```++يُنشأ مجلد ملف السجل تلقائيًا إذا لم يكن موجودًا. تستخدم الرسائل في الطرفية والملف التنسيق نفسه.diff --git a/docs/locales/ar/spiders/architecture.md b/docs/locales/ar/spiders/architecture.mdnew file mode 100644index 0000000..7c7b293--- /dev/null+++ b/docs/locales/ar/spiders/architecture.md@@ -0,0 +1,105 @@+---+title: "كيف يعمل زاحف الويب في Scrapling"+description: "تعرّف على دور العناكب والطلبات والجلسات وجدولة الطلبات ومحرك الزحف. قارن طريقة العمل مع Scrapy واختر نقطة البداية."+---++# بنية العناكب {#spiders-architecture}++!!! success "قبل البدء"++ 1. اقرأ صفحة [أساسيات أدوات الجلب](../fetching/choosing.md) لفهم أنواع أدوات الجلب المختلفة ومتى تستخدم كل نوع.+ 2. اقرأ صفحة [الكلاسات الأساسية](../parsing/main_classes.md) لفهم كلاس [Selector](../parsing/main_classes.md#selector) وكلاس [Response](../fetching/choosing.md#response-object).++نظام العناكب في Scrapling هو إطار زحف غير متزامن مستوحى من Scrapy. صُمّم لتشغيل طلبات متزامنة وجلسات متعددة، مع دعم مدمج للإيقاف المؤقت والاستكمال. يجمع بين محرك التحليل وأدوات الجلب في Scrapling ضمن API واحد للزحف، ويضيف جدولة الطلبات والتحكم في التزامن وحفظ نقاط الاستكمال.++إذا سبق لك استخدام Scrapy، فستجد طريقة العمل مألوفة. وإذا لم تستخدمه من قبل، فلا تقلق، فالنظام مصمّم ليكون سهل الاستخدام.++## مسار البيانات {#data-flow}++يوضح الرسم التالي مسار البيانات داخل نظام العناكب أثناء الزحف:++<img src="../assets/spider_architecture.png" title="رسم بنية العناكب من @TrueSkills" alt="رسم بنية العناكب من @TrueSkills" style="width: 70%;"/>++هذه هي الخطوات الأساسية عند تشغيل العنكبوت، دون الدخول في تفاصيل كثيرة:++1. ينشئ **العنكبوت** المجموعة الأولى من كائنات `Request`. افتراضيًا، ينشئ طلبًا لكل URL في `start_urls`، ويمكنك إعادة تعريف `start_requests()` لتخصيص هذه الخطوة.+2. يستقبل **Scheduler** الطلبات ويضعها في طابور حسب الأولوية، وينشئ بصمة لكل طلب. تخرج الطلبات الأعلى أولوية أولًا.+3. يطلب **محرك الزحف** من **Scheduler** إخراج الطلب التالي، مع الالتزام بحدود التزامن العامة ولكل نطاق، وفترات الانتظار بين الطلبات. إذا كان `robots_txt_obey` مفعّلًا، يفحص المحرك قواعد robots.txt للنطاق قبل المتابعة، ويتجاهل الطلبات غير المسموح بها دون رسالة. ثم يرسل الطلب إلى **مدير الجلسات** الذي يختار الجلسة المناسبة وفقًا لقيمة `sid`، أي معرّف الجلسة، في الطلب.+4. تجلب **الجلسة** الصفحة وتعيد كائن [Response](../fetching/choosing.md#response-object) إلى **محرك الزحف**. يسجّل المحرك الإحصاءات ويفحص الرد لمعرفة ما إذا كان الموقع قد حظر الطلب. عند الحظر، يعيد المحاولة حتى `max_blocked_retries` مرة. يمكنك تخصيص طريقة اكتشاف الحظر وطريقة إعادة المحاولة.+5. يمرّر **محرك الزحف** كائن [Response](../fetching/choosing.md#response-object) إلى دالة callback الخاصة بالطلب. تُخرج هذه الدالة إما قاموسًا يُعامل كعنصر بيانات مستخرج، أو طلب متابعة يُرسل إلى Scheduler لإضافته إلى الطابور.+6. تتكرر الدورة من الخطوة 2 حتى يفرغ الطابور ولا تبقى مهام تعمل، أو حتى يتوقف العنكبوت مؤقتًا.+7. إذا ضبطت `crawldir` عند تشغيل العنكبوت، يحفظ **محرك الزحف** نقطة استكمال على القرص بصورة دورية. تشمل الطلبات المعلّقة ومجموعة عناوين URL التي سبق رصدها. عند الإغلاق المنظم باستخدام Ctrl+C، يحفظ نقطة أخيرة. وعند تشغيل العنكبوت مجددًا بقيمة `crawldir` نفسها، يستكمل من حيث توقف، دون تشغيل `start_requests()`، مع استعادة حالة الطابور.++## المكونات {#components}++### Spider {#spider}++الكلاس الأساسي الذي تتعامل معه. أنشئ كلاسًا يرث من `Spider`، وحدد `start_urls` ودالة `parse()`. ويمكنك أيضًا إعداد الجلسات وإعادة تعريف دوال مراحل التشغيل.++```python+from scrapling.spiders import Spider, Response, Request++class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]++ async def parse(self, response: Response):+ for link in response.css("a::attr(href)").getall():+ yield response.follow(link, callback=self.parse_page)++ async def parse_page(self, response: Response):+ yield {"title": response.css("h1::text").get("")}+```++### محرك الزحف {#crawler-engine}++يدير المحرك عملية الزحف كلها. يشغّل الحلقة الأساسية، ويطبّق حدود التزامن، ويرسل الطلبات عبر مدير الجلسات، ويعالج النتائج التي تعيدها دوال callback. لا تحتاج إلى التعامل معه مباشرة، لأن `Spider.start()` و`Spider.stream()` يقومان بذلك.++### Scheduler {#scheduler}++طابور يرتّب الطلبات حسب الأولوية، مع منع التكرار تلقائيًا. تُحسب بصمة الطلب من عنوان URL وطريقة HTTP ومحتوى الطلب ومعرّف الجلسة. يدعم Scheduler الدالتين `snapshot()` و`restore()` لحفظ حالة الزحف واستعادتها من نقاط الاستكمال.++### مدير الجلسات {#session-manager}++يدير جلسة واحدة أو أكثر، لكل منها اسم. تكون كل جلسة من أحد النوعين:++- [FetcherSession](../fetching/static.md)+- [AsyncStealthySession](../fetching/stealthy.md)++عند وصول طلب، يختار مدير الجلسات الجلسة المناسبة حسب حقل `sid`. يمكن تشغيل الجلسات مع بداية العنكبوت، وهذا هو السلوك الافتراضي، أو عند أول استخدام لها فقط.++### نظام نقاط الاستكمال {#checkpoint-system}++نظام اختياري يحفظ حالة الزاحف، أي الطلبات المعلّقة وبصمات عناوين URL التي سبق رصدها، في ملف pickle على القرص. تتم الكتابة بإنشاء ملف مؤقت ثم إعادة تسميته، لتجنب تلف الملف. تُحفظ النقاط دوريًا بفاصل قابل للضبط، وعند الإغلاق المنظم. بعد اكتمال الزحف بنجاح دون إيقاف مؤقت، تُحذف ملفات نقاط الاستكمال تلقائيًا.++### ذاكرة الردود المؤقتة {#response-cache}++ميزة اختيارية تحفظ كل رد على القرص عند تفعيل وضع التطوير، وتعيد استخدامه في مرات التشغيل التالية. يُحفظ كل رد تحت مفتاح هو بصمة الطلب، بصيغة JSON، مع ترميز المحتوى باستخدام base64 للحفاظ على المحتوى الثنائي. الغرض منها هو تعديل منطق `parse()` وتجربته دون تكرار الطلبات إلى خوادم الموقع، وليست مخصّصة للتشغيل الفعلي.++### النتائج {#output}++تُجمع البيانات المستخرجة في `ItemList`، وهي كلاس يرث من list ويتيح التصدير عبر `to_json()` و`to_jsonl()` و`to_csv()` و`to_xml()`. تُسجّل إحصاءات الزحف في dataclass اسمها `CrawlStats` وتحتوي على معلومات كثيرة مفيدة.++## مقارنة مع Scrapy {#comparison-with-scrapy}++إذا كنت تستخدم Scrapy، فهذه هي المكونات المقابلة في Scrapling:++| المفهوم | Scrapy | Scrapling |+|---------|--------|-----------|+| تعريف العنكبوت | كلاس يرث من `scrapy.Spider` | كلاس يرث من `scrapling.spiders.Spider` |+| الطلبات الأولى | `start_requests()` | `async start_requests()` |+| دوال callback | `def parse(self, response)` | `async def parse(self, response)` |+| متابعة الروابط | `response.follow(url)` | `response.follow(url)` |+| إخراج البيانات | `yield dict` أو `yield Item` | `yield dict` |+| جدولة الطلبات | Scheduler + Dupefilter | Scheduler مع منع التكرار مدمجًا |+| التنزيل | Downloader + Middlewares | مدير جلسات يدعم جلسات متعددة |+| معالجة البيانات | Item Pipelines | دالة `on_scraped_item()` |+| اكتشاف الحظر | عبر middlewares مخصّصة | الدالتان المدمجتان `is_blocked()` و`retry_blocked_request()` |+| التزامن | الإعداد `CONCURRENT_REQUESTS` | خاصية الكلاس `concurrent_requests` |+| تصفية النطاقات | `allowed_domains` | `allowed_domains` |+| Robots.txt | الإعداد `ROBOTSTXT_OBEY` | خاصية الكلاس `robots_txt_obey` |+| الإيقاف المؤقت والاستكمال | الإعداد `JOBDIR` | معامل إنشاء الكلاس `crawldir` |+| التصدير | Feed exports | `result.items.to_json()` / `to_jsonl()` / `to_csv()` / `to_xml()` أو تخصيصه عبر دوال مراحل التشغيل |+| التشغيل | `scrapy crawl spider_name` | `MySpider().start()` |+| استقبال البيانات أثناء الزحف | غير متاح | `async for item in spider.stream()` |+| جلسات متعددة | غير متاح | عدة جلسات بأنواع مختلفة في العنكبوت نفسه |diff --git a/docs/locales/ar/spiders/generic-templates.md b/docs/locales/ar/spiders/generic-templates.mdnew file mode 100644index 0000000..719f822--- /dev/null+++ b/docs/locales/ar/spiders/generic-templates.md@@ -0,0 +1,278 @@+---+title: "قوالب العناكب للروابط وخرائط الموقع وملفات البيانات وMarkdown"+description: "اختر بين CrawlSpider وSitemapSpider وXMLFeedSpider وCSVFeedSpider وContentSpider. حدد قواعد جمع الصفحات أو صفوف البيانات أو مجموعة نصوص Markdown."+---++# قوالب العناكب العامة {#generic-spider-templates}++تتبع معظم عمليات الزحف أحد نمطين: متابعة الروابط التي تطابق نمطًا محددًا، أو زيارة كل عنوان URL في خريطة الموقع. توفر Scrapling قوالب للحالتين، حتى لا تحتاج إلى كتابة كود `parse()` المتكرر في كل مرة.++يعتمد `CrawlSpider` و`SitemapSpider` على `LinkExtractor`، الذي يستخرج عناوين URL من `Response`، أو يختبر عنوانًا واحدًا باستخدام `matches()`. كما يحلل `SitemapSpider` محتوى sitemap.xml وsitemap_index.xml داخليًا، سواء كان مضغوطًا باستخدام gzip أم لا.++يمكنك استخدام `LinkExtractor` مباشرة داخل `Spider.parse()` العادية. توفر لك القوالب فقط كود ربط الأجزاء ببعضها.++## CrawlSpider {#crawlspider}++يتابع `CrawlSpider` الروابط تلقائيًا وفقًا للقواعد التي تحددها.++```python+from scrapling.spiders import CrawlSpider, CrawlRule, LinkExtractor++class QuotesSpider(CrawlSpider):+ name = "blog"+ start_urls = ["https://quotes.toscrape.com/"]++ def rules(self):+ return [+ CrawlRule(LinkExtractor(allow=r"/author/"), callback=self.parse_author),+ CrawlRule(LinkExtractor(allow=r"/page/\d+/")), # follow pagination, no callback+ ]++ async def parse_author(self, response):+ yield {+ '.author-title': response.css('.author-title::text').get(),+ "birthday": response.css('.author-born-date::text').get(),+ "url": response.url,+ }++result = QuotesSpider().start()+```++تجمع `CrawlRule` بين `LinkExtractor` ودالة `callback` اختيارية، وهي دالة مرتبطة بكائن العنكبوت. ويمكنها أيضًا تحديد `priority` للطلب `Request` الناتج، ودالة `process_request` اختيارية تعدّل كل `Request` قبل إخراجه. تطبّق `parse()` الافتراضية جميع القواعد على كل رد، وتُخرج `Request` لكل عنوان URL مطابق.++إذا لم تحدد callback لقاعدة، تُرسل عناوين URL المطابقة إلى `parse()` الافتراضية للعنكبوت. يفيد ذلك في متابعة الصفحات: تستخرج روابط الصفحات التالية ليستمر الزحف دون الحاجة إلى دالة معالجة منفصلة.++### ترتيب الزحف {#crawl-order}++اضبط `crawl_strategy` في `CrawlSpider` أو في الكلاسات التي ترث منه، بما فيها `ContentSpider`، لاختيار الطلب المعلّق التالي:++| `crawl_strategy` | الترتيب بين الطلبات التي لها `Request.priority` نفسها |+|------------------|------------------------------------------------------|+| `"bfs"`، الافتراضي | أقدم طلب في الطابور أولًا |+| `"dfs"` | أحدث طلب في الطابور أولًا |++يختار Scheduler أولًا الطلبات المعلّقة ذات `Request.priority` الأعلى. تؤثر الاستراتيجية فقط في ترتيب الطلبات المتساوية في الأولوية.++اضبط `concurrent_requests = 1` لمعالجة طلب واحد في كل مرة حسب ترتيب الطابور الذي اخترته. يظل منع تكرار عناوين URL مفعّلًا، والعثور على عنوان مجددًا لا يغيّر موضع طلبه في الطابور. عند تشغيل طلبات بالتوازي، قد تكتمل الصفحات بترتيب مختلف، وقد تتداخل مستويات الزحف أو فروعه.++احتفظ بقيمة `crawl_strategy` نفسها عند الاستكمال من نقطة محفوظة.++### دمج القواعد مع منطق مخصّص {#combining-rules-with-custom-logic}++أعد تعريف `parse()` واستدعِ `super().parse(response)` لتطبيق القواعد وإخراج بياناتك الإضافية:++```python+class MySpider(CrawlSpider):+ def rules(self):+ return [CrawlRule(LinkExtractor(allow=r"/posts/"), callback=self.parse_post)]++ async def parse(self, response):+ yield {"page_url": response.url}+ async for req in super().parse(response):+ yield req+```++### تعديل الطلبات باستخدام `process_request` {#mutating-requests-with-process_request}++```python+def add_priority(self, request, response):+ request.priority = 10+ return request++def rules(self):+ return [CrawlRule(+ LinkExtractor(allow=r"/posts/"),+ callback=self.parse_post,+ process_request=self.add_priority,+ )]+```++## SitemapSpider {#sitemapspider}++يبدأ `SitemapSpider` الزحف من عناوين sitemap.xml. يستخدم واجهة `rules()` نفسها التي يستخدمها `CrawlSpider`، ولذلك تتشابه طريقة التعامل معهما.++```python+from scrapling.spiders import SitemapSpider, CrawlRule, LinkExtractor++class MySitemap(SitemapSpider):+ name = "sm"+ sitemap_urls = ["https://example.com/sitemap.xml"]++ def rules(self):+ return [+ CrawlRule(LinkExtractor(allow=r"/posts/"), callback=self.parse_post),+ CrawlRule(LinkExtractor(allow=r"/products/"), callback=self.parse_product),+ ]++ async def parse_post(self, response):+ yield {"title": response.css("h1::text").get()}++ async def parse_product(self, response):+ yield {"sku": response.css(".sku::text").get()}++result = MySitemap().start()+```++### كيفية توجيه عناوين URL {#how-urls-are-dispatched}++لكل URL في خريطة الموقع، يفحص `SitemapSpider` الدالة `LinkExtractor.matches(url)` لكل قاعدة بالترتيب. تُستخدم أول قاعدة مطابقة، ويُخرج `Request` بدالة callback الخاصة بها. إذا لم تطابق أي قاعدة وكان ناتج `rules()` غير فارغ، يُستبعد العنوان. وإذا أعادت `rules()` قائمة فارغة، يُرسل كل عنوان إلى `parse()` الخاصة بالعنكبوت. هذه الدالة ترفع `NotImplementedError` افتراضيًا إذا لم تُعد تعريفها.++### فهارس خرائط الموقع {#sitemap-indexes}++إذا وجد `SitemapSpider` عنصر `<sitemapindex>`، أي خريطة تحتوي على خرائط أخرى، يدخل إلى كل خريطة فرعية تلقائيًا. لتحديد الخرائط الفرعية التي تريد متابعتها، اضبط `sitemap_follow` على `LinkExtractor`:++```python+class MySitemap(SitemapSpider):+ name = "sm"+ sitemap_urls = ["https://example.com/sitemap.xml"]+ sitemap_follow = LinkExtractor(allow=r"/posts-sitemap-\d+\.xml") # only post sitemaps+```++### دعم robots.txt {#robotstxt-support}++ضع عنوان ملف `robots.txt` مباشرة في `sitemap_urls`. سيتعرف عليه `SitemapSpider`، ويستخرج كل خرائط الموقع المذكورة فيه، ثم يتابعها:++```python+class MySitemap(SitemapSpider):+ name = "sm"+ sitemap_urls = ["https://example.com/robots.txt"]+```++### عناوين اللغات الأخرى {#alternate-language-urls}++اضبط `sitemap_alternate_links = True` لتمرير عناوين `<xhtml:link rel="alternate" hreflang="...">` إلى القواعد أيضًا.++## XMLFeedSpider {#xmlfeedspider}++يمرّ `XMLFeedSpider` على عناصر مصدر بيانات XML، مثل RSS وAtom وملفات المنتجات. اضبط `itertag` على اسم العنصر المطلوب، والقيمة الافتراضية هي `"item"`. وأعد تعريف `parse_node()`، التي تُستدعى مرة لكل عنصر مطابق:++```python+from scrapling.spiders import XMLFeedSpider++class RSSSpider(XMLFeedSpider):+ name = "rss"+ start_urls = ["https://example.com/feed.xml"]+ itertag = "item"++ async def parse_node(self, response, node):+ yield {+ "title": node.findtext("title"),+ "link": node.findtext("link"),+ "date": node.findtext("pubDate"),+ }++result = RSSSpider().start()+```++مثل دوال callback الأخرى، يمكن لـ `parse_node()` إخراج كائنات `Request` أيضًا. مثلًا، يمكنك استخدام `response.follow(node.findtext("link"), callback=self.parse_post)` لزيارة الصفحات المشار إليها في مصدر البيانات.++### كيفية مطابقة العناصر وتحليلها {#how-nodes-are-matched-and-parsed}++كل عنصر يصل إلى `parse_node()` هو عنصر `lxml` أُزيلت منه جميع namespaces. لذلك تعمل `node.findtext("title")` و`node.find("thumbnail").get("url")` و`node.xpath(...)` الحساسة لحالة الأحرف مع أي مصدر بيانات دون خرائط namespaces. تطابق قيمة `itertag` البسيطة، مثل `"entry"`، العناصر حسب الاسم دون اعتبار للـ namespace، وهو ما تحتاجه مع Atom ومعظم مصادر البيانات التي تستخدم namespaces. لمطابقة عنصر ضمن namespace محدد فقط، استخدم `itertag` مع بادئة، وحدد هذه البادئة في `namespaces`:++```python+class ThumbnailSpider(XMLFeedSpider):+ name = "thumbs"+ start_urls = ["https://example.com/feed.xml"]+ itertag = "media:thumbnail"+ namespaces = (("media", "http://search.yahoo.com/mrss/"),)++ async def parse_node(self, response, node):+ yield {"thumbnail": node.get("url")}+```++تُفك ملفات البيانات المضغوطة باستخدام gzip تلقائيًا، سواء كان امتدادها `.xml.gz` أو كانت تُرسل بنوع محتوى gzip. تُطبّق الحماية نفسها المستخدمة في عنكبوت خرائط الموقع. وإذا كان XML غير صالح، تُسجّل رسالة تنبيه بدلًا من توقف الزحف بخطأ.++## CSVFeedSpider {#csvfeedspider}++يمرّ `CSVFeedSpider` على صفوف مصدر بيانات CSV. أعد تعريف `parse_row()`، التي تستقبل كل صف في صورة قاموس مفاتيحه أسماء الأعمدة:++```python+from scrapling.spiders import CSVFeedSpider++class PriceSpider(CSVFeedSpider):+ name = "prices"+ start_urls = ["https://example.com/products.csv"]++ async def parse_row(self, response, row):+ yield {"product": row["title"], "price": float(row["price"])}++result = PriceSpider().start()+```++يُستخدم الصف الأول كأسماء للأعمدة افتراضيًا. إذا لم يكن هناك صف أسماء، فحددها بنفسك في `headers`. واستخدم `delimiter` و`quotechar` مع الملفات التي لا تتبع صيغة الفواصل المعتادة:++```python+class PriceSpider(CSVFeedSpider):+ name = "prices"+ start_urls = ["https://example.com/products.csv"]+ headers = ["title", "price", "url"]+ delimiter = ";"+```++تُفك الملفات المضغوطة باستخدام gzip تلقائيًا هنا أيضًا، كما سبق في **XMLFeedSpider**.++<a id="sitetomarkdownspider"></a>++## ContentSpider {#contentspider}++يعتمد `ContentSpider` على **CrawlSpider** لزيارة الموقع وتحويل كل صفحة إلى Markdown نظيف وجاهز لنماذج LLM. يُخرج عنصرًا لكل صفحة، ويمكنه أيضًا كتابة ملف Markdown منفصل لكل صفحة:++```python+from scrapling.spiders import ContentSpider++class DocsSpider(ContentSpider):+ name = "docs"+ start_urls = ["https://example.com/docs/"]+ allowed_domains = {"example.com"}+ output_dir = "docs_markdown"++result = DocsSpider().start()+```++يتطلب تحديد `allowed_domains` لحصر الزحف في الموقع المستهدف. تجد الدليل الكامل، بما فيه جميع الخيارات وكيفية استخدام النتائج في مسارات عمل RAG، في صفحة [بناء أنظمة RAG](../ai/building-rag-systems.md).++## استخدام `LinkExtractor` مباشرة {#using-linkextractor-directly}++لا يلزم استخدام القوالب. يعمل `LinkExtractor` داخل أي `Spider` عادي:++```python+from scrapling.spiders import Spider, LinkExtractor++class CustomSpider(Spider):+ name = "custom"+ start_urls = ["https://example.com"]++ def __init__(self):+ super().__init__()+ self._links = LinkExtractor(allow=r"/posts/", deny_domains="ads.example.com")++ async def parse(self, response):+ for url in self._links.extract(response):+ yield response.follow(url, callback=self.parse_post)++ async def parse_post(self, response):+ yield {"title": response.css("h1::text").get()}+```++## مرجع LinkExtractor {#linkextractor-reference}++| المعامل | القيمة الافتراضية | الوصف |+|---------|-------------------|-------|+| `allow` | `()` | أنماط عناوين URL المقبولة. القيمة الفارغة تعني قبول الجميع. يقبل نصًا أو `Pattern` جاهزًا أو iterable يحتوي على أي منهما |+| `deny` | `()` | أنماط عناوين URL المستبعدة. تتقدم دائمًا على `allow` |+| `allow_domains` | `()` | أسماء المضيفين المقبولة. تُقبل النطاقات الفرعية تلقائيًا، فـ `example.com` يقبل `api.example.com` |+| `deny_domains` | `()` | أسماء المضيفين المستبعدة |+| `restrict_css` | `()` | محددات CSS تحصر استخراج الروابط من DOM في جزء معين |+| `restrict_xpath` | `()` | محددات XPath تحصر استخراج الروابط من DOM في جزء معين |+| `tags` | `("a", "area")` | وسوم العناصر التي يُبحث فيها عن الروابط |+| `attrs` | `("href",)` | خصائص هذه الوسوم التي تُقرأ منها عناوين URL |+| `canonicalize` | `True` | ترتيب معاملات الاستعلام وتوحيد صيغة المسار |+| `strip` | `True` | إزالة المسافات البيضاء من أطراف عناوين URL المستخرجة |+| `keep_fragment` | `False` | الحفاظ على `#fragment` عند توحيد صيغة العنوان |+| `deny_extensions` | `IGNORED_EXTENSIONS` | امتدادات الملفات المستبعدة، مثل pdf وzip والصور والفيديو وغيرها |+| `process` | `None` | دالة اختيارية تُطبّق على كل عنوان مستخرج قبل تصفيته. أعد قيمة falsy، أي تُعامل كقيمة غير صحيحة، لاستبعاد العنوان |++تعيد `LinkExtractor.extract(response)` قائمة `list[str]` من عناوين URL الكاملة، بعد التصفيّة وإزالة التكرار.++تعيد `LinkExtractor.matches(url)` قيمة `bool`. وهي تطبّق تصفية العناوين فقط حسب allow وdeny والنطاق والامتداد. يستخدمها `SitemapSpider` لتوجيه العناوين دون الحاجة إلى `Response`.diff --git a/docs/locales/ar/spiders/getting-started.md b/docs/locales/ar/spiders/getting-started.mdnew file mode 100644index 0000000..96b394e--- /dev/null+++ b/docs/locales/ar/spiders/getting-started.md@@ -0,0 +1,199 @@+---+title: "أنشئ أول زاحف ويب باستخدام Python وScrapling"+description: "أنشئ عنكبوتًا يستخرج البيانات ويتابع الصفحات ويصدّر النتائج. تعرّف على عناوين البداية ودوال callback وحدود النطاقات وإعدادات robots.txt."+---++# البداية {#getting-started}++## مقدمة {#introduction}++!!! success "قبل البدء"++ 1. اقرأ صفحة [أساسيات أدوات الجلب](../fetching/choosing.md) لفهم أنواع أدوات الجلب المختلفة ومتى تستخدم كل نوع.+ 2. اقرأ صفحة [الكلاسات الأساسية](../parsing/main_classes.md) لفهم كلاس [Selector](../parsing/main_classes.md#selector) وكلاس [Response](../fetching/choosing.md#response-object).+ 3. اقرأ صفحة [البنية](architecture.md) للحصول على فكرة عامة عن عمل نظام العناكب.++يتيح لك نظام العناكب إنشاء زواحف لصفحات متعددة، مع تنفيذ طلبات متزامنة، في بضعة أسطر من الكود. إذا سبق لك استخدام Scrapy، فستجد الأنماط مألوفة. وإذا لم تستخدمه من قبل، فسيشرح لك هذا الدليل كل ما تحتاجه للبدء.++## أول عنكبوت لك {#your-first-spider}++العنكبوت هو كلاس يحدد كيفية تصفح المواقع واستخراج بياناتها. هذا أبسط مثال:++```python+from scrapling.spiders import Spider, Response++class QuotesSpider(Spider):+ name = "quotes"+ start_urls = ["https://quotes.toscrape.com"]++ async def parse(self, response: Response):+ for quote in response.css("div.quote"):+ yield {+ "text": quote.css("span.text::text").get(""),+ "author": quote.css("small.author::text").get(""),+ }+```++يحتاج كل عنكبوت إلى ثلاثة أشياء:++1. **`name`**: اسم يميّز العنكبوت عن غيره.+2. **`start_urls`**: قائمة عناوين URL التي يبدأ منها الزحف.+3. **`parse()`**: دالة async generator تعالج كل رد وتُخرج النتائج باستخدام `yield`.++تجري عملية الاستخراج داخل `parse()`. تستخدم فيها طرق الاختيار نفسها التي تستخدمها مع [Selector](../parsing/main_classes.md#selector) أو [Response](../fetching/choosing.md#response-object) في Scrapling، وتُخرج قواميس البيانات المستخرجة باستخدام `yield`.++## تشغيل العنكبوت {#running-the-spider}++لتشغيل العنكبوت، أنشئ كائنًا منه واستدعِ `start()`:++```python+result = QuotesSpider().start()+```++تدير `start()` كل ما يتعلق بالتشغيل غير المتزامن داخليًا، فلا تحتاج إلى إعداد event loop بنفسك. أثناء التشغيل، تُسجّل الأحداث في الطرفية، وتحصل عند انتهاء الزحف على إحصاءات مفصّلة جدًا.++توجد هذه الإحصاءات في كائن `CrawlResult` الذي تعيده الدالة، وهو يحتوي على كل ما تحتاجه:++```python+result = QuotesSpider().start()++# Access scraped items+for item in result.items:+ print(item["text"], "-", item["author"])++# Check statistics+print(f"Scraped {result.stats.items_scraped} items")+print(f"Made {result.stats.requests_count} requests")+print(f"Took {result.stats.elapsed_seconds:.1f} seconds")++# Did the crawl finish or was it paused?+print(f"Completed: {result.completed}")+```++## متابعة الروابط {#following-links}++تحتاج معظم عمليات الزحف إلى متابعة الروابط عبر عدة صفحات. استخدم `response.follow()` لإنشاء طلبات المتابعة:++```python+from scrapling.spiders import Spider, Response++class QuotesSpider(Spider):+ name = "quotes"+ start_urls = ["https://quotes.toscrape.com"]++ async def parse(self, response: Response):+ # Extract items from the current page+ for quote in response.css("div.quote"):+ yield {+ "text": quote.css("span.text::text").get(""),+ "author": quote.css("small.author::text").get(""),+ }++ # Follow the "next page" link+ next_page = response.css("li.next a::attr(href)").get()+ if next_page:+ yield response.follow(next_page, callback=self.parse)+```++تتعامل `response.follow()` مع عناوين URL النسبية تلقائيًا، وتدمجها مع عنوان الصفحة الحالية. كما تضبط ترويسة `Referer` على عنوان الصفحة الحالية افتراضيًا.++يمكنك اختيار دوال callback مختلفة لطلبات المتابعة حسب نوع الصفحة:++```python+async def parse(self, response: Response):+ for link in response.css("a.product-link::attr(href)").getall():+ yield response.follow(link, callback=self.parse_product)++async def parse_product(self, response: Response):+ yield {+ "name": response.css("h1::text").get(""),+ "price": response.css(".price::text").get(""),+ }+```++!!! note "ملاحظة"++ يجب أن تكون كل دوال callback من نوع async generator، أي تستخدم `async def` و`yield`.++## تصدير البيانات {#exporting-data}++تحتوي `ItemList` الموجودة في `result.items` على دوال تصدير مدمجة:++```python+result = QuotesSpider().start()++# Export as JSON+result.items.to_json("quotes.json")++# Export as JSON with pretty-printing+result.items.to_json("quotes.json", indent=True)++# Export as JSON Lines (one JSON object per line)+result.items.to_jsonl("quotes.jsonl")++# Export as CSV or XML+result.items.to_csv("quotes.csv")+result.items.to_xml("quotes.xml")+```++تنشئ كل هذه الدوال المجلدات التي يحتويها المسار تلقائيًا إذا لم تكن موجودة.++تكتب `to_csv()` عمودًا لكل مفتاح موجود في أي عنصر. لذلك تُصدّر العناصر حتى لو كانت مفاتيحها مختلفة، وتترك الخلايا التي لا تتوفر لها قيمة فارغة. استخدم `fields=[...]` لاختيار الأعمدة وترتيبها بنفسك، أو `delimiter="\t"` لإنشاء ملف TSV. تضع `to_xml()` كل عنصر بيانات داخل عنصر `<item>` ضمن الجذر `<items>`، ويمكن تغيير الاسمين باستخدام `root_tag` و`item_tag`.++في الصيغتين، تُكتب القيم التي ليست مفردة وبسيطة، مثل القواميس المتداخلة والقوائم، بصيغة JSON حتى لا تُحذف أي بيانات دون تنبيه.++## تحديد النطاقات المسموح بها {#filtering-domains}++استخدم `allowed_domains` لحصر الزحف في نطاقات محددة. يمنع ذلك العنكبوت من متابعة روابط مواقع خارجية دون قصد:++```python+class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]+ allowed_domains = {"example.com"}++ async def parse(self, response: Response):+ for link in response.css("a::attr(href)").getall():+ # Links to other domains are silently dropped+ yield response.follow(link, callback=self.parse)+```++تُقبل النطاقات الفرعية تلقائيًا. فمثلًا، يسمح `allowed_domains = {"example.com"}` أيضًا بالنطاقين `sub.example.com` و`blog.example.com` وغيرهما.++يُحسب كل طلب مستبعد في `stats.offsite_requests_count`، لتعرف عدد الطلبات التي استُبعدت.++## الالتزام بملف robots.txt {#robotstxt-compliance}++اضبط `robots_txt_obey = True` ليلتزم العنكبوت بقواعد robots.txt قبل الزحف إلى أي نطاق:++```python+class PoliteSpider(Spider):+ name = "polite"+ start_urls = ["https://example.com"]+ robots_txt_obey = True++ async def parse(self, response: Response):+ for link in response.css("a::attr(href)").getall():+ yield response.follow(link, callback=self.parse)+```++عند التفعيل، يقوم العنكبوت بما يلي:++1. **يجلب robots.txt مسبقًا** لكل نطاق في `start_urls` قبل بدء الزحف، مع جلب الملفات بالتزامن.+2. **يفحص كل طلب** وفقًا لقواعد `Disallow` في robots.txt الخاص بالنطاق. يتجاهل الطلبات غير المسموح بها دون رسالة، ويحسبها في `stats.robots_disallowed_count`.+3. **يلتزم بتوجيهات `Crawl-delay` و`Request-rate`** باختيار القيمة الأكبر بين فترة الانتظار المطلوبة و`download_delay` الذي حددته. لذلك لا تُنقص توجيهات robots.txt فترة الانتظار التي ضبطتها، بل تزيدها عند الحاجة فقط. عند تفعيل AutoThrottle، يضع الحد الأقصى له سقفًا لهذه القيمة أيضًا. اضبط `autothrottle_max_delay` على قيمة تكفي للالتزام بالانتظار المطلوب.++تُجلب ملفات robots.txt باستخدام الجلسة الافتراضية للعنكبوت، وتُحفظ لكل نطاق طوال عملية الزحف. إذا اكتشف العنكبوت نطاقًا أثناء الزحف لم يكن ضمن `start_urls`، يجلب robots.txt عند أول طلب لذلك النطاق.++**ملاحظة:** يكون `robots_txt_obey` غير مفعّل افتراضيًا لتجنب سلوك غير متوقع. تفعيله لا يغيّر إعدادات التزامن `concurrent_requests` و`concurrent_requests_per_domain`، بل يغيّر فترة الانتظار بين الطلبات فقط.++إذا لم ترد اختيار `download_delay` يدويًا، فاضبط `autothrottle_enabled = True`. سيعدّل العنكبوت فترة الانتظار لكل نطاق حسب سرعة ردوده، ويبطئ عند الحظر. انظر [AutoThrottle](advanced.md#autothrottle).++## الخطوة التالية {#whats-next}++بعد تعلّم الأساسيات، يمكنك قراءة:++- [الطلبات والردود](requests-responses.md): أولوية الطلبات ومنع التكرار والبيانات الإضافية وغيرها.+- [الجلسات](sessions.md): استخدام أدوات جلب مختلفة، مثل HTTP والمتصفح وStealth، داخل عنكبوت واحد.+- [إدارة البروكسي والتعامل مع الحظر](proxy-blocking.md): تبديل البروكسي بين الطلبات ومعالجة الحظر داخل العنكبوت.+- [الميزات المتقدمة](advanced.md): التحكم في التزامن وAutoThrottle والإيقاف المؤقت والاستكمال واستقبال البيانات أثناء الزحف ودوال مراحل التشغيل والسجلات.diff --git a/docs/locales/ar/spiders/platform-templates.md b/docs/locales/ar/spiders/platform-templates.mdnew file mode 100644index 0000000..d06d7ba--- /dev/null+++ b/docs/locales/ar/spiders/platform-templates.md@@ -0,0 +1,59 @@+---+title: "استخراج بيانات منتجات Shopify باستخدام Python"+description: "استخرج كتالوج متجر Shopify باستخدام ShopifySpider. حدد عنوان المتجر واجمع خيارات المنتجات وتعرّف على حقول كل عنصر."+---++# قوالب العناكب الخاصة بالمنصات {#platform-spider-templates}++تغطي القوالب العامة *أنماط الزحف*، مثل متابعة الروابط وقراءة خرائط الموقع. أما قوالب المنصات فتغطي *منصات إنشاء المواقع* التي تعرض بياناتها ببنية موحدة قابلة للقراءة برمجيًا عبر مواقع مستقلة كثيرة. لذلك يعرف العنكبوت مسبقًا أين توجد البيانات، وكل ما عليك هو تحديد النطاق.++## ShopifySpider {#shopifyspider}++يستخرج `ShopifySpider` جميع المنتجات من أي متجر يعمل على Shopify باستخدام JSON API الخاص بالمنصة، دون قراءة HTML الموقع.++```python+from scrapling.spiders import ShopifySpider++class MyStore(ShopifySpider):+ target_website = "example.com"++result = MyStore().start()+print(result.items[0])+```++اضبط `target_website` على نطاق المتجر. إذا كان فارغًا، يستخدم العنكبوت أول قيمة في `start_urls`، ثم `allowed_domains`. ويرفع `ValueError` إذا كانت القيم الثلاث كلها فارغة. إذا أعطيته URL كاملًا، يستخرج النطاق منه تلقائيًا.++### كيف يعمل {#how-it-works}++1. يقرأ صفحات `https://<store>/collections.json`، بحد أقصى 250 مجموعة في الصفحة، وهو الحد الذي تضعه المنصة.+2. لكل مجموعة تشير إلى وجود منتجات فيها، يقرأ صفحات `/collections/<handle>/products.json`.+3. يُخرج عنصرًا لكل خيار منتج، أي variant، ويمنع تكرار الخيارات التي تظهر في أكثر من مجموعة.++### حقول البيانات {#item-fields}++| الحقل | المصدر |+|-------|--------|+| `name` | اسم المنتج، مع اسم الخيار إذا لم يكن الخيار الافتراضي |+| `price` | سعر الخيار كنص، تمامًا كما تعيده Shopify |+| `category` | معرّف المجموعة مع تحويل بداية كل كلمة إلى حرف كبير، مثل `summer-sale` الذي يصبح `Summer Sale` |+| `brand` | بائع المنتج |+| `identifier` | معرّف خيار المنتج |+| `sku` | قيمة SKU للخيار، أو `""` إذا لم يحددها المتجر |+| `stock` | القيمة `None` إذا كان الخيار متوفرًا، و`0` إذا نفد المخزون |+| `image_url` | صورة المنتج الأولى، أو `""` |+| `url` | صفحة المنتج داخل المجموعة |+| `description` | محتوى `body_html` للمنتج بعد إزالة وسوم HTML |+| `old_price` | قيمة `compare_at_price` إذا كانت سعرًا فعليًا قبل التخفيض، وإلا `""` |+| `barcode` | باركود الخيار، أو `""`، لأن معظم المتاجر لا تعرضه في هذه المسارات |++هذه الحقول ليست إلزامية. أعد تعريف `_process_product()` في الكلاس الذي يرث من القالب لتغيير بنية العنصر أو استخراج حقول أخرى من بيانات المنتج.++### ملاحظات وحدود {#notes-and-limits}++- تعرض مسارات JSON المنتجات المنشورة على قناة المتجر الإلكتروني فقط. لذلك قد تكون قيمة `products_count` للمجموعة أكبر من عدد المنتجات الذي يمكن جلبه فعليًا. يستخدم العنكبوت هذه القيمة فقط ليقرر جلب المجموعة إذا كانت غير صفرية، ولا يتعامل معها كعدد متوقع للنتائج.+- غالبًا لن يعمل هذا القالب مع المتاجر التي تستخدم حماية إضافية أو كلمة مرور. وحتى إذا أمكن تشغيله، فقد تحتاج إلى إعادة تعريف أجزاء كثيرة منه.+- تظل كل ميزات `Spider` متاحة، بما فيها إعدادات التزامن وفترات الانتظار والالتزام بـ robots.txt ونقاط الاستكمال ودوال مراحل التشغيل.++### ما الذي يصلح ليكون قالب منصة {#what-qualifies-as-a-platform-template}++تُقبل قوالب المنصات التي تعرض بيانات ببنية موحدة قابلة للقراءة برمجيًا عبر مواقع مستقلة كثيرة، مثل Shopify. أما العناكب المخصّصة لموقع واحد فلا مكان لها في المكتبة، مهما كانت شهرة الموقع.diff --git a/docs/locales/ar/spiders/proxy-blocking.md b/docs/locales/ar/spiders/proxy-blocking.mdnew file mode 100644index 0000000..9dbdbf2--- /dev/null+++ b/docs/locales/ar/spiders/proxy-blocking.md@@ -0,0 +1,247 @@+---+title: "تبديل البروكسي وإعادة طلبات الزحف المحظورة"+description: "استخدم البروكسي واستراتيجيات تبديله في عناكب Scrapling. اكتشف الردود المحظورة وأعد الطلبات وانتقل من جلسات HTTP إلى جلسات المتصفح."+---++# إدارة البروكسي والتعامل مع الحظر {#proxy-management-and-handling-blocks}++## مقدمة {#introduction}++!!! success "قبل البدء"++ 1. اقرأ صفحة [البداية](getting-started.md) وتعرّف على إنشاء عنكبوت بسيط وتشغيله.+ 2. اقرأ صفحة [الجلسات](sessions.md) وتعرّف على كيفية إعدادها.++عند استخراج البيانات على نطاق واسع، قد تحتاج إلى التبديل بين عدة خوادم بروكسي لتجنب حدود معدل الطلبات والحظر. يجعل `ProxyRotator` في Scrapling هذا الأمر سهلًا. يعمل مع جميع أنواع الجلسات، ويتكامل مع نظام إعادة الطلبات المحظورة في العنكبوت.++إذا لم تكن تعرف ما هو البروكسي أو كيف تختار بروكسي جيدًا، فيمكن أن يساعدك [هذا الدليل](https://substack.thewebscraping.club/p/everything-about-proxies).++## ProxyRotator {#proxyrotator}++يدير الكلاس `ProxyRotator` قائمة خوادم البروكسي ويبدّل بينها تلقائيًا. مرّره إلى أي نوع جلسة عبر المعامل `proxy_rotator`:++```python+from scrapling.spiders import Spider, Response+from scrapling.fetchers import FetcherSession, ProxyRotator++class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]++ def configure_sessions(self, manager):+ rotator = ProxyRotator([+ "http://proxy1:8080",+ "http://proxy2:8080",+ "http://user:pass@proxy3:8080",+ ])+ manager.add("default", FetcherSession(proxy_rotator=rotator))++ async def parse(self, response: Response):+ # Check which proxy was used+ print(f"Proxy used: {response.meta.get('proxy')}")+ yield {"title": response.css("title::text").get("")}+```++يحصل كل طلب تلقائيًا على البروكسي التالي في الترتيب. يُحفظ البروكسي المستخدم في `response.meta["proxy"]`، لتعرف أي بروكسي جلب كل صفحة.++عند استخدامه مع جلسات المتصفح، تحتاج إلى بعض التعديلات، كما في المثال التالي:++```python+from scrapling.fetchers import AsyncStealthySession, ProxyRotator++# String proxies work for all session types+rotator = ProxyRotator([+ "http://proxy1:8080",+ "http://proxy2:8080",+])++# Dict proxies (Playwright format) work for browser sessions+rotator = ProxyRotator([+ {"server": "http://proxy1:8080", "username": "user", "password": "pass"},+ {"server": "http://proxy2:8080"},+])++# Then inside the spider+def configure_sessions(self, manager):+ rotator = ProxyRotator(["http://proxy1:8080", "http://proxy2:8080"])+ manager.add("browser", AsyncStealthySession(proxy_rotator=rotator))+```++!!! info "معلومة"++ 1. لا يمكنك استخدام `proxy_rotator` مع `proxy` أو `proxies` الثابتة في الجلسة نفسها. اختر طريقة واحدة عند إعداد الجلسة، ويمكنك تغيير البروكسي لطلبات محددة لاحقًا، كما سنوضح.+ 2. تذكّر أن كل جلسات المتصفح تستخدم افتراضيًا سياق متصفح دائمًا مع مجموعة تبويبات. لكن المتصفحات لا تتيح تحديد بروكسي لكل تبويب. لذلك، عند استخدام `ProxyRotator`، تنشئ أداة الجلب سياقًا منفصلًا لكل بروكسي، مع تبويب واحد لكل سياق. وبمجرد انتهاء عمل التبويب، يُغلق هو وسياقه.++## استراتيجيات تبديل مخصّصة {#custom-rotation-strategies}++يستخدم `ProxyRotator` التبديل الدوري افتراضيًا، فيمرّ على البروكسي بالترتيب ثم يعود إلى البداية بعد آخر واحد.++يمكنك تمرير دالة استراتيجية مخصّصة لتغيير هذا السلوك، لكن يجب أن تلتزم بالتوقيع التالي:++```python+from scrapling.core._types import ProxyType++def my_strategy(proxies: list, current_index: int) -> tuple[ProxyType, int]:+ ...+```++تستقبل الدالة قائمة البروكسي والفهرس الحالي، ويجب أن تعيد البروكسي المختار والفهرس التالي.++فيما يلي بعض أمثلة استراتيجيات التبديل المخصّصة التي يمكنك استخدامها.++### التبديل العشوائي {#random-rotation}++```python+import random+from scrapling.fetchers import ProxyRotator++def random_strategy(proxies, current_index):+ idx = random.randint(0, len(proxies) - 1)+ return proxies[idx], idx++rotator = ProxyRotator(+ ["http://proxy1:8080", "http://proxy2:8080", "http://proxy3:8080"],+ strategy=random_strategy,+)+```++### التبديل حسب الأوزان {#weighted-rotation}++```python+import random++def weighted_strategy(proxies, current_index):+ # First proxy gets 60% of traffic, others split the rest+ weights = [60] + [40 // (len(proxies) - 1)] * (len(proxies) - 1)+ proxy = random.choices(proxies, weights=weights, k=1)[0]+ return proxy, current_index # Index doesn't matter for weighted++rotator = ProxyRotator(proxies, strategy=weighted_strategy)+```++## تغيير البروكسي لطلب محدد {#per-request-proxy-override}++يمكنك تجاوز اختيار `ProxyRotator` لطلب معين بتمرير `proxy=` كمعامل مسمّى:++```python+async def parse(self, response: Response):+ # This request uses the rotator's next proxy+ yield response.follow("/page1", callback=self.parse_page)++ # This request uses a specific proxy, bypassing the rotator+ yield response.follow(+ "/special-page",+ callback=self.parse_page,+ proxy="http://special-proxy:8080",+ )+```++يفيد ذلك عندما تحتاج صفحات معينة إلى بروكسي محدد، مثل بروكسي من بلد معين للوصول إلى محتوى خاص بتلك المنطقة.++## التعامل مع الطلبات المحظورة {#blocked-request-handling}++يحتوي العنكبوت على دعم مدمج لاكتشاف الطلبات المحظورة وإعادتها. يعتبر رموز حالة HTTP التالية حظرًا افتراضيًا: `401` و`403` و`407` و`429` و`444` و`500` و`502` و`503` و`504`.++يعمل نظام إعادة المحاولة كما يلي:++1. بعد وصول الرد، يستدعي العنكبوت `is_blocked(response)`.+2. إذا كان الطلب محظورًا، ينسخ الطلب ويستدعي `retry_blocked_request()`، لتتمكن من تعديله قبل إعادة المحاولة.+3. يُعاد الطلب إلى الطابور مع `dont_filter=True` لتجاوز منع التكرار، وبأولوية أقل حتى لا يُعاد فورًا.+4. تتكرر العملية حتى `max_blocked_retries` مرة، والقيمة الافتراضية هي 3.++!!! tip "نصيحة"++ 1. عند إعادة المحاولة، تُحذف قيم `proxy` و`proxies` السابقة من معاملات الطلب تلقائيًا، ليختار `ProxyRotator` بروكسي جديدًا.+ 2. تختلف الخاصية `max_blocked_retries` عن محاولات الإعادة داخل الجلسة، ولا تشاركها عداد المحاولات.++### تخصيص اكتشاف الحظر {#custom-block-detection}++أعد تعريف `is_blocked()` لإضافة طريقة اكتشاف خاصة بك:++```python+class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]++ async def is_blocked(self, response: Response) -> bool:+ # Check status codes (default behavior)+ if response.status in {403, 429, 503}:+ return True++ # Check response content+ body = response.body.decode("utf-8", errors="ignore")+ if "access denied" in body.lower() or "rate limit" in body.lower():+ return True++ return False++ async def parse(self, response: Response):+ yield {"title": response.css("title::text").get("")}+```++### تخصيص إعادة المحاولة {#customizing-retries}++أعد تعريف `retry_blocked_request()` لتعديل الطلب قبل إعادته. تحدد `max_blocked_retries` عدد مرات إعادة الطلب المحظور، وقيمتها الافتراضية هي 3:++```python+from scrapling.spiders import Spider, SessionManager, Request, Response+from scrapling.fetchers import FetcherSession, AsyncStealthySession+++class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]+ max_blocked_retries = 5++ def configure_sessions(self, manager: SessionManager) -> None:+ manager.add('requests', FetcherSession(impersonate=['chrome', 'firefox', 'safari']))+ manager.add('stealth', AsyncStealthySession(block_webrtc=True), lazy=True)++ async def retry_blocked_request(self, request: Request, response: Response) -> Request:+ request.sid = "stealth"+ self.logger.info(f"Retrying blocked request: {request.url}")+ return request++ async def parse(self, response: Response):+ yield {"title": response.css("title::text").get("")}+```++في المثال السابق، تركت طريقة اكتشاف الحظر كما هي، وجعلت العنكبوت يعتمد على طلبات HTTP حتى يُحظر، ثم ينتقل إلى متصفح Stealth.++هذا مثال يجمع كل ما سبق:++```python+from scrapling.spiders import Spider, SessionManager, Request, Response+from scrapling.fetchers import FetcherSession, AsyncStealthySession, ProxyRotator+++cheap_proxies = ProxyRotator([ "http://proxy1:8080", "http://proxy2:8080"])++# A format acceptable by the browser+expensive_proxies = ProxyRotator([+ {"server": "http://residential_proxy1:8080", "username": "user", "password": "pass"},+ {"server": "http://residential_proxy2:8080", "username": "user", "password": "pass"},+ {"server": "http://mobile_proxy1:8080", "username": "user", "password": "pass"},+ {"server": "http://mobile_proxy2:8080", "username": "user", "password": "pass"},+])+++class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]+ max_blocked_retries = 5++ def configure_sessions(self, manager: SessionManager) -> None:+ manager.add('requests', FetcherSession(impersonate=['chrome', 'firefox', 'safari'], proxy_rotator=cheap_proxies))+ manager.add('stealth', AsyncStealthySession(block_webrtc=True, proxy_rotator=expensive_proxies), lazy=True)++ async def retry_blocked_request(self, request: Request, response: Response) -> Request:+ request.sid = "stealth"+ self.logger.info(f"Retrying blocked request: {request.url}")+ return request++ async def parse(self, response: Response):+ yield {"title": response.css("title::text").get("")}+```++الفكرة هنا هي إرسال الطلبات ببروكسي منخفض التكلفة، مثل بروكسي مراكز البيانات، حتى تُحظر. ثم تُعاد باستخدام بروكسي أعلى جودة، مثل البروكسي السكني أو بروكسي شبكات الهاتف المحمول.diff --git a/docs/locales/ar/spiders/requests-responses.md b/docs/locales/ar/spiders/requests-responses.mdnew file mode 100644index 0000000..b5c2923--- /dev/null+++ b/docs/locales/ar/spiders/requests-responses.md@@ -0,0 +1,207 @@+---+title: "طلبات العناكب ودوال callback واستخدام Response.follow"+description: "أنشئ طلبات الزحف ومرّر البيانات الإضافية وتابع الروابط عبر response.follow. تعرّف على دوال callback والأولويات ومنع تكرار الطلبات."+---++# الطلبات والردود {#requests-responses}++!!! success "قبل البدء"++ 1. اقرأ صفحة [البداية](getting-started.md) وتعرّف على إنشاء عنكبوت بسيط وتشغيله.++تشرح هذه الصفحة كائن `Request` بالتفصيل: إنشاء الطلبات، وتمرير البيانات بين دوال callback، والتحكم في الأولوية ومنع التكرار، واستخدام `response.follow()` لمتابعة الروابط.++## كائن Request {#the-request-object}++يمثل `Request` عنوان URL تريد جلبه. يمكنك إنشاء الطلب مباشرة أو عبر `response.follow()`:++```python+from scrapling.spiders import Request++# Direct construction+request = Request(+ "https://example.com/page",+ callback=self.parse_page,+ priority=5,+)++# Via response.follow (preferred in callbacks)+request = response.follow("/page", callback=self.parse_page)+```++هذه هي جميع المعاملات التي يمكنك تمريرها إلى `Request`:++| المعامل | النوع | القيمة الافتراضية | الوصف |+|---------|-------|-------------------|-------|+| `url` | `str` | *مطلوب* | عنوان URL المراد جلبه |+| `sid` | `str` | `""` | معرّف الجلسة، ويوجّه الطلب إلى جلسة محددة. انظر [الجلسات](sessions.md) |+| `callback` | `callable` | `None` | دالة async generator لمعالجة الرد. تكون `parse()` افتراضيًا |+| `priority` | `int` | `0` | تُعالج القيم الأعلى أولًا |+| `dont_filter` | `bool` | `False` | عند `True`، يتجاوز منع التكرار ويسمح بالطلبات المكررة |+| `meta` | `dict` | `{}` | بيانات إضافية تختارها وتنتقل إلى الرد |+| `**kwargs` | | | معاملات مسماة إضافية تُمرّر إلى دالة الجلب في الجلسة، مثل `headers` و`method` و`data` |++تُمرّر أي معاملات مسماة إضافية مباشرة إلى الجلسة المستخدمة. مثلًا، لإرسال طلب POST:++```python+yield Request(+ "https://example.com/api",+ method="POST",+ data={"key": "value"},+ callback=self.parse_result,+)+```++## Response.follow() {#responsefollow}++الطريقة الموصى بها لإنشاء طلبات المتابعة داخل دوال callback هي `response.follow()`. وهي توفر مزايا عديدة مقارنة بإنشاء كائنات `Request` مباشرة:++- **عناوين URL النسبية** تُكمّل تلقائيًا باستخدام عنوان الصفحة الحالية.+- **ترويسة Referer** تُضبط افتراضيًا على عنوان الصفحة الحالية.+- **معاملات الجلسة** تُورث من الطلب الأصلي، مثل الترويسات وإعدادات البروكسي. تُستثنى `method` و`params` و`data` و`json` و`files` و`multipart`، حتى تكون متابعة الروابط بطلبات GET عادية.+- **دالة callback ومعرّف الجلسة والأولوية** تُورث من الطلب الأصلي إذا لم تحدد قيمًا جديدة لها.++```python+async def parse(self, response: Response):+ # Minimal - inherits callback, sid, priority from current request+ yield response.follow("/next-page")++ # Override specific fields+ yield response.follow(+ "/product/123",+ callback=self.parse_product,+ priority=10,+ )++ # Pass additional metadata to+ yield response.follow(+ "/details",+ callback=self.parse_details,+ meta={"category": "electronics"},+ )+```++| المعامل | النوع | القيمة الافتراضية | الوصف |+|---------|-------|-------------------|-------|+| `url` | `str` | *مطلوب* | عنوان URL المراد متابعته، سواء كان كاملًا أو نسبيًا |+| `sid` | `str` | `""` | معرّف الجلسة. يُورث من الطلب الأصلي إذا كان فارغًا |+| `callback` | `callable` | `None` | دالة callback. تُورث من الطلب الأصلي إذا كانت `None` |+| `priority` | `int` | `None` | الأولوية. تُورث من الطلب الأصلي إذا كانت `None` |+| `dont_filter` | `bool` | `False` | تجاوز منع التكرار |+| `meta` | `dict` | `None` | بيانات إضافية تُدمج مع `meta` الموجودة في الرد |+| **`referer_flow`** | `bool` | `True` | استخدام عنوان الصفحة الحالية كترويسة Referer |+| `**kwargs` | | | تُدمج مع معاملات الجلسة في الطلب الأصلي |++### تعطيل تمرير Referer {#disabling-referer-flow}++تضبط `response.follow()` ترويسة `Referer` على عنوان الصفحة الحالية افتراضيًا. لتعطيل ذلك:++```python+yield response.follow("/page", referer_flow=False)+```++## دوال callback {#callbacks}++دوال callback هي دوال async generator في العنكبوت، وتُستخدم لمعالجة الردود. يجب أن تُخرج باستخدام `yield` أحد الأنواع الثلاثة التالية:++- **`dict`**: عنصر بيانات مستخرج يُضاف إلى النتائج.+- **`Request`**: طلب متابعة يُضاف إلى الطابور.+- **`None`**: تُتجاهل دون رسالة.++```python+class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]++ async def parse(self, response: Response):+ # Yield items (dicts)+ yield {"url": response.url, "title": response.css("title::text").get("")}++ # Yield follow-up requests+ for link in response.css("a::attr(href)").getall():+ yield response.follow(link, callback=self.parse_page)++ async def parse_page(self, response: Response):+ yield {"content": response.css("article::text").get("")}+```++!!! tip "ملاحظة"++ يجب تعريف كل دوال callback باستخدام `async def`، واستخدام `yield` فيها بدلًا من `return`. حتى إذا كانت الدالة تُخرج بيانات فقط دون طلبات متابعة، فيجب أن تظل async generator.++## أولوية الطلبات {#request-priority}++تُعالج الطلبات ذات الأولوية الأعلى أولًا. يفيد ذلك عندما تكون بعض الصفحات أهم وتريد معالجتها قبل غيرها:++```python+async def parse(self, response: Response):+ # High priority - process product pages first+ for link in response.css("a.product::attr(href)").getall():+ yield response.follow(link, callback=self.parse_product, priority=10)++ # Low priority - pagination links processed after products+ next_page = response.css("a.next::attr(href)").get()+ if next_page:+ yield response.follow(next_page, callback=self.parse, priority=0)+```++عند استخدام `response.follow()`، تُورث الأولوية من الطلب الأصلي ما لم تحدد قيمة جديدة.++## منع التكرار {#deduplication}++يمنع العنكبوت تكرار الطلبات تلقائيًا باستخدام بصمة تُحسب من عنوان URL وطريقة HTTP ومحتوى الطلب ومعرّف الجلسة. إذا أعطى طلبان البصمة نفسها، يُتجاهل الثاني دون رسالة.++للسماح بطلبات مكررة، مثل إعادة زيارة صفحة بعد تسجيل الدخول، اضبط `dont_filter=True`:++```python+yield Request("https://example.com/dashboard", dont_filter=True, callback=self.parse_dashboard)++# Or with response.follow+yield response.follow("/dashboard", dont_filter=True, callback=self.parse_dashboard)+```++يمكنك تحديد ما يدخل في حساب البصمة باستخدام خصائص الكلاس التالية في العنكبوت:++| الخاصية | القيمة الافتراضية | التأثير |+|---------|-------------------|---------|+| `fp_include_kwargs` | `False` | إضافة معاملات الطلب الإضافية إلى البصمة، أي المعاملات التي مرّرتها إلى دالة الجلب في الجلسة، مثل الترويسات |+| `fp_keep_fragments` | `False` | إبقاء جزء URL الذي يبدأ بـ `#`، مثل `#section`، عند حساب البصمة |+| `fp_include_headers` | `False` | إضافة ترويسات الطلب إلى البصمة |++مثلًا، إذا أردت التعامل مع `https://example.com/page#section1` و`https://example.com/page#section2` كعنوانين مختلفين:++```python+class MySpider(Spider):+ name = "my_spider"+ fp_keep_fragments = True+ # ...+```++## بيانات الطلب الإضافية {#request-meta}++يتيح قاموس `meta` تمرير أي بيانات تختارها بين دوال callback. يفيد ذلك عندما تحتاج معلومات من صفحة لمعالجة صفحة أخرى:++```python+async def parse(self, response: Response):+ for product in response.css("div.product"):+ category = product.css("span.category::text").get("")+ link = product.css("a::attr(href)").get()+ if link:+ yield response.follow(+ link,+ callback=self.parse_product,+ meta={"category": category},+ )++async def parse_product(self, response: Response):+ yield {+ "name": response.css("h1::text").get(""),+ "price": response.css(".price::text").get(""),+ # Access meta from the request+ "category": response.meta.get("category", ""),+ }+```++عند استخدام `response.follow()`، تُدمج `meta` من الرد الحالي مع البيانات الجديدة التي تمرّرها. إذا تكرر مفتاح، تُستخدم القيمة الجديدة.++يحفظ نظام العناكب بعض البيانات الإضافية تلقائيًا أيضًا. مثلًا، عند تفعيل تبديل البروكسي، يمكنك معرفة البروكسي المستخدم للطلب من `response.meta["proxy"]`.diff --git a/docs/locales/ar/spiders/sessions.md b/docs/locales/ar/spiders/sessions.mdnew file mode 100644index 0000000..4b45dbb--- /dev/null+++ b/docs/locales/ar/spiders/sessions.md@@ -0,0 +1,230 @@+---+title: "استخدام جلسات HTTP والمتصفح في زاحف واحد"+description: "أعدّ جلسات بأسماء ووجّه طلبات العنكبوت إلى أدوات جلب HTTP أو المتصفح. أعد استخدام ملفات تعريف الارتباط وشغّل الجلسات عند الحاجة وافحص سجل ردود API."+---++# جلسات العناكب {#spiders-sessions}++!!! success "قبل البدء"++ 1. اقرأ صفحة [البداية](getting-started.md) وتعرّف على إنشاء عنكبوت بسيط وتشغيله.+ 2. تعرّف على [أساسيات أدوات الجلب](../fetching/choosing.md) والفرق بين جلسات HTTP وجلسات Stealthy.++يمكن للعنكبوت استخدام عدة جلسات جلب في الوقت نفسه. مثلًا، جلسة HTTP سريعة للصفحات البسيطة، وجلسة متصفح Stealth للصفحات المحمية. تشرح هذه الصفحة كيفية إعداد الجلسات واستخدامها.++## ما هي الجلسات؟ {#what-are-sessions}++الجلسة هي كائن جلب بإعدادات جاهزة يظل يعمل طوال عملية الزحف. يعيد العنكبوت استخدام الجلسات بدلًا من إنشاء اتصال أو متصفح جديد لكل طلب، مما يزيد السرعة ويقلل استهلاك الموارد.++ينشئ كل عنكبوت جلسة [FetcherSession](../fetching/static.md) واحدة افتراضيًا. يمكنك إضافة جلسات أو تغيير الجلسة الافتراضية بإعادة تعريف `configure_sessions()`، لكن يجب استخدام النسخة غير المتزامنة فقط من كل نوع، كما يوضح الجدول:++| نوع الجلسة | الاستخدام |+|------------|-----------|+| [FetcherSession](../fetching/static.md) | طلبات HTTP سريعة دون JavaScript |+| [AsyncStealthySession](../fetching/stealthy.md) | تشغيل JavaScript، والتحكم الآلي في المتصفح، وتجاوز أنظمة مكافحة البوتات |++## إعداد الجلسات {#configuring-sessions}++أعد تعريف `configure_sessions()` في العنكبوت لإعداد الجلسات. المعامل `manager` هو كائن `SessionManager`. استخدم `manager.add()` لتسجيل الجلسات:++```python+from scrapling.spiders import Spider, Response+from scrapling.fetchers import FetcherSession++class MySpider(Spider):+ name = "my_spider"+ start_urls = ["https://example.com"]++ def configure_sessions(self, manager):+ manager.add("default", FetcherSession())++ async def parse(self, response: Response):+ yield {"title": response.css("title::text").get("")}+```++تقبل `manager.add()` المعاملات التالية:++| المعامل | النوع | القيمة الافتراضية | الوصف |+|---------|-------|-------------------|-------|+| `session_id` | `str` | *مطلوب* | اسم لاختيار الجلسة في الطلبات |+| `session` | `Session` | *مطلوب* | كائن الجلسة |+| `default` | `bool` | `False` | جعل هذه الجلسة هي الافتراضية |+| `lazy` | `bool` | `False` | تشغيل الجلسة عند أول استخدام فقط |++!!! note "ملاحظات"++ 1. إذا لم تحدد جلسة في الطلب، تُستخدم الجلسة الافتراضية. تُحدد هذه الجلسة بإحدى طريقتين:+ 1. تصبح أول جلسة تضيفها إلى المدير هي الافتراضية تلقائيًا.+ 2. تصبح الجلسة التي تضيفها مع `default=True` هي الافتراضية.+ 2. لا تحتاج إلى تشغيل كائنات الجلسات قبل إضافتها. يفحص العنكبوت الجلسات ويشغّل كل جلسة لم تبدأ بعد.+ 3. إذا أردت تشغيل جلسة عند الحاجة فقط، فاستخدم `lazy` عند إضافتها إلى المدير. مثلًا، يمكنك تأخير تشغيل المتصفح حتى تحتاجه، بدلًا من تشغيله مع بداية العنكبوت.++## عنكبوت بجلسات متعددة {#multi-session-spider}++هذا مثال عملي يستخدم جلسة HTTP سريعة لصفحات القوائم، ومتصفح Stealth لصفحات التفاصيل التي تستخدم حماية ضد البوتات:++```python+from scrapling.spiders import Spider, Response+from scrapling.fetchers import FetcherSession, AsyncStealthySession++class ProductSpider(Spider):+ name = "products"+ start_urls = ["https://shop.example.com/products"]++ def configure_sessions(self, manager):+ # Fast HTTP for listing pages (default)+ manager.add("http", FetcherSession())++ self.browser_session = AsyncStealthySession(+ headless=True,+ network_idle=True,+ record_requests=True,+ )+ manager.add("stealth", self.browser_session)++ async def parse(self, response: Response):+ for link in response.css("a.product::attr(href)").getall():+ # Route product pages through the stealth session+ yield response.follow(link, sid="stealth", callback=self.parse_product)++ next_page = response.css("a.next::attr(href)").get()+ if next_page:+ yield response.follow(next_page)++ async def parse_product(self, response: Response):+ yield {+ "name": response.css("h1::text").get(""),+ "price": response.css(".price::text").get(""),+ }++ async def on_close(self):+ for api_response in self.browser_session.network.search(+ url_pattern=r"https://api\.shop\.example\.com/.*", limit=None+ ):+ self.logger.info(f"Saved API response: {api_response.url} ({api_response.status})")+```++يحتفظ المثال بكائن المتصفح، ويقرأ سجل ردود API المحفوظ مرة واحدة داخل `on_close()` قبل إغلاق الجلسات. يشمل السجل جميع صفحات المنتجات، ويظل قابلًا للقراءة بعد الإغلاق. لا ينتظر الكود عمليات التسجيل التي لم تكتمل بعد، وتظل حدود الاحتفاظ بالسجل مطبّقة.++المعامل الأساسي هنا هو `sid`، فهو يحدد الجلسة المستخدمة لكل طلب. عند استدعاء `response.follow()` دون `sid`، يُورث معرّف الجلسة من الطلب الأصلي.++لا يلزم أن تكون الجلسات من كلاسات مختلفة. يمكن إنشاء عدة كائنات من كلاس الجلسة نفسه، بإعدادات مختلفة، كما في المثال التالي:++```python+from scrapling.spiders import Spider, Response+from scrapling.fetchers import FetcherSession++class ProductSpider(Spider):+ name = "products"+ start_urls = ["https://shop.example.com/products"]++ def configure_sessions(self, manager):+ chrome_requests = FetcherSession(impersonate="chrome")+ firefox_requests = FetcherSession(impersonate="firefox")++ manager.add("chrome", chrome_requests)+ manager.add("firefox", firefox_requests)++ async def parse(self, response: Response):+ for link in response.css("a.product::attr(href)").getall():+ yield response.follow(link, callback=self.parse_product)++ next_page = response.css("a.next::attr(href)").get()+ if next_page:+ yield response.follow(next_page, sid="firefox")++ async def parse_product(self, response: Response):+ yield {+ "name": response.css("h1::text").get(""),+ "price": response.css(".price::text").get(""),+ }+```++ويمكنك أيضًا تخصيص جلسة بطلبات معينة، بحيث تحتفظ بملفات تعريف الارتباط والحالة الخاصة بهذه الطلبات، وغير ذلك.++## معاملات الجلسة {#session-arguments}++تُمرّر المعاملات المسماة الإضافية التي تضعها في `Request`، أو في `response.follow(**kwargs)`، إلى دالة الجلب في الجلسة. يتيح ذلك تخصيص كل طلب دون تغيير إعدادات الجلسة:++```python+async def parse(self, response: Response):+ # Pass extra headers for this specific request+ yield Request(+ "https://api.example.com/data",+ headers={"Authorization": "Bearer token123"},+ callback=self.parse_api,+ )++ # Use a different HTTP method+ yield Request(+ "https://example.com/submit",+ method="POST",+ data={"field": "value"},+ sid="firefox",+ callback=self.parse_result,+ )+```++!!! warning "تنبيه"++ عند استخدام `FetcherSession` أو `Fetcher` أو `AsyncFetcher` عادةً، تختار طريقة HTTP باستدعاء الدالة المناسبة مثل `.get()` أو `.post()`. لكن هذا لا ينطبق على `FetcherSession` داخل العناكب. يكون الطلب افتراضيًا من نوع _HTTP GET_. لاستخدام طريقة أخرى، مرّرها إلى المعامل `method` كما في المثال السابق. الهدف هو توحيد واجهة `Request` بين جميع أنواع الجلسات.++بعد تسجيل جلسة `"stealth"` من نوع `AsyncStealthySession` كما في مثال الجلسات المتعددة، يمكنك تمرير معاملات خاصة بالمتصفح، مثل `wait_selector` و`page_action` و`extra_headers`:++```python+async def parse(self, response: Response):+ # Use Cloudflare solver with the `AsyncStealthySession` we configured above+ yield Request(+ "https://nopecha.com/demo/cloudflare",+ sid="stealth",+ callback=self.parse_result,+ solve_cloudflare=True,+ block_webrtc=True,+ hide_canvas=True,+ google_search=True,+ )++ yield response.follow(+ "/dynamic-page",+ sid="stealth",+ callback=self.parse_dynamic,+ wait_selector="div.loaded",+ network_idle=True,+ )+```++!!! warning "تنبيه"++ ترث `response.follow()` معاملات الجلسة `**kwargs` من الطلب الأصلي، باستثناء `method` و`params` و`data` و`json` و`files` و`multipart`. لذلك تؤدي متابعة رابط بعد طلب POST إلى إرسال GET عادي. تتقدم المعاملات الجديدة على المعاملات الموروثة إذا تكرر الاسم.++```python+from scrapling.spiders import Spider, Response+from scrapling.fetchers import FetcherSession++class ProductSpider(Spider):+ name = "products"+ start_urls = ["https://shop.example.com/products"]++ def configure_sessions(self, manager):+ manager.add("http", FetcherSession(impersonate='chrome'))++ async def parse(self, response: Response):+ # I don't want the follow request to impersonate a desktop Chrome like the previous request, but a mobile one+ # so I override it like this+ for link in response.css("a.product::attr(href)").getall():+ yield response.follow(link, impersonate="chrome131_android", callback=self.parse_product)++ next_page = response.css("a.next::attr(href)").get()+ if next_page:+ yield response.follow(next_page)++ async def parse_product(self, response: Response):+ yield {+ "name": response.css("h1::text").get(""),+ "price": response.css(".price::text").get(""),+ }+```++!!! info "معلومة"++ عند إغلاق العنكبوت، يفحص مدير الجلسات تلقائيًا أي جلسات لا تزال تعمل ويغلقها قبل إغلاق العنكبوت.diff --git a/docs/locales/ar/stylesheets b/docs/locales/ar/stylesheetsnew file mode 120000index 0000000..02c6ba6--- /dev/null+++ b/docs/locales/ar/stylesheets@@ -0,0 +1 @@+../../stylesheets\ No newline at end of filediff --git a/docs/locales/ar/tutorials/migrating_from_beautifulsoup.md b/docs/locales/ar/tutorials/migrating_from_beautifulsoup.mdnew file mode 100644index 0000000..afad6b9--- /dev/null+++ b/docs/locales/ar/tutorials/migrating_from_beautifulsoup.md@@ -0,0 +1,99 @@+---+title: "الانتقال من BeautifulSoup إلى Scrapling"+description: "قارن مهام اختيار العناصر والنصوص والخصائص والتنقل الشائعة في BeautifulSoup بما يقابلها في Scrapling، مع أمثلة عملية لفروق API."+---++# الانتقال من BeautifulSoup إلى Scrapling {#migrating-from-beautifulsoup-to-scrapling}++إذا كنت تعرف BeautifulSoup بالفعل، فستجد ما يعجبك هنا. تعمل Scrapling بسرعة أكبر بكثير، وتوفر قدرات التحليل نفسها الموجودة في BS، مع قدرات إضافية لا توجد فيه، وميزات قوية لجلب صفحات الويب الحديثة والتعامل معها. يساعدك هذا الدليل على تعديل كود BeautifulSoup الحالي بسرعة للاستفادة من قدرات Scrapling.++يغطي الجدول التالي أشهر العمليات التي تستخدمها أثناء استخراج بيانات الصفحات. يوضح كل صف طريقة تنفيذ مهمة في BeautifulSoup والطريقة المقابلة في Scrapling.++ستلاحظ غياب بعض اختصارات BeautifulSoup من Scrapling. وهذا أحد أسباب أن BeautifulSoup أبطأ. الفكرة ببساطة: إذا أمكن تنفيذ الميزة نفسها في سطر قصير، فلا حاجة إلى التضحية بالأداء لتقصير هذا السطر أكثر :)++| المهمة | كود BeautifulSoup | كود Scrapling |+|-----------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------|+| استيراد المحلل | `from bs4 import BeautifulSoup` | `from scrapling.parser import Selector` |+| تحليل HTML من نص | `soup = BeautifulSoup(html, 'html.parser')` | `page = Selector(html)` |+| العثور على عنصر واحد | `element = soup.find('div', class_='example')` | `element = page.find('div', class_='example')` |+| العثور على عدة عناصر | `elements = soup.find_all('div', class_='example')` | `elements = page.find_all('div', class_='example')` |+| العثور على عنصر واحد، مثال 2 | `element = soup.find('div', attrs={"class": "example"})` | `element = page.find('div', {"class": "example"})` |+| العثور على عنصر واحد، مثال 3 | `element = soup.find(re.compile("^b"))` | `element = page.find(lambda e: re.search(r"^b", e.tag) is not None)` |+| العثور على عنصر واحد، مثال 4 | `element = soup.find(lambda e: len(list(e.children)) > 0)` | `element = page.find(lambda e: len(e.children) > 0)` |+| العثور على عنصر واحد، مثال 5 | `element = soup.find(["a", "b"])` | `element = page.find(["a", "b"])` |+| العثور على عنصر حسب نصه | `element = soup.find(text="some text")` | `element = page.find_by_text("some text", partial=False)` |+| استخدام CSS للعثور على أول عنصر مطابق | `elements = soup.select_one('div.example')` | `elements = page.css('div.example').first` |+| استخدام CSS للعثور على كل العناصر المطابقة | `elements = soup.select('div.example')` | `elements = page.css('div.example')` |+| عرض مصدر الصفحة أو العنصر بتنسيق واضح | `prettified = soup.prettify()` | `prettified = page.prettify()` |+| عرض مصدر الصفحة أو العنصر دون تحسين التنسيق | `source = str(soup)` | `source = page.html_content` |+| قراءة اسم وسم العنصر | `name = element.name` | `name = element.tag` |+| استخراج نص العنصر | `string = element.string` | `string = element.text` |+| استخراج كل النص في المستند أو داخل وسم | `text = soup.get_text(strip=True)` | `text = page.get_all_text(strip=True)` |+| الوصول إلى قاموس الخصائص | `attrs = element.attrs` | `attrs = element.attrib` |+| استخراج الخصائص | `attr = element['href']` | `attr = element['href']` |+| الانتقال إلى العنصر الأب | `parent = element.parent` | `parent = element.parent` |+| قراءة كل أسلاف العنصر | `parents = list(element.parents)` | `parents = list(element.iterancestors())` |+| البحث عن عنصر بين أسلاف العنصر | `target_parent = element.find_parent("a")` | `target_parent = element.find_ancestor(lambda p: p.tag == 'a')` |+| قراءة كل العناصر المجاورة | غير متاح | `siblings = element.siblings` |+| قراءة العنصر المجاور التالي | `next_element = element.next_sibling` | `next_element = element.next` |+| البحث عن عنصر بين العناصر المجاورة | `target_sibling = element.find_next_sibling("a")`<br/>`target_sibling = element.find_previous_sibling("a")` | `target_sibling = element.siblings.search(lambda s: s.tag == 'a')` |+| البحث عن عدة عناصر بين العناصر المجاورة | `target_sibling = element.find_next_siblings("a")`<br/>`target_sibling = element.find_previous_siblings("a")` | `target_sibling = element.siblings.filter(lambda s: s.tag == 'a')` |+| البحث عن عنصر بين العناصر التالية | `target_parent = element.find_next("a")` | `target_parent = element.below_elements.search(lambda p: p.tag == 'a')` |+| البحث عن عدة عناصر بين العناصر التالية | `target_parent = element.find_all_next("a")` | `target_parent = element.below_elements.filter(lambda p: p.tag == 'a')` |+| البحث عن عنصر بين الأسلاف | `target_parent = element.find_previous("a")` ¹ | `target_parent = element.path.search(lambda p: p.tag == 'a')` |+| البحث عن عدة عناصر بين الأسلاف | `target_parent = element.find_all_previous("a")` ¹ | `target_parent = element.path.filter(lambda p: p.tag == 'a')` |+| قراءة العنصر المجاور السابق | `prev_element = element.previous_sibling` | `prev_element = element.previous` |+| الانتقال إلى العناصر الأبناء | `children = list(element.children)` | `children = element.children` |+| قراءة جميع العناصر التابعة | `children = list(element.descendants)` | `children = element.below_elements` |+| اختيار الروابط داخل فقرات story | `group = soup.select('p.story a')` | `group = page.css('p.story a')` |++عند تمرير تعبير regex مُجمّع مباشرة إلى `find()` أو `find_all()` في Scrapling، فإنه يطابق نص العنصر، وليس اسم الوسم. استخدم دالة lambda الموضحة أعلاه لأسماء الوسوم، أو `page.find_by_regex(r"^b")` للبحث المباشر في النص.++¹ **ملاحظة:** تبحث `find_previous` و`find_all_previous` في BS4 في كل العناصر السابقة حسب ترتيب المستند. أما `path` في Scrapling فتُرجع الأسلاف فقط، أي سلسلة العناصر الآباء. لذا فهما ليستا متكافئتين تمامًا، لكن البحث في الأسلاف يغطي الحالة الأكثر شيوعًا.++**نقطة مهمة يجب تذكّرها**: توفر BeautifulSoup ميزات لتعديل الصفحة بعد تحليلها. أما Scrapling فتركز على استخراج البيانات بسرعة أكبر، ثم يمكنك فعل ما تريد بالبيانات الناتجة. كلتاهما تصلح لاستخراج بيانات الويب، لكن إحداهما متخصصة في هذا العمل :)++### تطبيق ذلك في مثال كامل {#putting-it-all-together}++إليك مثالًا بسيطًا لجلب صفحة واستخراج كل الروابط باستخدام BeautifulSoup وScrapling.++**باستخدام BeautifulSoup:**++```python+import requests+from bs4 import BeautifulSoup++url = 'https://example.com'+response = requests.get(url)+soup = BeautifulSoup(response.text, 'html.parser')++links = soup.find_all('a')+for link in links:+ print(link['href'])+```++**باستخدام Scrapling:**++```python+from scrapling import Fetcher++url = 'https://example.com'+page = Fetcher.get(url)++links = page.css('a::attr(href)').getall()+for link in links:+ print(link)+```++كما ترى، تبسّط Scrapling العملية بجمع الجلب والتحليل في خطوة واحدة، فيصبح الكود أوضح وأكثر كفاءة.++!!! abstract "**ملاحظات إضافية:**"++ - **محللات مختلفة**: تسمح BeautifulSoup باختيار محرك التحليل، ومنها `lxml`. أما Scrapling فتستخدم مكتبة `lxml` افتراضيًا لأسباب تتعلق بالأداء.+ - **أنواع العناصر**: العناصر في BeautifulSoup هي كائنات `Tag`، وفي Scrapling هي كائنات `Selector`. لكنها توفر دوال وخصائص متشابهة للتنقل واستخراج البيانات.+ - **معالجة الأخطاء**: تُرجع المكتبتان `None` عندما لا يوجد العنصر، مثل `soup.find()` أو `page.find()`. في Scrapling، تُرجع `page.css()` قائمة `Selectors` فارغة إذا لم يوجد تطابق. ويمكنك استخدام `page.css('.foo').first` للحصول على أول نتيجة أو `None` بأمان. لتجنب الأخطاء، تحقّق من `None` أو النتائج الفارغة قبل الوصول إلى الخصائص.+ - **استخراج النصوص**: توفر Scrapling دوال إضافية لمعالجة النصوص عبر `TextHandler`، مثل `clean()` لإزالة المسافات الزائدة أو المتتالية أو المحارف غير المرغوبة. راجع التوثيق للاطلاع على القائمة الكاملة.++يوفر التوثيق تفاصيل أكثر عن ميزات Scrapling، والقائمة الكاملة للمعاملات التي يمكن تمريرها إلى الدوال.++يساعدك هذا الدليل على الانتقال من BeautifulSoup إلى Scrapling بسهولة. نتمنى لك تجربة موفقة في استخراج البيانات!diff --git a/docs/locales/ar/tutorials/replacing_ai.md b/docs/locales/ar/tutorials/replacing_ai.mdnew file mode 100644index 0000000..f14ae3e--- /dev/null+++ b/docs/locales/ar/tutorials/replacing_ai.md@@ -0,0 +1,131 @@+---+title: "بديل مجاني للذكاء الاصطناعي لاستخراج بيانات الويب بثبات"+description: "تساعدك Scrapling مع تغيّر الصفحات والمحددات غير الثابتة والحماية من البوتات وتعدد الصفحات، دون استدعاء نموذج لغوي لكل صفحة."+---++# Scrapling: بديل مجاني للذكاء الاصطناعي لاستخراج بيانات الويب بثبات {#scrapling-a-free-alternative-to-ai-for-robust-web-scraping}++استخراج بيانات الويب أداة مهمة منذ زمن لجمع البيانات وفهرستها وتجهيز مجموعات البيانات، إلى جانب استخدامات أخرى. لكن المستخدمين ذوي الخبرة يواجهون مشكلات متكررة قد تقلل كفاءته. ومؤخرًا، زاد الاتجاه إلى استخدام الذكاء الاصطناعي في استخراج البيانات، لقدرته على معالجة هذه التحديات.++في هذا المقال، نناقش هذه المشكلات الشائعة، ولماذا تتجه الشركات إلى هذا الأسلوب، وما مشكلاته، وكيف تعالجها Scrapling دون تكلفة استخدام الذكاء الاصطناعي.++## مشكلات شائعة وأهداف صعبة {#common-issues-and-challenging-goals}++إذا كنت تعمل في استخراج بيانات الويب منذ فترة، فربما لاحظت مشكلات تتكرر، مثل:++1. **تغيّر بنية المواقع بسرعة**: تحدّث المواقع بنية DOM باستمرار، فتتوقف محددات XPath وCSS الثابتة عن العمل.+2. **محددات غير ثابتة**: تتغير أسماء class ومعرّفات id كثيرًا، أو تستخدم قيمًا عشوائية، مما يعطّل أدوات استخراج البيانات أو يصعّب عملها.+3. **زيادة تعقيد الحماية من البوتات**: تجعل أنظمة CAPTCHA وبصمات المتصفح وتحليل السلوك عملية الاستخراج التقليدية صعبة.++وغير ذلك من المشكلات.++لكن هذا يخص استخراج بيانات مستهدفة من مواقع معروفة، حيث يمكنك كتابة كود خاص لكل موقع.++أما إذا فكرت في أهداف أكبر، مثل الاستخراج الواسع أو العام من مواقع كثيرة، فإن المشكلات السابقة تزداد، وتظهر مشكلات جديدة، مثل:++1. **التنوع الكبير بين المواقع**: يجب على الأداة العامة التعامل مع اختلافات لا حصر لها في بنية HTML واستخدام CSS وأطر JavaScript وتقنيات الخادم.+2. **تحديد البيانات المهمة**: كيف تعرف الأداة البيانات المهمة في صفحة لم ترها من قبل؟+3. **اختلاف طرق الانتقال بين الصفحات**: التمرير المستمر، والصفحات التقليدية، وأزرار «تحميل المزيد»، وكل منها يحتاج إلى طريقة مختلفة.++وغيرها أيضًا.++كيف تعالج كل هذا يدويًا؟ أقصد الاستخراج العام من مواقع متنوعة لا تشترك في تقنيات واحدة.++## الذكاء الاصطناعي يساعد، لكن بتكلفة كبيرة {#ai-to-the-rescue-but-at-a-high-cost}++يمكن للذكاء الاصطناعي معالجة معظم هذه المشكلات بسهولة، لأنه يستطيع فهم مصدر الصفحة وتحديد الحقول المطلوبة أو إنشاء محددات لها. هذا بعد أن تعالج الحماية من البوتات بأدوات أخرى بالطبع :)++هذا الأسلوب جميل فعلًا. أحب الذكاء الاصطناعي وأجده مثيرًا للاهتمام، وخاصة الذكاء الاصطناعي التوليدي. ربما تقضي وقتًا طويلًا في كتابة prompts وتعديلها، لكن إذا كان ذلك مناسبًا لك، فستصل قريبًا إلى المشكلة الحقيقية هنا.++تحتوي معظم المواقع على كميات كبيرة من المحتوى في كل صفحة. ويجب أن تمرّر هذا المحتوى إلى الذكاء الاصطناعي بطريقة ما ليعمل عليه. سيستهلك ذلك الرموز بسرعة كبيرة، وتتراكم التكلفة سريعًا.++إذا كانت التكلفة تهمك، فستبحث عن طرق أقل تكلفة. وهنا يأتي دور Scrapling :smile:++## Scrapling تساعدك في ذلك {#scrapling-got-you-covered}++تستطيع Scrapling التعامل مع معظم المشكلات التي ستواجهها أثناء استخراج بيانات الويب، وستغطي التحديثات القادمة البقية بعناية.++### حل المشكلة T1: تغيّر بنية المواقع بسرعة {#solving-issue-t1-rapidly-changing-website-structures}++لهذا صُممت ميزة [adaptive](../parsing/adaptive.md). كنت تعرف أنني سأتحدث عنها، وها نحن هنا :)++عند تفعيل `adaptive` أثناء استخراج البيانات، يمكنك حفظ الخصائص المميزة لأي عنصر لتجده لاحقًا إذا تغيرت بنية الموقع. أكثر ما يزعج في هذه التغييرات هو أن أي جزء من العنصر قد يتغير، فلا تجد شيئًا ثابتًا تعتمد عليه.++تعمل الميزة التكيفية بحفظ كل ما يميز العنصر. وعندما تتغير بنية الموقع، تُرجع العنصر الذي يحصل على أعلى درجة تشابه مع العنصر السابق.++شرحت هذا بالتفصيل مع أمثلة كثيرة. اقرأ المزيد [هنا](../parsing/adaptive.md#how-the-adaptive-scraping-feature-works).++### حل المشكلة T2: محددات غير ثابتة {#solving-issue-t2-unstable-selectors}++إذا عملت في استخراج بيانات الويب مدة كافية، فربما واجهت هذا من قبل: موقع يستخدم تصميمًا ضعيفًا، أو HTML بلا معرّفات id أو أسماء class، أو أسماء class عشوائية دون خصائص أخرى يمكن الاعتماد عليها.++في هذه الحالات، لن تكون محددات CSS وXPath التقليدية أفضل اختيار. لذلك توفر Scrapling ثلاث طرق إضافية لاختيار العناصر:++1. [الاختيار حسب محتوى العنصر](../parsing/selection.md#text-content-selection): بالنص عبر `find_by_text`، أو بتعبير regex يطابق النص عبر `find_by_regex`.+2. [اختيار عناصر تشبه عنصرًا آخر](../parsing/selection.md#finding-similar-elements): اعثر على عنصر، وسنتولى الباقي!+3. [اختيار العناصر باستخدام شروط](../parsing/selection.md#filters-based-searching): حدّد الشروط التي يجب أن يحققها العنصر، وسنجده لك!++لن أكرر شرح هذه الطرق هنا. افتح الروابط لتعرف كيف تعالج Scrapling هذه المشكلة.++### حل المشكلة T3: زيادة تعقيد الحماية من البوتات {#solving-issue-t3-increasingly-complex-anti-bot-measures}++قد لا يكفي استخدام proxies وحركات تشبه تصرفات البشر مع المواقع المحمية. تجمع [StealthyFetcher](../fetching/stealthy.md) بين أتمتة المتصفح وتعديلات بصمته وخيارات التعامل مع الحماية من البوتات. فعّل `solve_cloudflare=True` للتعامل مع تحديات Cloudflare Turnstile وInterstitial.++### حل المشكلتين B1 وB2: تنوع المواقع وتحديد البيانات المهمة {#solving-issues-b1-b2-extreme-website-diversity-identifying-relevant-data}++هذه مشكلة صعبة، لكن مرونة Scrapling تجعل حلها ممكنًا.++تحدثت مع شخص يستخدم الذكاء الاصطناعي لاستخراج الأسعار من مواقع مختلفة. كان يهتم بالأسعار والعناوين فقط، لذلك يستخدم الذكاء الاصطناعي للعثور على السعر.++قلت له إن هذا لا يحتاج إلى ذكاء اصطناعي، وأعطيته الكود التالي كمثال:++```python+price_element = page.find_by_regex(r'£[\d\.,]+', first_match=True) # Get the first element that contains a text that matches price regex eg. £10.50+# If you want the container/element that contains the price element+price_element_container = price_element.parent or price_element.find_ancestor(lambda ancestor: ancestor.has_class('product')) # or other methods...+target_element_selector = price_element_container.generate_css_selector or price_element_container.generate_full_css_selector # or xpath+```++ثم سألني عن حالات مثل هذه:++```html+<span class='currency'> $ </span> <span class='a-price'> 45,000 </span>+```++فعدّلت الكود هكذا:++```python+price_element_container = page.find_by_regex(r'[\d,]+', first_match=True).parent # Adjusted the regex for this example+full_price_data = price_element_container.get_all_text(separator="", strip=True) # Returns '$45,000' in this case+```++كان هذا كافيًا لحالته. يمكنك تجربة التعبير الأول، وإذا لم يجد شيئًا فجرّب التعبير التالي، وهكذا. ابدأ بالأنماط الأكثر شيوعًا، ثم الأقل شيوعًا.+قد يكون العمل مملًا بعض الشيء، لكنه بالتأكيد أقل تكلفة من الذكاء الاصطناعي.++يوضح هذا المثال الفكرة التي أريد إيصالها. ليس كل تحدٍّ يحتاج إلى الذكاء الاصطناعي. أحيانًا تحتاج إلى فكرة مبتكرة فقط، وقد توفر عليك أموالًا كثيرة.++### حل المشكلة B3: اختلاف طرق الانتقال بين الصفحات {#solving-issue-b3-pagination-variations}++لا توفر Scrapling حاليًا طريقة مباشرة لاكتشاف روابط الصفحات التالية تلقائيًا. تتبع العناكب هذه الروابط باستخدام `response.follow()`.++لكن يمكنك التعامل مع معظم المواقع بالبحث عن الأنماط الشائعة، مثل `page.find_by_text('Next')['href']` أو `page.find_by_text('load more')['href']`، أو محددات مثل `'a[href*="?page="]'` و`'a[href*="/page/"]'`. الفكرة واضحة.++## مقارنة التكلفة والتوفير {#cost-comparison-and-savings}++إليك مقارنة سريعة.++| الجانب | Scrapling | أدوات تعتمد على الذكاء الاصطناعي، مثل Browse AI وOxylabs |+|---|---|---|+| التكلفة | مجانية، بلا رسوم على كل استخدام للمكتبة | خطط مدفوعة، والسعر حسب المزود والاستخدام |+| جهد الإعداد | تحتاج إلى معرفة تقنية بسيطة وإعداد يدوي | غالبًا لا تحتاج إلى كود، وأسهل لغير التقنيين |+| طرق الاستخدام | عبر الكود أو الطرفية أو خادم MCP | غالبًا عبر واجهة رسومية أو API، حسب ما توفره الشركة |+| التوسع | يعتمد على تنفيذ المستخدم | دعم مدمج لخدمات مُدارة تعمل على نطاق كبير |+| التكيف | مرتفع بفضل `adaptive` وطرق الاختيار التي لا تعتمد على المحددات | مرتفع وتلقائي بالذكاء الاصطناعي، لكنه مكلف عند كثرة التغييرات |++اطّلع على الأسعار الحالية في [أسعار Browse AI](https://www.browse.ai/pricing) و[أسعار Oxylabs Web Scraper API](https://oxylabs.io/products/scraper-api/web/pricing).++## الخلاصة {#conclusion}++يوفر الذكاء الاصطناعي قدرات قوية، لكن تكلفته قد تكون مرتفعة جدًا لكثير من مهام استخراج بيانات الويب. توفر Scrapling أدوات قوية ومرنة وقليلة التكلفة للتعامل مع التحديات الفعلية للاستخراج المستهدف والواسع، وغالبًا تغنيك عن حلول الذكاء الاصطناعي المكلفة. تساعدك ميزات مثل `adaptive` وطرق الاختيار المتنوعة وأدوات الجلب المتقدمة على بناء أدوات استخراج تتحمل التغييرات بكفاءة أكبر.++استكشف بقية التوثيق، وتعرّف على كيفية تبسيط Scrapling لمشاريع استخراج البيانات القادمة!diff --git a/docs/overrides/api/python/material/class.html.jinja b/docs/overrides/api/python/material/class.html.jinjanew file mode 100644index 0000000..81756d6--- /dev/null+++ b/docs/overrides/api/python/material/class.html.jinja@@ -0,0 +1,8 @@+{% set translation = "translations/" ~ locale ~ ".html.jinja" %}+{% if translation is existing_template %}+ {% import translation as translated %}+ {% set rendered %}{% include "_base/class.html.jinja" %}{% endset %}+ {{ translated.translate(rendered) }}+{% else %}+ {% include "_base/class.html.jinja" %}+{% endif %}diff --git a/docs/overrides/api/python/material/languages/ar.html.jinja b/docs/overrides/api/python/material/languages/ar.html.jinjanew file mode 100644index 0000000..327d38b--- /dev/null+++ b/docs/overrides/api/python/material/languages/ar.html.jinja@@ -0,0 +1,17 @@+{% macro t(key) %}{{ {+ "ATTRIBUTE": "الخاصية", "Attributes": "الخصائص", "Attributes:": "الخصائص:",+ "BOUND:": "الحد:", "Bound or Constraints": "الحد أو القيود",+ "Classes": "الفئات", "Classes:": "الفئات:", "CLASS": "الفئة",+ "Class Type Parameters:": "معاملات أنواع الفئة:", "CLASS TYPE PARAMETER": "معامل نوع الفئة",+ "CONSTRAINTS:": "القيود:", "DEFAULT:": "القيمة الافتراضية:", "Default": "القيمة الافتراضية", "default:": "القيمة الافتراضية:",+ "DESCRIPTION": "الوصف", "Description": "الوصف", "Examples:": "أمثلة:",+ "Functions": "الدوال", "Functions:": "الدوال:", "FUNCTION": "الدالة",+ "Init Type Parameters:": "معاملات أنواع التهيئة:", "INIT TYPE PARAMETER": "معامل نوع التهيئة",+ "Methods:": "الطرق:", "METHOD": "الطريقة", "Modules": "الوحدات", "Modules:": "الوحدات:", "MODULE": "الوحدة",+ "Name": "الاسم", "Other Parameters:": "معاملات أخرى:", "PARAMETER": "المعامل", "Parameters:": "المعاملات:",+ "RAISES": "الأخطاء", "Raises:": "الأخطاء:", "RECEIVES": "القيم المستقبلة", "Receives:": "القيم المستقبلة:",+ "required": "مطلوب", "RETURNS": "القيم المعادة", "Returns:": "القيم المعادة:", "Source code in": "الكود في",+ "TYPE:": "النوع:", "Type": "النوع", "Type Aliases": "أسماء الأنواع البديلة", "Type Aliases:": "أسماء الأنواع البديلة:",+ "TYPE ALIAS": "اسم نوع بديل", "Type Parameters:": "معاملات الأنواع:", "TYPE PARAMETER": "معامل النوع",+ "WARNS": "التحذيرات", "Warns:": "التحذيرات:", "YIELDS": "القيم الناتجة", "Yields:": "القيم الناتجة:"+}.get(key, "") }}{% endmacro %}diff --git a/docs/overrides/api/python/material/translations/ar.html.jinja b/docs/overrides/api/python/material/translations/ar.html.jinjanew file mode 100644index 0000000..ef61c63--- /dev/null+++ b/docs/overrides/api/python/material/translations/ar.html.jinja@@ -0,0 +1,369 @@+{% set translations = {+ "<p>This class is returned by all engines as a way to unify the response type between different libraries.</p>": "<p>تعيد كل المحركات هذه الفئة لتوحيد نوع الرد بين المكتبات المختلفة.</p>",+ "<p>HTTP status code.</p>": "<p>رمز حالة HTTP.</p>",+ "<p>HTTP status message.</p>": "<p>رسالة حالة HTTP.</p>",+ "<p>Response cookies.</p>": "<p>ملفات تعريف الارتباط في الرد.</p>",+ "<p>Response headers.</p>": "<p>ترويسات الرد.</p>",+ "<p>Request headers sent with the request.</p>": "<p>ترويسات الطلب المرسلة معه.</p>",+ "<p>List of redirect responses, if any.</p>": "<p>قائمة ردود إعادة التوجيه، إن وجدت.</p>",+ "<p>Metadata dictionary (e.g., proxy used).</p>": "<p>قاموس البيانات الوصفية، مثل البروكسي المستخدم.</p>",+ "<p>Associated spider Request object (set by crawler, in the spiders framework).</p>": "<p>كائن Request المرتبط من إطار Spiders، ويحدده برنامج الزحف.</p>",+ "<p>The main class that works as a wrapper for the HTML input data. Using this class, you can search for elements\nwith expressions in CSS, XPath, or with simply text. Check the docs for more info.</p>": "<p>الفئة الأساسية التي تغلّف بيانات HTML المدخلة. تتيح البحث عن العناصر باستخدام CSS أو XPath أو النص مباشرة. راجع التوثيق للمزيد.</p>",+ "<p>Here we try to extend module <code>lxml.html.HtmlElement</code> while maintaining a simpler interface, We are not\ninheriting from the <code>lxml.html.HtmlElement</code> because it's not pickleable, which makes a lot of reference jobs\nnot possible. You can test it here and see code explodes with <code>AssertionError: invalid Element proxy at...</code>.\nIt's an old issue with lxml, see <code>this entry <https://bugs.launchpad.net/lxml/+bug/736708></code></p>": "<p>نحاول هنا توسيع <code>lxml.html.HtmlElement</code> مع واجهة أبسط. لا نرث من <code>lxml.html.HtmlElement</code> لأنه لا يدعم pickle، مما يمنع كثيرًا من العمليات التي تعتمد على المراجع. يمكنك تجربته وسترى الخطأ <code>AssertionError: invalid Element proxy at...</code>. هذه مشكلة قديمة في lxml، راجع <code>this entry <https://bugs.launchpad.net/lxml/+bug/736708></code>.</p>",+ "<p>HTML content as either string or bytes.</p>": "<p>محتوى HTML كنص أو بايتات.</p>",+ "<p>It allows storing a URL with the HTML data for retrieving later.</p>": "<p>يتيح حفظ رابط مع بيانات HTML لاسترجاعه لاحقًا.</p>",+ "<p>The encoding type that will be used in HTML parsing, default is <code>UTF-8</code></p>": "<p>الترميز المستخدم في تحليل HTML. الافتراضي <code>UTF-8</code>.</p>",+ "<p>Enabled by default, should always be enabled when parsing large HTML documents. This controls\nthe libxml2 feature that forbids parsing certain large documents to protect from possible memory exhaustion.</p>": "<p>مفعّل افتراضيًا، ويجب إبقاؤه مفعّلًا عند تحليل مستندات HTML الكبيرة. يتحكم في ميزة libxml2 التي تمنع تحليل بعض المستندات الكبيرة للحماية من احتمال نفاد الذاكرة.</p>",+ "<p>Used internally to pass etree objects instead of text/body arguments, it takes the highest priority.\nDon't use it unless you know what you are doing!</p>": "<p>يُستخدم داخليًا لتمرير كائنات etree بدل النص أو المحتوى، وله أعلى أولوية. لا تستخدمه إلا إذا كنت تفهم أثره.</p>",+ "<p>While parsing the HTML body, drop comments or not. Disabled by default for obvious reasons</p>": "<p>يحدد هل تُحذف تعليقات HTML أثناء التحليل أم تُحفظ. الاحتفاظ بها معطّل افتراضيًا للأسباب المعروفة.</p>",+ "<p>Globally turn off the adaptive feature in all functions, this argument takes higher\npriority over all adaptive related arguments/functions in the class.</p>": "<p>يعطّل ميزة adaptive على المستوى العام في كل الدوال. لهذا الخيار أولوية أعلى من كل خيارات ودوال adaptive في الفئة.</p>",+ "<p>The storage class to be passed for adaptive functionalities, see <code>Docs</code> for more info.</p>": "<p>فئة التخزين التي تُستخدم مع adaptive. راجع <code>Docs</code> للمزيد.</p>",+ "<p>A dictionary of <code>argument->value</code> pairs to be passed for the storage class.\nIf empty, default values will be used.</p>": "<p>قاموس أزواج <code>argument->value</code> يُمرّر إلى فئة التخزين. إذا كان فارغًا، تُستخدم القيم الافتراضية.</p>",+ "<p>Return the raw body of the current <code>Selector</code> without any processing. Useful for binary and non-HTML requests.</p>": "<p>يعيد المحتوى الخام لكائن <code>Selector</code> الحالي دون معالجة. يفيد في الطلبات الثنائية والطلبات التي لا تعيد HTML.</p>",+ "<p>Return the raw body of the response as bytes.</p>": "<p>يعيد المحتوى الخام للرد من نوع bytes.</p>",+ "<p>Generate a CSS selector for the current element</p>": "<p>ينشئ محدد CSS للعنصر الحالي.</p>",+ "<p>A string of the generated selector.</p>": "<p>نص المحدد الناتج.</p>",+ "<p>Generate a complete CSS selector for the current element</p>": "<p>ينشئ محدد CSS كاملًا للعنصر الحالي.</p>",+ "<p>Generate an XPath selector for the current element</p>": "<p>ينشئ محدد XPath للعنصر الحالي.</p>",+ "<p>Generate a complete XPath selector for the current element</p>": "<p>ينشئ محدد XPath كاملًا للعنصر الحالي.</p>",+ "<p>Get the tag name of the element</p>": "<p>يعيد اسم وسم العنصر.</p>",+ "<p>Get text content of the element</p>": "<p>يعيد نص العنصر.</p>",+ "<p>Get attributes of the element</p>": "<p>يعيد خصائص العنصر.</p>",+ "<p>Return the inner HTML code of the element</p>": "<p>يعيد كود HTML الداخلي للعنصر.</p>",+ "<p>Return the direct parent of the element or <code>None</code> otherwise</p>": "<p>يعيد الأب المباشر للعنصر، أو <code>None</code> إذا لم يوجد.</p>",+ "<p>Return all elements under the current element in the DOM tree</p>": "<p>يعيد كل العناصر الموجودة تحت العنصر الحالي في شجرة DOM.</p>",+ "<p>Return the children elements of the current element or empty list otherwise</p>": "<p>يعيد أبناء العنصر الحالي، أو قائمة فارغة إذا لم يوجدوا.</p>",+ "<p>Return other children of the current element's parent or empty list otherwise</p>": "<p>يعيد أبناء الأب الآخرين، أي أشقاء العنصر الحالي، أو قائمة فارغة إذا لم يوجدوا.</p>",+ "<p>Returns a list of type <code>Selectors</code> that contains the path leading to the current element from the root.</p>": "<p>يعيد قائمة من نوع <code>Selectors</code> تحتوي المسار من الجذر إلى العنصر الحالي.</p>",+ "<p>Returns the next element of the current element in the children of the parent or <code>None</code> otherwise.</p>": "<p>يعيد العنصر التالي للعنصر الحالي بين أبناء الأب، أو <code>None</code> إذا لم يوجد.</p>",+ "<p>Returns the previous element of the current element in the children of the parent or <code>None</code> otherwise.</p>": "<p>يعيد العنصر السابق للعنصر الحالي بين أبناء الأب، أو <code>None</code> إذا لم يوجد.</p>",+ "<p>Convert the response content to clean Markdown.</p>": "<p>يحوّل محتوى الرد إلى Markdown نظيف.</p>",+ "<p>Scripts, styles, and hidden/prompt-injection content are always removed before conversion, which is\nthe same cleaning the MCP server does. Requires the \"markdownify\" package (<code>pip install \"scrapling[rag]\"</code>).</p>": "<p>تُزال السكربتات والأنماط والمحتوى المخفي ومحتوى حقن التعليمات دائمًا قبل التحويل، بالطريقة نفسها التي يستخدمها خادم MCP. يتطلب حزمة \"markdownify\" (<code>pip install \"scrapling[rag]\"</code>).</p>",+ "<p>CSS selector to convert only the matching elements. All matches are concatenated.</p>": "<p>محدد CSS لتحويل العناصر المطابقة فقط. تُجمع كل النتائج معًا.</p>",+ "<p>Convert only the content inside the <code><body></code> tag.</p>": "<p>يحوّل المحتوى الموجود داخل وسم <code><body></code> فقط.</p>",+ "<p>Create a Request to follow a URL.</p>": "<p>ينشئ Request لتتبع رابط.</p>",+ "<p>This is a helper method for spiders to easily follow links found in pages.</p>": "<p>دالة مساعدة لـSpiders لتتبع الروابط الموجودة في الصفحات بسهولة.</p>",+ "<p><strong>IMPORTANT</strong>: The below arguments if left empty, the corresponding value from the previous request will be used. The only exception is <code>dont_filter</code>.</p>": "<p><strong>مهم</strong>: إذا تُركت الخيارات التالية فارغة، تُستخدم قيمها من الطلب السابق. الاستثناء الوحيد هو <code>dont_filter</code>.</p>",+ "<p>The session kwargs of the previous request are inherited as well, except <code>method</code>, <code>params</code>, <code>data</code>, <code>json</code>, <code>files</code>, and <code>multipart</code>, so a followed link is a plain GET unless you pass them again.</p>": "<p>تُورث أيضًا خيارات الجلسة من الطلب السابق، باستثناء <code>method</code> و<code>params</code> و<code>data</code> و<code>json</code> و<code>files</code> و<code>multipart</code>. لذلك يكون تتبع الرابط طلب GET عاديًا ما لم تمرّر هذه الخيارات مجددًا.</p>",+ "<p>The URL to follow (can be relative, will be joined with current URL)</p>": "<p>الرابط المراد تتبعه. يمكن أن يكون نسبيًا، وسيُدمج مع الرابط الحالي.</p>",+ "<p>The session id to use</p>": "<p>معرّف الجلسة المستخدمة.</p>",+ "<p>Spider callback method to use</p>": "<p>دالة callback في Spider التي ستُستخدم.</p>",+ "<p>The priority number to use, the higher the number, the higher priority to be processed first.</p>": "<p>رقم الأولوية. كلما زاد الرقم، زادت الأولوية ليُعالج الطلب أولًا.</p>",+ "<p>If this request has been done before, disable the filter to allow it again.</p>": "<p>يعطّل مرشح التكرار للسماح بإرسال الطلب مجددًا إذا نُفّذ من قبل.</p>",+ "<p>Additional meta data to included in the request</p>": "<p>بيانات وصفية إضافية تُضم إلى الطلب.</p>",+ "<p>Enabled by default, set the current response url as referer for the new request url.</p>": "<p>مفعّل افتراضيًا. يضبط رابط الرد الحالي كقيمة referer للطلب الجديد.</p>",+ "<p>Additional Request arguments</p>": "<p>خيارات Request إضافية.</p>",+ "<p>Request object ready to be yielded</p>": "<p>كائن Request جاهز للإعادة باستخدام yield.</p>",+ "<p>Get all child strings of this element, concatenated using the given separator.</p>": "<p>يجمع كل النصوص الموجودة تحت العنصر، ويربطها بالفاصل المحدد.</p>",+ "<p>Strings will be concatenated using this separator.</p>": "<p>الفاصل المستخدم لربط النصوص.</p>",+ "<p>If True, strings will be stripped before being concatenated.</p>": "<p>إذا كانت True، تُزال المسافات البيضاء من طرفَي النصوص قبل ربطها.</p>",+ "<p>A tuple of all tag names you want to ignore</p>": "<p>tuple بأسماء الوسوم التي تريد تجاهلها.</p>",+ "<p>If enabled, elements with text-content that is empty or only whitespaces will be ignored</p>": "<p>عند تفعيله، تُتجاهل العناصر ذات النص الفارغ أو الذي يحتوي مسافات بيضاء فقط.</p>",+ "<p>A TextHandler</p>": "<p>كائن TextHandler.</p>",+ "<p>Join this Selector's url with a relative url to form an absolute full URL.</p>": "<p>يدمج رابط Selector مع رابط نسبي للحصول على رابط مطلق كامل.</p>",+ "<p>Return a prettified version of the element's inner html-code</p>": "<p>يعيد نسخة منسقة من HTML الداخلي للعنصر.</p>",+ "<p>Check if the element has a specific class</p>": "<p>يتحقق من وجود class محدد في العنصر.</p>",+ "<p>The class name to check for</p>": "<p>اسم class المطلوب التحقق منه.</p>",+ "<p>True if element has class with that name otherwise False</p>": "<p>True إذا كان العنصر يحمل class بهذا الاسم، وإلا False.</p>",+ "<p>Return a generator that loops over all ancestors of the element, starting with the element's parent.</p>": "<p>يعيد generator يمر على كل أسلاف العنصر، بدءًا من الأب المباشر.</p>",+ "<p>Loop over all ancestors of the element till one match the passed function</p>": "<p>يمر على أسلاف العنصر حتى يجد أول سلف يحقق الدالة الممرّرة.</p>",+ "<p>A function that takes each ancestor as an argument and returns True/False</p>": "<p>دالة تستقبل كل سلف وتعيد True أو False.</p>",+ "<p>The first ancestor that match the function or <code>None</code> otherwise.</p>": "<p>أول سلف يحقق الدالة، أو <code>None</code> إذا لم يوجد.</p>",+ "<p>Serialize this element to a string.\nFor text nodes, returns the text value. For HTML elements, returns the outer HTML.</p>": "<p>يحوّل العنصر إلى نص. يعيد قيمة النص للعقد النصية، أو HTML الخارجي لعناصر HTML.</p>",+ "<p>Return a single-element list containing this element's serialized string.</p>": "<p>يعيد قائمة من عنصر واحد تحتوي النص الناتج من تحويل هذا العنصر.</p>",+ "<p>This function will search again for the element in the page tree, used automatically on page structure change</p>": "<p>تعيد هذه الدالة البحث عن العنصر في شجرة الصفحة. تُستخدم تلقائيًا عند تغير بنية الصفحة.</p>",+ "<p>The element we want to relocate in the tree</p>": "<p>العنصر الذي نريد العثور على مكانه الجديد في الشجرة.</p>",+ "<p>The minimum percentage to accept and not going lower than that. Be aware that the percentage\ncalculation depends solely on the page structure, so don't play with this number unless you must know\nwhat you are doing!</p>": "<p>أقل نسبة مقبولة للمطابقة، ولا تُقبل نسبة دونها. يعتمد حساب النسبة على بنية الصفحة وحدها، لذلك لا تغيّر الرقم إلا إذا فهمت أثره.</p>",+ "<p>If True, the return result will be converted to <code>Selectors</code> object</p>": "<p>إذا كانت True، تُحوّل النتيجة إلى كائن <code>Selectors</code>.</p>",+ "<p>List of pure HTML elements that got the highest matching score or 'Selectors' object</p>": "<p>قائمة بعناصر HTML الخام ذات أعلى درجة تطابق، أو كائن 'Selectors'.</p>",+ "<p>Search the current tree with CSS3 selectors</p>": "<p>يبحث في الشجرة الحالية باستخدام محددات CSS3.</p>",+ "<p><strong>Important:\nIt's recommended to use the identifier argument if you plan to use a different selector later\nand want to relocate the same element(s)</strong></p>": "<p><strong>مهم: يُنصح باستخدام خيار identifier إذا كنت ستستخدم محددًا مختلفًا لاحقًا، وتريد العثور على العناصر نفسها بعد تغير موضعها.</strong></p>",+ "<p>The CSS3 selector to be used.</p>": "<p>محدد CSS3 المستخدم.</p>",+ "<p>Enabled will make the function try to relocate the element if it was 'saved' before</p>": "<p>عند تفعيله، تحاول الدالة العثور على مكان العنصر الجديد إذا حُفظ سابقًا.</p>",+ "<p>A string that will be used to save/retrieve element's data in adaptive,\notherwise the selector will be used.</p>": "<p>نص يُستخدم لحفظ بيانات العنصر واسترجاعها في adaptive. إذا لم تحدده، يُستخدم المحدد نفسه.</p>",+ "<p>Automatically save new elements for <code>adaptive</code> later</p>": "<p>يحفظ العناصر الجديدة تلقائيًا لاستخدام <code>adaptive</code> لاحقًا.</p>",+ "<p>The minimum percentage to accept while <code>adaptive</code> is working and not going lower than that.\nBe aware that the percentage calculation depends solely on the page structure, so don't play with this\nnumber unless you must know what you are doing!</p>": "<p>أقل نسبة مقبولة أثناء عمل <code>adaptive</code>، ولا تُقبل نسبة دونها. يعتمد حسابها على بنية الصفحة وحدها، لذلك لا تغيّر الرقم إلا إذا فهمت أثره.</p>",+ "<p><code>Selectors</code> class.</p>": "<p>فئة <code>Selectors</code>.</p>",+ "<p>Search the current tree with XPath selectors</p>": "<p>يبحث في الشجرة الحالية باستخدام محددات XPath.</p>",+ "<p>Note: <strong>Additional keyword arguments will be passed as XPath variables in the XPath expression!</strong></p>": "<p>ملاحظة: <strong>تُمرّر الخيارات الإضافية المسماة كمتغيرات XPath داخل التعبير!</strong></p>",+ "<p>The XPath selector to be used.</p>": "<p>محدد XPath المستخدم.</p>",+ "<p>Find elements by filters of your creations for ease.</p>": "<p>يبحث عن العناصر بسهولة باستخدام مرشحات تختارها.</p>",+ "<p>Tag name(s), iterable of tag names, regex patterns, function, or a dictionary of elements' attributes. Leave empty for selecting all.</p>": "<p>اسم وسم أو أسماء وسوم، أو iterable من أسماء الوسوم، أو أنماط regex، أو دالة، أو قاموس خصائص عناصر. اتركه فارغًا لاختيار الكل.</p>",+ "<p>The attributes you want to filter elements based on it.</p>": "<p>الخصائص التي تريد تصفية العناصر حسبها.</p>",+ "<p>The <code>Selectors</code> object of the elements or empty list</p>": "<p>كائن <code>Selectors</code> بالعناصر، أو قائمة فارغة.</p>",+ "<p>Find elements by filters of your creations for ease, then return the first result. Otherwise return <code>None</code>.</p>": "<p>يبحث عن العناصر باستخدام مرشحات تختارها ويعيد أول نتيجة، أو <code>None</code> إذا لم يجدها.</p>",+ "<p>The <code>Selector</code> object of the element or <code>None</code> if the result didn't match</p>": "<p>كائن <code>Selector</code> للعنصر، أو <code>None</code> إذا لم توجد نتيجة مطابقة.</p>",+ "<p>Saves the element's unique properties to the storage for retrieval and relocation later</p>": "<p>يحفظ خصائص العنصر المميزة في التخزين لاسترجاعها والعثور عليه لاحقًا.</p>",+ "<p>The element itself that we want to save to storage, it can be a <code>Selector</code> or pure <code>HtmlElement</code></p>": "<p>العنصر المطلوب حفظه. يمكن أن يكون <code>Selector</code> أو <code>HtmlElement</code> خامًا.</p>",+ "<p>This is the identifier that will be used to retrieve the element later from the storage. See\nthe docs for more info.</p>": "<p>المعرّف المستخدم لاسترجاع العنصر لاحقًا من التخزين. راجع التوثيق للمزيد.</p>",+ "<p>Using the identifier, we search the storage and return the unique properties of the element</p>": "<p>يبحث في التخزين باستخدام المعرّف، ويعيد الخصائص المميزة للعنصر.</p>",+ "<p>This is the identifier that will be used to retrieve the element from the storage. See\nthe docs for more info.</p>": "<p>المعرّف المستخدم لاسترجاع العنصر من التخزين. راجع التوثيق للمزيد.</p>",+ "<p>A dictionary of the unique properties</p>": "<p>قاموس الخصائص المميزة.</p>",+ "<p>Return JSON response if the response is jsonable otherwise throws error</p>": "<p>يعيد الرد كـJSON إذا أمكن تحويله، وإلا يرفع خطأ.</p>",+ "<p>Apply the given regex to the current text and return a list of strings with the matches.</p>": "<p>يطبّق التعبير المنتظم على النص الحالي، ويعيد قائمة بالنصوص المطابقة.</p>",+ "<p>Can be either a compiled regular expression or a string.</p>": "<p>يمكن أن يكون تعبيرًا منتظمًا مُجهّزًا أو نصًا.</p>",+ "<p>If enabled character entity references are replaced by their corresponding character</p>": "<p>عند تفعيله، تُستبدل مراجع كيانات الأحرف بالأحرف التي تمثلها.</p>",+ "<p>if enabled, this will ignore all whitespaces and consecutive spaces while matching</p>": "<p>عند تفعيله، تُتجاهل المسافات البيضاء والمتكررة أثناء المطابقة.</p>",+ "<p>if disabled, the function will set the regex to ignore the letters case while compiling it</p>": "<p>عند تعطيله، يُجهّز التعبير المنتظم ليتجاهل الفرق بين الأحرف الكبيرة والصغيرة.</p>",+ "<p>Apply the given regex to text and return the first match if found, otherwise return the default value.</p>": "<p>يطبّق التعبير المنتظم على النص ويعيد أول تطابق إن وجد، وإلا يعيد القيمة الافتراضية.</p>",+ "<p>The default value to be returned if there is no match</p>": "<p>القيمة الافتراضية عند عدم وجود تطابق.</p>",+ "<p>\n <span class=\"doc-param-default\">\n <b>DEFAULT:</b>\n <code>None</code>\n </span>\n </p>": "<p>\n <span class=\"doc-param-default\">\n <b>الافتراضي:</b>\n <code>None</code>\n </span>\n </p>",+ "<p>if enabled character entity references are replaced by their corresponding character</p>": "<p>عند تفعيله، تُستبدل مراجع كيانات الأحرف بالأحرف التي تمثلها.</p>",+ "<p>Find elements that are in the same tree depth in the page with the same tag name and same parent tag etc...\nthen return the ones that match the current element attributes with a percentage higher than the input threshold.</p>": "<p>يبحث عن العناصر ذات العمق نفسه في شجرة الصفحة، واسم الوسم نفسه واسم وسم الأب نفسه، وغيرها، ثم يعيد ما تتشابه خصائصه مع العنصر الحالي بنسبة أعلى من الحد المحدد.</p>",+ "<p>This function is inspired by AutoScraper and made for cases where you, for example, found a product div inside\na products-list container and want to find other products using that element as a starting point EXCEPT\nthis function works in any case without depending on the element type.</p>": "<p>استُلهمت هذه الدالة من AutoScraper. تفيد مثلًا عندما تجد div لمنتج داخل حاوية قائمة منتجات، وتريد استخدامه كنقطة بداية للعثور على المنتجات الأخرى. لكنها تعمل مع أي حالة، دون الاعتماد على نوع العنصر.</p>",+ "<p>The percentage to use while comparing element attributes.\nNote: Elements found before attributes matching/comparison will be sharing the same depth, same tag name,\nsame parent tag name, and same grand parent tag name. So they are 99% likely to be correct unless you are\nextremely unlucky, then attributes matching comes into play, so don't play with this number unless\nyou are getting the results you don't want.\nAlso, if the current element doesn't have attributes and the similar element as well, then it's a 100% match.</p>": "<p>النسبة المستخدمة لمقارنة خصائص العناصر. ملاحظة: قبل مقارنة الخصائص، تكون العناصر المرشحة في العمق نفسه، وباسم الوسم نفسه واسم وسم الأب والجد نفسيهما. لذلك تكون صحيحة بنسبة تقارب 99% ما لم تكن الحالة غير معتادة جدًا. تأتي مقارنة الخصائص كفحص أخير، فلا تغيّر هذه النسبة إلا إذا حصلت على نتائج غير مرغوبة. وإذا لم يكن للعنصر الحالي ولا العنصر المشابه أي خصائص، فالتطابق 100%.</p>",+ "<p>Attribute names passed will be ignored while matching the attributes in the last step.\nThe default value is to ignore <code>href</code> and <code>src</code> as URLs can change a lot between elements, so it's unreliable</p>": "<p>تُتجاهل أسماء الخصائص الممرّرة في المقارنة الأخيرة. الافتراضي تجاهل <code>href</code> و<code>src</code>، لأن الروابط قد تختلف كثيرًا بين العناصر ولا يُعتمد عليها هنا.</p>",+ "<p>If True, element text content will be taken into calculation while matching.\nNot recommended to use in normal cases, but it depends.</p>": "<p>إذا كانت True، يدخل نص العنصر في حساب التشابه. لا يُنصح بهذا في الحالات المعتادة، لكن القرار حسب الحالة.</p>",+ "<p>A <code>Selectors</code> container of <code>Selector</code> objects or empty list</p>": "<p>حاوية <code>Selectors</code> تضم كائنات <code>Selector</code>، أو قائمة فارغة.</p>",+ "<p>Find elements that its text content fully/partially matches input.</p>": "<p>يبحث عن العناصر التي يطابق نصها المُدخل بالكامل أو جزئيًا.</p>",+ "<p>Text query to match</p>": "<p>النص المطلوب مطابقته.</p>",+ "<p>Returns the first element that matches conditions, enabled by default</p>": "<p>يعيد أول عنصر يحقق الشروط. مفعّل افتراضيًا.</p>",+ "<p>If enabled, the function returns elements that contain the input text</p>": "<p>عند تفعيله، تعيد الدالة العناصر التي تحتوي النص المُدخل.</p>",+ "<p>if enabled, the letters case will be taken into consideration</p>": "<p>عند التفعيل، يراعي الفرق بين الأحرف الكبيرة والصغيرة.</p>",+ "<p>Find elements that its text content matches the input regex pattern.</p>": "<p>يعثر على العناصر التي يطابق نصها نمط regex المُدخل.</p>",+ "<p>Regex query/pattern to match</p>": "<p>تعبير أو نمط regex المطلوب مطابقته.</p>",+ "<p>Return the first element that matches conditions; enabled by default.</p>": "<p>يُرجع أول عنصر يطابق الشروط. هذا الخيار مفعّل افتراضيًا.</p>",+ "<p>If enabled, the letters case will be taken into consideration in the regex.</p>": "<p>عند التفعيل، يراعي regex الفرق بين الأحرف الكبيرة والصغيرة.</p>",+ "<p>If enabled, this will ignore all whitespaces and consecutive spaces while matching.</p>": "<p>عند التفعيل، يتجاهل جميع المحارف البيضاء والمسافات المتتالية أثناء المطابقة.</p>",+ "<p>A basic <code>Fetcher</code> class type that can only do basic GET, POST, PUT, and DELETE HTTP requests based on <code>curl_cffi</code>.</p>": "<p>صنف <code>Fetcher</code> أساسي ينفّذ طلبات HTTP من أنواع GET وPOST وPUT وDELETE فقط، باستخدام <code>curl_cffi</code>.</p>",+ "<p>Set multiple arguments for the parser at once globally</p>": "<p>يضبط عدة معاملات للمحلل مرة واحدة على مستوى المكتبة.</p>",+ "<p>The keywords can be any arguments of the following: huge_tree, keep_comments, adaptive, storage, storage_args, adaptive_domain</p>": "<p>يمكن أن تكون أسماء المعاملات أيًا من: huge_tree وkeep_comments وadaptive وstorage وstorage_args وadaptive_domain.</p>",+ "<p>\n <span class=\"doc-param-default\">\n <b>DEFAULT:</b>\n <code>{}</code>\n </span>\n </p>": "<p>\n <span class=\"doc-param-default\">\n <b>القيمة الافتراضية:</b>\n <code>{}</code>\n </span>\n </p>",+ "<p>A <code>Fetcher</code> class type which is a completely stealthy built on top of Chromium.</p>": "<p>صنف <code>Fetcher</code> يعمل بالتخفي الكامل، ومبني على Chromium.</p>",+ "<p>It works as real browsers passing almost all online tests/protections with many customization options.</p>": "<p>يعمل مثل المتصفحات الحقيقية ويتجاوز معظم الاختبارات ووسائل الحماية على الإنترنت، مع خيارات تخصيص كثيرة.</p>",+ "<p>Opens up a browser and do your request based on your chosen options below.</p>": "<p>يفتح متصفحًا وينفّذ الطلب حسب الخيارات التي تحددها أدناه.</p>",+ "<p>Target url.</p>": "<p>الرابط المطلوب.</p>",+ "<p>Run the browser in headless/hidden (default), or headful/visible mode.</p>": "<p>يشغّل المتصفح في وضع headless المخفي، وهو الافتراضي، أو وضع headful المرئي.</p>",+ "<p>Drop requests for unnecessary resources for a speed boost.\nRequests dropped are of type <code>font</code>, <code>image</code>, <code>media</code>, <code>beacon</code>, <code>object</code>, <code>imageset</code>, <code>texttrack</code>, <code>websocket</code>, <code>csp_report</code>, and <code>stylesheet</code>.</p>": "<p>يلغي طلبات الموارد غير الضرورية لزيادة السرعة.\nتشمل أنواع الطلبات الملغاة <code>font</code> و<code>image</code> و<code>media</code> و<code>beacon</code> و<code>object</code> و<code>imageset</code> و<code>texttrack</code> و<code>websocket</code> و<code>csp_report</code> و<code>stylesheet</code>.</p>",+ "<p>A set of domain names to block requests to. Subdomains are also matched (e.g., <code>\"example.com\"</code> blocks <code>\"sub.example.com\"</code> too).</p>": "<p>مجموعة أسماء نطاقات تُحظر الطلبات إليها. يشمل الحظر النطاقات الفرعية أيضًا، مثلًا: يحظر <code>\"example.com\"</code> النطاق <code>\"sub.example.com\"</code> أيضًا.</p>",+ "<p>Block requests to ~3,500 known ad/tracking domains. Can be combined with <code>blocked_domains</code>.</p>": "<p>يحظر الطلبات إلى نحو 3,500 نطاق معروف للإعلانات والتتبع. يمكن استخدامه مع <code>blocked_domains</code>.</p>",+ "<p>Route DNS queries through Cloudflare's DNS-over-HTTPS to prevent DNS leaks when using proxies.</p>": "<p>يمرّر استعلامات DNS عبر خدمة DNS-over-HTTPS من Cloudflare لمنع تسرب DNS عند استخدام proxies.</p>",+ "<p>Pass a useragent string to be used. Otherwise the fetcher will generate a real Useragent of the same browser and use it.</p>": "<p>مرّر نص useragent لاستخدامه. وإلا ستولّد أداة الجلب Useragent حقيقيًا للمتصفح نفسه وتستخدمه.</p>",+ "<p>Set cookies for the next request.</p>": "<p>يضبط cookies للطلب التالي.</p>",+ "<p>Wait for the page until there are no network connections for at least 500 ms.</p>": "<p>ينتظر الصفحة حتى تمر 500 مللي ثانية على الأقل دون اتصالات شبكة.</p>",+ "<p>The timeout in milliseconds that is used in all operations and waits through the page. The default is 30,000</p>": "<p>مهلة الانتظار بالمللي ثانية لجميع العمليات والانتظار داخل الصفحة. القيمة الافتراضية 30,000.</p>",+ "<p>The time (milliseconds) the fetcher will wait after everything finishes before closing the page and returning the <code>Response</code> object.</p>": "<p>الوقت بالمللي ثانية الذي تنتظره أداة الجلب بعد اكتمال كل شيء، وقبل إغلاق الصفحة وإرجاع كائن <code>Response</code>.</p>",+ "<p>Added for automation. A function that takes the <code>page</code> object, runs after navigation, and does the automation you need.</p>": "<p>أُضيف للأتمتة. دالة تستقبل كائن <code>page</code> وتعمل بعد الانتقال إلى الصفحة، وتنفّذ الإجراءات المطلوبة.</p>",+ "<p>A function that takes the <code>page</code> object, runs before navigation. Use it to register event listeners or routes that must be set up before the page loads.</p>": "<p>دالة تستقبل كائن <code>page</code> وتعمل قبل الانتقال. استخدمها لتسجيل مستمعي الأحداث أو routes التي يجب إعدادها قبل تحميل الصفحة.</p>",+ "<p>Wait for a specific CSS selector to be in a specific state.</p>": "<p>ينتظر وصول عنصر يطابق محدد CSS إلى حالة معينة.</p>",+ "<p>An absolute path to a JavaScript file to be executed on page creation for all pages in this session.</p>": "<p>مسار مطلق لملف JavaScript يُنفّذ عند إنشاء كل صفحة في هذه الجلسة.</p>",+ "<p>Specify user locale, for example, <code>en-GB</code>, <code>de-DE</code>, etc. Locale will affect navigator.language value, Accept-Language request header value as well as number and date formatting\nrules. Defaults to the system default locale.</p>": "<p>يحدد الإعداد المحلي للمستخدم، مثل <code>en-GB</code> أو <code>de-DE</code>. يؤثر في قيمة navigator.language وترويسة الطلب Accept-Language وقواعد تنسيق الأرقام والتواريخ.\nيستخدم الإعداد المحلي الافتراضي للنظام ما لم تحدد غيره.</p>",+ "<p>Changes the timezone of the browser. Defaults to the system timezone.</p>": "<p>يغيّر المنطقة الزمنية للمتصفح. يستخدم منطقة النظام الزمنية افتراضيًا.</p>",+ "<p>The state to wait for the selector given with <code>wait_selector</code>. The default state is <code>attached</code>.</p>": "<p>الحالة المطلوب انتظارها للمحدد الممرّر في <code>wait_selector</code>. الحالة الافتراضية هي <code>attached</code>.</p>",+ "<p>Solves all types of the Cloudflare's Turnstile/Interstitial challenges before returning the response to you.</p>": "<p>يحل كل أنواع تحديات Turnstile وInterstitial من Cloudflare قبل إرجاع الاستجابة.</p>",+ "<p>If you have a Chrome browser installed on your device, enable this, and the Fetcher will launch an instance of your browser and use it.</p>": "<p>إذا كان Chrome مثبّتًا على جهازك، فعّل هذا الخيار لتشغّل أداة الجلب نسخة من متصفحك وتستخدمها.</p>",+ "<p>Add random noise to canvas operations to prevent fingerprinting.</p>": "<p>يضيف ضوضاء عشوائية إلى عمليات canvas لمنع التعرف على البصمة.</p>",+ "<p>Forces WebRTC to respect proxy settings to prevent local IP address leak.</p>": "<p>يُلزم WebRTC باتباع إعدادات proxy لمنع تسرب عنوان IP المحلي.</p>",+ "<p>Enabled by default. Disabling it disables WebGL and WebGL 2.0 support entirely. Disabling WebGL is not recommended as many WAFs now check if WebGL is enabled.</p>": "<p>مفعّل افتراضيًا. يؤدي تعطيله إلى إيقاف دعم WebGL وWebGL 2.0 بالكامل. لا يُنصح بتعطيل WebGL لأن كثيرًا من أنظمة WAF تتحقق الآن من تفعيله.</p>",+ "<p>Enabled by default, wait for all JavaScript on page(s) to fully load and execute.</p>": "<p>مفعّل افتراضيًا. ينتظر اكتمال تحميل كل JavaScript في الصفحات وتنفيذه.</p>",+ "<p>Include open Shadow DOM content in the response HTML. Defaults to False.</p>": "<p>يضمّن محتوى Shadow DOM المفتوح في HTML الاستجابة. القيمة الافتراضية False.</p>",+ "<p>Instead of launching a new browser instance, connect to this CDP URL to control real browsers through CDP.</p>": "<p>يتصل بعنوان CDP هذا للتحكم في متصفحات حقيقية عبر CDP، بدلًا من تشغيل متصفح جديد.</p>",+ "<p>Enabled by default, Scrapling will set a Google referer header.</p>": "<p>مفعّل افتراضيًا. تضبط Scrapling ترويسة referer على Google.</p>",+ "<p>A dictionary of extra headers to add to the request. <em>The referer set by <code>google_search</code> takes priority over the referer set here if used together.</em></p>": "<p>قاموس ترويسات إضافية لإضافتها إلى الطلب. <em>تكون الأولوية لقيمة referer التي يحددها <code>google_search</code> على القيمة المحددة هنا عند استخدامهما معًا.</em></p>",+ "<p>The proxy to be used with requests, it can be a string or a dictionary with the keys 'server', 'username', and 'password' only.</p>": "<p>الـ proxy المستخدم في الطلبات. يمكن أن يكون نصًا أو قاموسًا بمفاتيح server وusername وpassword فقط.</p>",+ "<p>Path to a User Data Directory, which stores browser session data like cookies and local storage. The default is to create a temporary directory.</p>": "<p>مسار User Data Directory، وهو مجلد يحفظ بيانات جلسة المتصفح مثل cookies وlocal storage. افتراضيًا، يُنشأ مجلد مؤقت.</p>",+ "<p>A list of additional browser flags to pass to the browser on launch.</p>": "<p>قائمة خيارات إضافية تُمرّر إلى المتصفح عند تشغيله.</p>",+ "<p>The arguments that will be passed in the end while creating the final Selector's class.</p>": "<p>المعاملات التي تُمرّر في النهاية عند إنشاء صنف Selector النهائي.</p>",+ "<p>Additional arguments to be passed to Playwright's context as additional settings, and it takes higher priority than Scrapling's settings.</p>": "<p>معاملات إضافية تُمرّر كإعدادات إلى سياق Playwright، ولها أولوية أعلى من إعدادات Scrapling.</p>",+ "<p>A <code>Response</code> object.</p>": "<p>كائن <code>Response</code>.</p>",+ "<p>A factory context manager that provides configured Fetcher sessions.</p>": "<p>مدير سياق ينشئ جلسات Fetcher بالإعدادات المحددة.</p>",+ "<p>When this manager is used in a 'with' or 'async with' block,\nit yields a new session configured with the manager's defaults.\nA single instance of this manager should ideally be used for one active\nsession at a time (or sequentially). Re-entering a context with the\nsame manager instance while a session is already active is disallowed.</p>": "<p>عند استخدام هذا المدير داخل كتلة with أو async with،\nيوفر جلسة جديدة بالإعدادات الافتراضية للمدير.\nيُفضّل استخدام كائن المدير الواحد لجلسة نشطة واحدة في كل مرة، أو لجلسات متتابعة.\nلا يُسمح بإعادة الدخول إلى السياق بكائن المدير نفسه\nأثناء وجود جلسة نشطة بالفعل.</p>",+ "<p>Browser version to impersonate. Can be a single browser string or a list of browser strings for random selection. (Default: latest available Chrome version)</p>": "<p>إصدار المتصفح المطلوب محاكاته. يمكن تمرير نص لمتصفح واحد، أو قائمة نصوص للاختيار العشوائي. القيمة الافتراضية: أحدث إصدار Chrome متاح.</p>",+ "<p>Whether to use HTTP3. Defaults to False. It might be problematic if used it with <code>impersonate</code>.</p>": "<p>يحدد استخدام HTTP3. القيمة الافتراضية False. قد يسبب مشكلات عند استخدامه مع <code>impersonate</code>.</p>",+ "<p>If enabled (default), it creates and adds real browser headers. It also sets a Google referer header.</p>": "<p>عند التفعيل، وهو الإعداد الافتراضي، يُنشئ ترويسات متصفح حقيقية ويضيفها. ويضبط ترويسة referer على Google أيضًا.</p>",+ "<p>Dict of proxies to use. Format: {\"http\": proxy_url, \"https\": proxy_url}.</p>": "<p>قاموس proxies المطلوب استخدامها. التنسيق: {\"http\": proxy_url, \"https\": proxy_url}.</p>",+ "<p>Proxy URL to use. Format: \"http://username:password@localhost:8030\".\nCannot be used together with the <code>proxies</code> parameter.</p>": "<p>عنوان proxy المطلوب استخدامه. التنسيق: \"http://username:password@localhost:8030\".\nلا يمكن استخدامه مع المعامل <code>proxies</code>.</p>",+ "<p>HTTP basic auth for proxy, tuple of (username, password).</p>": "<p>بيانات HTTP basic auth للـ proxy، في tuple بالشكل (username, password).</p>",+ "<p>Number of seconds to wait before timing out.</p>": "<p>عدد الثواني قبل انتهاء مهلة الانتظار.</p>",+ "<p>Headers to include in the session with every request.</p>": "<p>ترويسات تُضاف إلى كل طلب في الجلسة.</p>",+ "<p>Number of retry attempts. Defaults to 3.</p>": "<p>عدد محاولات إعادة الطلب. القيمة الافتراضية 3.</p>",+ "<p>Number of seconds to wait between retry attempts. Defaults to 1 second.</p>": "<p>عدد الثواني بين محاولات إعادة الطلب. القيمة الافتراضية ثانية واحدة.</p>",+ "<p>Whether to follow redirects. Defaults to \"safe\", which follows redirects but rejects those targeting internal/private IPs (SSRF protection). Pass True to follow all redirects without restriction.</p>": "<p>يحدد اتباع إعادة التوجيه. القيمة الافتراضية \"safe\"، وهي تتبع إعادة التوجيه مع رفض العناوين الداخلية أو الخاصة للحماية من SSRF. مرّر True لاتباع كل عمليات إعادة التوجيه دون قيود.</p>",+ "<p>Maximum number of redirects. Default 30, use -1 for unlimited.</p>": "<p>أقصى عدد لعمليات إعادة التوجيه. القيمة الافتراضية 30. استخدم -1 لإلغاء الحد.</p>",+ "<p>Whether to verify HTTPS certificates. Defaults to True.</p>": "<p>يحدد التحقق من شهادات HTTPS. القيمة الافتراضية True.</p>",+ "<p>Tuple of (cert, key) filenames for the client certificate.</p>": "<p>tuple يحتوي على اسمي ملفي شهادة العميل ومفتاحها بالشكل (cert, key).</p>",+ "<p>Arguments passed when creating the final Selector class.</p>": "<p>معاملات تُمرّر عند إنشاء صنف Selector النهائي.</p>",+ "<p>A ProxyRotator instance for automatic proxy rotation.</p>": "<p>كائن ProxyRotator لتبديل proxies تلقائيًا.</p>",+ "<p>Creates and returns a new synchronous Fetcher Session</p>": "<p>ينشئ جلسة Fetcher متزامنة جديدة ويُرجعها.</p>",+ "<p>Creates and returns a new asynchronous Session.</p>": "<p>ينشئ جلسة غير متزامنة جديدة ويُرجعها.</p>",+ "<p>A Stealthy Browser session manager with page pooling.</p>": "<p>مدير جلسة متصفح Stealthy مع مجموعة صفحات لإعادة استخدامها.</p>",+ "<p>A Browser session manager with page pooling, it's using a persistent browser Context by default with a temporary user profile directory.</p>": "<p>مدير جلسة متصفح مع مجموعة صفحات لإعادة استخدامها. يستخدم افتراضيًا سياق متصفح مستمرًا مع مجلد مؤقت لملف المستخدم.</p>",+ "<p>Save completed browser requests and responses. Failed or unfinished requests are omitted. Defaults to False.</p>": "<p>يحفظ طلبات المتصفح المكتملة واستجاباتها. يستبعد الطلبات الفاشلة أو غير المكتملة. القيمة الافتراضية False.</p>",+ "<p>Maximum retained requests per session. Defaults to 1000; older entries are removed.</p>": "<p>أقصى عدد طلبات محفوظة في الجلسة. القيمة الافتراضية 1000، وتُحذف السجلات الأقدم.</p>",+ "<p>Save cookies, local storage and IndexedDB to a Playwright-compatible JSON file.</p>": "<p>يحفظ cookies وlocal storage وIndexedDB في ملف JSON متوافق مع Playwright.</p>",+ "<p>Requires a started session without proxy rotation. Does not save sessionStorage.</p>": "<p>يتطلب جلسة بدأت بالفعل دون تبديل proxies. لا يحفظ sessionStorage.</p>",+ "<p>Replace cookies, local storage and IndexedDB from a Playwright-compatible JSON file.</p>": "<p>يستبدل cookies وlocal storage وIndexedDB بالبيانات الموجودة في ملف JSON متوافق مع Playwright.</p>",+ "<p>Requires a started session without proxy rotation. Fetch or reload pages to use the restored login.</p>": "<p>يتطلب جلسة بدأت بالفعل دون تبديل proxies. اجلب الصفحات أو أعد تحميلها لاستخدام تسجيل الدخول المستعاد.</p>",+ "<p>Close every open tab in the session's pool. The next request opens a fresh tab.</p>": "<p>يغلق كل التبويبات المفتوحة في مجموعة صفحات الجلسة. يفتح الطلب التالي تبويبًا جديدًا.</p>",+ "<p>Close all resources</p>": "<p>يغلق كل الموارد.</p>",+ "<p>Get statistics about the current page pool</p>": "<p>يعرض إحصاءات مجموعة الصفحات الحالية.</p>",+ "<p>Create a browser for this instance and context.</p>": "<p>ينشئ متصفحًا لهذا الكائن والسياق.</p>",+ "<p>Opens up the browser and do your request based on your chosen options.</p>": "<p>يفتح المتصفح وينفّذ الطلب حسب الخيارات التي تحددها.</p>",+ "<p>The Target url.</p>": "<p>الرابط المطلوب.</p>",+ "<p>Static proxy to override rotator and session proxy. A new browser context will be created and used with it.</p>": "<p>proxy ثابت له أولوية على أداة التبديل وproxy الجلسة. يُنشأ سياق متصفح جديد لاستخدامه معه.</p>",+ "<p>An async Stealthy Browser session manager with page pooling.</p>": "<p>مدير جلسة متصفح Stealthy غير متزامن مع مجموعة صفحات لإعادة استخدامها.</p>",+ "<p>A thread-safe proxy rotator with pluggable rotation strategies.</p>": "<p>أداة تبديل proxies آمنة مع تعدد threads، وتدعم إضافة طرق تبديل مختلفة.</p>",+ "<p>Supports:\n- Cyclic rotation (default)\n- Custom rotation strategies via callable\n- Both string URLs and Playwright-style dict proxies</p>": "<p>يدعم:\n- التبديل الدوري، وهو الافتراضي.\n- طرق تبديل مخصصة عبر callable.\n- عناوين proxies النصية وقواميس proxies بتنسيق Playwright.</p>",+ "<p>Initialize the proxy rotator.</p>": "<p>يُهيّئ أداة تبديل proxies.</p>",+ "<p>List of proxy URLs or Playwright-style proxy dicts.\n- String format: \"http://proxy1:8080\" or \"http://user:pass@proxy:8080\"\n- Dict format: {\"server\": \"http://proxy:8080\", \"username\": \"user\", \"password\": \"pass\"}</p>": "<p>قائمة عناوين proxies أو قواميس proxies بتنسيق Playwright.\n- التنسيق النصي: \"http://proxy1:8080\" أو \"http://user:pass@proxy:8080\".\n- تنسيق القاموس: {\"server\": \"http://proxy:8080\", \"username\": \"user\", \"password\": \"pass\"}.</p>",+ "<p>Rotation strategy function. Takes (proxies, current_index) and returns (proxy, next_index). Defaults to cyclic_rotation.</p>": "<p>دالة تحدد طريقة التبديل. تستقبل (proxies, current_index) وتُرجع (proxy, next_index). القيمة الافتراضية cyclic_rotation.</p>",+ "<p>Get a copy of all configured proxies.</p>": "<p>يُرجع نسخة من كل proxies المضبوطة.</p>",+ "<p>Get the next proxy according to the rotation strategy.</p>": "<p>يُرجع proxy التالي حسب طريقة التبديل.</p>",+ "<p>Return the total number of configured proxies.</p>": "<p>يُرجع العدد الإجمالي لـ proxies المضبوطة.</p>",+ "<p>Extends standard Python string by adding more functionality</p>": "<p>يوسّع نوع النص القياسي في Python بإضافة وظائف أخرى.</p>",+ "<p>Return a sorted version of the string</p>": "<p>يُرجع نسخة مرتبة من النص.</p>",+ "<p>Return a new version of the string after removing all white spaces and consecutive spaces</p>": "<p>يُرجع نسخة جديدة من النص بعد إزالة جميع المحارف البيضاء والمسافات المتتالية.</p>",+ "<p>Return JSON response if the response is jsonable otherwise throw error</p>": "<p>يُرجع الاستجابة بصيغة JSON إذا أمكن تحويلها، وإلا يُرجع خطأ.</p>",+ "<p>If enabled, this will ignore all whitespaces and consecutive spaces while matching</p>": "<p>عند التفعيل، يتجاهل جميع المحارف البيضاء والمسافات المتتالية أثناء المطابقة.</p>",+ "<p>If disabled, function will set the regex to ignore the letters-case while compiling it</p>": "<p>عند التعطيل، تضبط الدالة regex ليتجاهل الفرق بين الأحرف الكبيرة والصغيرة أثناء تجميعه.</p>",+ "<p>Used to quickly check if this regex matches or not without any operations on the results</p>": "<p>يُستخدم للتحقق بسرعة من وجود تطابق مع regex دون إجراء عمليات على النتائج.</p>",+ "<p>The :class:<code>TextHandlers</code> class is a subclass of the builtin <code>List</code> class, which provides a few additional methods.</p>": "<p>يرث الصنف :class:<code>TextHandlers</code> من الصنف المدمج <code>List</code> ويضيف بعض الدوال.</p>",+ "<p>Call the <code>.re()</code> method for each element in this list and return\ntheir results flattened as TextHandlers.</p>": "<p>يستدعي الدالة <code>.re()</code> لكل عنصر في القائمة، ويجمع النتائج في قائمة واحدة من نوع TextHandlers.</p>",+ "<p>if disabled, the function will set the regex to ignore the letters-case while compiling it</p>": "<p>عند التعطيل، تضبط الدالة regex ليتجاهل الفرق بين الأحرف الكبيرة والصغيرة أثناء تجميعه.</p>",+ "<p>Call the <code>.re_first()</code> method for each element in this list and return\nthe first result or the default value otherwise.</p>": "<p>يستدعي الدالة <code>.re_first()</code> لكل عنصر في القائمة، ويُرجع أول نتيجة، أو القيمة الافتراضية إذا لم توجد نتيجة.</p>",+ "<p>Returns the first item of the current list</p>": "<p>يُرجع أول عنصر في القائمة الحالية.</p>",+ "<p>the default value to return if the current list is empty</p>": "<p>القيمة الافتراضية التي تُرجع إذا كانت القائمة الحالية فارغة.</p>",+ "<p>A read-only mapping to use instead of the standard dictionary for the speed boost, but at the same time I use it to add more functionalities.\nIf the standard dictionary is needed, convert this class to a dictionary with the <code>dict</code> function</p>": "<p>mapping للقراءة فقط يُستخدم بدلًا من القاموس القياسي لزيادة السرعة، ويضيف وظائف أخرى أيضًا.\nإذا احتجت إلى قاموس قياسي، فحوّل هذا الصنف إلى قاموس باستخدام الدالة <code>dict</code>.</p>",+ "<p>Convert current attributes to JSON bytes if the attributes are JSON serializable otherwise throws error</p>": "<p>يحوّل الخصائص الحالية إلى بايتات JSON إذا أمكن تحويلها، وإلا يُرجع خطأ.</p>",+ "<p>Acts like the standard dictionary <code>.get()</code> method</p>": "<p>يعمل مثل دالة <code>.get()</code> في القاموس القياسي.</p>",+ "<p>Search current attributes by values and return a dictionary of each matching item</p>": "<p>يبحث في الخصائص الحالية حسب القيم، ويُرجع قاموسًا لكل عنصر مطابق.</p>",+ "<p>The keyword to search for in the attribute values</p>": "<p>الكلمة المطلوب البحث عنها في قيم الخصائص.</p>",+ "<p>If True, the function will search if keyword in each value instead of perfect match</p>": "<p>عندما تكون القيمة True، تبحث الدالة عن وجود الكلمة داخل كل قيمة، بدلًا من اشتراط التطابق الكامل.</p>",+ "<p>Request's response information structure.</p>": "<p>بنية معلومات استجابة الطلب.</p>",+ "<p><code>browser_network_requests</code> returns <code>NetworkRequestsModel</code> with <code>requests</code>, <code>next_cursor</code>, <code>has_more</code>, and <code>dropped_count</code>. Each <code>NetworkRequestInfo</code> contains <code>id</code>, <code>url</code>, <code>method</code>, <code>resource_type</code>, and <code>status</code>. Pass <code>next_cursor</code> as <code>after_id</code> to continue; <code>has_more</code> indicates more current matches.</p>": "<p>تُرجع <code>browser_network_requests</code> كائن <code>NetworkRequestsModel</code> يحتوي على <code>requests</code> و<code>next_cursor</code> و<code>has_more</code> و<code>dropped_count</code>. يحتوي كل <code>NetworkRequestInfo</code> على <code>id</code> و<code>url</code> و<code>method</code> و<code>resource_type</code> و<code>status</code>. مرّر <code>next_cursor</code> كقيمة <code>after_id</code> للمتابعة. تشير <code>has_more</code> إلى وجود نتائج مطابقة أخرى حاليًا.</p>",+ "<p><code>browser_network_request</code> returns <code>NetworkRequestModel</code> with <code>request_id</code>, <code>part</code>, <code>data</code>, and <code>note</code>. Summaries and headers are objects; the full saved body text is returned as a string, including JSON response text. <code>note</code> explains missing body data or partial headers.</p>": "<p>تُرجع <code>browser_network_request</code> كائن <code>NetworkRequestModel</code> يحتوي على <code>request_id</code> و<code>part</code> و<code>data</code> و<code>note</code>. تكون الملخصات والترويسات كائنات، بينما يُرجع نص الجسم المحفوظ كاملًا كنص، بما فيه نص استجابة JSON. توضّح <code>note</code> سبب غياب بيانات الجسم أو عدم اكتمال الترويسات.</p>",+ "<p>Summary of a recorded browser request.</p>": "<p>ملخص طلب متصفح مسجل.</p>",+ "<p>Recorded request summaries and pagination details.</p>": "<p>ملخصات الطلبات المسجلة وتفاصيل تقسيمها إلى صفحات.</p>",+ "<p>One complete saved request part, with an optional note.</p>": "<p>جزء كامل محفوظ من طلب واحد، مع ملاحظة اختيارية.</p>",+ "<p>Model classes for session management:</p>": "<p>أصناف النماذج لإدارة الجلسات:</p>",+ "<p>Information about an open browser session.</p>": "<p>معلومات جلسة متصفح مفتوحة.</p>",+ "<p>Response returned when a new session is created.</p>": "<p>الاستجابة التي تُرجع عند إنشاء جلسة جديدة.</p>",+ "<p>Response returned when a session is closed.</p>": "<p>الاستجابة التي تُرجع عند إغلاق جلسة.</p>",+ "<p>The main MCP server class that provides all web scraping tools:</p>": "<p>الكلاس الأساسي لخادم MCP الذي يوفر جميع أدوات استخراج بيانات الويب:</p>",+ "<p><strong><code>browser_fetch_once</code></strong>: Fetch one URL through a stealthy browser with JavaScript rendering and Cloudflare handling, then close the browser. Use a persistent session for later actions or network history.</p>": "<p><strong><code>browser_fetch_once</code></strong>: يجلب عنوان URL واحدًا عبر متصفح Stealth، مع تشغيل JavaScript والتعامل مع Cloudflare، ثم يغلق المتصفح. استخدم جلسة دائمة إذا احتجت إلى إجراءات لاحقة أو سجل طلبات الشبكة.</p>",+ "<p><strong><code>browser_extract</code></strong>: Read the current page or one element as an AI snapshot, HTML, Markdown, or text without reloading it. Keep results from forms and page actions. Snapshots include element roles, names, references, positions, and sizes; regex search returns matching lines with nearby context and parent nodes.</p>": "<p><strong><code>browser_extract</code></strong>: يقرأ الصفحة الحالية أو عنصرًا واحدًا بصيغة snapshot للذكاء الاصطناعي، أو HTML أو Markdown أو نص، دون إعادة تحميل الصفحة. يحتفظ بنتائج النماذج وإجراءات الصفحة. تتضمن snapshot أدوار العناصر وأسماءها ومراجعها ومواضعها وأحجامها. يعيد البحث باستخدام regex الأسطر المطابقة مع السياق القريب والعناصر الأب.</p>",+ "<p><strong><code>browser_actions</code></strong>: Chain mouse moves, hovers, clicks, scrolling, field filling, keyboard shortcuts, dialog replies, and waits in one call. Accept or dismiss alerts and confirmations, or enter text in prompts. Fill a search box, submit it, wait for results, and open a result without a separate call for each step.</p>": "<p><strong><code>browser_actions</code></strong>: يجمع تحريك الماوس والمرور فوق العناصر والنقر والتمرير وملء الحقول واختصارات لوحة المفاتيح والرد على مربعات الحوار والانتظار في استدعاء واحد. يمكنك قبول التنبيهات والتأكيدات أو رفضها، أو إدخال نص في مربعات الإدخال. املأ مربع بحث، وأرسله، وانتظر النتائج، ثم افتح نتيجة دون استدعاء منفصل لكل خطوة.</p>",+ "<p>Moves and clicks target selectors, snapshot references, or coordinates; element targets wait and scroll into view. Supports movement in multiple steps, left, right, and middle clicks, double-clicks, and scrolling nested panels.</p>": "<p>تستهدف الحركة والنقر محددات العناصر أو مراجع snapshot أو الإحداثيات. عند استهداف عنصر، تنتظر الأداة توفره وتمرّر الصفحة حتى يظهر. تدعم الحركة عبر عدة خطوات، والنقر بالزر الأيسر والأيمن والأوسط، والنقر المزدوج، والتمرير داخل اللوحات المتداخلة.</p>",+ "<p>Target fields anywhere on the page through selectors or snapshot references. Fill text, check or uncheck boxes, select radio buttons, and choose one or more native dropdown options by label. Replace or clear text, or type at the current caret. Keyboard shortcuts use the current focus. Slow mode adds random pauses between typed characters and all actions.</p>": "<p>استهدف الحقول في أي مكان في الصفحة باستخدام المحددات أو مراجع snapshot. املأ النصوص، وحدد مربعات الاختيار أو ألغِ تحديدها، واختر أزرار الاختيار، وحدد خيارًا أو أكثر من القوائم المنسدلة الأصلية حسب التسمية. استبدل النص أو امسحه، أو اكتب عند موضع المؤشر الحالي. تعمل اختصارات لوحة المفاتيح على العنصر الذي عليه التركيز حاليًا. يضيف الوضع البطيء فترات انتظار عشوائية بين الأحرف المكتوبة وبين جميع الإجراءات.</p>",+ "<p>Wait for content or loading overlays through selectors or snapshot references, wait for page load events or settled network activity, or add a fixed pause before continuing.</p>": "<p>انتظر ظهور المحتوى أو اختفاء طبقات التحميل باستخدام المحددات أو مراجع snapshot، أو انتظر أحداث تحميل الصفحة أو استقرار نشاط الشبكة، أو أضف انتظارًا ثابتًا قبل المتابعة.</p>",+ "<p><strong><code>browser_evaluate</code></strong>: Run JavaScript on the current page to extract custom data, calculate results, read application state, or update page content. Supports asynchronous scripts and returns their results as JSON.</p>": "<p><strong><code>browser_evaluate</code></strong>: يشغّل JavaScript على الصفحة الحالية لاستخراج بيانات مخصّصة أو حساب النتائج أو قراءة حالة التطبيق أو تعديل محتوى الصفحة. يدعم السكربتات غير المتزامنة ويعيد نتائجها بصيغة JSON.</p>",+ "<p>Create a Scrapling MCP server.</p>": "<p>إنشاء خادم Scrapling MCP.</p>",+ "<p>Optional global Chromium-compatible browser executable path for browser tools.\nIf omitted, the SCRAPLING_EXECUTABLE_PATH environment variable is used when set.</p>": "<p>مسار عام اختياري لملف تشغيل متصفح متوافق مع Chromium، تستخدمه أدوات المتصفح.\nإذا لم تحدده، تُستخدم قيمة متغير البيئة SCRAPLING_EXECUTABLE_PATH إذا كان مضبوطًا.</p>",+ "<p>Optional shared token that clients must send as <code>Authorization: Bearer <token></code>.\nIf omitted, the SCRAPLING_MCP_AUTH_TOKEN environment variable is used when set. It only applies\nto the streamable-http transport.</p>": "<p>رمز مشترك اختياري يجب أن ترسله البرامج المتصلة بصيغة <code>Authorization: Bearer <token></code>.\nإذا لم تحدده، تُستخدم قيمة متغير البيئة SCRAPLING_MCP_AUTH_TOKEN إذا كان مضبوطًا. ينطبق ذلك فقط\nعلى طريقة النقل streamable-http.</p>",+ "<p>Open a reusable stealthy browser session. Pass per-request options to <code>browser_fetch</code>.</p>": "<p>فتح جلسة متصفح Stealth قابلة لإعادة الاستخدام. مرّر خيارات كل طلب إلى <code>browser_fetch</code>.</p>",+ "<p>Save browser cookies, local storage and IndexedDB as Playwright-compatible JSON. Excludes sessionStorage.</p>": "<p>حفظ ملفات تعريف ارتباط المتصفح وlocal storage وIndexedDB بصيغة JSON متوافقة مع Playwright. لا يشمل sessionStorage.</p>",+ "<p>Replace browser cookies, local storage and IndexedDB from a Playwright-compatible JSON file.</p>": "<p>استبدال ملفات تعريف ارتباط المتصفح وlocal storage وIndexedDB من ملف JSON متوافق مع Playwright.</p>",+ "<p>Leaves sessionStorage and open tabs unchanged. Fetch or reload pages to use the restored login.</p>": "<p>يترك sessionStorage والتبويبات المفتوحة كما هي. اجلب الصفحات أو أعد تحميلها لاستخدام حالة تسجيل الدخول المستعادة.</p>",+ "<p>Open a reusable HTTP session for <code>session_make_request</code>, keeping cookies, connections, and request settings.</p>": "<p>فتح جلسة HTTP قابلة لإعادة الاستخدام مع <code>session_make_request</code>، مع الاحتفاظ بملفات تعريف الارتباط والاتصالات وإعدادات الطلبات.</p>",+ "<p>Close a session and free its resources.</p>": "<p>إغلاق جلسة وتحرير الموارد التي تستخدمها.</p>",+ "<p>List registered sessions, their status, and effective settings.</p>": "<p>عرض الجلسات المسجلة وحالتها وإعداداتها الفعلية.</p>",+ "<p>List completed requests across page changes, with IDs and pagination. Recording starts when the browser session opens.</p>": "<p>عرض الطلبات المكتملة عبر التنقل بين الصفحات، مع المعرّفات وتقسيم النتائج إلى صفحات. يبدأ التسجيل عند فتح جلسة المتصفح.</p>",+ "<p>Read a complete saved request part without resending it, with structured data and availability notes.</p>": "<p>قراءة جزء كامل من طلب محفوظ دون إعادة إرساله، مع بيانات منظمة وملاحظات عن مدى توفرها.</p>",+ "<p>Read the current page or one element as snapshot, HTML, Markdown, or text without navigating.\nReturn plain text; snapshot search keeps refs, ancestor paths and three lines of nearby context.</p>": "<p>قراءة الصفحة الحالية أو عنصر واحد بصيغة snapshot أو HTML أو Markdown أو نص، دون الانتقال إلى صفحة أخرى.\nيعيد نصًا عاديًا. يحتفظ البحث في snapshot بالمراجع ومسارات العناصر الأعلى وثلاثة أسطر من السياق القريب.</p>",+ "<p>Run mouse, field, key, dialog, and wait actions in order; return plain text without a snapshot.\nStop on the first error, identifying its action; partial effects remain. No retries.\nElement mouse targets auto-wait and scroll into view; coordinates and wheel do not wait for navigation or scrolling.\nCancelled/timed-out clicks attempt button release. Load waits observe the current document, not future navigation.</p>": "<p>تنفيذ إجراءات الماوس والحقول والمفاتيح ومربعات الحوار والانتظار بالترتيب، ثم إعادة نص عادي دون snapshot.\nيتوقف عند أول خطأ ويحدد الإجراء الذي سببه. تبقى آثار الإجراءات السابقة، ولا توجد إعادة محاولة.\nعند استهداف عنصر بالماوس، تنتظر الأداة تلقائيًا وتمرّر الصفحة حتى يظهر. لا تنتظر الإحداثيات وعجلة الماوس اكتمال الانتقال أو التمرير.\nعند إلغاء النقر أو انتهاء مهلته، تحاول الأداة تحرير زر الماوس. يراقب انتظار التحميل المستند الحالي، ولا ينتظر انتقالًا لاحقًا.</p>",+ "<p>Run JavaScript on the current page, await promises, and return JSON text without a snapshot.\nReturn JSON-compatible values; null/undefined become null. Script effects are not undone on failure.\nCancellation stops waiting, but may not stop the script.</p>": "<p>تشغيل JavaScript على الصفحة الحالية، وانتظار promises، وإعادة نص JSON دون snapshot.\nأعد قيمًا متوافقة مع JSON. تتحول null وundefined إلى null. لا تُلغى آثار السكربت عند الفشل.\nيوقف الإلغاء الانتظار، لكنه قد لا يوقف السكربت.</p>",+ "<p>Capture the current page or one element without navigating; return the image and current URL.\nElement capture waits and scrolls into view. Use browser_actions for other waits before capture.</p>": "<p>التقاط صورة للصفحة الحالية أو لعنصر واحد دون الانتقال، وإعادة الصورة وعنوان URL الحالي.\nعند التقاط عنصر، تنتظر الأداة وتُمرّر الصفحة حتى يظهر. استخدم browser_actions لأي انتظار آخر قبل الالتقاط.</p>",+ "<p>Make an HTTP request without JavaScript. Suitable for low-to-mid protection.</p>": "<p>إرسال طلب HTTP دون JavaScript. مناسب للحماية المنخفضة إلى المتوسطة.</p>",+ "<p>Fetch a page with a stealth browser and JavaScript rendering.</p>": "<p>جلب صفحة باستخدام متصفح Stealth مع تشغيل JavaScript.</p>",+ "<p>Fetch a URL in an open stealthy browser session. Options apply only to this request.</p>": "<p>جلب عنوان URL داخل جلسة متصفح Stealth مفتوحة. تنطبق الخيارات على هذا الطلب فقط.</p>",+ "<p>Make an HTTP request using the session's cookies, connections, impersonation, and proxy. Options apply to this request.</p>": "<p>إرسال طلب HTTP باستخدام ملفات تعريف الارتباط والاتصالات ومحاكاة المتصفح والبروكسي الخاصة بالجلسة. تنطبق الخيارات على هذا الطلب.</p>",+ "<p>Serve the MCP server.</p>": "<p>تشغيل خادم MCP لاستقبال الاتصالات.</p>",+ "<p>Serve over the streamable-http transport instead of stdio.</p>": "<p>استخدام طريقة النقل streamable-http بدلًا من stdio.</p>",+ "<p>The host to bind to when <code>http</code> is enabled.</p>": "<p>المضيف الذي يستمع عليه الخادم عند تفعيل <code>http</code>.</p>",+ "<p>The port to bind to when <code>http</code> is enabled.</p>": "<p>المنفذ الذي يستمع عليه الخادم عند تفعيل <code>http</code>.</p>",+ "<p>Host names to accept, which turns on DNS-rebinding protection.</p>": "<p>أسماء المضيفين المقبولة، ويؤدي تحديدها إلى تفعيل الحماية من هجمات DNS rebinding.</p>",+ "<p>Start the streamable-http transport without a token. The transport\nrequires authentication by default, so this is the explicit opt-out.</p>": "<p>تشغيل النقل streamable-http دون رمز وصول. تتطلب طريقة النقل\nالتحقق من الهوية افتراضيًا، ولذلك يُستخدم هذا الخيار لتعطيله صراحةً.</p>",+ "<p>The <code>Selectors</code> class is a subclass of the builtin <code>List</code> class, which provides a few additional methods.</p>": "<p>الكلاس <code>Selectors</code> يرث من كلاس <code>List</code> المدمج، ويوفر بعض الدوال الإضافية.</p>",+ "<p>Returns the first Selector item of the current list or <code>None</code> if the list is empty</p>": "<p>يعيد أول عنصر Selector من القائمة الحالية، أو <code>None</code> إذا كانت القائمة فارغة.</p>",+ "<p>Returns the last Selector item of the current list or <code>None</code> if the list is empty</p>": "<p>يعيد آخر عنصر Selector من القائمة الحالية، أو <code>None</code> إذا كانت القائمة فارغة.</p>",+ "<p>Returns the length of the current list</p>": "<p>يعيد طول القائمة الحالية.</p>",+ "<p>Call the <code>.xpath()</code> method for each element in this list and return\ntheir results as another <code>Selectors</code> class.</p>": "<p>يستدعي <code>.xpath()</code> لكل عنصر في هذه القائمة، ويعيد\nالنتائج في كائن <code>Selectors</code> آخر.</p>",+ "<p>A string that will be used to retrieve element's data in adaptive,\notherwise the selector will be used.</p>": "<p>نص يُستخدم لاسترجاع بيانات العنصر في الوضع التكيفي.\nوإذا لم تحدده، يُستخدم المحدد.</p>",+ "<p>Call the <code>.css()</code> method for each element in this list and return\ntheir results flattened as another <code>Selectors</code> class.</p>": "<p>يستدعي <code>.css()</code> لكل عنصر في هذه القائمة، ويجمع\nالنتائج في كائن <code>Selectors</code> آخر دون قوائم متداخلة.</p>",+ "<p>Call the <code>.re()</code> method for each element in this list and return\ntheir results flattened as List of TextHandler.</p>": "<p>يستدعي <code>.re()</code> لكل عنصر في هذه القائمة، ويجمع\nالنتائج في قائمة من TextHandler دون قوائم متداخلة.</p>",+ "<p>if disabled, function will set the regex to ignore the letters case while compiling it</p>": "<p>إذا كان معطلًا، تضبط الدالة regex بحيث يتجاهل حالة الأحرف عند تجهيزه.</p>",+ "<p>Loop over all current elements and return the first element that matches the passed function</p>": "<p>يمرّ على جميع العناصر الحالية ويعيد أول عنصر يطابق الدالة الممرّرة.</p>",+ "<p>A function that takes each element as an argument and returns True/False</p>": "<p>دالة تستقبل كل عنصر كمعامل وتعيد True أو False.</p>",+ "<p>The first element that match the function or <code>None</code> otherwise.</p>": "<p>أول عنصر يطابق الدالة، أو <code>None</code> إذا لم يوجد.</p>",+ "<p>Filter current elements based on the passed function</p>": "<p>تصفية العناصر الحالية وفقًا للدالة الممرّرة.</p>",+ "<p>The new <code>Selectors</code> object or empty list otherwise.</p>": "<p>كائن <code>Selectors</code> الجديد، أو قائمة فارغة إذا لم توجد نتائج.</p>",+ "<p>Returns the serialized string of the first element, or <code>default</code> if empty.</p>": "<p>يعيد التمثيل النصي لأول عنصر، أو <code>default</code> إذا كانت القائمة فارغة.</p>",+ "<p>Serialize all elements and return as a TextHandlers list.</p>": "<p>يحوّل جميع العناصر إلى نصوص ويعيدها في قائمة TextHandlers.</p>",+ "<p>An abstract base class for creating web spiders.</p>": "<p>كلاس أساسي مجرد لإنشاء عناكب الويب.</p>",+ "<p>Check the documentation website for more information.</p>": "<p>راجع موقع التوثيق لمزيد من المعلومات.</p>",+ "<p>Initialize the spider.</p>": "<p>تهيئة العنكبوت.</p>",+ "<p>Directory for checkpoint files. If provided, enables pause/resume.</p>": "<p>مجلد ملفات نقاط الاستكمال. يؤدي تحديده إلى تفعيل الإيقاف المؤقت والاستكمال.</p>",+ "<p>Seconds between periodic checkpoint saves (default 5 minutes).</p>": "<p>عدد الثواني بين مرات الحفظ الدوري لنقاط الاستكمال. القيمة الافتراضية 5 دقائق.</p>",+ "<p>Access current crawl stats (works during streaming).</p>": "<p>الوصول إلى إحصاءات الزحف الحالية. يعمل أيضًا أثناء استقبال البيانات مباشرة.</p>",+ "<p>Generate initial requests to start the crawl.</p>": "<p>إنشاء الطلبات الأولى لبدء الزحف.</p>",+ "<p>By default, this generates Request objects for each URL in <code>start_urls</code>\nusing the session manager's default session and <code>parse()</code> as callback.</p>": "<p>ينشئ افتراضيًا كائن Request لكل عنوان URL في <code>start_urls</code>،\nباستخدام الجلسة الافتراضية لمدير الجلسات و<code>parse()</code> كدالة callback.</p>",+ "<p>Override this method for more control over initial requests\n(e.g., to add custom headers, use different callbacks, etc.)</p>": "<p>أعد تعريف هذه الدالة للتحكم بدرجة أكبر في الطلبات الأولى،\nمثل إضافة ترويسات مخصّصة أو استخدام دوال callback مختلفة.</p>",+ "<p>Default callback for processing responses</p>": "<p>دالة callback الافتراضية لمعالجة الردود.</p>",+ "<p>Called before crawling starts. Override for setup logic.</p>": "<p>تُستدعى قبل بدء الزحف. أعد تعريفها لتنفيذ خطوات الإعداد.</p>",+ "<p>It's enabled if the spider is resuming from a checkpoint, left for the user to use.</p>": "<p>تكون مفعّلة إذا كان العنكبوت يستكمل من نقطة محفوظة، وهي متاحة للمستخدم ليستفيد منها.</p>",+ "<p>Called after crawling finishes. Override for cleanup logic.</p>": "<p>تُستدعى بعد انتهاء الزحف. أعد تعريفها لتنفيذ خطوات التنظيف والإغلاق.</p>",+ "<p>Handle request errors for all spider requests.</p>": "<p>معالجة أخطاء جميع طلبات العنكبوت.</p>",+ "<p>Override for custom error handling.</p>": "<p>أعد تعريفها لتخصيص معالجة الأخطاء.</p>",+ "<p>A hook to be overridden by users to do some processing on scraped items, return <code>None</code> to drop the item silently.</p>": "<p>دالة يمكن للمستخدم إعادة تعريفها لمعالجة البيانات المستخرجة. أعد <code>None</code> لاستبعاد العنصر دون رسالة.</p>",+ "<p>Check if the response is blocked. Users should override this for custom detection logic.</p>": "<p>فحص ما إذا كان الرد يدل على حظر. أعد تعريفها لاستخدام طريقة اكتشاف مخصّصة.</p>",+ "<p>Users should override this to prepare the blocked request before retrying, if needed.</p>": "<p>يمكن للمستخدم إعادة تعريفها لتجهيز الطلب المحظور قبل إعادة المحاولة، إذا لزم الأمر.</p>",+ "<p>String representation of the spider.</p>": "<p>التمثيل النصي للعنكبوت.</p>",+ "<p>Configure sessions for this spider.</p>": "<p>إعداد جلسات هذا العنكبوت.</p>",+ "<p>Override this method to add custom sessions.\nThe default implementation creates a FetcherSession session.</p>": "<p>أعد تعريف هذه الدالة لإضافة جلسات مخصّصة.\nينشئ السلوك الافتراضي جلسة FetcherSession.</p>",+ "<p>The first session added becomes the default for <code>start_requests()</code> unless specified otherwise.</p>": "<p>تصبح أول جلسة تضيفها هي الافتراضية لـ <code>start_requests()</code> ما لم تحدد غير ذلك.</p>",+ "<p>SessionManager to configure</p>": "<p>كائن SessionManager المراد إعداده.</p>",+ "<p>Request graceful shutdown of the crawling process.</p>": "<p>طلب إغلاق منظم لعملية الزحف.</p>",+ "<p>Run the spider and return results.</p>": "<p>تشغيل العنكبوت وإعادة النتائج.</p>",+ "<p>This is the main entry point for running a spider.\nHandles async execution internally via anyio.</p>": "<p>هذه هي نقطة البدء الأساسية لتشغيل العنكبوت.\nتدير التنفيذ غير المتزامن داخليًا عبر anyio.</p>",+ "<p>Pressing Ctrl+C will initiate graceful shutdown (waits for active tasks to complete).\nPressing Ctrl+C a second time will force immediate stop.</p>": "<p>يبدأ الضغط على Ctrl+C إغلاقًا منظمًا ينتظر اكتمال المهام الجارية.\nالضغط على Ctrl+C مرة ثانية يفرض الإيقاف الفوري.</p>",+ "<p>If crawldir is set, a checkpoint will also be saved on graceful shutdown,\nallowing you to resume the crawl later by running the spider again.</p>": "<p>إذا حددت crawldir، تُحفظ نقطة استكمال عند الإغلاق المنظم أيضًا،\nمما يتيح استكمال الزحف لاحقًا بتشغيل العنكبوت مجددًا.</p>",+ "<p>Whether to use the faster uvloop/winloop event loop implementation, if available.</p>": "<p>ما إذا كان سيستخدم event loop الأسرع uvloop أو winloop، إذا كان متاحًا.</p>",+ "<p>Asyncio backend options to be used with <code>anyio.run</code></p>": "<p>خيارات خلفية Asyncio المستخدمة مع <code>anyio.run</code>.</p>",+ "<p>Stream items as they're scraped. Ideal for long-running spiders or building applications on top of the spiders.</p>": "<p>إخراج البيانات فور استخراجها. مناسب للعناكب التي تعمل طويلًا أو للتطبيقات المبنية على العناكب.</p>",+ "<p>Must be called from an async context. Yields items one by one as they are scraped.\nAccess <code>spider.stats</code> during iteration for real-time statistics.</p>": "<p>يجب استدعاؤها من سياق غير متزامن. تُخرج البيانات واحدة تلو الأخرى عند استخراجها.\nاقرأ <code>spider.stats</code> أثناء المرور على البيانات للحصول على إحصاءات مباشرة.</p>",+ "<p>Note: SIGINT handling for pause/resume is not available in stream mode.</p>": "<p>ملاحظة: معالجة SIGINT للإيقاف المؤقت والاستكمال غير متاحة في وضع استقبال البيانات مباشرة.</p>",+ "<p>Create a copy of this request.</p>": "<p>إنشاء نسخة من هذا الطلب.</p>",+ "<p>Generate a unique fingerprint for deduplication.</p>": "<p>إنشاء بصمة فريدة لمنع التكرار.</p>",+ "<p>Caches the result in self._fp after first computation.</p>": "<p>يحفظ النتيجة في self._fp بعد حسابها أول مرة.</p>",+ "<p>Compare requests by priority</p>": "<p>مقارنة الطلبات حسب الأولوية.</p>",+ "<p>Requests are equal if they have the same fingerprint.</p>": "<p>تُعتبر الطلبات متساوية إذا كانت لها البصمة نفسها.</p>",+ "<p>Prepare state for pickling - store callback as name string for pickle compatibility.</p>": "<p>تجهيز الحالة للحفظ باستخدام pickle. تُحفظ دالة callback كنص يحتوي على اسمها للتوافق مع pickle.</p>",+ "<p>Restore state from pickle - callback restored later via _restore_callback().</p>": "<p>استعادة الحالة من pickle. تُستعاد دالة callback لاحقًا عبر _restore_callback().</p>",+ "<p>Complete result from a spider run.</p>": "<p>النتيجة الكاملة لتشغيل العنكبوت.</p>",+ "<p>True if the crawl completed normally (not paused).</p>": "<p>تكون True إذا اكتمل الزحف بصورة طبيعية دون إيقاف مؤقت.</p>",+ "<p>Statistics for a crawl run.</p>": "<p>إحصاءات عملية زحف.</p>",+ "<p>A list of scraped items with export capabilities.</p>": "<p>قائمة بالبيانات المستخرجة تدعم التصدير.</p>",+ "<p>Export items to a JSON file.</p>": "<p>تصدير البيانات إلى ملف JSON.</p>",+ "<p>Path to the output file</p>": "<p>مسار ملف النتائج.</p>",+ "<p>Pretty-print with 2-space indentation (slightly slower)</p>": "<p>تنسيق الناتج بمسافة بادئة قدرها مسافتان. يكون أبطأ قليلًا.</p>",+ "<p>Export items as JSON Lines (one JSON object per line).</p>": "<p>تصدير البيانات بصيغة JSON Lines، بحيث يحتوي كل سطر على كائن JSON واحد.</p>",+ "<p>Export items to a CSV file.</p>": "<p>تصدير البيانات إلى ملف CSV.</p>",+ "<p>Items that don't share the same keys are still written, with the missing cells left empty, and any value\nthat isn't a scalar (a nested dictionary or a list) is written as JSON.</p>": "<p>تُكتب العناصر حتى لو لم تكن مفاتيحها متطابقة، وتُترك الخلايا التي لا تتوفر لها قيمة فارغة.\nوتُكتب أي قيمة غير مفردة، مثل قاموس متداخل أو قائمة، بصيغة JSON.</p>",+ "<p>The columns to write, defaulting to every key found in the items, in the order they appeared</p>": "<p>الأعمدة المراد كتابتها. افتراضيًا تشمل كل مفتاح موجود في البيانات، حسب ترتيب ظهوره.</p>",+ "<p>The character separating the columns</p>": "<p>الحرف الذي يفصل بين الأعمدة.</p>",+ "<p>Export items to an XML file.</p>": "<p>تصدير البيانات إلى ملف XML.</p>",+ "<p>Each item becomes an element whose children are named after the item's keys. Keys that aren't valid XML\nnames are rewritten and keep the original in a <code>name</code> attribute, and any value that isn't a scalar\n(a nested dictionary or a list) is written as JSON.</p>": "<p>يصبح كل عنصر بيانات عنصر XML، وتُسمّى عناصره الفرعية بأسماء مفاتيحه. تُعدّل المفاتيح التي لا تصلح كأسماء XML،\nمع حفظ الاسم الأصلي في الخاصية <code>name</code>. وتُكتب أي قيمة غير مفردة،\nمثل قاموس متداخل أو قائمة، بصيغة JSON.</p>",+ "<p>The name of the element wrapping all the items</p>": "<p>اسم العنصر الذي يحتوي على جميع عناصر البيانات.</p>",+ "<p>The name of the element wrapping every item</p>": "<p>اسم العنصر الذي يحتوي على كل عنصر بيانات.</p>",+ "<p>Pretty-print the file instead of writing it on a single line</p>": "<p>تنسيق الملف لتسهيل قراءته بدلًا من كتابته في سطر واحد.</p>",+ "<p>Manages pre-configured session instances.</p>": "<p>يدير كائنات جلسات جاهزة الإعداد.</p>",+ "<p>Register a session instance.</p>": "<p>تسجيل كائن جلسة.</p>",+ "<p>Name to reference this session in requests</p>": "<p>اسم لاختيار هذه الجلسة في الطلبات.</p>",+ "<p>Your pre-configured session instance</p>": "<p>كائن الجلسة الذي أعددته مسبقًا.</p>",+ "<p>If True, this becomes the default session</p>": "<p>إذا كانت True، تصبح هذه هي الجلسة الافتراضية.</p>",+ "<p>If True, the session will be started only when a request uses its ID.</p>": "<p>إذا كانت True، لا تبدأ الجلسة إلا عندما يستخدم طلب معرّفها.</p>",+ "<p>Removes a session.</p>": "<p>إزالة جلسة.</p>",+ "<p>ID of session to remove</p>": "<p>معرّف الجلسة المراد إزالتها.</p>",+ "<p>Remove and returns a session.</p>": "<p>إزالة جلسة وإعادتها.</p>",+ "<p>Start all sessions that aren't already alive.</p>": "<p>بدء جميع الجلسات التي لا تعمل بعد.</p>",+ "<p>Close all registered sessions.</p>": "<p>إغلاق جميع الجلسات المسجلة.</p>",+ "<p>Check if a session ID is registered.</p>": "<p>فحص ما إذا كان معرّف الجلسة مسجلًا.</p>",+ "<p>Number of registered sessions.</p>": "<p>عدد الجلسات المسجلة.</p>"+} %}+{% macro translate(value) %}+ {% set result = namespace(html=value | replace("Bases:", "الفئات الأساسية:")) %}+ {% for source, target in translations.items() %}+ {% set result.html = result.html | replace(source, target | safe) %}+ {% endfor %}+ {{ result.html | safe }}+{% endmacro %}diff --git a/includes/sponsors.html b/includes/sponsors.htmlnew file mode 100644index 0000000..6a5cd32--- /dev/null+++ b/includes/sponsors.html@@ -0,0 +1,43 @@+<style>+.ad {+ width:240px;+ height:100px;+}++</style>++<div style="text-align: center;">+ <a href="https://go.nodemaven.com/scraplingseptember" target="_blank" title="Proxies with the Highest IP Scores">+ <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/NodeMaven.jpg" class="ad">+ </a>+ <a href="https://hypersolutions.co/?utm_source=github&utm_medium=readme&utm_campaign=scrapling" target="_blank" title="Bot Protection Bypass API for Akamai, DataDome, Incapsula & Kasada">+ <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/HyperSolutions.png" class="ad">+ </a>+ <a href="https://evomi.com?utm_source=github&utm_medium=banner&utm_campaign=d4vinci-scrapling" target="_blank" title="Evomi is your Swiss Quality Proxy Provider, starting at $0.49/GB">+ <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/evomi.png" class="ad">+ </a>+ <a href="https://tikhub.io/?utm_source=github.com/D4Vinci/Scrapling&utm_medium=marketing_social&utm_campaign=retargeting&utm_content=carousel_ad" target="_blank" title="Unlock the Power of Social Media Data & AI">+ <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/TikHub.jpg" class="ad">+ </a>+ <a href="https://substack.thewebscraping.club/p/scrapling-hands-on-guide?utm_source=github&utm_medium=repo&utm_campaign=scrapling" target="_blank" title="The #1 newsletter dedicated to Web Scraping">+ <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/TWSC.png" class="ad">+ </a>+ <a href="https://www.swiftproxy.net/?ref=D4Vinci" target="_blank" title="Scalable Solutions for Web Data Access">+ <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/SwiftProxy.png" class="ad">+ </a>+ <a href="https://byteful.com/?utm_source=scrapling_website&utm_medium=github-sponsor&utm_campaign=scrapling_github_sponsor" target="_blank" title="Ethically sourced residential proxy infrastructure powering web scraping and AI agents">+ <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/byteful.png" class="ad">+ </a>+ <a href="https://proxylane.dev/?utm_source=scrapling&utm_medium=partnership&utm_campaign=scrapling_platinum_202609&utm_content=github_readme" target="_blank" title="28M+ clean residential IPs for browser automation. No Blocks. No CAPTCHAs. Pay-as-you-Go.">+ <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/proxylane.png" class="ad">+ </a>+ <a href="https://www.lundproxy.com/unlimited-residential-bandwidth.html?utm_source=github&utm_medium=sponsorship&utm_campaign=scrapling&utm_content=banner" target="_blank" title="Unlimited residential traffic, sized only by bandwidth.">+ <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/lundproxy.png" class="ad">+ </a>+ <a href="https://dataimpulse.com/?utm_source=website&utm_medium=github_readme&utm_campaign=scrapling_platinum" target="_blank" title="Buy Pay-as-you-go proxies from $1/GB">+ <img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/DataImpulse_Platinum.png" class="ad">+ </a>+ <br />+ <br />+ <a href="https://cloro.dev/?utm_source=referral&utm_medium=scrapling" target="_blank" title="The search API for the AI era"><img src="https://raw.githubusercontent.com/D4Vinci/Scrapling/main/images/cloro.jpg"></a>+</div>diff --git a/zensical-base.yml b/zensical-base.ymlnew file mode 100644index 0000000..d1c9b19--- /dev/null+++ b/zensical-base.yml@@ -0,0 +1,127 @@+site_name: Scrapling+site_description: Scrapling - Effortless Web Scraping for the Modern Web!+site_author: Karim Shoair+repo_url: https://github.com/D4Vinci/Scrapling+edit_uri: edit/main/docs/+repo_name: D4Vinci/Scrapling+use_directory_urls: false+exclude_docs: 'README*.md++ locales/++ '+extra_css:+- stylesheets/extra.css+extra_javascript:+- assets/javascripts/language-links.js+theme:+ custom_dir: docs/overrides+ logo: assets/logo.png+ favicon: assets/favicon.ico+ features:+ - navigation.path+ - navigation.top+ - navigation.footer+ - navigation.indexes+ - navigation.sections+ - navigation.tracking+ - navigation.instant+ - navigation.instant.prefetch+ - navigation.instant.progress+ - search.share+ - search.suggest+ - search.highlight+ - content.action.view+ - content.code.copy+markdown_extensions:+ pymdownx:+ caret: {}+ mark: {}+ tilde: {}+ details: {}+ superfences:+ custom_fences:+ - name: mermaid+ class: mermaid+ format: pymdownx.superfences.fence_code_format+ inlinehilite: {}+ snippets:+ base_path:+ - includes+ check_paths: true+ emoji:+ emoji_index: zensical.extensions.emoji.twemoji+ emoji_generator: zensical.extensions.emoji.to_svg+ highlight:+ pygments_lang_class: true+ anchor_linenums: true+ line_spans: __span+ tabbed:+ alternate_style: true+ admonition: {}+ abbr: {}+ attr_list: {}+ tables: {}+ codehilite:+ css_class: highlight+ toc:+ permalink: true+ toc_depth: 3+plugins:+ mkdocstrings:+ custom_templates: docs/overrides/api+ handlers:+ python:+ inventories:+ - https://docs.python.org/3/objects.inv+ paths:+ - scrapling+ options:+ docstring_style: sphinx+ show_source: true+ show_root_heading: true+ show_if_no_docstring: true+ inherited_members: true+ members_order: source+ separate_signature: true+ unwrap_annotated: true+ filters: public+ merge_init_into_class: true+ docstring_section_style: spacy+ signature_crossrefs: true+ show_symbol_type_heading: true+ show_symbol_type_toc: true+ show_inheritance_diagram: true+ modernize_annotations: true+ extensions:+ - griffe_runtime_objects+ - griffe_sphinx+ - griffe_inherited_docstrings:+ merge: true+extra:+ social:+ - icon: fontawesome/brands/github+ link: https://github.com/D4Vinci/Scrapling+ - icon: fontawesome/brands/x-twitter+ link: https://x.com/Scrapling_dev+ - icon: fontawesome/brands/discord+ link: https://discord.gg/EMgGbDceNQ+ - icon: fontawesome/brands/python+ link: https://pypi.org/project/scrapling/+ - icon: fontawesome/brands/docker+ link: https://hub.docker.com/r/pyd4vinci/scrapling+ analytics:+ provider: google+ property: G-CS3DKLY73Z+ alternate:+ - name: English+ link: https://scrapling.readthedocs.io/en/latest/+ lang: en+ - name: العربية+ link: https://scrapling.readthedocs.io/en/latest/ar/+ lang: ar+watch:+- zensical-base.yml+- docs/assets+- docs/stylesheets+- includesdiff --git a/zensical.ar.yml b/zensical.ar.ymlnew file mode 100644index 0000000..d609b4a--- /dev/null+++ b/zensical.ar.yml@@ -0,0 +1,98 @@+INHERIT: zensical-base.yml+site_url: https://scrapling.readthedocs.io/en/latest/ar/+docs_dir: docs/locales/ar+site_dir: site/ar+edit_uri: edit/main/docs/locales/ar/+copyright: حقوق النشر © 2025 Karim Shoair - <a href="#__consent">إعدادات ملفات تعريف الارتباط</a>+nav:+- مقدمة: index.md+- نظرة عامة: overview.md+- اختبارات الأداء: benchmarks.md+- دليل الاستخدام:+ - تحليل الصفحات:+ - اختيار العناصر: parsing/selection.md+ - الفئات الأساسية: parsing/main_classes.md+ - الاستخراج المتكيف: parsing/adaptive.md+ - جلب الصفحات:+ - أساسيات Fetchers: fetching/choosing.md+ - طلبات HTTP: fetching/static.md+ - الجلب بالمتصفح: fetching/stealthy.md+ - Spiders:+ - طريقة العمل: spiders/architecture.md+ - البدء: spiders/getting-started.md+ - الطلبات والاستجابات: spiders/requests-responses.md+ - الجلسات: spiders/sessions.md+ - إدارة Proxy والحظر: spiders/proxy-blocking.md+ - قوالب عامة: spiders/generic-templates.md+ - قوالب المنصات: spiders/platform-templates.md+ - ميزات متقدمة: spiders/advanced.md+ - سطر الأوامر:+ - نظرة عامة: cli/overview.md+ - البيئة التفاعلية: cli/interactive-shell.md+ - أوامر الاستخراج: cli/extract-commands.md+ - الاستخدام مع AI:+ - خادم MCP: ai/mcp-server.md+ - مهارة Agent Skill: ai/agent-skill.md+ - بناء أنظمة RAG: ai/building-rag-systems.md+ - التكامل والانتقال:+ - التكامل مع Scrapy: integrations/scrapy.md+ - الانتقال من BeautifulSoup: tutorials/migrating_from_beautifulsoup.md+- دروس تطبيقية:+ - بديل مجاني لـ AI لاستخراج بيانات الويب: tutorials/replacing_ai.md+- التطوير:+ - مرجع API:+ - Selector: api-reference/selector.md+ - Fetchers: api-reference/fetchers.md+ - خادم MCP: api-reference/mcp-server.md+ - الأنواع المخصصة: api-reference/custom-types.md+ - Response: api-reference/response.md+ - Spiders: api-reference/spiders.md+ - تبديل Proxy: api-reference/proxy-rotation.md+ - كتابة نظام استرجاع خاص بك: development/adaptive_storage_system.md+ - استخدام الأنواع المخصصة في Scrapling: development/scrapling_custom_types.md+- الدعم والإعلانات: donate.md+- المساهمة: https://github.com/D4Vinci/Scrapling/blob/main/CONTRIBUTING.md+- سجل التغييرات: https://github.com/D4Vinci/Scrapling/blob/main/CHANGELOG.md+theme:+ language: ar+ palette:+ - media: '(prefers-color-scheme: light)'+ scheme: default+ accent: green+ primary: deep purple+ toggle:+ icon: lucide/sun+ name: التبديل إلى الوضع الداكن+ - media: '(prefers-color-scheme: dark)'+ scheme: slate+ accent: light green+ primary: deep purple+ toggle:+ icon: lucide/moon+ name: التبديل إلى الوضع الفاتح+ font:+ text: Noto Sans Arabic+plugins:+ mkdocstrings:+ locale: ar+extra:+ analytics:+ feedback:+ title: هل أفادتك هذه الصفحة؟+ ratings:+ - icon: material/heart+ name: هذه الصفحة مفيدة+ data: 1+ note: شكرًا لملاحظاتك!+ - icon: material/heart-broken+ name: تحتاج هذه الصفحة إلى تحسين+ data: 0+ note: شكرًا لملاحظاتك! ساعدنا في تحسين الصفحة عبر <a href="https://github.com/D4Vinci/Scrapling/issues/new?template=04-docs_issue.yml"+ target="_blank" rel="noopener">فتح مشكلة في الوثائق</a>.+ consent:+ title: ملفات تعريف الارتباط+ description: نستخدم ملفات تعريف الارتباط لحفظ تفضيلاتك ومعرفة مدى فائدة هذه الوثائق. تساعدنا موافقتك على تحسينها.+ actions:+ - accept+ - reject+ - managediff --git a/zensical.toml b/zensical.tomldeleted file mode 100644index 03c8b40..0000000--- a/zensical.toml+++ /dev/null@@ -1,241 +0,0 @@-[project]-site_name = "Scrapling"-site_description = "Scrapling - Effortless Web Scraping for the Modern Web!"-site_author = "Karim Shoair"-repo_url = "https://github.com/D4Vinci/Scrapling"-edit_uri = "edit/main/docs/"-site_url = "https://scrapling.readthedocs.io/en/latest/"-repo_name = "D4Vinci/Scrapling"-copyright = "Copyright © 2025 Karim Shoair - <a href=\"#__consent\">Change cookie settings</a>"-docs_dir = "docs"-use_directory_urls = false-exclude_docs = """-README*.md-"""-extra_css = ["stylesheets/extra.css"]--nav = [- {Introduction = "index.md"},- {Overview = "overview.md"},- {"Performance Benchmarks" = "benchmarks.md"},- {"User Guide" = [- {Parsing = [- {"Querying elements" = "parsing/selection.md"},- {"Main classes" = "parsing/main_classes.md"},- {"Adaptive scraping" = "parsing/adaptive.md"}- ]},- {Fetching = [- {"Fetchers basics" = "fetching/choosing.md"},- {"HTTP requests" = "fetching/static.md"},- {"Browser fetching" = "fetching/stealthy.md"}- ]},- {Spiders = [- {"Architecture" = "spiders/architecture.md"},- {"Getting started" = "spiders/getting-started.md"},- {"Requests & Responses" = "spiders/requests-responses.md"},- {"Sessions" = "spiders/sessions.md"},- {"Proxy management & Blocking" = "spiders/proxy-blocking.md"},- {"Generic crawlers" = "spiders/generic-templates.md"},- {"Platform crawlers" = "spiders/platform-templates.md"},- {"Advanced features" = "spiders/advanced.md"}- ]},- {"Command Line Interface" = [- {Overview = "cli/overview.md"},- {"Interactive shell" = "cli/interactive-shell.md"},- {"Extract commands" = "cli/extract-commands.md"}- ]},- {"Using with AI" = [- {"MCP server" = "ai/mcp-server.md"},- {"Agent skill" = "ai/agent-skill.md"},- {"Building RAG systems" = "ai/building-rag-systems.md"}- ]},- {"Integrations and migrations" = [- {"Integrating into Scrapy" = "integrations/scrapy.md"},- {"Migrating from BeautifulSoup" = "tutorials/migrating_from_beautifulsoup.md"}- ]}- ]},- {Tutorials = [- {"A Free Alternative to AI for Robust Web Scraping" = "tutorials/replacing_ai.md"}- ]},- {Development = [- {"API Reference" = [- {Selector = "api-reference/selector.md"},- {Fetchers = "api-reference/fetchers.md"},- {"MCP Server" = "api-reference/mcp-server.md"},- {"Custom Types" = "api-reference/custom-types.md"},- {Response = "api-reference/response.md"},- {Spiders = "api-reference/spiders.md"},- {"Proxy Rotation" = "api-reference/proxy-rotation.md"}- ]},- {"Writing your retrieval system" = "development/adaptive_storage_system.md"},- {"Using Scrapling's custom types" = "development/scrapling_custom_types.md"}- ]},- {"Support and Advertisement" = "donate.md"},- {Contributing = "https://github.com/D4Vinci/Scrapling/blob/main/CONTRIBUTING.md"},- {Changelog = "https://github.com/D4Vinci/Scrapling/blob/main/CHANGELOG.md"}-]--[project.theme]-language = "en"-custom_dir = "docs/overrides"-logo = "assets/logo.png"-favicon = "assets/favicon.ico"-features = [- "navigation.path",-# "announce.dismiss",- "navigation.top",- "navigation.footer",- "navigation.indexes",- "navigation.sections",- "navigation.tracking",- "navigation.instant",- "navigation.instant.prefetch",- "navigation.instant.progress",-# "navigation.tabs",-# "navigation.expand",-# "toc.integrate",- "search.share",- "search.suggest",- "search.highlight",- "content.action.view",- "content.code.copy",-]--[[project.theme.palette]]-media = "(prefers-color-scheme: light)"-scheme = "default"-accent = "green"-primary = "deep purple"-toggle.icon = "lucide/sun"-toggle.name = "Switch to dark mode"--[[project.theme.palette]]-media = "(prefers-color-scheme: dark)"-scheme = "slate"-accent = "light green"-primary = "deep purple"-toggle.icon = "lucide/moon"-toggle.name = "Switch to light mode"--# Uncomment if needed:-# [project.theme.font]-# text = "Open Sans"-# code = "JetBrains Mono"--[project.markdown_extensions.pymdownx.caret]-[project.markdown_extensions.pymdownx.mark]-[project.markdown_extensions.pymdownx.tilde]-[project.markdown_extensions.admonition]-[project.markdown_extensions.abbr]-#[project.markdown_extensions.mkautodoc]-[project.markdown_extensions.pymdownx.details]-[project.markdown_extensions.pymdownx.superfences]-custom_fences = [- {name = "mermaid", class = "mermaid", format = "pymdownx.superfences.fence_code_format"}-]-[project.markdown_extensions.pymdownx.inlinehilite]-[project.markdown_extensions.pymdownx.snippets]-[project.markdown_extensions.tables]--[project.markdown_extensions.pymdownx.emoji]-emoji_index = "zensical.extensions.emoji.twemoji"-emoji_generator = "zensical.extensions.emoji.to_svg"--[project.markdown_extensions.pymdownx.highlight]-pygments_lang_class = true-anchor_linenums = true-line_spans = "__span"--[project.markdown_extensions.pymdownx.tabbed]-alternate_style = true--[project.markdown_extensions.codehilite]-css_class = "highlight"--[project.markdown_extensions.toc]-title = "On this page"-permalink = true-toc_depth = 3--[project.plugins.mkdocstrings.handlers.python]-inventories = ["https://docs.python.org/3/objects.inv"]-paths = ["scrapling"]--[project.plugins.mkdocstrings.handlers.python.options]-docstring_style = "sphinx"-show_source = true-show_root_heading = true-show_if_no_docstring = true-inherited_members = true-members_order = "source"-separate_signature = true-unwrap_annotated = true-filters = "public"-merge_init_into_class = true-docstring_section_style = "spacy"-signature_crossrefs = true-show_symbol_type_heading = true-show_symbol_type_toc = true-show_inheritance_diagram = true-modernize_annotations = true-extensions = [- "griffe_runtime_objects",- "griffe_sphinx",- {griffe_inherited_docstrings = {merge = true}}-]--[[project.extra.social]]-icon = "fontawesome/brands/github"-link = "https://github.com/D4Vinci/Scrapling"--[[project.extra.social]]-icon = "fontawesome/brands/x-twitter"-link = "https://x.com/Scrapling_dev"--[[project.extra.social]]-icon = "fontawesome/brands/discord"-link = "https://discord.gg/EMgGbDceNQ"--[[project.extra.social]]-icon = "fontawesome/brands/python"-link = "https://pypi.org/project/scrapling/"--[[project.extra.social]]-icon = "fontawesome/brands/docker"-link = "https://hub.docker.com/r/pyd4vinci/scrapling"--[project.extra.analytics]-provider = "google"-property = "G-CS3DKLY73Z"--[project.extra.analytics.feedback]-title = "Was this page helpful?"--[[project.extra.analytics.feedback.ratings]]-icon = "material/heart"-name = "This page was helpful"-data = 1-note = "Thanks for your feedback!"--[[project.extra.analytics.feedback.ratings]]-icon = "material/heart-broken"-name = "This page could be improved"-data = 0-note = """-Thanks for your feedback! Help us improve this page by-<a href="https://github.com/D4Vinci/Scrapling/issues/new?template=04-docs_issue.yml" target="_blank" rel="noopener">opening a documentation issue</a>.-"""--[project.extra.consent]-title = "Cookie consent"-description = """-We use cookies to recognize your repeated visits and preferences, as well-as to measure the effectiveness of our documentation and whether users-find what they're searching for. With your consent, you're helping us to-make our documentation better.-"""-actions = [- "accept",- "reject",- "manage"-]diff --git a/zensical.yml b/zensical.ymlnew file mode 100644index 0000000..8170361--- /dev/null+++ b/zensical.yml@@ -0,0 +1,104 @@+INHERIT: zensical-base.yml+site_url: https://scrapling.readthedocs.io/en/latest/+docs_dir: docs+site_dir: site+copyright: Copyright © 2025 Karim Shoair - <a href="#__consent">Change cookie settings</a>+nav:+- Introduction: index.md+- Overview: overview.md+- Performance Benchmarks: benchmarks.md+- User Guide:+ - Parsing:+ - Querying elements: parsing/selection.md+ - Main classes: parsing/main_classes.md+ - Adaptive scraping: parsing/adaptive.md+ - Fetching:+ - Fetchers basics: fetching/choosing.md+ - HTTP requests: fetching/static.md+ - Browser fetching: fetching/stealthy.md+ - Spiders:+ - Architecture: spiders/architecture.md+ - Getting started: spiders/getting-started.md+ - Requests & Responses: spiders/requests-responses.md+ - Sessions: spiders/sessions.md+ - Proxy management & Blocking: spiders/proxy-blocking.md+ - Generic crawlers: spiders/generic-templates.md+ - Platform crawlers: spiders/platform-templates.md+ - Advanced features: spiders/advanced.md+ - Command Line Interface:+ - Overview: cli/overview.md+ - Interactive shell: cli/interactive-shell.md+ - Extract commands: cli/extract-commands.md+ - Using with AI:+ - MCP server: ai/mcp-server.md+ - Agent skill: ai/agent-skill.md+ - Building RAG systems: ai/building-rag-systems.md+ - Integrations and migrations:+ - Integrating into Scrapy: integrations/scrapy.md+ - Migrating from BeautifulSoup: tutorials/migrating_from_beautifulsoup.md+- Tutorials:+ - A Free Alternative to AI for Robust Web Scraping: tutorials/replacing_ai.md+- Development:+ - API Reference:+ - Selector: api-reference/selector.md+ - Fetchers: api-reference/fetchers.md+ - MCP Server: api-reference/mcp-server.md+ - Custom Types: api-reference/custom-types.md+ - Response: api-reference/response.md+ - Spiders: api-reference/spiders.md+ - Proxy Rotation: api-reference/proxy-rotation.md+ - Writing your retrieval system: development/adaptive_storage_system.md+ - Using Scrapling's custom types: development/scrapling_custom_types.md+- Support and Advertisement: donate.md+- Contributing: https://github.com/D4Vinci/Scrapling/blob/main/CONTRIBUTING.md+- Changelog: https://github.com/D4Vinci/Scrapling/blob/main/CHANGELOG.md+theme:+ language: en+ palette:+ - media: '(prefers-color-scheme: light)'+ scheme: default+ accent: green+ primary: deep purple+ toggle:+ icon: lucide/sun+ name: Switch to dark mode+ - media: '(prefers-color-scheme: dark)'+ scheme: slate+ accent: light green+ primary: deep purple+ toggle:+ icon: lucide/moon+ name: Switch to light mode+extra:+ analytics:+ feedback:+ title: Was this page helpful?+ ratings:+ - icon: material/heart+ name: This page was helpful+ data: 1+ note: Thanks for your feedback!+ - icon: material/heart-broken+ name: This page could be improved+ data: 0+ note: 'Thanks for your feedback! Help us improve this page by++ <a href="https://github.com/D4Vinci/Scrapling/issues/new?template=04-docs_issue.yml" target="_blank" rel="noopener">opening+ a documentation issue</a>.++ '+ consent:+ title: Cookie consent+ description: 'We use cookies to recognize your repeated visits and preferences, as well++ as to measure the effectiveness of our documentation and whether users++ find what they''re searching for. With your consent, you''re helping us to++ make our documentation better.++ '+ actions:+ - accept+ - reject+ - manage