From f170287903d5940af808e562dc75f6b0fbad2f13 Mon Sep 17 00:00:00 2001 From: ysrg2003 <1.93751419e+08+ysrg2003@users.noreply.github.com> Date: Sat, 15 Aug 2026 11:06:06 +0000 Subject: [PATCH] docs: embed Arabic guide in README.rst --- README.rst | 619 +++++++++++++++++++++++++++++++++++++++++++++++++++-- 1 file changed, 603 insertions(+), 16 deletions(-) diff --git a/README.rst b/README.rst index 0065e6561..9a33a2843 100644 --- a/README.rst +++ b/README.rst @@ -1,10 +1,10 @@ -|logo| - .. |logo| image:: https://raw.githubusercontent.com/scrapy/scrapy/master/docs/_static/logo.svg :target: https://scrapy.org :alt: Scrapy :width: 480px +.. _Scrapy: https://scrapy.org/ + |version| |python_version| |tests| |coverage| |conda| |deepwiki| .. |version| image:: https://img.shields.io/pypi/v/Scrapy.svg @@ -31,25 +31,612 @@ :target: https://deepwiki.com/scrapy/scrapy :alt: Ask DeepWiki -Scrapy_ is a web scraping framework to extract structured data from websites. -It is cross-platform, and requires Python 3.10+. It is maintained by Zyte_ -(formerly Scrapinghub) and `many other contributors`_. +دليل Scrapy العربي +================== -.. _many other contributors: https://github.com/scrapy/scrapy/graphs/contributors -.. _Scrapy: https://scrapy.org/ -.. _Zyte: https://www.zyte.com/ +هذا المستودع هو المصدر البرمجي لإطار **Scrapy**، وهو إطار عمل مرتفع +المستوى مكتوب بلغة Python لبناء الزواحف التي تزور صفحات الويب وتستخرج منها +بيانات منظَّمة. صُمم Scrapy أساسًا للاستخلاص من الويب، لكنه يصلح أيضًا +لاستهلاك بعض واجهات البرمجة وبناء زواحف عامة لجمع البيانات والمراقبة +والأرشفة والاختبارات الآلية [1]_. -Install with: +لا يُعد Scrapy قاعدة بيانات أو خدمة استضافة بحد ذاته؛ فهو ينفذ دورة الزحف +والاستخراج، بينما تحدد أنت طريقة التخزين أو التصدير أو التكامل مع خدمة +خارجية. يعمل بأسلوب غير حاجب يعتمد على Twisted، ولذلك يستطيع تنفيذ عدة +طلبات وفق إعدادات التزامن والتهذيب [2]_. -.. code:: bash +ما الذي ستحققه؟ +---------------- - pip install scrapy +بعد اتباع هذا الدليل ستتمكن من إنشاء بيئة افتراضية، تثبيت نسخة المستودع +محليًا، إنشاء مشروع Scrapy، كتابة عنكبوت صغير، تشغيله، وحفظ الناتج في ملف +JSON Lines. لا يحتاج هذا المسار الأول إلى مفتاح API أو كلمة مرور أو حساب +خدمة؛ الاعتماديات الخارجية لا تصبح مطلوبة إلا عند اختيار تكامل اختياري مثل +S3 أو Google Cloud Storage أو FTP أو وكيل محمي. -And follow the documentation_ to learn how to use it. -For the Arabic repository guide, see `README.md `_. +المتطلبات +========= -.. _documentation: https://docs.scrapy.org/en/latest/ +.. list-table:: + :header-rows: 1 + :widths: 24 16 60 -If you wish to contribute, see Contributing_. + * - المتطلب + - الحالة + - التفاصيل + * - Python + - مطلوب + - الإصدار 3.10 أو أحدث. يدعم المشروع CPython وPyPy وفق دليل التثبيت الرسمي [3]_. + * - Git + - مطلوب للمساهمين + - مطلوب لاستنساخ المستودع والعمل على فروعه. + * - بيئة افتراضية + - موصى بها بشدة + - تمنع تعارض Scrapy واعتمادياته مع حزم Python النظامية [3]_. + * - اتصال بالإنترنت + - مطلوب + - يحتاج pip إلى الوصول إلى فهرس الحزم، ويحتاج العنكبوت إلى الوصول إلى الموقع المستهدف. + * - أدوات بناء النظام + - حسب المنصة + - قد تحتاج Linux إلى حزم تطوير، وقد تحتاج Windows إلى Microsoft C++ Build Tools، وقد تحتاج macOS إلى Xcode Command Line Tools [3]_. + * - أسرار أو مفاتيح API + - غير مطلوبة للمسار الأول + - أضف بيانات الاعتماد فقط عند تفعيل تكامل يحتاجها، ولا تضعها في Git. -.. _Contributing: https://docs.scrapy.org/en/master/contributing.html +خريطة المستودع +============== + +هذا المستودع هو مصدر Scrapy نفسه، وليس مشروع زحف جاهزًا لموقع واحد. لذلك +ستجد فيه نواة الإطار، التوثيق، الاختبارات، وقوالب المشاريع التي ينشئها أمر +``startproject``. + +.. list-table:: + :header-rows: 1 + :widths: 26 74 + + * - المسار + - الدور + * - ``scrapy/`` + - الحزمة البرمجية الأساسية، وتشمل المحرك، المجدول، المنزّل، العناكب، الطلبات والاستجابات، المحددات، خطوط المعالجة، الوسطاء، الإضافات، وإدارة الإعدادات. + * - ``scrapy/cmdline.py`` + - نقطة التنفيذ الفعلية لأداة سطر الأوامر ``scrapy``. + * - ``scrapy/__main__.py`` + - يتيح تشغيل الأداة بصيغة ``python -m scrapy``. + * - ``scrapy/VERSION`` + - مصدر رقم الإصدار الذي يقرأه نظام البناء. + * - ``scrapy/templates/`` + - قوالب المشاريع والعناكب التي تستخدمها أوامر الإنشاء. + * - ``tests/`` + - اختبارات الوحدة والتكامل والسلوك، ومنها اختبارات أوامر CLI ومحرك الزحف. + * - ``docs/`` + - التوثيق المحلي بصيغة reStructuredText، ويحتوي دليل التثبيت والبرنامج التعليمي ومرجع الأوامر. + * - ``pyproject.toml`` + - تعريف الحزمة، إصدار Python المطلوب، الاعتماديات، الإضافات الاختيارية، نقطة الدخول، وإعدادات الأدوات. + * - ``tox.ini`` + - بيئات الاختبار والتحقق الآلي للمساهمين. + * - ``.github/workflows/`` + - سير عمل GitHub Actions للاختبارات والنشر والتحقق على المنصات المختلفة. + * - ``SECURITY.md`` + - الإصدارات المدعومة وطريقة الإبلاغ عن الثغرات. + +التثبيت من نسخة المستودع +======================== + +Linux وmacOS +------------ + +نفّذ الأوامر التالية في الطرفية. يبدأ المسار بالانتقال إلى مجلد العمل حتى +لا تُنشأ البيئة الافتراضية في مكان غير مقصود. + +.. code-block:: bash + + git clone https://github.com/ysrg2003/scrapy.git + cd scrapy + python3 -m venv .venv + . .venv/bin/activate + python -m pip install --upgrade pip + python -m pip install -e . + +يُثبت الخيار ``-e .`` نسخة تحريرية من المستودع؛ أي إن تعديلاتك على ملفات +المصدر تنعكس في البيئة دون إعادة تثبيت الحزمة في كل مرة. أما إن أردت +استخدام Scrapy كمستخدم عادي خارج هذا المستودع فاستخدم الأمر التالي داخل +بيئة افتراضية، وهو المسار الذي يوصي به الدليل الرسمي [3]_. + +.. code-block:: bash + + python -m pip install Scrapy + +تحقق من التثبيت بالأمر: + +.. code-block:: bash + + scrapy version -v + +يجب أن يظهر سطر يبدأ بـ ``Scrapy`` ويعرض الإصدار ومعلومات الاعتماديات. إذا +ظهر ``command not found`` فتحقق من تفعيل البيئة عبر ``which python`` و +``which scrapy``، ثم نفّذ ``. .venv/bin/activate`` من جذر المستودع. + +Ubuntu أو Debian عند فشل بناء الاعتماديات +------------------------------------------ + +تحتوي النسخ الحديثة من Python غالبًا على عجلات ثنائية جاهزة، لكن بعض +الأنظمة قد تحتاج إلى أدوات التطوير الخاصة بـ lxml وcryptography [3]_. عند +ظهور أخطاء ترجمة أو غياب ملفات مثل ``libxml/xmlversion.h`` أو +``openssl/ssl.h``، نفّذ ما يلي خارج البيئة الافتراضية: + +.. code-block:: bash + + sudo apt-get update + sudo apt-get install -y python3 python3-dev python3-pip libxml2-dev libxslt1-dev zlib1g-dev libffi-dev libssl-dev + +ثم من جذر المستودع فعّل البيئة وأعد التثبيت: + +.. code-block:: bash + + . .venv/bin/activate + python -m pip install -e . + +إذا استمر الفشل، احتفظ برسالة الخطأ كاملة؛ لا تستبدل هذه الحزم بحزمة +Ubuntu القديمة ``python-scrapy`` لأن التوثيق الرسمي يحذر من أنها قد تكون +أقدم من الإصدار الحالي [3]_. + +Windows PowerShell +------------------ + +يوصي دليل Scrapy باستخدام Anaconda أو Miniconda على Windows لتقليل مشكلات +بناء الاعتماديات [3]_. + +.. code-block:: powershell + + conda create -n scrapy-env python=3.12 + conda activate scrapy-env + conda install -c conda-forge scrapy + +إذا كنت تعمل على نسخة المصدر نفسها وتريد تثبيتها تحريريًا، استخدم PowerShell +من جذر المستودع: + +.. code-block:: powershell + + py -3.12 -m venv .venv + .\\.venv\\Scripts\\Activate.ps1 + python -m pip install --upgrade pip + python -m pip install -e . + +قد يتطلب مسار pip على Windows تثبيت **Microsoft C++ Build Tools** مع +مكونات MSVC وWindows SDK [3]_. إذا رفض PowerShell تشغيل ``Activate.ps1`` +بسبب سياسة التنفيذ، استخدم جلسة PowerShell مناسبة أو فعّل البيئة من +``cmd.exe`` عبر ``.venv\\Scripts\\activate.bat``. + +PyPy وConda +----------- + +يمكن تثبيت الحزمة من قناة conda-forge بالأمر التالي: + +.. code-block:: bash + + conda install -c conda-forge scrapy + +أما PyPy فقد يبني بعض الاعتماديات من المصدر بدل استخدام عجلات CPython، +ولذلك قد يحتاج إلى أدوات بناء إضافية. بعد التثبيت يمكن استخدام +``scrapy bench`` كفحص سريع لسلامة التشغيل [3]_. + +أول تشغيل: إنشاء مشروع وعنكبوت +============================== + +نفّذ هذا القسم داخل مجلد عمل منفصل عن جذر مستودع Scrapy، حتى لا تخلط بين +مصدر الإطار ومشروع الزحف الذي ستنشئه. + +الخطوة الأولى: إنشاء مشروع +--------------------------- + +.. code-block:: bash + + mkdir -p ~/scrapy-work + cd ~/scrapy-work + scrapy startproject quotes_project + cd quotes_project + +ينشئ الأمر مجلد ``quotes_project`` وملف ``scrapy.cfg`` وحزمة Python تحتوي +على ``items.py`` و``middlewares.py`` و``pipelines.py`` و``settings.py`` +ومجلد ``spiders/`` [4]_. تحقق من البنية: + +.. code-block:: bash + + find . -maxdepth 3 -type f | sort + +ينبغي أن ترى على الأقل: + +.. code-block:: text + + scrapy.cfg + quotes_project/__init__.py + quotes_project/items.py + quotes_project/middlewares.py + quotes_project/pipelines.py + quotes_project/settings.py + quotes_project/spiders/__init__.py + +إذا قال Scrapy إن المجلد موجود أو إن المشروع غير صالح، انتقل إلى +``~/scrapy-work`` وتأكد من اسم مجلد جديد. + +الخطوة الثانية: كتابة العنكبوت +------------------------------- + +أنشئ الملف ``quotes_project/spiders/quotes.py`` بالمحتوى التالي: + +.. code-block:: python + + import scrapy + + + class QuotesSpider(scrapy.Spider): + name = "quotes" + start_urls = ["https://quotes.toscrape.com/tag/humor/"] + + def parse(self, response): + for quote in response.css("div.quote"): + yield { + "author": quote.css("small.author::text").get(), + "text": quote.css("span.text::text").get(), + } + + next_page = response.css('li.next a::attr("href")').get() + if next_page is not None: + yield response.follow(next_page, callback=self.parse) + +يعرّف ``name`` الاسم الذي سيستعمله أمر ``crawl``، وتحدد ``start_urls`` +الطلبات الأولى، ويستخرج ``parse`` البيانات بمحددات CSS، ثم يتبع رابط +الصفحة التالية باستخدام ``response.follow``. عند عدم العثور على عنصر، +يعيد ``.get()`` القيمة ``None`` بدل كسر العنكبوت بفهرس غير موجود [1]_ [4]_. + +الخطوة الثالثة: فحص العنكبوت +----------------------------- + +.. code-block:: bash + + scrapy list + scrapy check quotes + +ينبغي أن يعرض ``scrapy list`` الاسم ``quotes``. إذا لم يظهر العنكبوت، +تحقق من أن الملف داخل ``quotes_project/spiders/`` وأنه يحتوي على فئة ترث +من ``scrapy.Spider`` وتملك قيمة ``name`` فريدة. + +الخطوة الرابعة: تشغيل الزحف وحفظ الناتج +---------------------------------------- + +لإنشاء ملف جديد أو استبدال ملف موجود، استخدم ``-O``: + +.. code-block:: bash + + scrapy crawl quotes -O quotes.jsonl + +ولإضافة العناصر إلى ملف موجود، استخدم ``-o``: + +.. code-block:: bash + + scrapy crawl quotes -o quotes.jsonl + +يعني ``-O`` الاستبدال، بينما يعني ``-o`` الإضافة. وعند التشغيل المتكرر +يفضل استخدام JSON Lines بامتداد ``.jsonl``؛ فإضافة سجلات إلى ملف JSON +تقليدي قد تجعله غير صالح نحويًا [4]_. يجب أن ينتهي التشغيل برسالة إغلاق +للعنكبوت وأن ينشأ ملف ``quotes.jsonl``، بحيث يكون كل سطر كائن JSON مستقلًا. + +استخدام Scrapy Shell +==================== + +قبل تعديل العنكبوت، جرّب المحددات في الصدفة التفاعلية: + +.. code-block:: bash + + scrapy shell "https://quotes.toscrape.com/page/1/" + +داخل الصدفة: + +.. code-block:: python + + response.css("title::text").get() + response.css("div.quote span.text::text").getall() + response.xpath("//small[@class='author']/text()").getall() + +يستخدم Scrapy محددات CSS وXPath، ويُرجع ``.getall()`` قائمة النتائج، بينما +يعيد ``.get()`` أول نتيجة أو ``None`` عند عدم وجودها [4]_. إذا أعاد المحدد +قائمة فارغة، فالمشكلة غالبًا في تغير HTML أو في أن المحتوى يُحمّل بواسطة +JavaScript بعد وصول HTML الأول. افحص الاستجابة الخام، وجرب XPath، ثم راجع +دليل التعامل مع المحتوى الديناميكي. + +خريطة دورة التنفيذ +================== + +تتحكم **الآلة التنفيذية** في تدفق الزحف. تحصل على الطلبات الابتدائية من +العنكبوت، وتضعها في **المجدول**، ثم تمررها إلى **المنزّل** عبر Downloader +Middleware. يعيد المنزّل استجابة تمر مرة أخرى عبر الوسيط إلى الآلة، التي +تسلمها إلى العنكبوت عبر Spider Middleware. ينتج العنكبوت عناصر وطلبات +جديدة؛ تذهب العناصر إلى Item Pipeline وتعود الطلبات إلى المجدول حتى تنتهي +قائمة العمل [2]_. + +.. list-table:: + :header-rows: 1 + :widths: 28 72 + + * - المكوّن + - المسؤولية + * - Engine + - تنسيق تدفق البيانات وتشغيل المكونات وإطلاق الأحداث. + * - Scheduler + - ترتيب الطلبات التي ستنفذ وتغذية الآلة بالطلب التالي. + * - Downloader + - جلب الصفحات وإنشاء كائنات ``Response``. + * - Spider + - تفسير الاستجابات وإنتاج العناصر والطلبات الجديدة. + * - Downloader Middleware + - تعديل الطلب قبل الإرسال أو الاستجابة بعد التنزيل، أو إسقاط الطلب، أو إرجاع استجابة بديلة. + * - Spider Middleware + - معالجة مدخلات ومخرجات العنكبوت ومعالجة بعض الاستثناءات. + * - Item Pipeline + - تنظيف العناصر والتحقق منها وتخزينها أو تمريرها إلى مكونات لاحقة. + * - Feed Export + - تصدير العناصر إلى JSON أو JSON Lines أو CSV أو XML أو مخازن مدعومة. + +أوامر CLI المهمة +================ + +تبحث أداة ``scrapy`` عن ``scrapy.cfg`` في مسارات النظام والمستخدم وجذر +المشروع، وتمنح إعدادات المشروع أولوية أعلى من الإعدادات العامة. وتدعم +متغيرات بيئية لتحديد وحدة الإعدادات أو المشروع أو غلاف Python [5]_. + +.. list-table:: + :header-rows: 1 + :widths: 30 15 55 + + * - الأمر + - يحتاج مشروعًا؟ + - الاستخدام + * - ``scrapy startproject NAME`` + - لا + - إنشاء هيكل مشروع جديد. + * - ``scrapy genspider NAME DOMAIN`` + - لا + - توليد عنكبوت من قالب. + * - ``scrapy crawl SPIDER`` + - نعم + - تشغيل عنكبوت مسجل في المشروع. + * - ``scrapy runspider FILE.py`` + - لا + - تشغيل ملف عنكبوت مستقل دون مشروع. + * - ``scrapy list`` + - نعم + - عرض أسماء العناكب المكتشفة. + * - ``scrapy check SPIDER`` + - نعم + - تنفيذ اختبارات العقود. + * - ``scrapy shell URL`` + - لا + - تجربة الطلبات والمحددات تفاعليًا. + * - ``scrapy fetch URL`` + - لا + - جلب رابط بالطريقة التي يستخدمها Scrapy. + * - ``scrapy settings --get NAME`` + - حسب الإعداد + - قراءة قيمة إعداد. + * - ``scrapy bench`` + - لا + - قياس أداء سريع محلي. + * - ``scrapy version -v`` + - لا + - عرض إصدار Scrapy والاعتماديات والمنصة. + +يمكن تشغيل الأداة أيضًا بصيغة: + +.. code-block:: bash + + python -m scrapy version -v + +إعدادات المشروع والبيئة +------------------------ + +يحتوي ``scrapy.cfg`` الذي ينشئه ``startproject`` عادةً على اسم وحدة +الإعدادات: + +.. code-block:: ini + + [settings] + default = quotes_project.settings + +ولا ينبغي وضع كلمات المرور أو مفاتيح API داخل هذا الملف. هذه المتغيرات +العامة مرتبطة باكتشاف المشروع: + +.. list-table:: + :header-rows: 1 + :widths: 30 20 50 + + * - المتغير + - النوع + - الأثر والمثال + * - ``SCRAPY_SETTINGS_MODULE`` + - اسم وحدة Python + - يحدد وحدة الإعدادات، مثل ``quotes_project.settings``. + * - ``SCRAPY_PROJECT`` + - اسم مستعار + - يختار مشروعًا غير ``default`` عندما يحتوي ``scrapy.cfg`` على أكثر من وحدة إعدادات. + * - ``SCRAPY_PYTHON_SHELL`` + - اسم غلاف + - يحدد الغلاف التفاعلي المفضل عند توفره، مثل ``python``. + +هذه ليست أسرارًا بحد ذاتها، لكنها قد تشير إلى ملفات إعدادات تحتوي بيانات +حساسة؛ احتفظ بالأسرار في مدير أسرار أو ملف محلي مستبعد من Git، ولا تطبع +قيمها في السجلات. + +الاعتماديات والإضافات الاختيارية +================================ + +يعرّف ``pyproject.toml`` الاعتماديات الأساسية مثل Twisted وlxml وparsel +و w3lib وcryptography وpyOpenSSL، كما يعرّف إضافات تثبت مكونات اختيارية +عند الحاجة [6]_. لا تثبت كل الإضافات دون سبب؛ اختر فقط ما يطابق ميزة +ستستخدمها. + +.. list-table:: + :header-rows: 1 + :widths: 25 75 + + * - الإضافة + - الميزة + * - ``bpython`` + - غلاف Bpython. + * - ``gcs`` + - Google Cloud Storage لتصدير الملفات وخطوط الوسائط. + * - ``httpx`` + - معالج HTTPX مع HTTP/2 ودعم SOCKS. + * - ``images`` + - خط معالجة الصور. + * - ``ipython`` + - غلاف IPython. + * - ``ptpython`` + - غلاف ptpython. + * - ``robotparser`` + - محلل robots.txt بديل. + * - ``s3`` + - تخزين Amazon S3 للتصدير والوسائط والتنزيلات. + * - ``twisted-http2`` + - دعم HTTP/2 عبر Twisted. + * - ``uvloop`` + - حلقة أحداث uvloop في الأنظمة المدعومة. + * - ``zstd`` + - فك ضغط استجابات Zstandard. + +مثال تثبيت ميزتين فقط: + +.. code-block:: bash + + python -m pip install -e '.[s3,images]' + +تثبيت ``s3`` لا يمنحك حساب AWS ولا ينشئ صلاحياته؛ ستظل بحاجة إلى إعداد +اعتماديات AWS وفق بيئتك، ويجب عدم وضع المفاتيح في المستودع. وبالمثل، اختيار +``gcs`` أو ``httpx`` لا يعني أن التكامل سيعمل دون إعداد الخدمة أو الشبكة +المطلوبة. + +التطوير والاختبار +================= + +للتطوير من المصدر استخدم التثبيت التحريري داخل ``.venv`` كما في قسم +التثبيت. يعرّف المستودع اعتماديات الاختبار وبيئاتها في ``tox.ini``، ويُستخدم +tox لتشغيل مصفوفة التحقق التي تشمل Python وmypy وpylint والتوثيق واختبارات +الوحدات [7]_. + +للفحص السريع بعد تثبيت اعتماديات الاختبار الأساسية: + +.. code-block:: bash + + python -m pip install pytest pytest-cov pytest-twisted + python -m pytest -q tests/test_command_version.py tests/test_command_startproject.py + +ولتشغيل بيئة Python 3.12 المعرفة في إعدادات ``tox.ini``: + +.. code-block:: bash + + python -m pip install tox + tox -e py312 + +يتطلب المسار الكامل أن تكون نسخة Python المطلوبة والأدوات التي يثبتها tox +متاحة. إذا أردت اختبار التغيير في أمر واحد، ابدأ بالاختبار المقابل له بدل +تشغيل كامل المصفوفة. + +الأمان والامتثال التشغيلي +========================== + +يستطيع Scrapy إرسال رؤوس HTTP وبيانات اعتماد وطلبات عبر بروكسيات أو خدمات +تخزين؛ لذلك يجب اعتبار أي قيمة مثل كلمة مرور HTTP أو بيانات FTP أو مفاتيح +S3 أو رموز الجلسة سرية. ضعها في متغيرات البيئة أو مدير أسرار أو إعدادات +محلية مستبعدة من Git، وتحقق من أن السجل لا يطبع رؤوس ``Authorization`` أو +عناوين تحتوي اسم مستخدم وكلمة مرور. لا تضع مفاتيح حقيقية في الأمثلة أو +الاختبارات أو Issues. + +احترم شروط استخدام الموقع وسياسة ``robots.txt`` ومعدلات الطلب المناسبة، +ولا تجمع بيانات شخصية أو محمية إلا إذا كان لديك أساس مشروع وصلاحية واضحة. +استخدم ``DOWNLOAD_DELAY`` أو حدود التزامن وAutoThrottle عند ملاءمة ذلك، +واختبر أولًا على موقع تملكه أو على موقع التدريب المستخدم في الأمثلة. هذا +الدليل يشرح تشغيل الإطار ولا يمنح إذنًا للوصول إلى أي موقع. + +وفق ``SECURITY.md``، الإصدار المدعوم في هذا المستودع هو فرع ``2.17.x``، +ويجب إرسال بلاغات الثغرات عبر `نموذج GitHub Security Advisory`_ بدل نشر +تفاصيل الثغرة علنًا [8]_. + +.. _نموذج GitHub Security Advisory: https://github.com/scrapy/scrapy/security/advisories/new + +استكشاف الأخطاء +=============== + +.. list-table:: + :header-rows: 1 + :widths: 25 35 40 + + * - العرض + - السبب المرجح + - الإجراء + * - ``scrapy: command not found`` + - البيئة الافتراضية غير مفعلة أو لم يثبت المشروع. + - نفّذ ``. .venv/bin/activate`` ثم ``python -m pip install -e .``، وتحقق من ``which scrapy``. + * - فشل بناء ``lxml`` أو ``cryptography`` + - غياب حزم التطوير أو المترجم. + - طبّق حزم Ubuntu المذكورة في قسم التثبيت، أو استخدم Conda، أو ثبّت أدوات البناء المناسبة [3]_. + * - ``No active project`` عند ``crawl`` + - التنفيذ خارج مجلد يحتوي ``scrapy.cfg``. + - انتقل إلى جذر مشروع الزحف، أو استخدم ``scrapy runspider path/to/spider.py`` للملف المستقل. + * - لا يظهر العنكبوت في ``scrapy list`` + - مسار الملف أو اسم الفئة أو الوراثة غير صحيح. + - ضع الملف تحت ``PROJECT/spiders/``، واجعل الفئة ترث من ``scrapy.Spider`` وتملك ``name`` فريدًا. + * - الناتج فارغ + - المحدد لا يطابق HTML، أو المحتوى ديناميكي، أو الاستجابة غير ناجحة. + - افحص ``scrapy shell`` و``response.status`` و``response.text`` ثم عدّل CSS/XPath. + * - إضافة ``-o`` إلى JSON أفسدت الملف + - الإضافة إلى JSON تقليدي قد تنتج أكثر من قيمة JSON متجاورة. + - استخدم ``-O`` للاستبدال، أو استخدم JSON Lines بامتداد ``.jsonl`` مع ``-o`` [4]_. + * - خطأ ``OP_NO_TLSv1_1`` + - عدم توافق إصدار Twisted مع pyOpenSSL. + - أعد تثبيت Twisted مع إضافة TLS: ``python -m pip install 'Twisted[tls]'`` [3]_. + * - يفشل الطلب رغم نجاح المتصفح + - الموقع يتطلب JavaScript أو جلسة أو رؤوسًا أو يحظر المعدل. + - افحص الاستجابة الخام، خفّض معدل الطلب، وأضف المعالجة اللازمة دون تجاوز ضوابط الموقع أو شروطه. + +تنظيف البيئة وإعادة الضبط +========================== + +لإيقاف البيئة الافتراضية نفّذ: + +.. code-block:: bash + + deactivate + +لحذف البيئة والملفات الناتجة محليًا من مشروع الزحف، تحقق من المسار أولًا +ثم نفّذ: + +.. code-block:: bash + + rm -rf .venv + rm -f quotes.json quotes.jsonl + +لا تنفذ أمر الحذف إذا لم تكن داخل المجلد الصحيح. أما في مستودع Scrapy +نفسه، فاحذف فقط ملفات البناء أو البيئات التي أنشأتها أنت، ولا تحذف +``scrapy/`` أو ``tests/`` أو ``docs/``. + +المراجع +------- + +.. [1] `Scrapy at a glance `_. +.. [2] `Scrapy architecture overview `_. +.. [3] `Scrapy installation guide `_. +.. [4] `Scrapy tutorial `_. +.. [5] `Scrapy command line tool `_. +.. [6] `Repository pyproject.toml `_. +.. [7] `Repository tox.ini `_. +.. [8] `Repository security policy `_. + +Scrapy_ هو إطار لاستخلاص البيانات من الويب، وهو متعدد المنصات ويتطلب +Python 3.10 أو أحدث. تتم صيانته بواسطة `Zyte `_ +والعديد من `المساهمين `_. +للتثبيت المباشر خارج نسخة المصدر: + +.. code-block:: bash + + pip install scrapy + +للمساهمة في المشروع، راجع `دليل المساهمة `_.