🕷️ 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 a migration guide to v0.5
Karim shoaire5d1e3660048
diff --git a/docs/locales/ar/migrating-to-v0.5.md b/docs/locales/ar/migrating-to-v0.5.mdnew file mode 100644index 0000000..67df6e0--- /dev/null+++ b/docs/locales/ar/migrating-to-v0.5.md@@ -0,0 +1,293 @@+---+title: "الانتقال إلى v0.5"+description: "انتقل من Scrapling v0.4.15 إلى v0.5. حدّث استيرادات المتصفح، وتسجيل طلبات الشبكة، وأدوات MCP، وأوامر CLI، وإعدادات المحلّل، وسلوك Spiders."+---++# الانتقال إلى v0.5 {#migrating-to-v05}++يغطي هذا الدليل التغييرات التي تحتاج إلى مراجعتها عند الانتقال من **v0.4.15 إلى v0.5**. ويشمل واجهات API المحذوفة، والأدوات التي تغيّرت أسماؤها، والإصلاحات التي قد تغيّر نتائج الزحف أو الملفات المحفوظة.++## قائمة سريعة للانتقال {#quick-migration-checklist}++| إذا كنت تستخدم... | ما يجب تغييره |+| --- | --- |+| `DynamicFetcher` أو `DynamicSession` أو `AsyncDynamicSession` | استخدم فئة التخفي المقابلة. |+| `capture_xhr` أو `response.captured_xhr` | استخدم جلسة متصفح مع `record_requests=True` و`session.network`. |+| `keep_cdata` | احذفه من إعدادات المحلّل وFetcher. |+| `scrapling extract stealthy-fetch` أو `stealthy_fetch()` في البيئة التفاعلية | استخدم `fetch` بدلًا منه. |+| أدوات MCP | حدّث أسماء الأدوات واستدعاءات لقطات الشاشة وطريقة التعامل مع استجابة إنشاء الجلسة. |+| `response.follow()` بعد طلب POST أو طلب يحتوي على معاملات استعلام | مرّر الطريقة والاستعلام والمحتوى من جديد عند الحاجة إليها. |+| نقاط استئناف الزحف أو ذاكرة الاستجابات المؤقتة المحفوظة | ابدأ زحفًا جديدًا إذا كانت طلباتك تستخدم مدخلات بصمة الطلب التي تغيّرت. |+| `robots_txt_obey=True` | تعامل مع فشل جلب robots.txt، فهو يمنع الزحف إلى ذلك النطاق الآن. |++## الجلب بالمتصفح {#browser-fetching}++### استبدل فئات المتصفح الديناميكي {#replace-the-dynamic-browser-classes}++حُذف محرك المتصفح الذي يستخدم Playwright مباشرة. كل عمليات الجلب بالمتصفح تستخدم الآن محرك التخفي المبني على Patchright.++| واجهة API المحذوفة | البديل |+| --- | --- |+| `scrapling.DynamicFetcher` | `scrapling.StealthyFetcher` |+| `scrapling.fetchers.DynamicFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.chrome.PlayWrightFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.DynamicSession` | `scrapling.fetchers.StealthySession` |+| `scrapling.fetchers.AsyncDynamicSession` | `scrapling.fetchers.AsyncStealthySession` |++حُذفت وحدة `scrapling.fetchers.chrome` والوحدة الخاصة `_browsers._controllers`. استخدم الاستيرادات العامة المذكورة أعلاه.++**قبل:**++```python+from scrapling.fetchers import DynamicFetcher++page = DynamicFetcher.fetch("https://example.com", headless=True)+```++**الآن:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", headless=True)+```++للجلسات، استبدل `DynamicSession` بـ`StealthySession`، أو `AsyncDynamicSession` بـ`AsyncStealthySession`. طبّق التغيير نفسه في طريقة `configure_sessions()` داخل Spider. تظل طريقة استخدام `fetch()` و`async with` كما هي.++إذا كانت دوال callback تستورد أنواع المتصفح أو تلتقط أخطاءه، غيّر `playwright.sync_api` إلى `patchright.sync_api`، أو `playwright.async_api` إلى `patchright.async_api`. يشمل ذلك `Page` و`Locator` و`Error` و`TimeoutError`.++ينفّذ Patchright كود JavaScript في سياق معزول افتراضيًا. إذا كانت دالة callback تقرأ متغيرات JavaScript الخاصة بالصفحة، استخدم `page.evaluate(..., isolated_context=False)`.++يتغيّر سلوك المتصفح إلى جانب اسم الاستيراد. راجع خيارات المتصفح وإعدادات البصمة. ما زال حل Cloudflare يتطلب `solve_cloudflare=True`؛ فهو غير مفعّل افتراضيًا. كذلك، يضيف `extra_flags` الآن إلى خيارات التخفي المدمجة بدلًا من استبدالها.++راجع [الجلب بالمتصفح](fetching/stealthy.md) لمعرفة الخيارات الحالية.++### استبدل التقاط XHR بسجل شبكة الجلسة {#replace-xhr-capture-with-session-network-history}++حُذف المعامل `capture_xhr` والخاصية `Response.captured_xhr`. احذف المعامل حتى لو كانت قيمته `None`. لم تعد عملية الجلب المنفردة تُرفق قائمة XHR باستجابتها.++يجب أن تحذف التكاملات المخصصة التي تستدعي `ResponseFactory.from_playwright_response()` أو `ResponseFactory.from_async_playwright_response()` المعامل `xhr_captured` أيضًا. مرّر `collect_history` باسمه لتجنب أثر تغيّر ترتيب المعاملات الموضعية.++**قبل:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", capture_xhr="/api/")+for response in page.captured_xhr:+ print(response.url, response.body)+```++**الآن:**++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True) as session:+ page = session.fetch("https://example.com", network_idle=True)+ for response in session.network.search(url_pattern=r"/api/", limit=None):+ print(response.url, response.body)+```++استخدم `AsyncStealthySession` و`await session.fetch(...)` للكود غير المتزامن. لا تحتاج قراءة `session.network` إلى `await`.++هناك بعض الفروق المهمة:++- اضبط `record_requests=True` عند إنشاء الجلسة. هذا إعداد للجلسة، وليس لكل عملية جلب.+- يخص السجل **الجلسة كلها**، بما فيها علامات التبويب وعمليات تحميل الصفحات والإجراءات. استخدم `after_id` أو المرشحات أو `session.network.clear()` إذا كنت تحتاج إلى نطاق أصغر.+- انقل التعبير النمطي القديم في `capture_xhr` إلى `url_pattern` عند البحث في السجل.+- تعيد `search()` كائنات `Response` محفوظة. اقرأ `.url` أو `.status` أو `.headers` أو `.body` أو `.json()` مباشرة. تجد معرّف التسجيل ونوع المورد والمحتوى المرسَل في `response.meta["network_id"]` و`response.meta["resource_type"]` و`response.meta["request_body"]`.+- يشمل سجل Python كل أنواع الموارد افتراضيًا. استخدم `resource_type="xhr"` أو `resource_type="fetch"` لاختيار أحدهما، أو `include_static=False` لطلبات XHR/fetch مع أخطاء HTTP.+- تعيد `search()` ما يصل إلى 100 نتيجة افتراضيًا. مرّر `limit=None` للحصول على كل النتائج المحفوظة. تحتفظ الجلسات بما يصل إلى 1,000 طلب افتراضيًا؛ غيّر ذلك باستخدام `max_recorded_requests`.+- تُحفظ الطلبات المكتملة فقط. يقتصر تسجيل المحتوى على أنواع المحتوى النصي المدعومة، بحد 1 MiB لكل استجابة و20 MiB لإجمالي بيانات المحتوى المحفوظة. قد تُحذف السجلات الأقدم عند الوصول إلى الحدود. راجع `response.meta.get("body_note")` لمعرفة سبب تخطي المحتوى.+- لا تنتظر قراءة السجل أو إغلاق الجلسة عمليات التسجيل المعلّقة. انتظر البيانات التي تحتاج إليها قبل قراءتها. يظل سجل Python المحفوظ قابلًا للقراءة بعد إغلاق الجلسة.++راجع [سجل الشبكة](fetching/stealthy.md#network-history) لمعرفة المرشحات والحدود.++## إعدادات المحلّل {#parser-settings}++### احذف `keep_cdata` {#remove-keep_cdata}++حُذف `keep_cdata` من `Selector` وإعدادات Fetcher والإعدادات التي تعيدها `display_config()`. احذفه من استدعاءات المحلّل المباشرة و`Fetcher.configure(...)` وقواميس `selector_config` التي تمرّرها إلى Fetchers أو التكاملات.++**قبل:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>", keep_cdata=True)+```++**الآن:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>")+```++لا يوجد إعداد بديل. لم يكن هذا الإعداد يؤثر في ناتج محلّل HTML. إذا كنت تمرّر خيارات المحلّل حسب ترتيبها دون أسماء، فاحذف المعامل القديم `keep_cdata`، ومرّر `adaptive` وخيارات التخزين بأسمائها.++## سطر الأوامر والبيئة التفاعلية {#command-line-and-interactive-shell}++### استخدم `fetch` لطلبات المتصفح {#use-fetch-for-browser-requests}++تحتوي CLI الآن على أمر واحد للمتصفح: `scrapling extract fetch`. ويستخدم `StealthyFetcher`.++**قبل:**++```bash+scrapling extract stealthy-fetch "https://example.com" page.md+```++**الآن:**++```bash+scrapling extract fetch "https://example.com" page.md+```++إذا كنت تستخدم `scrapling extract fetch` بالفعل، يظل اسم الأمر كما هو، لكن محركه يتغيّر من `DynamicFetcher` إلى `StealthyFetcher`. أصبحت خيارات مثل `--solve-cloudflare` تابعة لـ`fetch`.++في `scrapling shell`، استبدل `stealthy_fetch(...)` بـ`fetch(...)`. يستدعي الاختصار الحالي `fetch(...)` الآن `StealthyFetcher.fetch`. لم تعد الفئات الديناميكية تُضاف إلى نطاق أسماء البيئة التفاعلية.++### اقرأ ملفات Markdown والنص بترميز UTF-8 {#read-markdown-and-text-files-as-utf-8}++تكتب أوامر الاستخراج و`Convertor.write_content_to_file()` الآن ملفات `.md` و`.txt` بترميز **UTF-8**، بصرف النظر عن ترميز الصفحة الأصلية. حدّث أي كود يقرأ تلك الملفات بترميز الصفحة الأصلي. ما زال ناتج `.html` يستخدم `page.encoding`.++يحتوي Markdown المستخرج من عدة عناصر محددة الآن على أسطر فارغة بين العناصر. ينطبق هذا على `Response.markdown()` وملفات Markdown الناتجة. حدّث الاختبارات التي تقارن الناتج حرفيًا أو قيم التجزئة المحفوظة التي كانت تعتمد على النص المتصل.++## خادم MCP {#mcp-server}++حدّث التعليمات المحفوظة وقوائم الأدوات المسموح بها والدوال الوسيطة وتعريفات أدوات عميل MCP. أعد تشغيل عميل MCP أو توصيله بعد تحديث الخادم كي يقرأ الأدوات الحالية.++### حدّث أسماء الأدوات والاستدعاءات المجمّعة {#update-tool-names-and-bulk-calls}++| أداة v0.4.15 | البديل في v0.5 |+| --- | --- |+| `fetch`, `stealthy_fetch` | `browser_fetch_once` |+| `open_session` | `browser_open` |+| `session_fetch` | `browser_fetch` |+| `screenshot` | `browser_screenshot` |+| `bulk_fetch`, `bulk_stealthy_fetch` | استدعاء واحد لـ`browser_fetch_once` لكل URL، أو استدعاءات متكررة لـ`browser_fetch` عبر جلسة مفتوحة |+| `bulk_get` | استدعاء واحد لـ`make_request` أو `session_make_request` لكل URL |++حُذفت كل أدوات العمليات المجمّعة. تعيد أدوات جلب URL واحد كائن `ResponseModel` واحدًا يحتوي على `status` و`content` و`url`، وليس قائمة استجابات. ما زال `content` نفسه قائمة نصوص.++تستخدم كل أدوات متصفح MCP الآن محرك التخفي. احذف `session_type` من استدعاءات `browser_open`؛ لم يعد هناك خيار للمتصفح الديناميكي. تحتوي نتيجته على `session_type="stealthy"`. ما زالت جلسات HTTP تستخدم `open_request_session` وتعيد `session_type="static"`.++يجب أن تتوقف تكاملات Python أيضًا عن استيراد `BrowserSessionType`، فقد حُذف. يقبل `SessionType` الآن `"stealthy"` و`"static"` فقط.++يجب تشغيل الاستدعاءات عبر جلسة متصفح واحدة بالترتيب لأنها تشترك في صفحة. أغلق الجلسات باستخدام `close_session` عند الانتهاء.++### اقرأ الإعدادات عبر `list_sessions` {#read-settings-through-list_sessions}++تعيد `browser_open` و`open_request_session` الآن ما يلي فقط:++```json+{+ "session_id": "my-session",+ "session_type": "stealthy"+}+```++لم تعد نتيجة الإنشاء تتضمن `created_at` أو `is_alive` أو `settings` أو `message`. استدعِ `list_sessions` للحصول على الحقول الثلاثة الأولى. حُذفت رسالة التأكيد `message`. يجب أيضًا تغيير الكود الذي كان يفترض أن `SessionCreatedModel` يحتوي على كل حقول `SessionInfo`.++### اجلب الصفحة قبل أخذ لقطة شاشة {#fetch-before-taking-a-screenshot}++تلتقط `browser_screenshot` **الصفحة الحالية دون إعادة تحميلها**. لم تعد تقبل URL أو خيارات التنقل والانتظار القديمة: `wait` و`wait_selector` و`wait_selector_state` و`network_idle`.++استخدم هذا الترتيب:++1. استدعِ `browser_open`.+2. استدعِ `browser_fetch` مع URL وأي خيارات لتحميل الصفحة.+3. عند الحاجة، استدعِ `browser_actions` للتفاعل مع الصفحة أو انتظار المحتوى.+4. استدعِ `browser_screenshot` مع معرّف الجلسة.+5. استدعِ `close_session` عند الانتهاء.++مثلًا، معاملات لقطة شاشة للصفحة كاملة هي:++```json+{+ "session_id": "my-session",+ "full_page": true+}+```++يحدد `timeout` في هذه الأداة الآن مهلة أخذ اللقطة فقط. لا تحمّل الأداة صفحة. لأخذ لقطة لعنصر، استخدم `selector` أو `ref`، ولا تضبط `full_page=true`.++ما زالت لقطات الشاشة تعيد كتل محتوى للصور والنص، مع URL الصفحة الحالية في كتلة النص. ولا تعيد `ResponseModel` الخاص بالجلب.++راجع [دليل MCP](ai/mcp-server.md) و[مرجع API](api-reference/mcp-server.md) لمعرفة بنية المدخلات والنتائج كاملة.++## Spiders وطلبات HTTP {#spiders-and-http-requests}++### مرّر بيانات الطلب من جديد عند متابعة رابط {#pass-request-data-again-when-following-a-link}++لم تعد `response.follow()` تنسخ `method` أو `params` أو `data` أو `json` أو `files` أو `multipart` من الطلب السابق. وتحذف أيضًا ترويسات `Content-Length` الموروثة من `headers` و`extra_headers`.++يبدأ الرابط الذي تتابعه الآن بطلب GET عادي ما لم تمرّر بيانات الطلب صراحة. ما زالت الإعدادات المشتركة الأخرى، مثل الجلسة وProxy ودوال callback، تتبع قواعد التوريث الحالية.++إذا كان كودك القديم يعتمد على بيانات POST الموروثة، غيّر:++```python+yield response.follow("/next")+```++إلى:++```python+yield response.follow("/next", method="POST", json={"page": 2})+```++مرّر `params` صراحة أيضًا عندما يحتاج إليها الطلب التالي. اترك عميل HTTP يحسب `Content-Length` الجديد.++### راجع بصمات الطلبات وحالة الزحف المحفوظة {#check-request-fingerprints-and-saved-crawl-state}++بصمة الطلب هي المفتاح المستخدم لاكتشاف الطلبات المكررة والعثور على الاستجابات المخزنة مؤقتًا. تتعامل مدخلاتها الآن مع ثلاث حالات بطريقة مختلفة:++- تُدمج `params` في URL قبل إنشاء المفتاح. لم تعد الطلبات إلى URL نفسه بمعاملات استعلام مختلفة تُعد مكررة افتراضيًا.+- تُحفظ محتويات JSON مثل `{}` و`[]` و`false` و`0` و`""` في المفتاح. لم تعد تشترك في مفتاح الطلب الذي لا يحتوي على محتوى. ما زالت `None` تعني عدم وجود محتوى JSON.+- عند ضبط `fp_include_headers=True`، لم يعد تغيير ترتيب إدراج الترويسات وحده يغيّر المفتاح.++إذا كان الزحف يستخدم هذه المدخلات، أنهِه قبل الترقية أو ابدأ زحفًا جديدًا بنقطة استئناف جديدة ومجلد جديد لذاكرة الاستجابات المؤقتة. قد تختلف المفاتيح القديمة المحفوظة عن المفاتيح الجديدة. هذا تغيير في هوية الطلب، وليس في تنسيق ملف نقطة الاستئناف.++يكتب وضع التطوير الآن الاستجابات في الذاكرة المؤقتة فقط بعد التحقق من حظر الاستجابة. لا تُحفظ صفحات الحظر كنتائج ناجحة في الذاكرة المؤقتة. لا تُنظف الملفات الموجودة تلقائيًا؛ احذف السجلات القديمة إذا كنت قد خزّنت صفحة تحقق سابقًا.++تحتفظ عمليات الزحف الفاشلة الآن بملفات نقاط الاستئناف. راجع كود التنظيف إذا كان يفترض اختفاء تلك الملفات بعد الخطأ. راجع [الإيقاف والاستئناف](spiders/advanced.md#pause-resume) و[وضع التطوير](spiders/advanced.md#development-mode).++### راجع حالات فشل robots.txt {#check-robotstxt-failures}++عند ضبط `robots_txt_obey=True`، تُمنع الطلبات إلى النطاق إذا حدث استثناء أثناء جلب robots.txt أو كانت حالة الاستجابة غير HTTP 200 أو 4xx. كانت هذه الحالات تسمح بالزحف سابقًا. ما زالت HTTP 200 توفّر القواعد، وHTTP 4xx تسمح بالوصول.++تُخزن النتيجة طوال عملية الزحف. أصلح مشكلة الوصول إلى robots.txt وابدأ زحفًا جديدًا؛ لن تعيد الطلبات اللاحقة في عملية الزحف نفسها محاولة الجلب الفاشلة. لا يغيّر ذلك القيمة الافتراضية `robots_txt_obey=False`.++### راجع قيود الروابط ودوال callback لخرائط الموقع {#check-link-restrictions-and-sitemap-callbacks}++- يعيد قيد `LinkExtractor` الذي لا يطابق أي عنصر الآن قائمة بلا روابط. لم يعد يرجع إلى الصفحة كلها. أصلح تعبير `restrict_css` أو `restrict_xpath` إذا أصبح الزحف يعثر على روابط أقل.+- يمكن للقيد الآن اختيار عنصر الرابط نفسه، وليس عنصرًا أبًا فقط. قد يضيف ذلك روابط لم تكن تظهر سابقًا. راجع مجموعات عناوين URL المتوقعة.+- يرسل `SitemapSpider` الآن عناوين URL للصفحات إلى `parse()` عند عدم وجود قواعد، أو عندما تحتوي قاعدة مطابقة على `callback=None`. لم يعد يرسل صفحات HTML هذه إلى محلّل خريطة الموقع مرة أخرى. اكتب `parse()` لهذه الحالات واحذف الحلول البديلة التي عالجت التوجيه القديم.+- تُحذف علامة ترتيب بايتات Unicode من بداية robots.txt وتغذيات CSV. يعمل الآن أول توجيه في robots، ولم يعد عنوان أول عمود CSV يبدأ بـ`\ufeff`. إذا حددت `headers` مخصصة، تُحذف العلامة من قيمة أول حقل بدلًا من ذلك. حدّث الكود الذي كان يعالج هذه البادئة المخفية. تُتخطى أيضًا تعليقات XML وتعليمات المعالجة في خرائط الموقع بدلًا من التسبب في فشل التحليل.++### راجع بيانات النماذج والترويسات وJSON في CLI {#check-form-data-headers-and-cli-json}++توسّع بيانات النماذج في القواميس الآن قيم القوائم وtuples إلى مفاتيح متكررة. مثلًا، ترسل `data={"tag": ["a", "b"]}` القيمة `tag=a&tag=b`. لا يُرسل المفتاح إذا كانت قيمته قائمة فارغة. تُضاف الترويسة الافتراضية `Content-Type: application/x-www-form-urlencoded` إذا لم توفّرها.++إذا كنت تحتاج إلى تنسيق إرسال مختلف، مرّر نصًا أو bytes مرمّزة صراحة. تحتفظ `json` و`content` الخام وعمليات رفع multipart بطريقة معالجة محتواها. قيم `None` **لا تُحذف** من بيانات النماذج أو معاملات الاستعلام؛ وتظل النص `None`.++تتجاوز ترويسات HTTP لكل طلب الآن ترويسات الجلسة بصرف النظر عن حالة الأحرف. تستبدل ترويسة الطلب المسماة `authorization` ترويسة الجلسة `Authorization` بدلًا من إرسال الاثنتين. احذف الكود الذي كان يعالج تكرار أسماء الترويسات.++تُرسل الآن قيم JSON في CLI مثل `{}` و`[]` و`false` و`0` و`""` بدلًا من حذفها بصمت. كذلك، تطبّق `curl2fetcher()` الآن User-Agent المحدد بخيار curl `-A`، وتمرّر Proxy المحدد بخيار `-x` بشكل صحيح كنص URL. ما زالت ترويسة curl الصريحة `-H 'User-Agent: ...'` لها الأولوية على `-A`.++## تغييرات أخرى في الناتج يجب مراجعتها {#other-output-changes-to-check}++لا تحذف هذه الإصلاحات واجهات API، لكنها قد تغيّر النتائج المحفوظة واختبارات التطابق التام للناتج:++- تتضمن محددات CSS وXPath المُنشأة الآن `:nth-of-type(1)` أو `[1]` عند الحاجة إلى تحديد أول عنصر بين عدة عناصر شقيقة لها الوسم نفسه. حدّث نصوص المحددات المتوقعة؛ لا تحذف علامة الموضع الجديدة.+- يحتفظ محتوى AI المنظّف الآن بالعناصر المرئية ذات القيم مثل `opacity:0.95`، ويزيل العناصر التي تخفيها أشكال إضافية من الأنماط المضمنة وعناصر `<slot hidden>`، ويزيل كل وسوم الضوضاء المطابقة حتى عندما تكون متداخلة. راجع التطابق التام لناتج Markdown والنص وHTML المنظّف.+- يقرأ تحويل استجابات المتصفح الآن تعريفات charset التي تختلف فيها حالة الأحرف أو تحتوي على مسافات أو قيم بين علامتي اقتباس، مثل `text/plain; CHARSET = "iso-8859-15"`. تستخدم الاستجابات غير المكتوبة بصيغة HTML التي تحمل هذه الترويسات الآن الترميز المحدد بدلًا من الرجوع إلى UTF-8. راجع النص المستخرج من تلك الاستجابات بعد فك ترميزه.++## تحقق من الترقية {#verify-your-upgrade}++شغّل زحفًا صغيرًا قبل المهمة الكاملة. تحقق من البيانات المستخرجة وعناوين URL التي يتابعها الزحف ومحتويات الطلبات المرسلة وترميز الملفات المحفوظة وأي سلوك تعتمد عليه للذاكرة المؤقتة أو نقاط الاستئناف. لتكاملات MCP، راجع مدخلات الأدوات والبيانات التي تعيدها وفق البنية الحالية.++لتغييرات الإصدارات الأقدم، راجع [سجل التغييرات](changelog.md).diff --git a/docs/locales/de/migrating-to-v0.5.md b/docs/locales/de/migrating-to-v0.5.mdnew file mode 100644index 0000000..edd0648--- /dev/null+++ b/docs/locales/de/migrating-to-v0.5.md@@ -0,0 +1,293 @@+---+title: "Migration auf v0.5"+description: "Wechseln Sie von Scrapling v0.4.15 auf v0.5. Aktualisieren Sie Browser-Imports, Netzwerkaufzeichnung, MCP-Tools, CLI-Befehle, Parser-Einstellungen und das Verhalten Ihrer Spider."+---++# Migration auf v0.5 {#migrating-to-v05}++Diese Anleitung beschreibt die Änderungen, die Sie beim Wechsel von **v0.4.15 auf v0.5** prüfen sollten. Sie enthält entfernte APIs, umbenannte Tools und Korrekturen, die Ihre Crawl-Ergebnisse oder gespeicherten Dateien verändern können.++## Kurze Checkliste für die Migration {#quick-migration-checklist}++| Wenn Sie Folgendes verwenden... | Was Sie ändern müssen |+| --- | --- |+| `DynamicFetcher`, `DynamicSession` oder `AsyncDynamicSession` | Verwenden Sie die passende Stealth-Klasse. |+| `capture_xhr` oder `response.captured_xhr` | Verwenden Sie eine Browsersitzung mit `record_requests=True` und `session.network`. |+| `keep_cdata` | Entfernen Sie die Option aus den Parser- und Fetcher-Einstellungen. |+| `scrapling extract stealthy-fetch` oder `stealthy_fetch()` in der Shell | Verwenden Sie stattdessen `fetch`. |+| MCP-Tools | Aktualisieren Sie die Tool-Namen, Screenshot-Aufrufe und die Verarbeitung der Antwort beim Erstellen einer Sitzung. |+| `response.follow()` nach einer POST-Anfrage oder einer Anfrage mit Abfrageparametern | Übergeben Sie Methode, Abfrageparameter und Body erneut, wenn Sie diese benötigen. |+| Gespeicherte Crawl-Checkpoints oder Antwort-Caches | Starten Sie einen neuen Crawl, wenn Ihre Anfragen die geänderten Fingerprint-Eingaben verwenden. |+| `robots_txt_obey=True` | Behandeln Sie Fehler beim Abrufen von robots.txt. Diese blockieren jetzt das Crawling für die betroffene Domain. |++## Abrufen mit dem Browser {#browser-fetching}++### Ersetzen Sie die dynamischen Browserklassen {#replace-the-dynamic-browser-classes}++Das Browser-Backend, das Playwright direkt verwendet hat, wurde entfernt. Alle Browserabrufe nutzen jetzt das Stealth-Backend auf Basis von Patchright.++| Entfernte API | Ersatz |+| --- | --- |+| `scrapling.DynamicFetcher` | `scrapling.StealthyFetcher` |+| `scrapling.fetchers.DynamicFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.chrome.PlayWrightFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.DynamicSession` | `scrapling.fetchers.StealthySession` |+| `scrapling.fetchers.AsyncDynamicSession` | `scrapling.fetchers.AsyncStealthySession` |++Das Modul `scrapling.fetchers.chrome` und das private Modul `_browsers._controllers` wurden entfernt. Verwenden Sie die oben genannten öffentlichen Imports.++**Vorher:**++```python+from scrapling.fetchers import DynamicFetcher++page = DynamicFetcher.fetch("https://example.com", headless=True)+```++**Jetzt:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", headless=True)+```++Ersetzen Sie bei Sitzungen `DynamicSession` durch `StealthySession` oder `AsyncDynamicSession` durch `AsyncStealthySession`. Ändern Sie auch die Methode `configure_sessions()` Ihres Spiders entsprechend. Die Verwendung von `fetch()` und `async with` bleibt gleich.++Wenn Ihre Callbacks Browsertypen importieren oder Browserfehler abfangen, ersetzen Sie `playwright.sync_api` durch `patchright.sync_api` oder `playwright.async_api` durch `patchright.async_api`. Dazu gehören `Page`, `Locator`, `Error` und `TimeoutError`.++Patchright führt JavaScript standardmäßig in einem isolierten Kontext aus. Wenn ein Callback die JavaScript-Variablen der Seite selbst liest, verwenden Sie `page.evaluate(..., isolated_context=False)`.++Neben dem Importnamen ändert sich auch das Verhalten des Browsers. Prüfen Sie Ihre Browser-Flags und Fingerprint-Einstellungen. Das Lösen von Cloudflare-Prüfungen erfordert weiterhin `solve_cloudflare=True` und ist standardmäßig nicht aktiviert. Außerdem ergänzt `extra_flags` jetzt die eingebauten Stealth-Flags, statt sie zu ersetzen.++Die aktuellen Optionen finden Sie unter [Abrufen mit dem Browser](fetching/stealthy.md).++### Ersetzen Sie die XHR-Erfassung durch den Netzwerkverlauf der Sitzung {#replace-xhr-capture-with-session-network-history}++Der Parameter `capture_xhr` und das Attribut `Response.captured_xhr` wurden entfernt. Entfernen Sie den Parameter auch dann, wenn sein Wert `None` ist. Ein Einzelabruf hängt keine XHR-Liste mehr an seine Antwort an.++Eigene Integrationen, die `ResponseFactory.from_playwright_response()` oder `ResponseFactory.from_async_playwright_response()` aufrufen, müssen ebenfalls `xhr_captured` entfernen. Übergeben Sie `collect_history` als benanntes Argument, um Probleme durch die geänderte Reihenfolge der Positionsargumente zu vermeiden.++**Vorher:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", capture_xhr="/api/")+for response in page.captured_xhr:+ print(response.url, response.body)+```++**Jetzt:**++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True) as session:+ page = session.fetch("https://example.com", network_idle=True)+ for response in session.network.search(url_pattern=r"/api/", limit=None):+ print(response.url, response.body)+```++Verwenden Sie für asynchronen Code `AsyncStealthySession` und `await session.fetch(...)`. Zum Lesen von `session.network` ist kein `await` nötig.++Es gibt einige wichtige Unterschiede:++- Setzen Sie `record_requests=True`, wenn Sie die Sitzung erstellen. Dies ist eine Sitzungseinstellung und keine Einstellung für einzelne Abrufe.+- Der Verlauf gehört zur **gesamten Sitzung**, über Tabs, Seitenaufrufe und Aktionen hinweg. Verwenden Sie `after_id`, Filter oder `session.network.clear()`, wenn Sie einen kleineren Bereich benötigen.+- Verwenden Sie den bisherigen regulären Ausdruck aus `capture_xhr` beim Durchsuchen des Verlaufs als `url_pattern`.+- `search()` gibt gespeicherte `Response`-Objekte zurück. Lesen Sie `.url`, `.status`, `.headers`, `.body` oder `.json()` direkt. Die Aufzeichnungs-ID, der Ressourcentyp und der gesendete Body stehen in `response.meta["network_id"]`, `response.meta["resource_type"]` und `response.meta["request_body"]`.+- Der Python-Verlauf enthält standardmäßig alle Ressourcentypen. Verwenden Sie `resource_type="xhr"` oder `resource_type="fetch"`, um einen auszuwählen, oder `include_static=False` für XHR/fetch-Anfragen zusammen mit HTTP-Fehlern.+- `search()` gibt standardmäßig höchstens 100 Treffer zurück. Übergeben Sie `limit=None` für alle gespeicherten Treffer. Sitzungen behalten standardmäßig höchstens 1.000 Anfragen; ändern Sie dies mit `max_recorded_requests`.+- Nur abgeschlossene Anfragen werden gespeichert. Die Body-Erfassung ist auf unterstützte Textinhaltstypen, 1 MiB pro Antwort und insgesamt 20 MiB gespeicherte Body-Daten begrenzt. Ältere Einträge können beim Erreichen der Grenzen entfernt werden. In `response.meta.get("body_note")` finden Sie den Grund, warum ein Body ausgelassen wurde.+- Das Lesen des Verlaufs oder das Schließen der Sitzung wartet nicht auf ausstehende Aufzeichnungen. Warten Sie auf die benötigten Daten, bevor Sie sie lesen. Der gespeicherte Python-Verlauf bleibt nach dem Schließen der Sitzung lesbar.++Filter und Grenzen finden Sie unter [Netzwerkverlauf](fetching/stealthy.md#network-history).++## Parser-Einstellungen {#parser-settings}++### Entfernen Sie `keep_cdata` {#remove-keep_cdata}++`keep_cdata` wurde aus `Selector`, der Fetcher-Konfiguration und den von `display_config()` zurückgegebenen Einstellungen entfernt. Entfernen Sie die Option aus direkten Parser-Aufrufen, `Fetcher.configure(...)` und den `selector_config`-Dictionaries, die Sie an Fetcher oder Integrationen übergeben.++**Vorher:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>", keep_cdata=True)+```++**Jetzt:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>")+```++Es gibt keine Ersatzeinstellung. Sie hatte keinen Einfluss auf die Ausgabe des HTML-Parsers. Wenn Sie Parser-Optionen als Positionsargumente übergeben haben, entfernen Sie das alte Argument `keep_cdata` und verwenden Sie für `adaptive` und die Speicheroptionen benannte Argumente.++## Kommandozeile und interaktive Shell {#command-line-and-interactive-shell}++### Verwenden Sie `fetch` für Browseranfragen {#use-fetch-for-browser-requests}++Die CLI hat jetzt nur noch einen Browserbefehl: `scrapling extract fetch`. Er verwendet `StealthyFetcher`.++**Vorher:**++```bash+scrapling extract stealthy-fetch "https://example.com" page.md+```++**Jetzt:**++```bash+scrapling extract fetch "https://example.com" page.md+```++Wenn Sie bereits `scrapling extract fetch` verwenden, bleibt der Befehlsname gleich. Das Backend wechselt aber von `DynamicFetcher` zu `StealthyFetcher`. Optionen wie `--solve-cloudflare` gehören jetzt zu `fetch`.++Ersetzen Sie in `scrapling shell` den Aufruf `stealthy_fetch(...)` durch `fetch(...)`. Die vorhandene Kurzform `fetch(...)` ruft jetzt `StealthyFetcher.fetch` auf. Die dynamischen Klassen werden nicht mehr zum Namensraum der Shell hinzugefügt.++### Lesen Sie Markdown- und Textdateien als UTF-8 {#read-markdown-and-text-files-as-utf-8}++Die Extraktionsbefehle und `Convertor.write_content_to_file()` schreiben `.md`- und `.txt`-Dateien jetzt in **UTF-8**, unabhängig vom Zeichensatz der Quellseite. Aktualisieren Sie Code, der diese Dateien mit der ursprünglichen Kodierung der Seite liest. Die `.html`-Ausgabe verwendet weiterhin `page.encoding`.++Markdown aus mehreren ausgewählten Elementen enthält jetzt Leerzeilen zwischen den Elementen. Das gilt für `Response.markdown()` und die Ausgabe in Markdown-Dateien. Aktualisieren Sie exakte Ausgabevergleiche oder gespeicherte Hashes, die vom zusammengefügten Text abhingen.++## MCP-Server {#mcp-server}++Aktualisieren Sie gespeicherte Prompts, Listen erlaubter Tools, Wrapper und die Tool-Definitionen Ihres MCP-Clients. Starten Sie den MCP-Client nach der Serveraktualisierung neu oder verbinden Sie ihn erneut, damit er die aktuellen Tools einliest.++### Aktualisieren Sie Tool-Namen und Sammelaufrufe {#update-tool-names-and-bulk-calls}++| Tool in v0.4.15 | Ersatz in v0.5 |+| --- | --- |+| `fetch`, `stealthy_fetch` | `browser_fetch_once` |+| `open_session` | `browser_open` |+| `session_fetch` | `browser_fetch` |+| `screenshot` | `browser_screenshot` |+| `bulk_fetch`, `bulk_stealthy_fetch` | Ein Aufruf von `browser_fetch_once` pro URL oder wiederholte Aufrufe von `browser_fetch` über eine offene Sitzung |+| `bulk_get` | Ein Aufruf von `make_request` oder `session_make_request` pro URL |++Alle Tools für Sammelabrufe wurden entfernt. Abruf-Tools für eine einzelne URL geben ein `ResponseModel` mit `status`, `content` und `url` zurück, keine Liste von Antworten. `content` selbst bleibt eine Liste von Zeichenfolgen.++Alle MCP-Browsertools verwenden jetzt das Stealth-Backend. Entfernen Sie `session_type` aus Aufrufen von `browser_open`; die Auswahl eines dynamischen Browsers entfällt. Das Ergebnis enthält `session_type="stealthy"`. HTTP-Sitzungen verwenden weiterhin `open_request_session` und geben `session_type="static"` zurück.++Python-Integrationen dürfen auch `BrowserSessionType` nicht mehr importieren, da dieser Typ entfernt wurde. `SessionType` akzeptiert jetzt nur noch `"stealthy"` und `"static"`.++Aufrufe über dieselbe Browsersitzung müssen nacheinander ausgeführt werden, weil sie eine Seite gemeinsam nutzen. Schließen Sie Sitzungen mit `close_session`, wenn Sie fertig sind.++### Lesen Sie Einstellungen über `list_sessions` {#read-settings-through-list_sessions}++`browser_open` und `open_request_session` geben jetzt nur noch Folgendes zurück:++```json+{+ "session_id": "my-session",+ "session_type": "stealthy"+}+```++Das Ergebnis der Sitzungserstellung enthält nicht mehr `created_at`, `is_alive`, `settings` oder `message`. Rufen Sie `list_sessions` für die ersten drei Felder auf. Die Bestätigung `message` wurde entfernt. Code, der davon ausgeht, dass `SessionCreatedModel` alle Felder von `SessionInfo` enthält, muss ebenfalls angepasst werden.++### Rufen Sie die Seite vor einem Screenshot ab {#fetch-before-taking-a-screenshot}++`browser_screenshot` erfasst die **aktuelle Seite, ohne sie neu zu laden**. Das Tool akzeptiert keine URL und keine der alten Navigations- und Warteoptionen mehr: `wait`, `wait_selector`, `wait_selector_state` und `network_idle`.++Gehen Sie in dieser Reihenfolge vor:++1. Rufen Sie `browser_open` auf.+2. Rufen Sie `browser_fetch` mit der URL und den benötigten Optionen zum Laden der Seite auf.+3. Rufen Sie bei Bedarf `browser_actions` auf, um mit der Seite zu interagieren oder auf Inhalte zu warten.+4. Rufen Sie `browser_screenshot` mit der Sitzungs-ID auf.+5. Rufen Sie `close_session` auf, wenn Sie fertig sind.++Die Argumente für einen Screenshot der gesamten Seite sehen zum Beispiel so aus:++```json+{+ "session_id": "my-session",+ "full_page": true+}+```++`timeout` begrenzt bei diesem Tool jetzt die Erstellung des Screenshots. Das Tool lädt keine Seite. Verwenden Sie für den Screenshot eines Elements entweder `selector` oder `ref` und setzen Sie nicht `full_page=true`.++Screenshots geben weiterhin Bild- und Textinhaltsblöcke zurück. Der Textblock enthält die URL der aktuellen Seite. Sie geben kein Abruf-`ResponseModel` zurück.++Die vollständigen Schemas finden Sie in der [MCP-Anleitung](ai/mcp-server.md) und der [API-Referenz](api-reference/mcp-server.md).++## Spider und HTTP-Anfragen {#spiders-and-http-requests}++### Übergeben Sie Anfragedaten erneut, wenn Sie einem Link folgen {#pass-request-data-again-when-following-a-link}++`response.follow()` kopiert `method`, `params`, `data`, `json`, `files` oder `multipart` nicht mehr aus der vorherigen Anfrage. Außerdem werden geerbte `Content-Length`-Header aus `headers` und `extra_headers` entfernt.++Ein verfolgter Link beginnt jetzt als einfache GET-Anfrage, sofern Sie keine Anfragedaten ausdrücklich übergeben. Andere gemeinsame Einstellungen wie Sitzung, Proxy und Callbacks folgen weiterhin den bestehenden Vererbungsregeln.++Wenn Ihr bisheriger Code auf geerbte POST-Daten angewiesen war, ersetzen Sie:++```python+yield response.follow("/next")+```++durch:++```python+yield response.follow("/next", method="POST", json={"page": 2})+```++Übergeben Sie auch `params` ausdrücklich, wenn die nächste Anfrage sie benötigt. Lassen Sie den HTTP-Client den neuen `Content-Length` berechnen.++### Prüfen Sie Anfrage-Fingerprints und den gespeicherten Crawl-Zustand {#check-request-fingerprints-and-saved-crawl-state}++Ein Anfrage-Fingerprint ist der Schlüssel, mit dem doppelte Anfragen erkannt und Antworten im Cache gefunden werden. Drei Fälle werden bei seinen Eingaben jetzt anders behandelt:++- `params` werden vor der Schlüsselbildung in die URL aufgenommen. Anfragen an dieselbe URL mit unterschiedlichen Abfrageparametern gelten standardmäßig nicht mehr als Duplikate.+- JSON-Bodys wie `{}`, `[]`, `false`, `0` und `""` bleiben im Schlüssel erhalten. Sie haben nicht mehr denselben Schlüssel wie ein fehlender Body. `None` bedeutet weiterhin, dass kein JSON-Body vorhanden ist.+- Bei `fp_include_headers=True` ändert eine andere Einfügereihenfolge der Header allein den Schlüssel nicht mehr.++Wenn Ihr Crawl diese Eingaben verwendet, schließen Sie ihn vor der Aktualisierung ab oder starten Sie einen neuen Crawl mit einem neuen Checkpoint und einem neuen Verzeichnis für den Antwort-Cache. Alte gespeicherte Schlüssel können von den neuen abweichen. Dies ändert die Identität einer Anfrage, nicht das Dateiformat der Checkpoints.++Der Entwicklungsmodus schreibt Antworten jetzt erst nach der Prüfung auf blockierte Antworten in den Cache. Blockierte Seiten werden nicht als erfolgreiche Ergebnisse im Cache gespeichert. Vorhandene Cache-Dateien werden nicht automatisch bereinigt. Löschen Sie veraltete Einträge, wenn Sie zuvor eine Prüfseite im Cache gespeichert haben.++Fehlgeschlagene Crawls behalten jetzt ihre Checkpoint-Dateien. Prüfen Sie Ihren Bereinigungscode, falls er davon ausging, dass diese Dateien nach einem Fehler verschwinden. Siehe [Pausieren und fortsetzen](spiders/advanced.md#pause-resume) und [Entwicklungsmodus](spiders/advanced.md#development-mode).++### Prüfen Sie Fehler beim Abrufen von robots.txt {#check-robotstxt-failures}++Mit `robots_txt_obey=True` blockiert eine Ausnahme beim Abrufen von robots.txt oder eine Antwort außerhalb von HTTP 200 oder 4xx jetzt Anfragen an diese Domain. Zuvor erlaubten solche Fehler das Crawling. HTTP 200 liefert weiterhin die Regeln, und HTTP 4xx erlaubt weiterhin den Zugriff.++Das Ergebnis wird für den gesamten Crawl zwischengespeichert. Beheben Sie das Zugriffsproblem bei robots.txt und starten Sie einen neuen Crawl. Spätere Anfragen im selben Crawl wiederholen den fehlgeschlagenen Abruf nicht. Der Standardwert `robots_txt_obey=False` bleibt unverändert.++### Prüfen Sie Link-Einschränkungen und Sitemap-Callbacks {#check-link-restrictions-and-sitemap-callbacks}++- Eine `LinkExtractor`-Einschränkung ohne Treffer gibt jetzt keine Links zurück. Sie greift nicht mehr auf die gesamte Seite zurück. Korrigieren Sie den Ausdruck `restrict_css` oder `restrict_xpath`, wenn Ihr Crawl jetzt weniger Links findet.+- Eine Einschränkung kann jetzt das Link-Element selbst auswählen, nicht nur ein übergeordnetes Element. Dadurch können Links hinzukommen, die zuvor fehlten. Prüfen Sie die erwarteten URL-Mengen.+- `SitemapSpider` sendet Seiten-URLs jetzt an `parse()`, wenn keine Regeln vorhanden sind oder eine passende Regel `callback=None` hat. Diese HTML-Seiten werden nicht mehr an den Sitemap-Parser zurückgesendet. Implementieren Sie für diese Fälle `parse()` und entfernen Sie Umgehungslösungen für die alte Weiterleitung.+- Ein führendes Unicode-Byte-Order-Mark wird aus robots.txt und CSV-Feeds entfernt. Die erste robots-Anweisung wird jetzt wirksam, und die erste CSV-Spaltenüberschrift beginnt nicht mehr mit `\ufeff`. Wenn Sie eigene `headers` festlegen, wird die Markierung stattdessen aus dem ersten Feldwert entfernt. Aktualisieren Sie Code, der dieses unsichtbare Präfix umgangen hat. XML-Kommentare und Verarbeitungsanweisungen in Sitemaps werden ebenfalls übersprungen, statt einen Parserfehler auszulösen.++### Prüfen Sie Formulardaten, Header und CLI-JSON {#check-form-data-headers-and-cli-json}++Bei Formulardaten in Dictionaries werden Listen- und Tupelwerte jetzt als wiederholte Schlüssel gesendet. Zum Beispiel sendet `data={"tag": ["a", "b"]}` die Daten `tag=a&tag=b`. Eine leere Liste sendet keinen Eintrag für diesen Schlüssel. Wenn Sie keinen eigenen Content-Type-Header angegeben haben, wird standardmäßig `Content-Type: application/x-www-form-urlencoded` hinzugefügt.++Wenn Sie ein anderes Übertragungsformat benötigen, übergeben Sie eine ausdrücklich kodierte Zeichenfolge oder Bytes. `json`, rohe `content`-Daten und Multipart-Uploads behalten ihre eigene Body-Verarbeitung. `None`-Werte werden **nicht entfernt**, weder aus Formulardaten noch aus Abfrageparametern. Sie bleiben als Zeichenfolge `None` erhalten.++HTTP-Header einzelner Anfragen überschreiben jetzt Sitzungs-Header unabhängig von der Groß- und Kleinschreibung. Ein Anfrage-Header namens `authorization` ersetzt den `Authorization`-Header der Sitzung, statt beide zu senden. Entfernen Sie Code, der doppelte Headernamen umgangen hat.++Die CLI-JSON-Werte `{}`, `[]`, `false`, `0` und `""` werden jetzt gesendet, statt ohne Hinweis ausgelassen zu werden. Außerdem übernimmt `curl2fetcher()` jetzt den User-Agent aus der curl-Option `-A` und übergibt Proxys aus `-x` korrekt als URL-Zeichenfolge. Ein ausdrücklich angegebener curl-Header `-H 'User-Agent: ...'` hat weiterhin Vorrang vor `-A`.++## Weitere Änderungen an der Ausgabe prüfen {#other-output-changes-to-check}++Diese Korrekturen entfernen keine APIs, können aber gespeicherte Ergebnisse und Tests mit exakten Ausgabevergleichen verändern:++- Erzeugte CSS- und XPath-Selektoren enthalten jetzt bei Bedarf `:nth-of-type(1)` oder `[1]`, um das erste von mehreren gleichnamigen Geschwisterelementen zu erkennen. Aktualisieren Sie erwartete Selektor-Zeichenfolgen. Entfernen Sie die neue Positionsangabe nicht.+- Bei der Bereinigung von KI-Inhalten bleiben jetzt sichtbare Elemente mit Werten wie `opacity:0.95` erhalten. Die Bereinigung erkennt mehr Varianten von Inline-Stilen zum Ausblenden und entfernt die betroffenen Elemente. Sie entfernt auch `<slot hidden>`-Elemente sowie alle passenden störenden Tags, selbst wenn diese verschachtelt sind. Prüfen Sie erneut die exakte Ausgabe von Markdown, Text und bereinigtem HTML.+- Die Umwandlung von Browserantworten liest jetzt charset-Angaben mit abweichender Groß- und Kleinschreibung, Leerzeichen oder Werten in Anführungszeichen, etwa `text/plain; CHARSET = "iso-8859-15"`. Antworten ohne HTML mit diesen Headern verwenden jetzt die angegebene Kodierung, statt auf UTF-8 zurückzufallen. Prüfen Sie den aus diesen Antworten dekodierten Text erneut.++## Prüfen Sie Ihre Aktualisierung {#verify-your-upgrade}++Führen Sie vor dem vollständigen Auftrag einen kleinen Crawl aus. Prüfen Sie die extrahierten Daten, die verfolgten URLs, die gesendeten Anfrage-Bodys, die Kodierung gespeicherter Dateien und das Verhalten von Cache und Checkpoints, auf das Sie angewiesen sind. Prüfen Sie bei MCP-Integrationen die Tool-Eingaben und die zurückgegebenen Daten anhand der aktuellen Schemas.++Änderungen älterer Versionen finden Sie im [Änderungsprotokoll](changelog.md).diff --git a/docs/locales/es/migrating-to-v0.5.md b/docs/locales/es/migrating-to-v0.5.mdnew file mode 100644index 0000000..b4c3497--- /dev/null+++ b/docs/locales/es/migrating-to-v0.5.md@@ -0,0 +1,293 @@+---+title: "Migrar a v0.5"+description: "Pasa de Scrapling v0.4.15 a v0.5. Actualiza las importaciones del navegador, la captura de red, las herramientas MCP, los comandos CLI, los ajustes del parser y el comportamiento de los spiders."+---++# Migrar a v0.5 {#migrating-to-v05}++Esta guía cubre los cambios que debes revisar al pasar de **v0.4.15 a v0.5**. Incluye API eliminadas, herramientas con nuevos nombres y correcciones que pueden cambiar los resultados del rastreo o los archivos guardados.++## Lista rápida de migración {#quick-migration-checklist}++| Si usas... | Qué cambiar |+| --- | --- |+| `DynamicFetcher`, `DynamicSession` o `AsyncDynamicSession` | Usa la clase de navegación sigilosa correspondiente. |+| `capture_xhr` o `response.captured_xhr` | Usa una sesión de navegador con `record_requests=True` y `session.network`. |+| `keep_cdata` | Elimínalo de los ajustes del parser y del fetcher. |+| `scrapling extract stealthy-fetch` o `stealthy_fetch()` del shell | Usa `fetch` en su lugar. |+| Herramientas MCP | Actualiza los nombres de las herramientas, las llamadas para hacer capturas de pantalla y el manejo de la respuesta al crear sesiones. |+| `response.follow()` después de un POST o una solicitud con parámetros de consulta | Vuelve a pasar el método, la consulta y el cuerpo cuando los necesites. |+| Puntos de control de rastreo o cachés de respuestas guardados | Inicia un rastreo nuevo si tus solicitudes usan los datos de entrada de la huella que han cambiado. |+| `robots_txt_obey=True` | Maneja los fallos al obtener robots.txt, que ahora bloquean el rastreo de ese dominio. |++## Obtención con navegador {#browser-fetching}++### Sustituye las clases de navegador dinámico {#replace-the-dynamic-browser-classes}++Se ha eliminado el motor de navegador que usaba Playwright directamente. Toda la obtención con navegador usa ahora el motor sigiloso basado en Patchright.++| API eliminada | Sustitución |+| --- | --- |+| `scrapling.DynamicFetcher` | `scrapling.StealthyFetcher` |+| `scrapling.fetchers.DynamicFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.chrome.PlayWrightFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.DynamicSession` | `scrapling.fetchers.StealthySession` |+| `scrapling.fetchers.AsyncDynamicSession` | `scrapling.fetchers.AsyncStealthySession` |++Se han eliminado el módulo `scrapling.fetchers.chrome` y el módulo privado `_browsers._controllers`. Usa las importaciones públicas de la tabla anterior.++**Antes:**++```python+from scrapling.fetchers import DynamicFetcher++page = DynamicFetcher.fetch("https://example.com", headless=True)+```++**Ahora:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", headless=True)+```++Para las sesiones, sustituye `DynamicSession` por `StealthySession`, o `AsyncDynamicSession` por `AsyncStealthySession`. Haz el mismo cambio en el método `configure_sessions()` de tu spider. Los patrones de uso de `fetch()` y `async with` siguen siendo válidos.++Si tus callbacks importan tipos del navegador o capturan errores del navegador, cambia `playwright.sync_api` por `patchright.sync_api`, o `playwright.async_api` por `patchright.async_api`. Esto incluye `Page`, `Locator`, `Error` y `TimeoutError`.++Patchright evalúa JavaScript en un contexto aislado de forma predeterminada. Si un callback lee las variables JavaScript de la propia página, usa `page.evaluate(..., isolated_context=False)`.++Esto cambia el comportamiento del navegador además del nombre de importación. Revisa las opciones del navegador y los ajustes de su huella. Resolver Cloudflare sigue requiriendo `solve_cloudflare=True`; no está activado de forma predeterminada. Además, `extra_flags` ahora añade opciones a las de sigilo integradas en vez de sustituirlas.++Consulta [Obtención con navegador](fetching/stealthy.md) para ver las opciones actuales.++### Sustituye la captura XHR por el historial de red de la sesión {#replace-xhr-capture-with-session-network-history}++Se han eliminado el parámetro `capture_xhr` y el atributo `Response.captured_xhr`. Elimina el parámetro aunque su valor sea `None`. Una obtención de un solo uso ya no adjunta una lista XHR a su respuesta.++Las integraciones personalizadas que llaman a `ResponseFactory.from_playwright_response()` o `ResponseFactory.from_async_playwright_response()` también deben eliminar `xhr_captured`. Pasa `collect_history` por nombre para evitar problemas con el cambio de orden de los argumentos posicionales.++**Antes:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", capture_xhr="/api/")+for response in page.captured_xhr:+ print(response.url, response.body)+```++**Ahora:**++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True) as session:+ page = session.fetch("https://example.com", network_idle=True)+ for response in session.network.search(url_pattern=r"/api/", limit=None):+ print(response.url, response.body)+```++Usa `AsyncStealthySession` y `await session.fetch(...)` para código asíncrono. Leer `session.network` no requiere `await`.++Hay algunas diferencias importantes:++- Establece `record_requests=True` al crear la sesión. Es un ajuste de la sesión, no de cada obtención.+- El historial pertenece a **toda la sesión**, incluidas las pestañas, las cargas de páginas y las acciones. Usa `after_id`, filtros o `session.network.clear()` si necesitas un alcance menor.+- Mueve la antigua expresión regular de `capture_xhr` a `url_pattern` al buscar en el historial.+- `search()` devuelve objetos `Response` guardados. Lee `.url`, `.status`, `.headers`, `.body` o `.json()` directamente. El ID de registro, el tipo de recurso y el cuerpo enviado están en `response.meta["network_id"]`, `response.meta["resource_type"]` y `response.meta["request_body"]`.+- El historial de Python incluye todos los tipos de recursos de forma predeterminada. Usa `resource_type="xhr"` o `resource_type="fetch"` para elegir uno, o `include_static=False` para solicitudes XHR/fetch y errores HTTP.+- `search()` devuelve un máximo de 100 coincidencias de forma predeterminada. Pasa `limit=None` para obtener todas las coincidencias guardadas. Las sesiones conservan hasta 1000 solicitudes de forma predeterminada; cambia este límite con `max_recorded_requests`.+- Solo se guardan las solicitudes completadas. La captura del cuerpo se limita a los tipos de contenido de texto admitidos, a 1 MiB por respuesta y a 20 MiB de datos de cuerpo guardados en total. Los registros más antiguos pueden eliminarse al alcanzar los límites. Consulta `response.meta.get("body_note")` para saber por qué se omitió un cuerpo.+- Al leer el historial o cerrar la sesión, no se espera a que terminen las capturas pendientes. Espera a los datos que necesitas antes de leerlos. El historial de Python guardado sigue disponible después de cerrar la sesión.++Consulta [Historial de red](fetching/stealthy.md#network-history) para ver los filtros y límites.++## Ajustes del parser {#parser-settings}++### Elimina `keep_cdata` {#remove-keep_cdata}++Se ha eliminado `keep_cdata` de `Selector`, de la configuración de los fetchers y de los ajustes que devuelve `display_config()`. Elimínalo de las llamadas directas al parser, de `Fetcher.configure(...)` y de los diccionarios `selector_config` que pases a fetchers o integraciones.++**Antes:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>", keep_cdata=True)+```++**Ahora:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>")+```++No hay ningún ajuste que lo sustituya. No afectaba al resultado del parser HTML. Si pasabas las opciones del parser por posición, elimina el antiguo argumento `keep_cdata` y usa nombres para `adaptive` y las opciones de almacenamiento.++## Línea de comandos y shell interactivo {#command-line-and-interactive-shell}++### Usa `fetch` para las solicitudes del navegador {#use-fetch-for-browser-requests}++La CLI tiene ahora un solo comando de navegador: `scrapling extract fetch`. Usa `StealthyFetcher`.++**Antes:**++```bash+scrapling extract stealthy-fetch "https://example.com" page.md+```++**Ahora:**++```bash+scrapling extract fetch "https://example.com" page.md+```++Si ya usas `scrapling extract fetch`, el nombre del comando no cambia, pero su motor pasa de `DynamicFetcher` a `StealthyFetcher`. Opciones como `--solve-cloudflare` pertenecen ahora a `fetch`.++En `scrapling shell`, sustituye `stealthy_fetch(...)` por `fetch(...)`. El atajo `fetch(...)` existente llama ahora a `StealthyFetcher.fetch`. Las clases dinámicas ya no se añaden al espacio de nombres del shell.++### Lee los archivos Markdown y de texto como UTF-8 {#read-markdown-and-text-files-as-utf-8}++Los comandos de extracción y `Convertor.write_content_to_file()` escriben ahora los archivos `.md` y `.txt` en **UTF-8**, sin importar el juego de caracteres de la página de origen. Actualiza cualquier código que lea esos archivos con la codificación original de la página. La salida `.html` sigue usando `page.encoding`.++El Markdown de varios elementos seleccionados tiene ahora líneas en blanco entre los elementos. Esto se aplica a `Response.markdown()` y a la salida en archivos Markdown. Actualiza las comparaciones exactas de la salida o los hashes guardados que dependían del texto concatenado.++## Servidor MCP {#mcp-server}++Actualiza los prompts guardados, las listas de herramientas permitidas, los wrappers y las definiciones de herramientas del cliente MCP. Reinicia o vuelve a conectar tu cliente MCP después de actualizar el servidor para que lea las herramientas actuales.++### Actualiza los nombres de herramientas y las llamadas en lote {#update-tool-names-and-bulk-calls}++| Herramienta de v0.4.15 | Sustitución en v0.5 |+| --- | --- |+| `fetch`, `stealthy_fetch` | `browser_fetch_once` |+| `open_session` | `browser_open` |+| `session_fetch` | `browser_fetch` |+| `screenshot` | `browser_screenshot` |+| `bulk_fetch`, `bulk_stealthy_fetch` | Una llamada a `browser_fetch_once` por URL, o varias llamadas a `browser_fetch` a través de una sesión abierta |+| `bulk_get` | Una llamada a `make_request` o `session_make_request` por URL |++Se han eliminado todas las herramientas en lote. Las herramientas que obtienen una sola URL devuelven un único `ResponseModel` con `status`, `content` y `url`, no una lista de respuestas. `content` sigue siendo una lista de cadenas.++Todas las herramientas de navegador MCP usan ahora el motor sigiloso. Elimina `session_type` de las llamadas a `browser_open`; ya no existe la opción de navegador dinámico. Su resultado contiene `session_type="stealthy"`. Las sesiones HTTP siguen usando `open_request_session` y devuelven `session_type="static"`.++Las integraciones de Python también deben dejar de importar `BrowserSessionType`, que se ha eliminado. `SessionType` solo acepta ahora `"stealthy"` y `"static"`.++Las llamadas a través de una misma sesión de navegador deben ejecutarse en orden porque comparten una página. Cierra las sesiones con `close_session` cuando termines.++### Lee los ajustes mediante `list_sessions` {#read-settings-through-list_sessions}++`browser_open` y `open_request_session` ahora solo devuelven:++```json+{+ "session_id": "my-session",+ "session_type": "stealthy"+}+```++El resultado de la creación ya no incluye `created_at`, `is_alive`, `settings` ni `message`. Llama a `list_sessions` para obtener los tres primeros campos. Se ha eliminado el `message` de confirmación. También debes cambiar el código que asumía que `SessionCreatedModel` tenía todos los campos de `SessionInfo`.++### Obtén la página antes de hacer una captura de pantalla {#fetch-before-taking-a-screenshot}++`browser_screenshot` captura la **página actual sin volver a cargarla**. Ya no acepta una URL ni las antiguas opciones de navegación y espera: `wait`, `wait_selector`, `wait_selector_state` y `network_idle`.++Sigue este orden:++1. Llama a `browser_open`.+2. Llama a `browser_fetch` con la URL y las opciones de carga de la página que necesites.+3. Si hace falta, llama a `browser_actions` para interactuar con la página o esperar al contenido.+4. Llama a `browser_screenshot` con el ID de sesión.+5. Llama a `close_session` cuando termines.++Por ejemplo, los argumentos para una captura de toda la página son:++```json+{+ "session_id": "my-session",+ "full_page": true+}+```++El `timeout` de esta herramienta limita ahora la operación de captura de pantalla. La herramienta no carga ninguna página. Para capturar un elemento, usa `selector` o `ref` y no establezcas `full_page=true`.++Las capturas de pantalla siguen devolviendo bloques de contenido de imagen y texto, con la URL de la página actual en el bloque de texto. No devuelven un `ResponseModel` de obtención.++Consulta la [guía MCP](ai/mcp-server.md) y la [referencia de la API](api-reference/mcp-server.md) para ver los esquemas completos.++## Spiders y solicitudes HTTP {#spiders-and-http-requests}++### Vuelve a pasar los datos de la solicitud al seguir un enlace {#pass-request-data-again-when-following-a-link}++`response.follow()` ya no copia `method`, `params`, `data`, `json`, `files` ni `multipart` de la solicitud anterior. También elimina los encabezados `Content-Length` heredados de `headers` y `extra_headers`.++Un enlace que sigues empieza ahora como una solicitud GET normal, salvo que pases los datos de la solicitud de forma explícita. Otros ajustes compartidos, como la sesión, el proxy y los callbacks, siguen las reglas de herencia existentes.++Si tu código anterior dependía de los datos POST heredados, cambia:++```python+yield response.follow("/next")+```++por:++```python+yield response.follow("/next", method="POST", json={"page": 2})+```++Pasa también `params` de forma explícita cuando la siguiente solicitud los necesite. Deja que el cliente HTTP calcule el nuevo `Content-Length`.++### Revisa las huellas de las solicitudes y el estado de rastreo guardado {#check-request-fingerprints-and-saved-crawl-state}++La huella de una solicitud es la clave que se usa para detectar solicitudes duplicadas y encontrar respuestas en caché. Sus datos de entrada ahora manejan tres casos de forma distinta:++- Los `params` se combinan con la URL antes de crear la clave. Las solicitudes a la misma URL con distintos parámetros de consulta ya no se consideran duplicadas de forma predeterminada.+- Los cuerpos JSON como `{}`, `[]`, `false`, `0` y `""` se conservan en la clave. Ya no comparten la clave de un cuerpo ausente. `None` sigue indicando que no hay cuerpo JSON.+- Con `fp_include_headers=True`, cambiar solo el orden de inserción de los encabezados ya no cambia la clave.++Si tu rastreo usa estos datos de entrada, termínalo antes de actualizar o inicia un rastreo nuevo con un nuevo punto de control y un nuevo directorio de caché de respuestas. Las claves guardadas anteriormente pueden ser distintas de las nuevas. Este es un cambio en la identidad de las solicitudes, no un formato nuevo para los archivos de puntos de control.++El modo de desarrollo ahora solo escribe las respuestas en la caché después de comprobar si están bloqueadas. Las páginas bloqueadas no se guardan como resultados correctos en caché. Los archivos de caché existentes no se limpian automáticamente; borra las entradas antiguas si antes guardaste una página de verificación.++Los rastreos fallidos conservan ahora sus archivos de puntos de control. Revisa tu código de limpieza si asumía que esos archivos desaparecían después de un error. Consulta [Pausar y reanudar](spiders/advanced.md#pause-resume) y [Modo de desarrollo](spiders/advanced.md#development-mode).++### Revisa los fallos de robots.txt {#check-robotstxt-failures}++Con `robots_txt_obey=True`, una excepción al obtener robots.txt o una respuesta distinta de HTTP 200 o 4xx ahora bloquea las solicitudes a ese dominio. Antes, esos fallos permitían el rastreo. HTTP 200 sigue proporcionando las reglas y HTTP 4xx sigue permitiendo el acceso.++El resultado se guarda en caché durante todo el rastreo. Soluciona el problema de acceso a robots.txt e inicia un rastreo nuevo; las solicitudes posteriores del mismo rastreo no volverán a intentar la consulta fallida. Esto no cambia el valor predeterminado `robots_txt_obey=False`.++### Revisa las restricciones de enlaces y los callbacks de sitemaps {#check-link-restrictions-and-sitemap-callbacks}++- Una restricción de `LinkExtractor` que no coincide con nada ahora no devuelve enlaces. Ya no recurre a la página completa. Corrige la expresión `restrict_css` o `restrict_xpath` si tu rastreo encuentra ahora menos enlaces.+- Una restricción ahora puede seleccionar el propio elemento del enlace, no solo un elemento padre. Esto puede añadir enlaces que antes se omitían. Revisa los conjuntos de URL esperados.+- `SitemapSpider` envía ahora las URL de las páginas a `parse()` cuando no hay reglas o cuando una regla coincidente tiene `callback=None`. Ya no vuelve a enviar esas páginas HTML al parser del sitemap. Implementa `parse()` para esos casos y elimina las soluciones alternativas para el enrutamiento anterior.+- Se elimina la marca de orden de bytes Unicode al principio de robots.txt y de las fuentes CSV. La primera directiva de robots ahora tiene efecto y el primer encabezado CSV ya no empieza con `\ufeff`. Si defines `headers` personalizados, la marca se elimina del valor del primer campo en su lugar. Actualiza el código que compensaba ese prefijo oculto. Los comentarios XML y las instrucciones de procesamiento de los sitemaps también se omiten en lugar de provocar un fallo de análisis.++### Revisa los datos de formularios, los encabezados y el JSON de la CLI {#check-form-data-headers-and-cli-json}++Los datos de formularios en diccionarios expanden ahora los valores de listas y tuplas en claves repetidas. Por ejemplo, `data={"tag": ["a", "b"]}` envía `tag=a&tag=b`. Una lista vacía no envía ninguna entrada para esa clave. Se añade el encabezado predeterminado `Content-Type: application/x-www-form-urlencoded` si no has proporcionado uno.++Si necesitas otro formato de envío, pasa una cadena o bytes codificados de forma explícita. `json`, el `content` sin procesar y las cargas multipart mantienen su propio manejo del cuerpo. Los valores `None` **no se eliminan** de los datos del formulario ni de los parámetros de consulta; se conservan como la cadena `None`.++Los encabezados HTTP de cada solicitud ahora sustituyen a los de la sesión sin distinguir entre mayúsculas y minúsculas. Un encabezado de solicitud llamado `authorization` sustituye al `Authorization` de la sesión en vez de enviar ambos. Elimina el código que compensaba los nombres de encabezados duplicados.++Los valores JSON de la CLI `{}`, `[]`, `false`, `0` y `""` ahora se envían en vez de omitirse sin aviso. Además, `curl2fetcher()` aplica ahora el agente de usuario de `-A` de curl y pasa correctamente los proxies de `-x` como una cadena URL. Un encabezado explícito `-H 'User-Agent: ...'` de curl sigue teniendo prioridad sobre `-A`.++## Otros cambios en la salida que debes revisar {#other-output-changes-to-check}++Estas correcciones no eliminan API, pero pueden cambiar los resultados guardados y las pruebas de salida exacta:++- Los selectores CSS y XPath generados ahora incluyen `:nth-of-type(1)` o `[1]` cuando es necesario para identificar al primero de varios elementos hermanos con la misma etiqueta. Actualiza las cadenas de selectores esperadas; no elimines la nueva marca de posición.+- El contenido limpiado para IA ahora conserva los elementos visibles con valores como `opacity:0.95`, elimina elementos ocultos por más variantes de estilos en línea y los elementos `<slot hidden>`, y elimina todas las etiquetas de ruido coincidentes aunque estén anidadas. Vuelve a comprobar la salida exacta de Markdown, texto y HTML saneado.+- La conversión de respuestas del navegador ahora lee declaraciones de charset con distintas mayúsculas y minúsculas, espacios o valores entre comillas, como `text/plain; CHARSET = "iso-8859-15"`. Las respuestas que no son HTML y tienen estos encabezados ahora usan la codificación declarada en vez de recurrir a UTF-8. Vuelve a comprobar el texto decodificado de esas respuestas.++## Verifica la actualización {#verify-your-upgrade}++Ejecuta un rastreo pequeño antes del trabajo completo. Comprueba los datos extraídos, las URL seguidas, los cuerpos de las solicitudes enviadas, la codificación de los archivos guardados y el comportamiento de la caché o de los puntos de control del que dependas. Para las integraciones MCP, comprueba los datos de entrada de las herramientas y los datos devueltos con los esquemas actuales.++Para los cambios de versiones anteriores, consulta el [registro de cambios](changelog.md).diff --git a/docs/locales/fr/migrating-to-v0.5.md b/docs/locales/fr/migrating-to-v0.5.mdnew file mode 100644index 0000000..01ba27a--- /dev/null+++ b/docs/locales/fr/migrating-to-v0.5.md@@ -0,0 +1,293 @@+---+title: "Migrer vers la v0.5"+description: "Passez de Scrapling v0.4.15 à la v0.5. Mettez à jour les imports du navigateur, la capture réseau, les outils MCP, les commandes CLI, les réglages de l’analyseur et le comportement des spiders."+---++# Migrer vers la v0.5 {#migrating-to-v05}++Ce guide présente les changements à vérifier lors du passage de la **v0.4.15 à la v0.5**. Il couvre les API supprimées, les outils renommés et les corrections qui peuvent modifier les résultats de votre exploration ou vos fichiers enregistrés.++## Liste rapide de migration {#quick-migration-checklist}++| Si vous utilisez... | Ce qu’il faut changer |+| --- | --- |+| `DynamicFetcher`, `DynamicSession` ou `AsyncDynamicSession` | Utilisez la classe furtive correspondante. |+| `capture_xhr` ou `response.captured_xhr` | Utilisez une session de navigateur avec `record_requests=True` et `session.network`. |+| `keep_cdata` | Supprimez-le des réglages de l’analyseur et du fetcher. |+| `scrapling extract stealthy-fetch` ou `stealthy_fetch()` dans le shell | Utilisez `fetch` à la place. |+| Les outils MCP | Mettez à jour les noms des outils, les appels de capture d’écran et le traitement de la réponse de création de session. |+| `response.follow()` après un POST ou une requête avec des paramètres de requête | Transmettez à nouveau la méthode, les paramètres de requête et le corps quand vous en avez besoin. |+| Des points de reprise d’exploration ou des caches de réponses enregistrés | Démarrez une nouvelle exploration si vos requêtes utilisent les données d’entrée de l’empreinte qui ont changé. |+| `robots_txt_obey=True` | Gérez les échecs de récupération de robots.txt, qui bloquent maintenant l’exploration de ce domaine. |++## Récupération avec un navigateur {#browser-fetching}++### Remplacez les classes de navigateur dynamique {#replace-the-dynamic-browser-classes}++Le moteur de navigateur qui utilisait directement Playwright a été supprimé. Toute récupération avec un navigateur utilise maintenant le moteur furtif basé sur Patchright.++| API supprimée | Remplacement |+| --- | --- |+| `scrapling.DynamicFetcher` | `scrapling.StealthyFetcher` |+| `scrapling.fetchers.DynamicFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.chrome.PlayWrightFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.DynamicSession` | `scrapling.fetchers.StealthySession` |+| `scrapling.fetchers.AsyncDynamicSession` | `scrapling.fetchers.AsyncStealthySession` |++Le module `scrapling.fetchers.chrome` et le module privé `_browsers._controllers` ont été supprimés. Utilisez les imports publics ci-dessus.++**Avant :**++```python+from scrapling.fetchers import DynamicFetcher++page = DynamicFetcher.fetch("https://example.com", headless=True)+```++**Maintenant :**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", headless=True)+```++Pour les sessions, remplacez `DynamicSession` par `StealthySession`, ou `AsyncDynamicSession` par `AsyncStealthySession`. Faites le même changement dans la méthode `configure_sessions()` de votre spider. Les modes d’utilisation de `fetch()` et de `async with` restent valables.++Si vos callbacks importent des types du navigateur ou interceptent ses erreurs, remplacez `playwright.sync_api` par `patchright.sync_api`, ou `playwright.async_api` par `patchright.async_api`. Cela concerne notamment `Page`, `Locator`, `Error` et `TimeoutError`.++Patchright évalue le JavaScript dans un contexte isolé par défaut. Si un callback lit les variables JavaScript propres à la page, utilisez `page.evaluate(..., isolated_context=False)`.++Le comportement du navigateur change en plus du nom de l’import. Vérifiez les options du navigateur et les réglages de son empreinte. La résolution de Cloudflare nécessite toujours `solve_cloudflare=True` ; elle n’est pas activée par défaut. De plus, `extra_flags` complète maintenant les options furtives intégrées au lieu de les remplacer.++Consultez [Récupération avec un navigateur](fetching/stealthy.md) pour connaître les options actuelles.++### Remplacez la capture XHR par l’historique réseau de la session {#replace-xhr-capture-with-session-network-history}++Le paramètre `capture_xhr` et l’attribut `Response.captured_xhr` ont été supprimés. Supprimez le paramètre même si sa valeur est `None`. Une récupération ponctuelle n’ajoute plus de liste XHR à sa réponse.++Les intégrations personnalisées qui appellent `ResponseFactory.from_playwright_response()` ou `ResponseFactory.from_async_playwright_response()` doivent aussi supprimer `xhr_captured`. Transmettez `collect_history` par son nom pour éviter les problèmes liés au changement d’ordre des arguments positionnels.++**Avant :**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", capture_xhr="/api/")+for response in page.captured_xhr:+ print(response.url, response.body)+```++**Maintenant :**++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True) as session:+ page = session.fetch("https://example.com", network_idle=True)+ for response in session.network.search(url_pattern=r"/api/", limit=None):+ print(response.url, response.body)+```++Utilisez `AsyncStealthySession` et `await session.fetch(...)` pour le code asynchrone. Lire `session.network` ne nécessite pas `await`.++Voici quelques différences importantes :++- Définissez `record_requests=True` lors de la création de la session. C’est un réglage de session, pas un réglage par récupération.+- L’historique appartient à **toute la session**, y compris les onglets, les chargements de pages et les actions. Utilisez `after_id`, des filtres ou `session.network.clear()` si vous avez besoin d’un périmètre plus réduit.+- Déplacez l’ancienne expression régulière de `capture_xhr` vers `url_pattern` lors des recherches dans l’historique.+- `search()` renvoie des objets `Response` enregistrés. Lisez directement `.url`, `.status`, `.headers`, `.body` ou `.json()`. L’identifiant d’enregistrement, le type de ressource et le corps envoyé sont dans `response.meta["network_id"]`, `response.meta["resource_type"]` et `response.meta["request_body"]`.+- L’historique Python inclut tous les types de ressources par défaut. Utilisez `resource_type="xhr"` ou `resource_type="fetch"` pour en choisir un, ou `include_static=False` pour les requêtes XHR/fetch et les erreurs HTTP.+- `search()` renvoie au maximum 100 résultats par défaut. Transmettez `limit=None` pour obtenir tous les résultats conservés. Les sessions conservent au maximum 1 000 requêtes par défaut ; modifiez cette limite avec `max_recorded_requests`.+- Seules les requêtes terminées sont enregistrées. La capture du corps se limite aux types de contenu textuel pris en charge, à 1 MiB par réponse et à 20 MiB de données de corps conservées au total. Les anciens enregistrements peuvent être supprimés lorsque les limites sont atteintes. Consultez `response.meta.get("body_note")` pour savoir pourquoi un corps a été ignoré.+- La lecture de l’historique et la fermeture de la session n’attendent pas la fin des captures en cours. Attendez les données dont vous avez besoin avant de les lire. L’historique Python enregistré reste lisible après la fermeture de la session.++Consultez [Historique réseau](fetching/stealthy.md#network-history) pour connaître les filtres et les limites.++## Réglages de l’analyseur {#parser-settings}++### Supprimez `keep_cdata` {#remove-keep_cdata}++`keep_cdata` a été supprimé de `Selector`, de la configuration des fetchers et des réglages renvoyés par `display_config()`. Supprimez-le des appels directs à l’analyseur, de `Fetcher.configure(...)` et des dictionnaires `selector_config` transmis aux fetchers ou aux intégrations.++**Avant :**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>", keep_cdata=True)+```++**Maintenant :**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>")+```++Il n’existe pas de réglage de remplacement. Ce réglage n’affectait pas la sortie de l’analyseur HTML. Si vous transmettiez les options de l’analyseur par position, supprimez l’ancien argument `keep_cdata` et utilisez des arguments nommés pour `adaptive` et les options de stockage.++## Ligne de commande et shell interactif {#command-line-and-interactive-shell}++### Utilisez `fetch` pour les requêtes du navigateur {#use-fetch-for-browser-requests}++La CLI n’a plus qu’une commande de navigateur : `scrapling extract fetch`. Elle utilise `StealthyFetcher`.++**Avant :**++```bash+scrapling extract stealthy-fetch "https://example.com" page.md+```++**Maintenant :**++```bash+scrapling extract fetch "https://example.com" page.md+```++Si vous utilisez déjà `scrapling extract fetch`, le nom de la commande reste le même, mais son moteur passe de `DynamicFetcher` à `StealthyFetcher`. Les options telles que `--solve-cloudflare` appartiennent maintenant à `fetch`.++Dans `scrapling shell`, remplacez `stealthy_fetch(...)` par `fetch(...)`. Le raccourci existant `fetch(...)` appelle maintenant `StealthyFetcher.fetch`. Les classes dynamiques ne sont plus ajoutées à l’espace de noms du shell.++### Lisez les fichiers Markdown et texte en UTF-8 {#read-markdown-and-text-files-as-utf-8}++Les commandes d’extraction et `Convertor.write_content_to_file()` écrivent maintenant les fichiers `.md` et `.txt` en **UTF-8**, quel que soit le jeu de caractères de la page source. Mettez à jour le code qui lit ces fichiers avec l’encodage d’origine de la page. La sortie `.html` utilise toujours `page.encoding`.++Le Markdown provenant de plusieurs éléments sélectionnés comporte maintenant des lignes vides entre les éléments. Cela s’applique à `Response.markdown()` et aux fichiers Markdown produits. Mettez à jour les comparaisons exactes de la sortie ou les empreintes de hachage enregistrées qui dépendaient du texte concaténé.++## Serveur MCP {#mcp-server}++Mettez à jour les prompts enregistrés, les listes d’outils autorisés, les wrappers et les définitions d’outils du client MCP. Redémarrez ou reconnectez votre client MCP après la mise à jour du serveur pour qu’il lise les outils actuels.++### Mettez à jour les noms d’outils et les appels par lot {#update-tool-names-and-bulk-calls}++| Outil de la v0.4.15 | Remplacement dans la v0.5 |+| --- | --- |+| `fetch`, `stealthy_fetch` | `browser_fetch_once` |+| `open_session` | `browser_open` |+| `session_fetch` | `browser_fetch` |+| `screenshot` | `browser_screenshot` |+| `bulk_fetch`, `bulk_stealthy_fetch` | Un appel à `browser_fetch_once` par URL, ou plusieurs appels à `browser_fetch` dans une session ouverte |+| `bulk_get` | Un appel à `make_request` ou à `session_make_request` par URL |++Tous les outils par lot ont été supprimés. Les outils qui récupèrent une seule URL renvoient un seul `ResponseModel` avec `status`, `content` et `url`, pas une liste de réponses. `content` reste lui-même une liste de chaînes.++Tous les outils de navigateur MCP utilisent maintenant le moteur furtif. Supprimez `session_type` des appels à `browser_open` ; le navigateur dynamique n’est plus proposé. Le résultat contient `session_type="stealthy"`. Les sessions HTTP utilisent toujours `open_request_session` et renvoient `session_type="static"`.++Les intégrations Python doivent aussi cesser d’importer `BrowserSessionType`, qui a été supprimé. `SessionType` n’accepte maintenant que `"stealthy"` et `"static"`.++Les appels dans une même session de navigateur doivent s’exécuter dans l’ordre, car ils partagent une page. Fermez les sessions avec `close_session` quand vous avez terminé.++### Lisez les réglages avec `list_sessions` {#read-settings-through-list_sessions}++`browser_open` et `open_request_session` renvoient maintenant uniquement :++```json+{+ "session_id": "my-session",+ "session_type": "stealthy"+}+```++Le résultat de création n’inclut plus `created_at`, `is_alive`, `settings` ni `message`. Appelez `list_sessions` pour obtenir les trois premiers champs. Le `message` de confirmation a été supprimé. Le code qui supposait que `SessionCreatedModel` possédait tous les champs de `SessionInfo` doit aussi changer.++### Récupérez la page avant de faire une capture d’écran {#fetch-before-taking-a-screenshot}++`browser_screenshot` capture la **page actuelle sans la recharger**. Cet outil n’accepte plus d’URL ni les anciennes options de navigation et d’attente : `wait`, `wait_selector`, `wait_selector_state` et `network_idle`.++Suivez cet ordre :++1. Appelez `browser_open`.+2. Appelez `browser_fetch` avec l’URL et les options de chargement de page nécessaires.+3. Si nécessaire, appelez `browser_actions` pour interagir avec la page ou attendre du contenu.+4. Appelez `browser_screenshot` avec l’identifiant de session.+5. Appelez `close_session` quand vous avez terminé.++Par exemple, les arguments pour une capture de la page entière sont :++```json+{+ "session_id": "my-session",+ "full_page": true+}+```++Le `timeout` de cet outil limite maintenant l’opération de capture d’écran. L’outil ne charge pas de page. Pour capturer un élément, utilisez `selector` ou `ref`, et ne définissez pas `full_page=true`.++Les captures d’écran renvoient toujours des blocs de contenu image et texte, avec l’URL de la page actuelle dans le bloc texte. Elles ne renvoient pas de `ResponseModel` de récupération.++Consultez le [guide MCP](ai/mcp-server.md) et la [référence de l’API](api-reference/mcp-server.md) pour connaître les schémas complets.++## Spiders et requêtes HTTP {#spiders-and-http-requests}++### Transmettez à nouveau les données de requête quand vous suivez un lien {#pass-request-data-again-when-following-a-link}++`response.follow()` ne copie plus `method`, `params`, `data`, `json`, `files` ni `multipart` depuis la requête précédente. Cette méthode supprime aussi les en-têtes `Content-Length` hérités de `headers` et `extra_headers`.++Un lien suivi commence maintenant par une simple requête GET, sauf si vous transmettez explicitement les données de requête. Les autres réglages partagés, comme la session, le proxy et les callbacks, suivent toujours les règles d’héritage existantes.++Si votre ancien code dépendait de données POST héritées, remplacez :++```python+yield response.follow("/next")+```++par :++```python+yield response.follow("/next", method="POST", json={"page": 2})+```++Transmettez aussi explicitement `params` lorsque la requête suivante en a besoin. Laissez le client HTTP calculer le nouveau `Content-Length`.++### Vérifiez les empreintes des requêtes et l’état d’exploration enregistré {#check-request-fingerprints-and-saved-crawl-state}++L’empreinte d’une requête est la clé utilisée pour détecter les doublons et trouver les réponses en cache. Ses données d’entrée traitent maintenant trois cas différemment :++- Les `params` sont fusionnés avec l’URL avant la création de la clé. Les requêtes vers la même URL avec des paramètres de requête différents ne sont plus considérées comme des doublons par défaut.+- Les corps JSON tels que `{}`, `[]`, `false`, `0` et `""` sont conservés dans la clé. Ils ne partagent plus la clé d’un corps absent. `None` signifie toujours qu’il n’y a pas de corps JSON.+- Avec `fp_include_headers=True`, changer uniquement l’ordre d’insertion des en-têtes ne change plus la clé.++Si votre exploration utilise ces données d’entrée, terminez-la avant la mise à jour ou démarrez une nouvelle exploration avec un nouveau point de reprise et un nouveau répertoire de cache de réponses. Les anciennes clés enregistrées peuvent différer des nouvelles. Il s’agit d’un changement d’identité des requêtes, pas d’un nouveau format de fichier de point de reprise.++Le mode développement n’écrit maintenant les réponses dans le cache qu’après avoir vérifié si elles sont bloquées. Les pages bloquées ne sont pas enregistrées comme des résultats réussis dans le cache. Les fichiers de cache existants ne sont pas nettoyés automatiquement ; supprimez les entrées obsolètes si vous avez déjà mis en cache une page de vérification.++Les explorations qui échouent conservent maintenant leurs fichiers de points de reprise. Vérifiez votre code de nettoyage s’il supposait que ces fichiers disparaissaient après une erreur. Consultez [Pause et reprise](spiders/advanced.md#pause-resume) et [Mode développement](spiders/advanced.md#development-mode).++### Vérifiez les échecs de robots.txt {#check-robotstxt-failures}++Avec `robots_txt_obey=True`, une exception lors de la récupération de robots.txt ou une réponse autre que HTTP 200 ou 4xx bloque maintenant les requêtes vers ce domaine. Auparavant, ces échecs autorisaient l’exploration. HTTP 200 fournit toujours les règles, et HTTP 4xx autorise toujours l’accès.++Le résultat est mis en cache pour toute l’exploration. Corrigez le problème d’accès à robots.txt et démarrez une nouvelle exploration ; les requêtes suivantes de la même exploration ne réessaieront pas la récupération qui a échoué. Cela ne change pas la valeur par défaut `robots_txt_obey=False`.++### Vérifiez les restrictions de liens et les callbacks de sitemaps {#check-link-restrictions-and-sitemap-callbacks}++- Une restriction de `LinkExtractor` qui ne correspond à rien ne renvoie maintenant aucun lien. Elle ne revient plus à la page entière. Corrigez l’expression `restrict_css` ou `restrict_xpath` si votre exploration trouve maintenant moins de liens.+- Une restriction peut maintenant sélectionner l’élément du lien lui-même, pas seulement un parent. Cela peut ajouter des liens qui étaient ignorés auparavant. Vérifiez les ensembles d’URL attendus.+- `SitemapSpider` envoie maintenant les URL des pages à `parse()` lorsqu’il n’y a pas de règles, ou lorsqu’une règle correspondante a `callback=None`. Il ne renvoie plus ces pages HTML à l’analyseur de sitemap. Implémentez `parse()` pour ces cas et supprimez les contournements de l’ancien routage.+- La marque d’ordre des octets Unicode en début de robots.txt et des flux CSV est supprimée. La première directive robots prend maintenant effet, et le premier en-tête CSV ne commence plus par `\ufeff`. Si vous définissez des `headers` personnalisés, la marque est supprimée de la valeur du premier champ à la place. Mettez à jour le code qui contournait ce préfixe invisible. Les commentaires XML et les instructions de traitement des sitemaps sont aussi ignorés au lieu de provoquer un échec de l’analyse.++### Vérifiez les données de formulaire, les en-têtes et le JSON de la CLI {#check-form-data-headers-and-cli-json}++Les données de formulaire sous forme de dictionnaire développent maintenant les valeurs de listes et de tuples en clés répétées. Par exemple, `data={"tag": ["a", "b"]}` envoie `tag=a&tag=b`. Une liste vide n’envoie aucune entrée pour cette clé. L’en-tête par défaut `Content-Type: application/x-www-form-urlencoded` est ajouté lorsque vous n’en fournissez pas.++Si vous avez besoin d’un autre format d’envoi, transmettez une chaîne ou des octets explicitement encodés. `json`, le `content` brut et les envois multipart conservent leur propre traitement du corps. Les valeurs `None` **ne sont pas supprimées** des données de formulaire ni des paramètres de requête ; elles restent la chaîne `None`.++Les en-têtes HTTP de chaque requête remplacent maintenant ceux de la session sans distinguer les majuscules des minuscules. Un en-tête de requête nommé `authorization` remplace l’`Authorization` de la session au lieu d’envoyer les deux. Supprimez le code qui contournait les noms d’en-têtes en double.++Les valeurs JSON de la CLI `{}`, `[]`, `false`, `0` et `""` sont maintenant envoyées au lieu d’être ignorées sans avertissement. De plus, `curl2fetcher()` applique maintenant l’agent utilisateur de l’option `-A` de curl et transmet correctement les proxies de `-x` sous forme de chaîne URL. Un en-tête curl explicite `-H 'User-Agent: ...'` reste prioritaire sur `-A`.++## Autres changements de sortie à vérifier {#other-output-changes-to-check}++Ces corrections ne suppriment pas d’API, mais elles peuvent modifier les résultats enregistrés et les tests de sortie exacte :++- Les sélecteurs CSS et XPath générés incluent maintenant `:nth-of-type(1)` ou `[1]` lorsque c’est nécessaire pour identifier le premier de plusieurs éléments frères de même balise. Mettez à jour les chaînes de sélecteurs attendues ; ne supprimez pas le nouveau repère de position.+- Le contenu nettoyé pour l’IA conserve maintenant les éléments visibles avec des valeurs comme `opacity:0.95`, supprime les éléments masqués par davantage de variantes de styles en ligne et les éléments `<slot hidden>`, et supprime toutes les balises parasites correspondantes, même imbriquées. Vérifiez à nouveau la sortie exacte en Markdown, en texte et en HTML assaini.+- La conversion des réponses du navigateur lit maintenant les déclarations de charset avec des différences de majuscules et de minuscules, des espaces ou des valeurs entre guillemets, comme `text/plain; CHARSET = "iso-8859-15"`. Les réponses non HTML avec ces en-têtes utilisent maintenant l’encodage déclaré au lieu de se rabattre sur UTF-8. Vérifiez à nouveau le texte décodé à partir de ces réponses.++## Vérifiez la mise à jour {#verify-your-upgrade}++Exécutez une petite exploration avant votre tâche complète. Vérifiez les données extraites, les URL suivies, les corps des requêtes envoyées, l’encodage des fichiers enregistrés et les comportements du cache ou des points de reprise dont vous dépendez. Pour les intégrations MCP, vérifiez les données d’entrée des outils et les données renvoyées par rapport aux schémas actuels.++Pour les changements des versions précédentes, consultez le [journal des modifications](changelog.md).diff --git a/docs/locales/ja/migrating-to-v0.5.md b/docs/locales/ja/migrating-to-v0.5.mdnew file mode 100644index 0000000..44de099--- /dev/null+++ b/docs/locales/ja/migrating-to-v0.5.md@@ -0,0 +1,293 @@+---+title: "v0.5 への移行"+description: "Scrapling v0.4.15 から v0.5 に移行します。ブラウザのインポート、ネットワーク記録、MCP ツール、CLI コマンド、パーサーの設定、Spider の動作を更新します。"+---++# v0.5 への移行 {#migrating-to-v05}++このガイドでは、**v0.4.15 から v0.5** に移行するときに確認すべき変更を説明します。削除された API、名前が変わったツール、クロール結果や保存ファイルに影響する修正を扱います。++## 移行チェックリスト {#quick-migration-checklist}++| 使用しているもの | 必要な変更 |+| --- | --- |+| `DynamicFetcher`、`DynamicSession`、`AsyncDynamicSession` | 対応するステルスクラスを使います。 |+| `capture_xhr` または `response.captured_xhr` | `record_requests=True` を設定したブラウザセッションと `session.network` を使います。 |+| `keep_cdata` | パーサーと Fetcher の設定から削除します。 |+| `scrapling extract stealthy-fetch` またはシェルの `stealthy_fetch()` | 代わりに `fetch` を使います。 |+| MCP ツール | ツール名、スクリーンショットの呼び出し、セッション作成時のレスポンス処理を更新します。 |+| POST またはクエリパラメーター付きリクエストの後の `response.follow()` | 必要な場合は、メソッド、クエリ、ボディを再度渡します。 |+| 保存済みのクロールチェックポイントやレスポンスキャッシュ | リクエストが変更されたフィンガープリント入力を使う場合は、新しいクロールを始めます。 |+| `robots_txt_obey=True` | robots.txt の取得失敗に対応します。取得に失敗すると、そのドメインのクロールがブロックされるようになりました。 |++## ブラウザでの取得 {#browser-fetching}++### 動的ブラウザクラスを置き換える {#replace-the-dynamic-browser-classes}++Playwright を直接使うブラウザバックエンドは削除されました。ブラウザによる取得はすべて、Patchright ベースのステルスバックエンドを使うようになりました。++| 削除された API | 代わりに使う API |+| --- | --- |+| `scrapling.DynamicFetcher` | `scrapling.StealthyFetcher` |+| `scrapling.fetchers.DynamicFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.chrome.PlayWrightFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.DynamicSession` | `scrapling.fetchers.StealthySession` |+| `scrapling.fetchers.AsyncDynamicSession` | `scrapling.fetchers.AsyncStealthySession` |++`scrapling.fetchers.chrome` モジュールと非公開の `_browsers._controllers` モジュールは削除されました。上の公開インポートを使ってください。++**変更前:**++```python+from scrapling.fetchers import DynamicFetcher++page = DynamicFetcher.fetch("https://example.com", headless=True)+```++**変更後:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", headless=True)+```++セッションでは、`DynamicSession` を `StealthySession` に、または `AsyncDynamicSession` を `AsyncStealthySession` に置き換えます。Spider の `configure_sessions()` メソッドでも同じ変更を行ってください。`fetch()` と `async with` の使い方は引き続き有効です。++コールバックでブラウザの型をインポートしたり、ブラウザのエラーを捕捉したりする場合は、`playwright.sync_api` を `patchright.sync_api` に、または `playwright.async_api` を `patchright.async_api` に変えてください。対象には `Page`、`Locator`、`Error`、`TimeoutError` が含まれます。++Patchright はデフォルトで、分離されたコンテキスト内で JavaScript を評価します。コールバックがページ自身の JavaScript 変数を読む場合は、`page.evaluate(..., isolated_context=False)` を使ってください。++インポート名だけでなく、ブラウザの動作も変わります。ブラウザのフラグとフィンガープリントの設定を確認してください。Cloudflare の解決には引き続き `solve_cloudflare=True` が必要で、デフォルトでは有効になりません。また、`extra_flags` は組み込みのステルスフラグを置き換えず、追加するようになりました。++現在のオプションは[ブラウザでの取得](fetching/stealthy.md)を参照してください。++### XHR キャプチャをセッションのネットワーク履歴に置き換える {#replace-xhr-capture-with-session-network-history}++`capture_xhr` パラメーターと `Response.captured_xhr` 属性は削除されました。値が `None` でも、このパラメーターを削除してください。単発取得のレスポンスには XHR のリストが付かなくなりました。++`ResponseFactory.from_playwright_response()` または `ResponseFactory.from_async_playwright_response()` を呼ぶ独自の連携コードでも、`xhr_captured` を削除する必要があります。位置引数の順序変更による問題を避けるため、`collect_history` は名前を指定して渡してください。++**変更前:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", capture_xhr="/api/")+for response in page.captured_xhr:+ print(response.url, response.body)+```++**変更後:**++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True) as session:+ page = session.fetch("https://example.com", network_idle=True)+ for response in session.network.search(url_pattern=r"/api/", limit=None):+ print(response.url, response.body)+```++非同期コードでは `AsyncStealthySession` と `await session.fetch(...)` を使います。`session.network` の読み取りに `await` は不要です。++主な違いは次のとおりです。++- セッションの作成時に `record_requests=True` を設定します。取得ごとの設定ではなく、セッションの設定です。+- 履歴は**セッション全体**に属し、タブ、ページの読み込み、操作をまたいで記録されます。範囲を絞る場合は、`after_id`、フィルター、`session.network.clear()` を使ってください。+- 履歴を検索するときは、以前の `capture_xhr` の正規表現を `url_pattern` に渡します。+- `search()` は保存済みの `Response` オブジェクトを返します。`.url`、`.status`、`.headers`、`.body`、`.json()` を直接読めます。記録 ID、リソースの種類、送信したボディは、`response.meta["network_id"]`、`response.meta["resource_type"]`、`response.meta["request_body"]` に入っています。+- Python の履歴は、デフォルトですべてのリソースの種類を含みます。`resource_type="xhr"` または `resource_type="fetch"` で種類を選ぶか、`include_static=False` で XHR/fetch リクエストと HTTP エラーを選んでください。+- `search()` はデフォルトで最大 100 件の一致を返します。保持されている一致をすべて取得するには、`limit=None` を渡します。セッションはデフォルトで最大 1,000 件のリクエストを保持します。`max_recorded_requests` で変更できます。+- 完了したリクエストだけが保存されます。ボディのキャプチャは対応するテキストコンテンツ型に限られ、1 レスポンスあたり 1 MiB、保持するボディデータ全体で 20 MiB が上限です。上限に達すると古い記録が削除される場合があります。ボディが省略された理由は `response.meta.get("body_note")` で確認できます。+- 履歴の読み取りやセッションの終了は、未完了のキャプチャを待ちません。必要なデータがそろってから読んでください。保存済みの Python の履歴は、セッション終了後も読めます。++フィルターと上限は[ネットワーク履歴](fetching/stealthy.md#network-history)を参照してください。++## パーサーの設定 {#parser-settings}++### `keep_cdata` を削除する {#remove-keep_cdata}++`keep_cdata` は `Selector`、Fetcher の設定、`display_config()` が返す設定から削除されました。パーサーの直接呼び出し、`Fetcher.configure(...)`、Fetcher や連携機能に渡す `selector_config` 辞書から削除してください。++**変更前:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>", keep_cdata=True)+```++**変更後:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>")+```++代わりの設定はありません。この設定は HTML パーサーの出力に影響していませんでした。パーサーのオプションを位置引数で渡していた場合は、古い `keep_cdata` 引数を削除し、`adaptive` とストレージのオプションを名前付きで渡してください。++## コマンドラインと対話型シェル {#command-line-and-interactive-shell}++### ブラウザのリクエストに `fetch` を使う {#use-fetch-for-browser-requests}++CLI のブラウザコマンドは `scrapling extract fetch` の 1 つになりました。これは `StealthyFetcher` を使います。++**変更前:**++```bash+scrapling extract stealthy-fetch "https://example.com" page.md+```++**変更後:**++```bash+scrapling extract fetch "https://example.com" page.md+```++すでに `scrapling extract fetch` を使っている場合、コマンド名は変わりません。ただし、バックエンドが `DynamicFetcher` から `StealthyFetcher` に変わります。`--solve-cloudflare` などのオプションは、`fetch` のオプションになりました。++`scrapling shell` では、`stealthy_fetch(...)` を `fetch(...)` に置き換えてください。既存のショートカット `fetch(...)` は `StealthyFetcher.fetch` を呼ぶようになりました。動的クラスはシェルの名前空間に追加されなくなりました。++### Markdown とテキストファイルを UTF-8 として読む {#read-markdown-and-text-files-as-utf-8}++抽出コマンドと `Convertor.write_content_to_file()` は、元ページの文字セットにかかわらず、`.md` と `.txt` ファイルを **UTF-8** で書き込むようになりました。元ページのエンコーディングでこれらのファイルを読むコードを更新してください。`.html` の出力は引き続き `page.encoding` を使います。++複数の選択要素から作る Markdown には、要素間に空行が入るようになりました。これは `Response.markdown()` と Markdown ファイルの出力に適用されます。テキストの直接連結に依存していた完全一致の出力比較や保存済みハッシュを更新してください。++## MCP サーバー {#mcp-server}++保存済みのプロンプト、ツールの許可リスト、ラッパー、MCP クライアントのツール定義を更新してください。サーバーを更新した後は、MCP クライアントを再起動または再接続し、現在のツールを読み込ませてください。++### ツール名と一括呼び出しを更新する {#update-tool-names-and-bulk-calls}++| v0.4.15 のツール | v0.5 での代替 |+| --- | --- |+| `fetch`, `stealthy_fetch` | `browser_fetch_once` |+| `open_session` | `browser_open` |+| `session_fetch` | `browser_fetch` |+| `screenshot` | `browser_screenshot` |+| `bulk_fetch`, `bulk_stealthy_fetch` | URL ごとに `browser_fetch_once` を 1 回呼ぶか、開いているセッションで `browser_fetch` を繰り返し呼び出す |+| `bulk_get` | URL ごとに `make_request` または `session_make_request` を 1 回呼び出す |++一括処理ツールはすべて削除されました。単一 URL の取得ツールは、レスポンスのリストではなく、`status`、`content`、`url` を持つ 1 つの `ResponseModel` を返します。`content` 自体は引き続き文字列のリストです。++MCP のブラウザツールはすべてステルスバックエンドを使うようになりました。`browser_open` の呼び出しから `session_type` を削除してください。動的ブラウザは選べなくなりました。結果には `session_type="stealthy"` が含まれます。HTTP セッションは引き続き `open_request_session` を使い、`session_type="static"` を返します。++Python の連携コードも、削除された `BrowserSessionType` のインポートをやめる必要があります。`SessionType` が受け付ける値は `"stealthy"` と `"static"` だけになりました。++同じブラウザセッションの呼び出しはページを共有するため、順番に実行する必要があります。完了したら `close_session` でセッションを閉じてください。++### `list_sessions` で設定を読む {#read-settings-through-list_sessions}++`browser_open` と `open_request_session` が返す内容は、次の項目だけになりました。++```json+{+ "session_id": "my-session",+ "session_type": "stealthy"+}+```++作成結果には `created_at`、`is_alive`、`settings`、`message` が含まれなくなりました。最初の 3 項目は `list_sessions` で取得してください。確認用の `message` は削除されました。`SessionCreatedModel` が `SessionInfo` の全フィールドを持つと想定していたコードも変更が必要です。++### スクリーンショットの前にページを取得する {#fetch-before-taking-a-screenshot}++`browser_screenshot` は、**現在のページを再読み込みせずに撮影**します。URL と、以前の移動・待機オプションである `wait`、`wait_selector`、`wait_selector_state`、`network_idle` は受け付けなくなりました。++次の順序で使ってください。++1. `browser_open` を呼び出します。+2. URL と必要なページ読み込みオプションを指定して `browser_fetch` を呼び出します。+3. 必要に応じて `browser_actions` を呼び、ページを操作したりコンテンツを待ったりします。+4. セッション ID を指定して `browser_screenshot` を呼び出します。+5. 完了したら `close_session` を呼び出します。++たとえば、ページ全体のスクリーンショットの引数は次のとおりです。++```json+{+ "session_id": "my-session",+ "full_page": true+}+```++このツールの `timeout` は、スクリーンショット操作の制限時間になりました。ツールはページを読み込みません。要素のスクリーンショットでは `selector` または `ref` を使い、`full_page=true` は設定しないでください。++スクリーンショットは引き続き画像とテキストのコンテンツブロックを返し、テキストブロックには現在のページ URL が含まれます。取得用の `ResponseModel` は返しません。++完全なスキーマは [MCP ガイド](ai/mcp-server.md)と [API リファレンス](api-reference/mcp-server.md)を参照してください。++## Spider と HTTP リクエスト {#spiders-and-http-requests}++### リンクをたどるときにリクエストデータを再度渡す {#pass-request-data-again-when-following-a-link}++`response.follow()` は、前のリクエストから `method`、`params`、`data`、`json`、`files`、`multipart` をコピーしなくなりました。また、`headers` と `extra_headers` から継承された `Content-Length` ヘッダーも削除します。++リンクをたどるときは、リクエストデータを明示的に渡さない限り、通常の GET リクエストになります。セッション、プロキシ、コールバックなど、ほかの共有設定は既存の継承規則に従います。++古いコードが継承された POST データに依存していた場合は、次のコードを変更してください。++```python+yield response.follow("/next")+```++変更後:++```python+yield response.follow("/next", method="POST", json={"page": 2})+```++次のリクエストで `params` が必要な場合も、明示的に渡してください。新しい `Content-Length` の計算は HTTP クライアントに任せてください。++### リクエストのフィンガープリントと保存済みクロール状態を確認する {#check-request-fingerprints-and-saved-crawl-state}++リクエストのフィンガープリントは、重複リクエストの検出とキャッシュ済みレスポンスの検索に使うキーです。入力の扱いが次の 3 点で変わりました。++- キーを作る前に `params` が URL に統合されます。同じ URL でもクエリパラメーターが異なるリクエストは、デフォルトでは重複と見なされなくなりました。+- `{}`、`[]`、`false`、`0`、`""` などの JSON ボディがキーに保持されます。ボディがない場合と同じキーにはならなくなりました。`None` は引き続き JSON ボディがないことを意味します。+- `fp_include_headers=True` の場合、ヘッダーの挿入順序だけを変えてもキーは変わらなくなりました。++クロールがこれらの入力を使っている場合は、更新前に完了させるか、新しいチェックポイントとレスポンスキャッシュ用ディレクトリで新しいクロールを始めてください。保存済みの古いキーは、新しいキーと異なる場合があります。これはリクエストの識別方法の変更であり、チェックポイントのファイル形式の変更ではありません。++開発モードでは、ブロックされたレスポンスかどうかを確認してからキャッシュに書き込むようになりました。ブロックされたページは、成功した結果としてキャッシュに保存されません。既存のキャッシュファイルは自動で整理されません。以前に認証チャレンジのページを保存した場合は、古い項目を削除してください。++失敗したクロールは、チェックポイントファイルを保持するようになりました。エラー後にこれらのファイルが消えると想定していた場合は、クリーンアップ用コードを確認してください。[一時停止と再開](spiders/advanced.md#pause-resume)と[開発モード](spiders/advanced.md#development-mode)を参照してください。++### robots.txt の取得失敗を確認する {#check-robotstxt-failures}++`robots_txt_obey=True` の場合、robots.txt の取得中の例外や、HTTP 200 または 4xx 以外のレスポンスによって、そのドメインへのリクエストがブロックされるようになりました。以前は、このような失敗でもクロールが許可されていました。HTTP 200 は引き続き規則を提供し、HTTP 4xx は引き続きアクセスを許可します。++結果はクロール全体でキャッシュされます。robots.txt へのアクセス問題を直して、新しいクロールを始めてください。同じクロール内の後続リクエストでは、失敗した取得を再試行しません。デフォルトの `robots_txt_obey=False` は変わりません。++### リンクの制限とサイトマップのコールバックを確認する {#check-link-restrictions-and-sitemap-callbacks}++- `LinkExtractor` の制限に一致するものがない場合、リンクを返さなくなりました。ページ全体に戻って探すことはありません。見つかるリンクが減った場合は、`restrict_css` または `restrict_xpath` の式を修正してください。+- 制限で親要素だけでなく、リンク要素自体も選べるようになりました。以前は見落としていたリンクが追加される場合があります。想定する URL の集合を確認してください。+- 規則がない場合、または一致した規則が `callback=None` の場合、`SitemapSpider` はページ URL を `parse()` に送るようになりました。これらの HTML ページをサイトマップパーサーに戻すことはありません。該当する場合の `parse()` を実装し、以前の振り分けに対する回避策を削除してください。+- robots.txt と CSV フィードの先頭にある Unicode バイトオーダーマークが削除されます。robots の最初の指示が有効になり、CSV の最初の列名が `\ufeff` で始まらなくなりました。独自の `headers` を設定した場合は、代わりに最初のフィールド値からマークが削除されます。この見えない接頭辞に対処していたコードを更新してください。サイトマップの XML コメントと処理命令も、解析エラーの原因になるのではなく、読み飛ばされるようになりました。++### フォームデータ、ヘッダー、CLI の JSON を確認する {#check-form-data-headers-and-cli-json}++辞書形式のフォームデータでは、リストとタプルの値が同じキーの繰り返しに展開されるようになりました。たとえば `data={"tag": ["a", "b"]}` は `tag=a&tag=b` を送信します。空のリストでは、そのキーの項目は送信されません。Content-Type を指定していない場合は、デフォルトの `Content-Type: application/x-www-form-urlencoded` が追加されます。++別の送信形式が必要な場合は、明示的にエンコードした文字列またはバイト列を渡してください。`json`、生の `content`、multipart アップロードは、それぞれのボディ処理を維持します。フォームデータやクエリパラメーターの `None` 値は**削除されません**。文字列 `None` のまま残ります。++リクエストごとの HTTP ヘッダーは、大文字と小文字に関係なくセッションのヘッダーを上書きするようになりました。`authorization` というリクエストヘッダーは、セッションの `Authorization` と両方送信されるのではなく、それを置き換えます。ヘッダー名の重複を回避していたコードを削除してください。++CLI の JSON 値 `{}`、`[]`、`false`、`0`、`""` は、通知なしに省略されず、送信されるようになりました。また、`curl2fetcher()` は curl の `-A` のユーザーエージェントを適用し、`-x` のプロキシを URL 文字列として正しく渡すようになりました。curl で明示した `-H 'User-Agent: ...'` は、引き続き `-A` より優先されます。++## 確認すべきその他の出力変更 {#other-output-changes-to-check}++これらの修正は API を削除しませんが、保存済みの結果や出力の完全一致テストに影響する場合があります。++- 生成される CSS と XPath のセレクターは、同じタグの兄弟要素が複数あるとき、その先頭を特定するために必要なら `:nth-of-type(1)` または `[1]` を含むようになりました。期待するセレクター文字列を更新し、新しい位置指定を削除しないでください。+- AI 向けに整形したコンテンツは、`opacity:0.95` などの値を持つ表示要素を保持するようになりました。また、より多くの形式のインラインスタイルで非表示になった要素や `<slot hidden>` 要素を削除し、一致する不要なタグは入れ子でもすべて削除します。Markdown、テキスト、サニタイズ済み HTML の正確な出力を再確認してください。+- ブラウザレスポンスの変換では、大文字と小文字の違い、空白、引用符付きの値がある charset 宣言も読めるようになりました。たとえば `text/plain; CHARSET = "iso-8859-15"` です。このようなヘッダーを持つ HTML 以外のレスポンスは、UTF-8 に戻るのではなく、宣言されたエンコーディングを使うようになりました。これらのレスポンスからデコードしたテキストを再確認してください。++## 更新結果を確認する {#verify-your-upgrade}++全体の処理を実行する前に、小さなクロールを試してください。抽出データ、たどった URL、送信したリクエストボディ、保存ファイルのエンコーディング、依存しているキャッシュやチェックポイントの動作を確認します。MCP の連携では、ツールへの入力と返されるデータの両方を、現在のスキーマと照合してください。++以前のリリースの変更は[変更履歴](changelog.md)を参照してください。diff --git a/docs/locales/ko/migrating-to-v0.5.md b/docs/locales/ko/migrating-to-v0.5.mdnew file mode 100644index 0000000..87c7328--- /dev/null+++ b/docs/locales/ko/migrating-to-v0.5.md@@ -0,0 +1,293 @@+---+title: "v0.5로 마이그레이션"+description: "Scrapling v0.4.15에서 v0.5로 업그레이드하세요. 브라우저 가져오기 구문, 네트워크 기록, MCP 도구, CLI 명령, 파서 설정, 스파이더 동작을 업데이트합니다."+---++# v0.5로 마이그레이션 {#migrating-to-v05}++이 가이드는 **v0.4.15에서 v0.5로** 옮길 때 확인할 변경 사항을 다룹니다. 삭제된 API, 이름이 바뀐 도구, 크롤링 결과나 저장된 파일에 영향을 줄 수 있는 수정 사항을 설명합니다.++## 빠른 마이그레이션 점검표 {#quick-migration-checklist}++| 사용 중인 기능 | 변경할 내용 |+| --- | --- |+| `DynamicFetcher`, `DynamicSession` 또는 `AsyncDynamicSession` | 대응하는 스텔스 클래스를 사용하세요. |+| `capture_xhr` 또는 `response.captured_xhr` | `record_requests=True`로 설정한 브라우저 세션과 `session.network`를 사용하세요. |+| `keep_cdata` | 파서와 Fetcher 설정에서 삭제하세요. |+| `scrapling extract stealthy-fetch` 또는 셸의 `stealthy_fetch()` | 대신 `fetch`를 사용하세요. |+| MCP 도구 | 도구 이름, 스크린샷 호출, 세션 생성 응답 처리 방식을 업데이트하세요. |+| POST 요청이나 쿼리 매개변수가 있는 요청 뒤의 `response.follow()` | 필요하면 메서드, 쿼리, 본문을 다시 전달하세요. |+| 저장된 크롤링 체크포인트 또는 응답 캐시 | 요청이 변경된 지문 입력값을 사용하면 새 크롤링을 시작하세요. |+| `robots_txt_obey=True` | robots.txt 가져오기 실패를 처리하세요. 이제 실패하면 해당 도메인의 크롤링이 차단됩니다. |++## 브라우저로 가져오기 {#browser-fetching}++### 동적 브라우저 클래스 교체 {#replace-the-dynamic-browser-classes}++Playwright를 직접 사용하는 브라우저 백엔드는 삭제되었습니다. 이제 모든 브라우저 가져오기는 Patchright 기반 스텔스 백엔드를 사용합니다.++| 삭제된 API | 대체 API |+| --- | --- |+| `scrapling.DynamicFetcher` | `scrapling.StealthyFetcher` |+| `scrapling.fetchers.DynamicFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.chrome.PlayWrightFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.DynamicSession` | `scrapling.fetchers.StealthySession` |+| `scrapling.fetchers.AsyncDynamicSession` | `scrapling.fetchers.AsyncStealthySession` |++`scrapling.fetchers.chrome` 모듈과 비공개 `_browsers._controllers` 모듈은 삭제되었습니다. 위에 나온 공개 가져오기 경로를 사용하세요.++**이전:**++```python+from scrapling.fetchers import DynamicFetcher++page = DynamicFetcher.fetch("https://example.com", headless=True)+```++**현재:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", headless=True)+```++세션에서는 `DynamicSession`을 `StealthySession`으로, 또는 `AsyncDynamicSession`을 `AsyncStealthySession`으로 바꾸세요. 스파이더의 `configure_sessions()` 메서드에도 같은 변경을 적용하세요. `fetch()`와 `async with` 사용 방식은 그대로입니다.++콜백이 브라우저 타입을 가져오거나 브라우저 오류를 처리한다면 `playwright.sync_api`를 `patchright.sync_api`로, 또는 `playwright.async_api`를 `patchright.async_api`로 바꾸세요. 여기에는 `Page`, `Locator`, `Error`, `TimeoutError`가 포함됩니다.++Patchright는 기본적으로 격리된 컨텍스트에서 JavaScript를 실행합니다. 콜백이 페이지 자체의 JavaScript 변수를 읽는다면 `page.evaluate(..., isolated_context=False)`를 사용하세요.++가져오기 이름과 함께 브라우저 동작도 바뀝니다. 브라우저 플래그와 지문 설정을 확인하세요. Cloudflare 해결에는 여전히 `solve_cloudflare=True`가 필요하며, 기본적으로 활성화되지 않습니다. 또한 `extra_flags`는 이제 내장 스텔스 플래그를 교체하지 않고 추가합니다.++현재 옵션은 [브라우저로 가져오기](fetching/stealthy.md)를 참고하세요.++### XHR 캡처를 세션 네트워크 기록으로 교체 {#replace-xhr-capture-with-session-network-history}++`capture_xhr` 매개변수와 `Response.captured_xhr` 속성은 삭제되었습니다. 값이 `None`이어도 매개변수를 삭제하세요. 일회성 가져오기의 응답에는 더 이상 XHR 목록이 붙지 않습니다.++`ResponseFactory.from_playwright_response()` 또는 `ResponseFactory.from_async_playwright_response()`를 호출하는 사용자 정의 통합 코드에서도 `xhr_captured`를 삭제해야 합니다. 위치 인수 순서 변경으로 생기는 문제를 피하려면 `collect_history`를 이름으로 전달하세요.++**이전:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", capture_xhr="/api/")+for response in page.captured_xhr:+ print(response.url, response.body)+```++**현재:**++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True) as session:+ page = session.fetch("https://example.com", network_idle=True)+ for response in session.network.search(url_pattern=r"/api/", limit=None):+ print(response.url, response.body)+```++비동기 코드에서는 `AsyncStealthySession`과 `await session.fetch(...)`를 사용하세요. `session.network`를 읽는 데는 `await`가 필요하지 않습니다.++다음 차이를 확인하세요.++- 세션을 만들 때 `record_requests=True`를 설정하세요. 개별 가져오기 설정이 아니라 세션 설정입니다.+- 기록은 탭, 페이지 로드, 작업을 아우르는 **세션 전체**에 속합니다. 범위를 줄여야 한다면 `after_id`, 필터 또는 `session.network.clear()`를 사용하세요.+- 기록을 검색할 때는 이전 `capture_xhr` 정규식을 `url_pattern`으로 옮기세요.+- `search()`는 저장된 `Response` 객체를 반환합니다. `.url`, `.status`, `.headers`, `.body` 또는 `.json()`을 직접 읽으세요. 기록 ID, 리소스 타입, 전송한 본문은 `response.meta["network_id"]`, `response.meta["resource_type"]`, `response.meta["request_body"]`에 있습니다.+- Python 기록은 기본적으로 모든 리소스 타입을 포함합니다. `resource_type="xhr"` 또는 `resource_type="fetch"`로 하나를 선택하거나, `include_static=False`로 XHR/fetch 요청과 HTTP 오류를 선택하세요.+- `search()`는 기본적으로 최대 100개의 일치 항목을 반환합니다. 보관된 일치 항목을 모두 얻으려면 `limit=None`을 전달하세요. 세션은 기본적으로 최대 1,000개의 요청을 보관하며, `max_recorded_requests`로 변경할 수 있습니다.+- 완료된 요청만 저장합니다. 본문 캡처는 지원되는 텍스트 콘텐츠 타입으로 제한되며, 응답당 1 MiB, 보관된 본문 데이터 전체는 20 MiB가 한도입니다. 한도에 도달하면 오래된 기록이 삭제될 수 있습니다. 본문을 건너뛴 이유는 `response.meta.get("body_note")`로 확인하세요.+- 기록을 읽거나 세션을 닫아도 진행 중인 캡처가 끝날 때까지 기다리지 않습니다. 필요한 데이터가 준비된 뒤에 읽으세요. 저장된 Python 기록은 세션을 닫은 후에도 읽을 수 있습니다.++필터와 한도는 [네트워크 기록](fetching/stealthy.md#network-history)을 참고하세요.++## 파서 설정 {#parser-settings}++### `keep_cdata` 삭제 {#remove-keep_cdata}++`keep_cdata`는 `Selector`, Fetcher 구성, `display_config()`가 반환하는 설정에서 삭제되었습니다. 직접 파서를 호출하는 코드, `Fetcher.configure(...)`, Fetcher나 통합 기능에 전달하는 `selector_config` 딕셔너리에서 삭제하세요.++**이전:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>", keep_cdata=True)+```++**현재:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>")+```++대체 설정은 없습니다. 이 설정은 HTML 파서의 출력에 영향을 주지 않았습니다. 파서 옵션을 위치 인수로 전달했다면 기존 `keep_cdata` 인수를 삭제하고 `adaptive`와 저장소 옵션을 이름으로 전달하세요.++## 명령줄과 대화형 셸 {#command-line-and-interactive-shell}++### 브라우저 요청에 `fetch` 사용 {#use-fetch-for-browser-requests}++CLI의 브라우저 명령은 이제 `scrapling extract fetch` 하나입니다. 이 명령은 `StealthyFetcher`를 사용합니다.++**이전:**++```bash+scrapling extract stealthy-fetch "https://example.com" page.md+```++**현재:**++```bash+scrapling extract fetch "https://example.com" page.md+```++이미 `scrapling extract fetch`를 사용한다면 명령 이름은 그대로지만, 백엔드가 `DynamicFetcher`에서 `StealthyFetcher`로 바뀝니다. `--solve-cloudflare` 같은 옵션은 이제 `fetch`에 속합니다.++`scrapling shell`에서는 `stealthy_fetch(...)`를 `fetch(...)`로 바꾸세요. 기존 `fetch(...)` 바로가기는 이제 `StealthyFetcher.fetch`를 호출합니다. 동적 클래스는 더 이상 셸의 이름 공간에 추가되지 않습니다.++### Markdown과 텍스트 파일을 UTF-8로 읽기 {#read-markdown-and-text-files-as-utf-8}++추출 명령과 `Convertor.write_content_to_file()`은 이제 원본 페이지의 문자 집합과 관계없이 `.md`와 `.txt` 파일을 **UTF-8**로 기록합니다. 원본 페이지 인코딩으로 이 파일을 읽는 코드를 업데이트하세요. `.html` 출력은 여전히 `page.encoding`을 사용합니다.++선택한 여러 요소에서 만든 Markdown은 이제 요소 사이에 빈 줄을 넣습니다. 이는 `Response.markdown()`과 Markdown 파일 출력에 적용됩니다. 직접 이어 붙인 텍스트에 의존하던 정확한 출력 비교나 저장된 해시를 업데이트하세요.++## MCP 서버 {#mcp-server}++저장된 프롬프트, 도구 허용 목록, 래퍼, MCP 클라이언트의 도구 정의를 업데이트하세요. 서버를 업데이트한 후에는 MCP 클라이언트를 다시 시작하거나 다시 연결해 현재 도구 목록을 읽게 하세요.++### 도구 이름과 일괄 호출 업데이트 {#update-tool-names-and-bulk-calls}++| v0.4.15 도구 | v0.5 대체 방법 |+| --- | --- |+| `fetch`, `stealthy_fetch` | `browser_fetch_once` |+| `open_session` | `browser_open` |+| `session_fetch` | `browser_fetch` |+| `screenshot` | `browser_screenshot` |+| `bulk_fetch`, `bulk_stealthy_fetch` | URL마다 `browser_fetch_once`를 한 번 호출하거나 열린 세션에서 `browser_fetch`를 반복 호출 |+| `bulk_get` | URL마다 `make_request` 또는 `session_make_request`를 한 번 호출 |++모든 일괄 도구가 삭제되었습니다. 단일 URL 가져오기 도구는 응답 목록 대신 `status`, `content`, `url`이 있는 `ResponseModel` 하나를 반환합니다. `content` 자체는 여전히 문자열 목록입니다.++모든 MCP 브라우저 도구는 이제 스텔스 백엔드를 사용합니다. `browser_open` 호출에서 `session_type`을 삭제하세요. 동적 브라우저는 더 이상 선택할 수 없습니다. 결과에는 `session_type="stealthy"`가 들어 있습니다. HTTP 세션은 여전히 `open_request_session`을 사용하고 `session_type="static"`을 반환합니다.++Python 통합 코드에서도 삭제된 `BrowserSessionType`을 가져오지 않아야 합니다. `SessionType`은 이제 `"stealthy"`와 `"static"`만 허용합니다.++같은 브라우저 세션의 호출은 페이지를 공유하므로 순서대로 실행해야 합니다. 작업을 마치면 `close_session`으로 세션을 닫으세요.++### `list_sessions`로 설정 읽기 {#read-settings-through-list_sessions}++`browser_open`과 `open_request_session`은 이제 다음 항목만 반환합니다.++```json+{+ "session_id": "my-session",+ "session_type": "stealthy"+}+```++생성 결과에는 더 이상 `created_at`, `is_alive`, `settings`, `message`가 포함되지 않습니다. 앞의 세 필드는 `list_sessions`를 호출해 얻으세요. 확인 메시지인 `message`는 삭제되었습니다. `SessionCreatedModel`이 `SessionInfo`의 모든 필드를 가진다고 가정하던 코드도 바꿔야 합니다.++### 스크린샷을 찍기 전에 페이지 가져오기 {#fetch-before-taking-a-screenshot}++`browser_screenshot`은 **현재 페이지를 다시 로드하지 않고 캡처**합니다. URL이나 기존 탐색 및 대기 옵션인 `wait`, `wait_selector`, `wait_selector_state`, `network_idle`은 더 이상 받지 않습니다.++다음 순서로 사용하세요.++1. `browser_open`을 호출합니다.+2. URL과 필요한 페이지 로드 옵션을 넣어 `browser_fetch`를 호출합니다.+3. 필요하면 `browser_actions`를 호출해 페이지와 상호작용하거나 콘텐츠를 기다립니다.+4. 세션 ID를 넣어 `browser_screenshot`을 호출합니다.+5. 작업을 마치면 `close_session`을 호출합니다.++예를 들어 전체 페이지 스크린샷의 인수는 다음과 같습니다.++```json+{+ "session_id": "my-session",+ "full_page": true+}+```++이 도구의 `timeout`은 이제 스크린샷 작업 시간을 제한합니다. 도구는 페이지를 로드하지 않습니다. 요소 스크린샷을 찍으려면 `selector` 또는 `ref`를 사용하고 `full_page=true`는 설정하지 마세요.++스크린샷은 여전히 이미지와 텍스트 콘텐츠 블록을 반환하며, 텍스트 블록에는 현재 페이지 URL이 들어 있습니다. 가져오기용 `ResponseModel`은 반환하지 않습니다.++전체 스키마는 [MCP 가이드](ai/mcp-server.md)와 [API 참조](api-reference/mcp-server.md)를 참고하세요.++## 스파이더와 HTTP 요청 {#spiders-and-http-requests}++### 링크를 따라갈 때 요청 데이터 다시 전달 {#pass-request-data-again-when-following-a-link}++`response.follow()`는 이전 요청에서 `method`, `params`, `data`, `json`, `files`, `multipart`를 더 이상 복사하지 않습니다. 또한 `headers`와 `extra_headers`에서 상속된 `Content-Length` 헤더를 삭제합니다.++요청 데이터를 명시적으로 전달하지 않으면 링크를 따라가는 요청은 이제 일반 GET으로 시작합니다. 세션, 프록시, 콜백 등 다른 공유 설정은 기존 상속 규칙을 따릅니다.++기존 코드가 상속된 POST 데이터에 의존했다면 다음 코드를 바꾸세요.++```python+yield response.follow("/next")+```++변경 후:++```python+yield response.follow("/next", method="POST", json={"page": 2})+```++다음 요청에 `params`가 필요하면 이 값도 명시적으로 전달하세요. 새 `Content-Length`는 HTTP 클라이언트가 계산하게 하세요.++### 요청 지문과 저장된 크롤링 상태 확인 {#check-request-fingerprints-and-saved-crawl-state}++요청 지문은 중복 요청을 찾고 캐시된 응답을 검색하는 데 사용하는 키입니다. 입력값을 처리하는 방식이 다음 세 경우에 달라졌습니다.++- 키를 만들기 전에 `params`가 URL에 합쳐집니다. 같은 URL이라도 쿼리 매개변수가 다르면 기본적으로 중복 요청으로 취급하지 않습니다.+- `{}`, `[]`, `false`, `0`, `""` 같은 JSON 본문은 키에 유지됩니다. 이제 본문이 없는 경우와 같은 키를 쓰지 않습니다. `None`은 여전히 JSON 본문이 없다는 뜻입니다.+- `fp_include_headers=True`일 때 헤더를 추가한 순서만 달라져도 키가 바뀌던 동작이 사라졌습니다.++크롤링이 이 입력값을 사용한다면 업그레이드 전에 마치거나, 새 체크포인트와 새 응답 캐시 디렉터리로 새 크롤링을 시작하세요. 이전에 저장한 키는 새 키와 다를 수 있습니다. 이는 요청 식별 방식의 변경이며 체크포인트 파일 형식의 변경은 아닙니다.++개발 모드는 이제 응답이 차단되었는지 확인한 뒤에만 캐시에 응답을 기록합니다. 차단된 페이지는 성공한 결과로 캐시에 저장되지 않습니다. 기존 캐시 파일은 자동으로 정리되지 않습니다. 이전에 검증 페이지를 캐시했다면 오래된 항목을 지우세요.++실패한 크롤링은 이제 체크포인트 파일을 유지합니다. 오류 후에 이 파일이 사라진다고 가정했다면 정리 코드를 확인하세요. [일시 중지와 재개](spiders/advanced.md#pause-resume) 및 [개발 모드](spiders/advanced.md#development-mode)를 참고하세요.++### robots.txt 가져오기 실패 확인 {#check-robotstxt-failures}++`robots_txt_obey=True`일 때 robots.txt를 가져오다가 예외가 발생하거나 HTTP 200 또는 4xx가 아닌 응답을 받으면 이제 해당 도메인 요청을 차단합니다. 이전에는 이 실패 상황에서도 크롤링을 허용했습니다. HTTP 200은 여전히 규칙을 제공하고 HTTP 4xx는 여전히 접근을 허용합니다.++결과는 크롤링 전체에 걸쳐 캐시됩니다. robots.txt 접근 문제를 해결한 뒤 새 크롤링을 시작하세요. 같은 크롤링의 후속 요청은 실패한 조회를 다시 시도하지 않습니다. 기본값 `robots_txt_obey=False`는 바뀌지 않습니다.++### 링크 제한과 사이트맵 콜백 확인 {#check-link-restrictions-and-sitemap-callbacks}++- `LinkExtractor` 제한 조건에 일치하는 항목이 없으면 이제 링크를 반환하지 않습니다. 전체 페이지로 범위를 넓혀 다시 찾지 않습니다. 크롤링에서 찾는 링크가 줄었다면 `restrict_css` 또는 `restrict_xpath` 표현식을 수정하세요.+- 제한 조건은 이제 부모 요소뿐 아니라 링크 요소 자체도 선택할 수 있습니다. 이전에 놓쳤던 링크가 추가될 수 있으므로 예상 URL 집합을 확인하세요.+- 규칙이 없거나 일치하는 규칙에 `callback=None`이 있으면 `SitemapSpider`는 이제 페이지 URL을 `parse()`로 보냅니다. 해당 HTML 페이지를 사이트맵 파서로 다시 보내지 않습니다. 이 경우를 위한 `parse()`를 구현하고 이전 처리 경로의 문제를 우회하던 코드를 삭제하세요.+- robots.txt와 CSV 피드의 맨 앞에 있는 Unicode 바이트 순서 표시가 제거됩니다. 이제 robots의 첫 지시문이 적용되고 CSV의 첫 열 이름이 `\ufeff`로 시작하지 않습니다. 사용자 정의 `headers`를 설정했다면 대신 첫 필드 값에서 표시가 제거됩니다. 이 숨은 접두사를 처리하던 코드를 업데이트하세요. 사이트맵의 XML 주석과 처리 명령도 파싱 실패를 일으키지 않고 건너뜁니다.++### 폼 데이터, 헤더, CLI JSON 확인 {#check-form-data-headers-and-cli-json}++딕셔너리 형태의 폼 데이터는 이제 리스트와 튜플 값을 반복되는 키로 펼칩니다. 예를 들어 `data={"tag": ["a", "b"]}`는 `tag=a&tag=b`를 보냅니다. 빈 리스트는 해당 키의 항목을 보내지 않습니다. Content-Type을 지정하지 않았다면 기본값 `Content-Type: application/x-www-form-urlencoded`를 추가합니다.++다른 전송 형식이 필요하면 명시적으로 인코딩한 문자열이나 바이트를 전달하세요. `json`, 원시 `content`, multipart 업로드는 각자의 본문 처리 방식을 유지합니다. 폼 데이터나 쿼리 매개변수의 `None` 값은 **제거되지 않습니다**. 문자열 `None`으로 남습니다.++요청별 HTTP 헤더는 이제 대소문자와 관계없이 세션 헤더를 덮어씁니다. 이름이 `authorization`인 요청 헤더는 세션의 `Authorization`과 함께 전송되지 않고 이를 교체합니다. 중복된 헤더 이름을 처리하던 코드를 삭제하세요.++CLI JSON 값 `{}`, `[]`, `false`, `0`, `""`는 이제 알림 없이 버려지지 않고 전송됩니다. 또한 `curl2fetcher()`는 curl의 `-A` 사용자 에이전트를 적용하고 `-x` 프록시를 URL 문자열로 올바르게 전달합니다. 명시적인 curl 헤더 `-H 'User-Agent: ...'`는 여전히 `-A`보다 우선합니다.++## 그 밖에 확인할 출력 변경 {#other-output-changes-to-check}++이 수정 사항은 API를 삭제하지 않지만 저장된 결과와 정확한 출력 비교 테스트를 바꿀 수 있습니다.++- 생성된 CSS 및 XPath 선택자는 같은 태그를 가진 여러 형제 요소 중 첫 요소를 식별해야 할 때 `:nth-of-type(1)` 또는 `[1]`을 포함합니다. 예상 선택자 문자열을 업데이트하고 새 위치 표시를 삭제하지 마세요.+- AI용으로 정리한 콘텐츠는 이제 `opacity:0.95` 같은 값을 가진 표시 요소를 유지합니다. 더 다양한 인라인 스타일로 숨긴 요소와 `<slot hidden>` 요소를 제거하며, 일치하는 불필요한 태그는 중첩되어 있어도 모두 제거합니다. Markdown, 텍스트, 정리된 HTML의 정확한 출력을 다시 확인하세요.+- 브라우저 응답 변환은 이제 대소문자가 다르거나 공백 또는 따옴표로 감싼 값이 있는 charset 선언을 읽습니다. 예를 들어 `text/plain; CHARSET = "iso-8859-15"`입니다. 이 헤더가 있는 HTML이 아닌 응답은 이제 UTF-8로 대체하지 않고 선언된 인코딩을 사용합니다. 해당 응답에서 디코딩한 텍스트를 다시 확인하세요.++## 업그레이드 검증 {#verify-your-upgrade}++전체 작업 전에 작은 크롤링을 실행하세요. 추출된 데이터, 따라간 URL, 전송한 요청 본문, 저장된 파일의 인코딩, 의존하는 캐시나 체크포인트 동작을 확인하세요. MCP 통합에서는 도구 입력과 반환된 데이터를 모두 현재 스키마와 비교하세요.++이전 릴리스의 변경 사항은 [변경 기록](changelog.md)을 참고하세요.diff --git a/docs/locales/pt-BR/migrating-to-v0.5.md b/docs/locales/pt-BR/migrating-to-v0.5.mdnew file mode 100644index 0000000..58a3b84--- /dev/null+++ b/docs/locales/pt-BR/migrating-to-v0.5.md@@ -0,0 +1,293 @@+---+title: "Migrar para a v0.5"+description: "Passe do Scrapling v0.4.15 para a v0.5. Atualize as importações do navegador, a captura de rede, as ferramentas MCP, os comandos CLI, as configurações do parser e o comportamento dos spiders."+---++# Migrar para a v0.5 {#migrating-to-v05}++Este guia cobre as mudanças que você precisa verificar ao passar da **v0.4.15 para a v0.5**. Inclui APIs removidas, ferramentas renomeadas e correções que podem alterar os resultados do rastreamento ou os arquivos salvos.++## Lista rápida de migração {#quick-migration-checklist}++| Se você usa... | O que mudar |+| --- | --- |+| `DynamicFetcher`, `DynamicSession` ou `AsyncDynamicSession` | Use a classe de navegação furtiva correspondente. |+| `capture_xhr` ou `response.captured_xhr` | Use uma sessão de navegador com `record_requests=True` e `session.network`. |+| `keep_cdata` | Remova das configurações do parser e do fetcher. |+| `scrapling extract stealthy-fetch` ou `stealthy_fetch()` do shell | Use `fetch` no lugar. |+| Ferramentas MCP | Atualize os nomes das ferramentas, as chamadas de captura de tela e o tratamento da resposta de criação de sessão. |+| `response.follow()` após um POST ou uma solicitação com parâmetros de consulta | Passe o método, a consulta e o corpo novamente quando precisar deles. |+| Checkpoints de rastreamento ou caches de respostas salvos | Inicie um novo rastreamento se suas solicitações usarem os dados de entrada da impressão digital que mudaram. |+| `robots_txt_obey=True` | Trate as falhas ao obter robots.txt, que agora bloqueiam o rastreamento daquele domínio. |++## Obtenção com navegador {#browser-fetching}++### Substitua as classes de navegador dinâmico {#replace-the-dynamic-browser-classes}++O mecanismo de navegador que usava Playwright diretamente foi removido. Toda obtenção com navegador agora usa o mecanismo furtivo baseado em Patchright.++| API removida | Substituição |+| --- | --- |+| `scrapling.DynamicFetcher` | `scrapling.StealthyFetcher` |+| `scrapling.fetchers.DynamicFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.chrome.PlayWrightFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.DynamicSession` | `scrapling.fetchers.StealthySession` |+| `scrapling.fetchers.AsyncDynamicSession` | `scrapling.fetchers.AsyncStealthySession` |++O módulo `scrapling.fetchers.chrome` e o módulo privado `_browsers._controllers` foram removidos. Use as importações públicas acima.++**Antes:**++```python+from scrapling.fetchers import DynamicFetcher++page = DynamicFetcher.fetch("https://example.com", headless=True)+```++**Agora:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", headless=True)+```++Para sessões, substitua `DynamicSession` por `StealthySession`, ou `AsyncDynamicSession` por `AsyncStealthySession`. Faça a mesma mudança no método `configure_sessions()` do seu spider. Os padrões de uso de `fetch()` e `async with` continuam válidos.++Se seus callbacks importam tipos do navegador ou capturam erros do navegador, troque `playwright.sync_api` por `patchright.sync_api`, ou `playwright.async_api` por `patchright.async_api`. Isso inclui `Page`, `Locator`, `Error` e `TimeoutError`.++O Patchright avalia JavaScript em um contexto isolado por padrão. Se um callback lê as variáveis JavaScript da própria página, use `page.evaluate(..., isolated_context=False)`.++Isso muda o comportamento do navegador além do nome de importação. Revise as opções do navegador e as configurações de impressão digital. Resolver o Cloudflare ainda exige `solve_cloudflare=True`; isso não vem ativado por padrão. Além disso, `extra_flags` agora complementa as opções furtivas integradas, em vez de substituí-las.++Veja [Obtenção com navegador](fetching/stealthy.md) para conhecer as opções atuais.++### Substitua a captura XHR pelo histórico de rede da sessão {#replace-xhr-capture-with-session-network-history}++O parâmetro `capture_xhr` e o atributo `Response.captured_xhr` foram removidos. Remova o parâmetro mesmo quando seu valor for `None`. Uma obtenção avulsa não tem mais uma lista XHR anexada à resposta.++Integrações personalizadas que chamam `ResponseFactory.from_playwright_response()` ou `ResponseFactory.from_async_playwright_response()` também precisam remover `xhr_captured`. Passe `collect_history` pelo nome para evitar problemas com a mudança na ordem dos argumentos posicionais.++**Antes:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", capture_xhr="/api/")+for response in page.captured_xhr:+ print(response.url, response.body)+```++**Agora:**++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True) as session:+ page = session.fetch("https://example.com", network_idle=True)+ for response in session.network.search(url_pattern=r"/api/", limit=None):+ print(response.url, response.body)+```++Use `AsyncStealthySession` e `await session.fetch(...)` para código assíncrono. Ler `session.network` não exige `await`.++Há algumas diferenças importantes:++- Defina `record_requests=True` ao criar a sessão. É uma configuração da sessão, não de cada obtenção.+- O histórico pertence à **sessão inteira**, incluindo abas, carregamentos de páginas e ações. Use `after_id`, filtros ou `session.network.clear()` se precisar de um escopo menor.+- Mova a expressão regular antiga de `capture_xhr` para `url_pattern` ao pesquisar no histórico.+- `search()` retorna objetos `Response` salvos. Leia `.url`, `.status`, `.headers`, `.body` ou `.json()` diretamente. O ID do registro, o tipo de recurso e o corpo enviado estão em `response.meta["network_id"]`, `response.meta["resource_type"]` e `response.meta["request_body"]`.+- O histórico em Python inclui todos os tipos de recursos por padrão. Use `resource_type="xhr"` ou `resource_type="fetch"` para escolher um, ou `include_static=False` para solicitações XHR/fetch junto com erros HTTP.+- `search()` retorna no máximo 100 resultados por padrão. Passe `limit=None` para obter todos os resultados mantidos. As sessões mantêm até 1.000 solicitações por padrão; altere isso com `max_recorded_requests`.+- Só as solicitações concluídas são salvas. A captura do corpo é limitada aos tipos de conteúdo de texto aceitos, a 1 MiB por resposta e a 20 MiB de dados de corpo mantidos no total. Registros mais antigos podem ser removidos quando os limites forem atingidos. Veja `response.meta.get("body_note")` para saber por que um corpo foi ignorado.+- A leitura do histórico e o fechamento da sessão não aguardam as capturas pendentes. Espere os dados necessários antes de lê-los. O histórico em Python salvo continua disponível após fechar a sessão.++Veja [Histórico de rede](fetching/stealthy.md#network-history) para conhecer os filtros e limites.++## Configurações do parser {#parser-settings}++### Remova `keep_cdata` {#remove-keep_cdata}++`keep_cdata` foi removido de `Selector`, da configuração dos fetchers e das configurações retornadas por `display_config()`. Remova das chamadas diretas ao parser, de `Fetcher.configure(...)` e dos dicionários `selector_config` passados a fetchers ou integrações.++**Antes:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>", keep_cdata=True)+```++**Agora:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>")+```++Não há uma configuração substituta. Ela não afetava a saída do parser HTML. Se você passava as opções do parser por posição, remova o antigo argumento `keep_cdata` e use nomes para `adaptive` e as opções de armazenamento.++## Linha de comando e shell interativo {#command-line-and-interactive-shell}++### Use `fetch` para solicitações do navegador {#use-fetch-for-browser-requests}++A CLI agora tem um único comando de navegador: `scrapling extract fetch`. Ele usa `StealthyFetcher`.++**Antes:**++```bash+scrapling extract stealthy-fetch "https://example.com" page.md+```++**Agora:**++```bash+scrapling extract fetch "https://example.com" page.md+```++Se você já usa `scrapling extract fetch`, o nome do comando continua igual, mas seu mecanismo muda de `DynamicFetcher` para `StealthyFetcher`. Opções como `--solve-cloudflare` agora pertencem a `fetch`.++Em `scrapling shell`, substitua `stealthy_fetch(...)` por `fetch(...)`. O atalho existente `fetch(...)` agora chama `StealthyFetcher.fetch`. As classes dinâmicas não são mais adicionadas ao espaço de nomes do shell.++### Leia arquivos Markdown e de texto como UTF-8 {#read-markdown-and-text-files-as-utf-8}++Os comandos de extração e `Convertor.write_content_to_file()` agora gravam arquivos `.md` e `.txt` em **UTF-8**, independentemente do conjunto de caracteres da página de origem. Atualize qualquer código que leia esses arquivos com a codificação original da página. A saída `.html` ainda usa `page.encoding`.++O Markdown de vários elementos selecionados agora tem linhas em branco entre os elementos. Isso se aplica a `Response.markdown()` e à saída em arquivos Markdown. Atualize as comparações exatas da saída ou os hashes salvos que dependiam do texto concatenado.++## Servidor MCP {#mcp-server}++Atualize os prompts salvos, as listas de ferramentas permitidas, os wrappers e as definições de ferramentas do cliente MCP. Reinicie ou reconecte seu cliente MCP após atualizar o servidor para que ele leia as ferramentas atuais.++### Atualize os nomes de ferramentas e as chamadas em lote {#update-tool-names-and-bulk-calls}++| Ferramenta da v0.4.15 | Substituição na v0.5 |+| --- | --- |+| `fetch`, `stealthy_fetch` | `browser_fetch_once` |+| `open_session` | `browser_open` |+| `session_fetch` | `browser_fetch` |+| `screenshot` | `browser_screenshot` |+| `bulk_fetch`, `bulk_stealthy_fetch` | Uma chamada de `browser_fetch_once` por URL, ou chamadas repetidas de `browser_fetch` por uma sessão aberta |+| `bulk_get` | Uma chamada de `make_request` ou `session_make_request` por URL |++Todas as ferramentas em lote foram removidas. As ferramentas que obtêm uma única URL retornam um `ResponseModel` com `status`, `content` e `url`, não uma lista de respostas. O próprio `content` ainda é uma lista de strings.++Todas as ferramentas de navegador MCP agora usam o mecanismo furtivo. Remova `session_type` das chamadas de `browser_open`; não existe mais a opção de navegador dinâmico. O resultado contém `session_type="stealthy"`. As sessões HTTP ainda usam `open_request_session` e retornam `session_type="static"`.++As integrações Python também devem parar de importar `BrowserSessionType`, que foi removido. `SessionType` agora aceita apenas `"stealthy"` e `"static"`.++As chamadas por uma mesma sessão de navegador devem ser executadas em ordem porque compartilham uma página. Feche as sessões com `close_session` ao terminar.++### Leia as configurações por `list_sessions` {#read-settings-through-list_sessions}++`browser_open` e `open_request_session` agora retornam apenas:++```json+{+ "session_id": "my-session",+ "session_type": "stealthy"+}+```++O resultado da criação não inclui mais `created_at`, `is_alive`, `settings` ou `message`. Chame `list_sessions` para obter os três primeiros campos. A confirmação `message` foi removida. O código que assumia que `SessionCreatedModel` tinha todos os campos de `SessionInfo` também precisa mudar.++### Obtenha a página antes de fazer uma captura de tela {#fetch-before-taking-a-screenshot}++`browser_screenshot` captura a **página atual sem recarregá-la**. Não aceita mais uma URL nem as opções antigas de navegação e espera: `wait`, `wait_selector`, `wait_selector_state` e `network_idle`.++Use esta ordem:++1. Chame `browser_open`.+2. Chame `browser_fetch` com a URL e as opções de carregamento da página que precisar.+3. Se necessário, chame `browser_actions` para interagir com a página ou esperar o conteúdo.+4. Chame `browser_screenshot` com o ID da sessão.+5. Chame `close_session` ao terminar.++Por exemplo, os argumentos para uma captura da página inteira são:++```json+{+ "session_id": "my-session",+ "full_page": true+}+```++O `timeout` dessa ferramenta agora limita a operação de captura de tela. A ferramenta não carrega uma página. Para capturar um elemento, use `selector` ou `ref` e não defina `full_page=true`.++As capturas de tela ainda retornam blocos de conteúdo de imagem e texto, com a URL da página atual no bloco de texto. Não retornam um `ResponseModel` de obtenção.++Veja o [guia MCP](ai/mcp-server.md) e a [referência da API](api-reference/mcp-server.md) para conhecer os esquemas completos.++## Spiders e solicitações HTTP {#spiders-and-http-requests}++### Passe os dados da solicitação novamente ao seguir um link {#pass-request-data-again-when-following-a-link}++`response.follow()` não copia mais `method`, `params`, `data`, `json`, `files` ou `multipart` da solicitação anterior. Também remove os cabeçalhos `Content-Length` herdados de `headers` e `extra_headers`.++Um link seguido agora começa como uma solicitação GET simples, a menos que você passe os dados da solicitação explicitamente. Outras configurações compartilhadas, como a sessão, o proxy e os callbacks, ainda seguem as regras de herança existentes.++Se seu código antigo dependia de dados POST herdados, troque:++```python+yield response.follow("/next")+```++por:++```python+yield response.follow("/next", method="POST", json={"page": 2})+```++Passe `params` explicitamente também quando a próxima solicitação precisar deles. Deixe o cliente HTTP calcular o novo `Content-Length`.++### Verifique as impressões digitais das solicitações e o estado de rastreamento salvo {#check-request-fingerprints-and-saved-crawl-state}++A impressão digital de uma solicitação é a chave usada para detectar solicitações duplicadas e encontrar respostas em cache. Seus dados de entrada agora tratam três casos de forma diferente:++- Os `params` são combinados com a URL antes de criar a chave. Solicitações para a mesma URL com parâmetros de consulta diferentes não são mais tratadas como duplicadas por padrão.+- Corpos JSON como `{}`, `[]`, `false`, `0` e `""` são mantidos na chave. Eles não compartilham mais a chave de um corpo ausente. `None` ainda significa que não há corpo JSON.+- Com `fp_include_headers=True`, mudar apenas a ordem de inserção dos cabeçalhos não altera mais a chave.++Se seu rastreamento usa esses dados de entrada, termine antes de atualizar ou inicie um novo rastreamento com um novo checkpoint e um novo diretório de cache de respostas. As chaves antigas salvas podem ser diferentes das novas. Essa é uma mudança na identidade da solicitação, não um novo formato de arquivo de checkpoint.++O modo de desenvolvimento agora só grava respostas no cache após verificar se estão bloqueadas. Páginas bloqueadas não são salvas como resultados bem-sucedidos em cache. Os arquivos de cache existentes não são limpos automaticamente; remova entradas antigas se você já armazenou uma página de verificação.++Os rastreamentos que falham agora mantêm seus arquivos de checkpoint. Verifique seu código de limpeza se ele assumia que esses arquivos desapareciam após um erro. Veja [Pausar e retomar](spiders/advanced.md#pause-resume) e [Modo de desenvolvimento](spiders/advanced.md#development-mode).++### Verifique as falhas de robots.txt {#check-robotstxt-failures}++Com `robots_txt_obey=True`, uma exceção ao obter robots.txt ou uma resposta diferente de HTTP 200 ou 4xx agora bloqueia solicitações para aquele domínio. Antes, essas falhas permitiam o rastreamento. HTTP 200 ainda fornece as regras, e HTTP 4xx ainda permite o acesso.++O resultado fica em cache durante todo o rastreamento. Corrija o problema de acesso a robots.txt e inicie um novo rastreamento; as solicitações seguintes do mesmo rastreamento não repetirão a consulta que falhou. Isso não altera o padrão `robots_txt_obey=False`.++### Verifique as restrições de links e os callbacks de sitemaps {#check-link-restrictions-and-sitemap-callbacks}++- Uma restrição de `LinkExtractor` que não encontra nada agora não retorna links. Ela não usa mais a página inteira como alternativa. Corrija a expressão `restrict_css` ou `restrict_xpath` se seu rastreamento agora encontrar menos links.+- Uma restrição agora pode selecionar o próprio elemento do link, não apenas um elemento pai. Isso pode adicionar links que antes eram ignorados. Revise os conjuntos de URLs esperados.+- `SitemapSpider` agora envia URLs de páginas para `parse()` quando não há regras ou quando uma regra correspondente tem `callback=None`. Ele não envia mais essas páginas HTML de volta ao parser do sitemap. Implemente `parse()` para esses casos e remova as soluções alternativas para o roteamento antigo.+- A marca de ordem de bytes Unicode no início de robots.txt e de feeds CSV é removida. A primeira diretiva de robots agora tem efeito, e o primeiro cabeçalho CSV não começa mais com `\ufeff`. Se você definir `headers` personalizados, a marca será removida do valor do primeiro campo. Atualize o código que compensava esse prefixo oculto. Comentários XML e instruções de processamento de sitemaps também são ignorados, em vez de causar uma falha de análise.++### Verifique dados de formulários, cabeçalhos e JSON da CLI {#check-form-data-headers-and-cli-json}++Dados de formulários em dicionários agora expandem valores de listas e tuplas em chaves repetidas. Por exemplo, `data={"tag": ["a", "b"]}` envia `tag=a&tag=b`. Uma lista vazia não envia nenhuma entrada para essa chave. O cabeçalho padrão `Content-Type: application/x-www-form-urlencoded` é adicionado quando você não fornece um.++Se precisar de outro formato de envio, passe uma string ou bytes codificados explicitamente. `json`, `content` bruto e uploads multipart mantêm seu próprio tratamento do corpo. Valores `None` **não são removidos** dos dados de formulários ou parâmetros de consulta; eles continuam como a string `None`.++Os cabeçalhos HTTP de cada solicitação agora substituem os cabeçalhos da sessão sem diferenciar maiúsculas de minúsculas. Um cabeçalho de solicitação chamado `authorization` substitui o `Authorization` da sessão em vez de enviar ambos. Remova o código que compensava nomes de cabeçalhos duplicados.++Os valores JSON da CLI `{}`, `[]`, `false`, `0` e `""` agora são enviados em vez de descartados sem aviso. Além disso, `curl2fetcher()` agora aplica o agente de usuário de `-A` do curl e passa corretamente os proxies de `-x` como uma string de URL. Um cabeçalho explícito `-H 'User-Agent: ...'` do curl ainda tem prioridade sobre `-A`.++## Outras mudanças na saída a verificar {#other-output-changes-to-check}++Estas correções não removem APIs, mas podem alterar resultados salvos e testes de saída exata:++- Os seletores CSS e XPath gerados agora incluem `:nth-of-type(1)` ou `[1]` quando necessário para identificar o primeiro de vários elementos irmãos com a mesma tag. Atualize as strings de seletores esperadas; não remova a nova marca de posição.+- O conteúdo limpo para IA agora mantém elementos visíveis com valores como `opacity:0.95`, remove elementos ocultos por mais variações de estilos inline e elementos `<slot hidden>`, e remove todas as tags de ruído correspondentes mesmo quando estão aninhadas. Verifique novamente a saída exata de Markdown, texto e HTML sanitizado.+- A conversão de respostas do navegador agora lê declarações de charset com diferenças entre maiúsculas e minúsculas, espaços ou valores entre aspas, como `text/plain; CHARSET = "iso-8859-15"`. Respostas que não são HTML e têm esses cabeçalhos agora usam a codificação declarada em vez de recorrer ao UTF-8. Verifique novamente o texto decodificado dessas respostas.++## Verifique a atualização {#verify-your-upgrade}++Execute um rastreamento pequeno antes do trabalho completo. Verifique os dados extraídos, as URLs seguidas, os corpos das solicitações enviadas, a codificação dos arquivos salvos e qualquer comportamento de cache ou checkpoint de que você dependa. Para integrações MCP, verifique os dados de entrada das ferramentas e os dados retornados de acordo com os esquemas atuais.++Para mudanças de versões anteriores, veja o [histórico de alterações](changelog.md).diff --git a/docs/locales/ru/migrating-to-v0.5.md b/docs/locales/ru/migrating-to-v0.5.mdnew file mode 100644index 0000000..7e73a7a--- /dev/null+++ b/docs/locales/ru/migrating-to-v0.5.md@@ -0,0 +1,293 @@+---+title: "Переход на v0.5"+description: "Переход со Scrapling v0.4.15 на v0.5. Обновите импорты браузера, запись сетевых запросов, инструменты MCP, команды CLI, настройки парсера и поведение пауков."+---++# Переход на v0.5 {#migrating-to-v05}++В этом руководстве описаны изменения, которые нужно проверить при переходе с **v0.4.15 на v0.5**. Сюда входят удалённые API, переименованные инструменты и исправления, которые могут изменить результаты обхода или сохранённые файлы.++## Краткий список изменений {#quick-migration-checklist}++| Если вы используете... | Что изменить |+| --- | --- |+| `DynamicFetcher`, `DynamicSession` или `AsyncDynamicSession` | Используйте соответствующий класс со скрытным режимом. |+| `capture_xhr` или `response.captured_xhr` | Используйте браузерную сессию с `record_requests=True` и `session.network`. |+| `keep_cdata` | Удалите из настроек парсера и Fetcher. |+| `scrapling extract stealthy-fetch` или `stealthy_fetch()` в оболочке | Используйте `fetch` вместо них. |+| Инструменты MCP | Обновите имена инструментов, вызовы снимков экрана и обработку ответа при создании сессии. |+| `response.follow()` после POST-запроса или запроса с параметрами строки запроса | Передайте метод, параметры и тело заново, если они нужны. |+| Сохранённые контрольные точки обхода или кэши ответов | Начните новый обход, если ваши запросы используют изменившиеся входные данные отпечатка. |+| `robots_txt_obey=True` | Обрабатывайте ошибки загрузки robots.txt: теперь они блокируют обход этого домена. |++## Загрузка через браузер {#browser-fetching}++### Замените классы динамического браузера {#replace-the-dynamic-browser-classes}++Браузерный движок, который напрямую использовал Playwright, удалён. Теперь вся загрузка через браузер использует скрытный движок на основе Patchright.++| Удалённый API | Замена |+| --- | --- |+| `scrapling.DynamicFetcher` | `scrapling.StealthyFetcher` |+| `scrapling.fetchers.DynamicFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.chrome.PlayWrightFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.DynamicSession` | `scrapling.fetchers.StealthySession` |+| `scrapling.fetchers.AsyncDynamicSession` | `scrapling.fetchers.AsyncStealthySession` |++Модуль `scrapling.fetchers.chrome` и приватный модуль `_browsers._controllers` удалены. Используйте публичные импорты из таблицы выше.++**Раньше:**++```python+from scrapling.fetchers import DynamicFetcher++page = DynamicFetcher.fetch("https://example.com", headless=True)+```++**Теперь:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", headless=True)+```++Для сессий замените `DynamicSession` на `StealthySession`, а `AsyncDynamicSession` на `AsyncStealthySession`. Сделайте ту же замену в методе `configure_sessions()` вашего паука. Способы использования `fetch()` и `async with` остаются прежними.++Если ваши обработчики импортируют типы браузера или перехватывают его ошибки, замените `playwright.sync_api` на `patchright.sync_api` или `playwright.async_api` на `patchright.async_api`. Это относится к `Page`, `Locator`, `Error` и `TimeoutError`.++По умолчанию Patchright выполняет JavaScript в изолированном контексте. Если обработчик читает собственные JavaScript-переменные страницы, используйте `page.evaluate(..., isolated_context=False)`.++Меняется не только имя импорта, но и поведение браузера. Проверьте флаги браузера и настройки отпечатка. Для прохождения Cloudflare по-прежнему нужно `solve_cloudflare=True`; по умолчанию эта возможность отключена. Кроме того, `extra_flags` теперь дополняет встроенные флаги скрытного режима, а не заменяет их.++Текущие параметры описаны в разделе [Загрузка через браузер](fetching/stealthy.md).++### Замените захват XHR историей сетевых запросов сессии {#replace-xhr-capture-with-session-network-history}++Параметр `capture_xhr` и атрибут `Response.captured_xhr` удалены. Удалите параметр, даже если его значение равно `None`. Ответ разовой загрузки больше не содержит список XHR.++Пользовательские интеграции, вызывающие `ResponseFactory.from_playwright_response()` или `ResponseFactory.from_async_playwright_response()`, также должны удалить `xhr_captured`. Передавайте `collect_history` по имени, чтобы избежать проблем из-за нового порядка позиционных аргументов.++**Раньше:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", capture_xhr="/api/")+for response in page.captured_xhr:+ print(response.url, response.body)+```++**Теперь:**++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True) as session:+ page = session.fetch("https://example.com", network_idle=True)+ for response in session.network.search(url_pattern=r"/api/", limit=None):+ print(response.url, response.body)+```++В асинхронном коде используйте `AsyncStealthySession` и `await session.fetch(...)`. Для чтения `session.network` не нужен `await`.++Есть несколько важных отличий:++- Задайте `record_requests=True` при создании сессии. Это настройка сессии, а не отдельной загрузки.+- История относится ко **всей сессии**, включая вкладки, загрузки страниц и действия. Используйте `after_id`, фильтры или `session.network.clear()`, если нужен более узкий охват.+- При поиске в истории перенесите прежнее регулярное выражение из `capture_xhr` в `url_pattern`.+- `search()` возвращает сохранённые объекты `Response`. Читайте `.url`, `.status`, `.headers`, `.body` или `.json()` напрямую. ID записи, тип ресурса и отправленное тело находятся в `response.meta["network_id"]`, `response.meta["resource_type"]` и `response.meta["request_body"]`.+- История в Python по умолчанию включает все типы ресурсов. Используйте `resource_type="xhr"` или `resource_type="fetch"`, чтобы выбрать один тип, либо `include_static=False` для запросов XHR/fetch вместе с ошибками HTTP.+- `search()` по умолчанию возвращает не более 100 совпадений. Передайте `limit=None`, чтобы получить все сохранённые совпадения. Сессии по умолчанию хранят не более 1 000 запросов; это можно изменить через `max_recorded_requests`.+- Сохраняются только завершённые запросы. Захват тела доступен только для поддерживаемых текстовых типов содержимого. Ограничения составляют 1 MiB на ответ и 20 MiB для всех сохранённых тел ответов. При достижении лимитов старые записи могут удаляться. Причину пропуска тела можно узнать через `response.meta.get("body_note")`.+- Чтение истории или закрытие сессии не ожидает завершения записи ответов. Дождитесь нужных данных, прежде чем читать их. Сохранённая история Python остаётся доступной после закрытия сессии.++Фильтры и ограничения описаны в разделе [История сетевых запросов](fetching/stealthy.md#network-history).++## Настройки парсера {#parser-settings}++### Удалите `keep_cdata` {#remove-keep_cdata}++`keep_cdata` удалён из `Selector`, конфигурации Fetcher и настроек, которые возвращает `display_config()`. Удалите его из прямых вызовов парсера, `Fetcher.configure(...)` и словарей `selector_config`, передаваемых в Fetcher или интеграции.++**Раньше:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>", keep_cdata=True)+```++**Теперь:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>")+```++Замены этой настройке нет. Она не влияла на результат HTML-парсера. Если вы передавали настройки парсера по позиции, удалите старый аргумент `keep_cdata` и передавайте `adaptive` и настройки хранения по имени.++## Командная строка и интерактивная оболочка {#command-line-and-interactive-shell}++### Используйте `fetch` для запросов через браузер {#use-fetch-for-browser-requests}++В CLI теперь одна браузерная команда: `scrapling extract fetch`. Она использует `StealthyFetcher`.++**Раньше:**++```bash+scrapling extract stealthy-fetch "https://example.com" page.md+```++**Теперь:**++```bash+scrapling extract fetch "https://example.com" page.md+```++Если вы уже используете `scrapling extract fetch`, имя команды не меняется, но её движок меняется с `DynamicFetcher` на `StealthyFetcher`. Такие параметры, как `--solve-cloudflare`, теперь относятся к `fetch`.++В `scrapling shell` замените `stealthy_fetch(...)` на `fetch(...)`. Существующий сокращённый вызов `fetch(...)` теперь вызывает `StealthyFetcher.fetch`. Динамические классы больше не добавляются в пространство имён оболочки.++### Читайте файлы Markdown и текстовые файлы как UTF-8 {#read-markdown-and-text-files-as-utf-8}++Команды извлечения и `Convertor.write_content_to_file()` теперь записывают файлы `.md` и `.txt` в **UTF-8**, независимо от кодировки исходной страницы. Обновите код, который читает эти файлы в исходной кодировке страницы. Вывод `.html` по-прежнему использует `page.encoding`.++Markdown из нескольких выбранных элементов теперь содержит пустые строки между элементами. Это относится к `Response.markdown()` и записи файлов Markdown. Обновите точные сравнения вывода или сохранённые хеши, которые зависели от текста, склеенного без разделителей.++## MCP-сервер {#mcp-server}++Обновите сохранённые промпты, списки разрешённых инструментов, обёртки и определения инструментов MCP-клиента. После обновления сервера перезапустите или переподключите MCP-клиент, чтобы он прочитал текущий список инструментов.++### Обновите имена инструментов и пакетные вызовы {#update-tool-names-and-bulk-calls}++| Инструмент в v0.4.15 | Замена в v0.5 |+| --- | --- |+| `fetch`, `stealthy_fetch` | `browser_fetch_once` |+| `open_session` | `browser_open` |+| `session_fetch` | `browser_fetch` |+| `screenshot` | `browser_screenshot` |+| `bulk_fetch`, `bulk_stealthy_fetch` | Один вызов `browser_fetch_once` на URL или повторные вызовы `browser_fetch` через открытую сессию |+| `bulk_get` | Один вызов `make_request` или `session_make_request` на URL |++Все пакетные инструменты удалены. Инструменты загрузки одного URL возвращают один `ResponseModel` с `status`, `content` и `url`, а не список ответов. Само поле `content` по-прежнему содержит список строк.++Все браузерные инструменты MCP теперь используют скрытный движок. Удалите `session_type` из вызовов `browser_open`; выбор динамического браузера больше недоступен. Результат содержит `session_type="stealthy"`. HTTP-сессии по-прежнему используют `open_request_session` и возвращают `session_type="static"`.++Интеграции Python также должны перестать импортировать удалённый `BrowserSessionType`. `SessionType` теперь принимает только `"stealthy"` и `"static"`.++Вызовы в одной браузерной сессии должны выполняться по порядку, так как они используют общую страницу. По завершении закрывайте сессии через `close_session`.++### Читайте настройки через `list_sessions` {#read-settings-through-list_sessions}++`browser_open` и `open_request_session` теперь возвращают только:++```json+{+ "session_id": "my-session",+ "session_type": "stealthy"+}+```++Результат создания больше не включает `created_at`, `is_alive`, `settings` или `message`. Вызовите `list_sessions`, чтобы получить первые три поля. Подтверждение `message` удалено. Код, который предполагал, что `SessionCreatedModel` содержит все поля `SessionInfo`, тоже нужно изменить.++### Загрузите страницу перед снимком экрана {#fetch-before-taking-a-screenshot}++`browser_screenshot` снимает **текущую страницу без повторной загрузки**. Инструмент больше не принимает URL и прежние параметры перехода и ожидания: `wait`, `wait_selector`, `wait_selector_state` и `network_idle`.++Используйте такой порядок:++1. Вызовите `browser_open`.+2. Вызовите `browser_fetch` с URL и нужными параметрами загрузки страницы.+3. При необходимости вызовите `browser_actions`, чтобы взаимодействовать со страницей или дождаться содержимого.+4. Вызовите `browser_screenshot` с ID сессии.+5. По завершении вызовите `close_session`.++Например, аргументы для снимка всей страницы:++```json+{+ "session_id": "my-session",+ "full_page": true+}+```++Параметр `timeout` этого инструмента теперь ограничивает время создания снимка. Инструмент не загружает страницу. Для снимка элемента используйте `selector` или `ref` и не задавайте `full_page=true`.++Снимки экрана по-прежнему возвращают блоки изображения и текста. Текстовый блок содержит URL текущей страницы. Они не возвращают `ResponseModel` загрузки.++Полные схемы приведены в [руководстве MCP](ai/mcp-server.md) и [справочнике API](api-reference/mcp-server.md).++## Пауки и HTTP-запросы {#spiders-and-http-requests}++### Передавайте данные запроса заново при переходе по ссылке {#pass-request-data-again-when-following-a-link}++`response.follow()` больше не копирует `method`, `params`, `data`, `json`, `files` или `multipart` из предыдущего запроса. Он также удаляет унаследованные заголовки `Content-Length` из `headers` и `extra_headers`.++Переход по ссылке теперь начинается с обычного GET-запроса, если данные запроса не переданы явно. Другие общие настройки, например сессия, прокси и обработчики, по-прежнему следуют существующим правилам наследования.++Если старый код зависел от унаследованных POST-данных, замените:++```python+yield response.follow("/next")+```++на:++```python+yield response.follow("/next", method="POST", json={"page": 2})+```++Также явно передавайте `params`, если они нужны следующему запросу. Позвольте HTTP-клиенту вычислить новый `Content-Length`.++### Проверьте отпечатки запросов и сохранённое состояние обхода {#check-request-fingerprints-and-saved-crawl-state}++Отпечаток запроса служит ключом для поиска повторных запросов и ответов в кэше. Теперь его входные данные обрабатываются иначе в трёх случаях:++- `params` объединяются с URL до создания ключа. Запросы к одному URL с разными параметрами строки запроса больше не считаются дубликатами по умолчанию.+- JSON-тела, такие как `{}`, `[]`, `false`, `0` и `""`, сохраняются в ключе. Их ключ больше не совпадает с ключом запроса без тела. `None` по-прежнему означает отсутствие JSON-тела.+- При `fp_include_headers=True` изменение только порядка добавления заголовков больше не меняет ключ.++Если ваш обход использует эти данные, завершите его до обновления или начните новый обход с новой контрольной точкой и новым каталогом кэша ответов. Старые сохранённые ключи могут отличаться от новых. Это изменение идентичности запроса, а не новый формат файла контрольной точки.++Режим разработки теперь записывает ответы в кэш только после проверки на блокировку. Страницы блокировки не сохраняются в кэше как успешные результаты. Существующие файлы кэша не очищаются автоматически. Удалите устаревшие записи, если ранее сохраняли страницу проверки.++Неудачные обходы теперь сохраняют файлы контрольных точек. Проверьте код очистки, если он предполагал, что эти файлы исчезают после ошибки. См. [Пауза и возобновление](spiders/advanced.md#pause-resume) и [Режим разработки](spiders/advanced.md#development-mode).++### Проверьте ошибки robots.txt {#check-robotstxt-failures}++При `robots_txt_obey=True` исключение во время загрузки robots.txt или ответ, отличный от HTTP 200 или 4xx, теперь блокирует запросы к этому домену. Раньше такие ошибки разрешали обход. HTTP 200 по-прежнему предоставляет правила, а HTTP 4xx разрешает доступ.++Результат хранится в кэше на протяжении всего обхода. Исправьте проблему доступа к robots.txt и начните новый обход. Последующие запросы в том же обходе не повторяют неудачную загрузку. Значение по умолчанию `robots_txt_obey=False` не меняется.++### Проверьте ограничения ссылок и обработчики карт сайта {#check-link-restrictions-and-sitemap-callbacks}++- Ограничение `LinkExtractor`, которое ничего не находит, теперь не возвращает ссылки. Оно больше не переключается на всю страницу. Исправьте выражение `restrict_css` или `restrict_xpath`, если обход стал находить меньше ссылок.+- Ограничение теперь может выбрать сам элемент ссылки, а не только родительский элемент. Это может добавить ссылки, которые раньше пропускались. Проверьте ожидаемые наборы URL.+- `SitemapSpider` теперь передаёт URL страниц в `parse()`, если правил нет или у подходящего правила задано `callback=None`. Эти HTML-страницы больше не возвращаются в парсер карты сайта. Реализуйте `parse()` для таких случаев и удалите обходные решения для прежней маршрутизации.+- Начальная метка порядка байтов Unicode удаляется из robots.txt и CSV-каналов. Первая директива robots теперь действует, а заголовок первого столбца CSV больше не начинается с `\ufeff`. Если заданы собственные `headers`, метка удаляется из значения первого поля. Обновите код, который обходил этот невидимый префикс. XML-комментарии и инструкции обработки в картах сайта тоже пропускаются, а не вызывают ошибку разбора.++### Проверьте данные форм, заголовки и JSON в CLI {#check-form-data-headers-and-cli-json}++В данных формы, переданных словарём, значения списков и кортежей теперь разворачиваются в повторяющиеся ключи. Например, `data={"tag": ["a", "b"]}` отправляет `tag=a&tag=b`. Пустой список не отправляет ни одной записи для этого ключа. Если вы не задали заголовок Content-Type, добавляется значение по умолчанию `Content-Type: application/x-www-form-urlencoded`.++Если нужен другой формат передачи, передайте явно закодированную строку или байты. `json`, необработанный `content` и загрузки multipart сохраняют собственную обработку тела. Значения `None` **не удаляются** из данных форм и параметров строки запроса. Они остаются строкой `None`.++HTTP-заголовки отдельного запроса теперь заменяют заголовки сессии независимо от регистра букв. Заголовок запроса `authorization` заменяет `Authorization` сессии, а не отправляется вместе с ним. Удалите код, который обходил повторяющиеся имена заголовков.++Значения JSON в CLI `{}`, `[]`, `false`, `0` и `""` теперь отправляются, а не отбрасываются без уведомления. Кроме того, `curl2fetcher()` теперь применяет User-Agent из параметра curl `-A` и правильно передаёт прокси из `-x` как строку URL. Явный заголовок curl `-H 'User-Agent: ...'` по-прежнему имеет приоритет над `-A`.++## Другие изменения вывода, которые нужно проверить {#other-output-changes-to-check}++Эти исправления не удаляют API, но могут изменить сохранённые результаты и тесты на точное совпадение вывода:++- Сгенерированные селекторы CSS и XPath теперь включают `:nth-of-type(1)` или `[1]`, когда это нужно для выбора первого из нескольких элементов с общим родителем и одинаковым тегом. Обновите ожидаемые строки селекторов. Не удаляйте новую отметку позиции.+- Очищенное содержимое для ИИ теперь сохраняет видимые элементы со значениями вроде `opacity:0.95`, удаляет элементы, скрытые большим числом вариантов встроенных стилей, и элементы `<slot hidden>`. Оно также удаляет все подходящие лишние теги, даже вложенные. Перепроверьте точный вывод Markdown, текста и очищенного HTML.+- Преобразование браузерных ответов теперь читает объявления charset с другим регистром букв, пробелами или значениями в кавычках, например `text/plain; CHARSET = "iso-8859-15"`. Ответы не в формате HTML с такими заголовками теперь используют объявленную кодировку, а не UTF-8 в качестве запасного варианта. Перепроверьте текст, декодированный из этих ответов.++## Проверьте обновление {#verify-your-upgrade}++Запустите небольшой обход перед полной задачей. Проверьте извлечённые данные, посещённые по ссылкам URL, отправленные тела запросов, кодировку сохранённых файлов и поведение кэша или контрольных точек, на которое вы полагаетесь. Для интеграций MCP сверьте входные данные инструментов и возвращаемые данные с текущими схемами.++Изменения прежних выпусков описаны в [истории изменений](changelog.md).diff --git a/docs/locales/zh/migrating-to-v0.5.md b/docs/locales/zh/migrating-to-v0.5.mdnew file mode 100644index 0000000..0711046--- /dev/null+++ b/docs/locales/zh/migrating-to-v0.5.md@@ -0,0 +1,293 @@+---+title: "迁移到 v0.5"+description: "从 Scrapling v0.4.15 升级到 v0.5。更新浏览器导入、网络记录、MCP 工具、CLI 命令、解析器设置和爬虫行为。"+---++# 迁移到 v0.5 {#migrating-to-v05}++本指南介绍从 **v0.4.15 升级到 v0.5** 时需要检查的变化,包括已移除的 API、重命名的工具,以及可能改变抓取结果或已保存文件的修复。++## 迁移速查表 {#quick-migration-checklist}++| 如果使用了…… | 需要修改的内容 |+| --- | --- |+| `DynamicFetcher`、`DynamicSession` 或 `AsyncDynamicSession` | 使用对应的隐身类。 |+| `capture_xhr` 或 `response.captured_xhr` | 使用启用了 `record_requests=True` 的浏览器会话和 `session.network`。 |+| `keep_cdata` | 从解析器和 Fetcher 设置中移除。 |+| `scrapling extract stealthy-fetch` 或 Shell 中的 `stealthy_fetch()` | 改用 `fetch`。 |+| MCP 工具 | 更新工具名称、截图调用,以及会话创建响应的处理方式。 |+| 在 POST 请求或带查询参数的请求后使用 `response.follow()` | 需要时再次传入方法、查询参数和请求体。 |+| 已保存的抓取检查点或响应缓存 | 如果请求使用了已变化的指纹输入,请开始新的抓取。 |+| `robots_txt_obey=True` | 处理 robots.txt 获取失败的情况。现在这会阻止对该域名的抓取。 |++## 浏览器抓取 {#browser-fetching}++### 替换动态浏览器类 {#replace-the-dynamic-browser-classes}++直接使用 Playwright 的浏览器后端已被移除。所有浏览器抓取现在都使用基于 Patchright 的隐身后端。++| 已移除的 API | 替代 API |+| --- | --- |+| `scrapling.DynamicFetcher` | `scrapling.StealthyFetcher` |+| `scrapling.fetchers.DynamicFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.chrome.PlayWrightFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.DynamicSession` | `scrapling.fetchers.StealthySession` |+| `scrapling.fetchers.AsyncDynamicSession` | `scrapling.fetchers.AsyncStealthySession` |++`scrapling.fetchers.chrome` 模块和私有的 `_browsers._controllers` 模块已被移除。请使用上表中的公开导入路径。++**之前:**++```python+from scrapling.fetchers import DynamicFetcher++page = DynamicFetcher.fetch("https://example.com", headless=True)+```++**现在:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", headless=True)+```++对于会话,将 `DynamicSession` 替换为 `StealthySession`,或将 `AsyncDynamicSession` 替换为 `AsyncStealthySession`。在爬虫的 `configure_sessions()` 方法中也做相同修改。`fetch()` 和 `async with` 的用法仍然适用。++如果回调导入了浏览器类型或捕获浏览器错误,将 `playwright.sync_api` 改为 `patchright.sync_api`,或将 `playwright.async_api` 改为 `patchright.async_api`。这包括 `Page`、`Locator`、`Error` 和 `TimeoutError`。++Patchright 默认在隔离的上下文中执行 JavaScript。如果回调需要读取页面自身的 JavaScript 变量,请使用 `page.evaluate(..., isolated_context=False)`。++除了导入名称,浏览器行为也会改变。请检查浏览器启动参数和指纹设置。处理 Cloudflare 验证仍需设置 `solve_cloudflare=True`,默认不会启用。此外,`extra_flags` 现在会追加到内置隐身启动参数中,而不是替换它们。++当前选项见[浏览器抓取](fetching/stealthy.md)。++### 用会话网络历史替代 XHR 捕获 {#replace-xhr-capture-with-session-network-history}++`capture_xhr` 参数和 `Response.captured_xhr` 属性已被移除。即使参数值为 `None`,也需要移除该参数。单次抓取的响应不再附带 XHR 列表。++调用 `ResponseFactory.from_playwright_response()` 或 `ResponseFactory.from_async_playwright_response()` 的自定义集成也必须移除 `xhr_captured`。请按名称传入 `collect_history`,避免位置参数顺序变化带来的问题。++**之前:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", capture_xhr="/api/")+for response in page.captured_xhr:+ print(response.url, response.body)+```++**现在:**++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True) as session:+ page = session.fetch("https://example.com", network_idle=True)+ for response in session.network.search(url_pattern=r"/api/", limit=None):+ print(response.url, response.body)+```++异步代码使用 `AsyncStealthySession` 和 `await session.fetch(...)`。读取 `session.network` 不需要 `await`。++需要注意以下区别:++- 在创建会话时设置 `record_requests=True`。这是会话设置,不能按单次抓取设置。+- 历史记录属于**整个会话**,涵盖各个标签页、页面加载和操作。如果需要缩小范围,请使用 `after_id`、筛选条件或 `session.network.clear()`。+- 搜索历史记录时,将原来的 `capture_xhr` 正则表达式移到 `url_pattern`。+- `search()` 返回已保存的 `Response` 对象。直接读取 `.url`、`.status`、`.headers`、`.body` 或 `.json()`。记录 ID、资源类型和已发送的请求体分别位于 `response.meta["network_id"]`、`response.meta["resource_type"]` 和 `response.meta["request_body"]`。+- Python 历史记录默认包含所有资源类型。使用 `resource_type="xhr"` 或 `resource_type="fetch"` 选择其中一种,或使用 `include_static=False` 获取 XHR/fetch 请求和 HTTP 错误。+- `search()` 默认最多返回 100 条匹配记录。传入 `limit=None` 可获取所有保留的匹配记录。会话默认最多保留 1,000 个请求;可通过 `max_recorded_requests` 修改。+- 只保存已完成的请求。响应体捕获仅支持指定的文本内容类型,每个响应最多 1 MiB,保留的响应体数据总量最多 20 MiB。达到限制时,较旧的记录可能被移除。查看 `response.meta.get("body_note")` 可了解跳过响应体的原因。+- 读取历史记录或关闭会话不会等待尚未完成的捕获。请先等待所需数据就绪,再读取数据。会话关闭后,已保存的 Python 历史记录仍可读取。++筛选条件和限制见[网络历史](fetching/stealthy.md#network-history)。++## 解析器设置 {#parser-settings}++### 移除 `keep_cdata` {#remove-keep_cdata}++`keep_cdata` 已从 `Selector`、Fetcher 配置和 `display_config()` 返回的设置中移除。请从直接调用解析器的代码、`Fetcher.configure(...)`,以及传给 Fetcher 或集成的 `selector_config` 字典中移除它。++**之前:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>", keep_cdata=True)+```++**现在:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>")+```++没有替代设置。该设置原本不会影响 HTML 解析器的输出。如果之前按位置传入解析器选项,请移除旧的 `keep_cdata` 参数,并按名称传入 `adaptive` 和存储选项。++## 命令行和交互式 Shell {#command-line-and-interactive-shell}++### 使用 `fetch` 发送浏览器请求 {#use-fetch-for-browser-requests}++CLI 现在只有一个浏览器命令:`scrapling extract fetch`。它使用 `StealthyFetcher`。++**之前:**++```bash+scrapling extract stealthy-fetch "https://example.com" page.md+```++**现在:**++```bash+scrapling extract fetch "https://example.com" page.md+```++如果已经使用 `scrapling extract fetch`,命令名称不变,但其后端会从 `DynamicFetcher` 改为 `StealthyFetcher`。`--solve-cloudflare` 等选项现在属于 `fetch`。++在 `scrapling shell` 中,将 `stealthy_fetch(...)` 替换为 `fetch(...)`。现有的 `fetch(...)` 快捷调用现在会调用 `StealthyFetcher.fetch`。动态类不再加入 Shell 的命名空间。++### 按 UTF-8 读取 Markdown 和文本文件 {#read-markdown-and-text-files-as-utf-8}++提取命令和 `Convertor.write_content_to_file()` 现在会以 **UTF-8** 写入 `.md` 和 `.txt` 文件,不受源页面字符集的影响。如果代码使用页面原始编码读取这些文件,请更新它。`.html` 输出仍使用 `page.encoding`。++从多个选中元素生成的 Markdown 现在会在元素之间加入空行。这适用于 `Response.markdown()` 和 Markdown 文件输出。请更新依赖直接拼接文本的精确输出比较或已保存的哈希值。++## MCP 服务器 {#mcp-server}++请更新已保存的提示词、工具允许列表、封装代码和 MCP 客户端的工具定义。更新服务器后,请重启或重新连接 MCP 客户端,让它读取当前工具列表。++### 更新工具名称和批量调用 {#update-tool-names-and-bulk-calls}++| v0.4.15 工具 | v0.5 替代方式 |+| --- | --- |+| `fetch`, `stealthy_fetch` | `browser_fetch_once` |+| `open_session` | `browser_open` |+| `session_fetch` | `browser_fetch` |+| `screenshot` | `browser_screenshot` |+| `bulk_fetch`, `bulk_stealthy_fetch` | 每个 URL 调用一次 `browser_fetch_once`,或通过已打开的会话重复调用 `browser_fetch` |+| `bulk_get` | 每个 URL 调用一次 `make_request` 或 `session_make_request` |++所有批量工具已被移除。单 URL 抓取工具返回一个包含 `status`、`content` 和 `url` 的 `ResponseModel`,不再返回响应列表。`content` 本身仍然是字符串列表。++所有 MCP 浏览器工具现在都使用隐身后端。请从 `browser_open` 调用中移除 `session_type`;不再提供动态浏览器选项。其结果包含 `session_type="stealthy"`。HTTP 会话仍使用 `open_request_session`,并返回 `session_type="static"`。++Python 集成还必须停止导入已被移除的 `BrowserSessionType`。`SessionType` 现在只接受 `"stealthy"` 和 `"static"`。++同一浏览器会话中的调用必须按顺序执行,因为它们共用一个页面。完成后使用 `close_session` 关闭会话。++### 通过 `list_sessions` 读取设置 {#read-settings-through-list_sessions}++`browser_open` 和 `open_request_session` 现在只返回:++```json+{+ "session_id": "my-session",+ "session_type": "stealthy"+}+```++创建结果不再包含 `created_at`、`is_alive`、`settings` 或 `message`。调用 `list_sessions` 可获取前三个字段。确认信息 `message` 已被移除。如果代码假设 `SessionCreatedModel` 具有 `SessionInfo` 的所有字段,也需要修改。++### 截图前先获取页面 {#fetch-before-taking-a-screenshot}++`browser_screenshot` 会截取**当前页面,不会重新加载页面**。它不再接受 URL,也不再接受旧的导航和等待选项:`wait`、`wait_selector`、`wait_selector_state` 和 `network_idle`。++请按以下顺序操作:++1. 调用 `browser_open`。+2. 调用 `browser_fetch`,传入 URL 和所需的页面加载选项。+3. 如有需要,调用 `browser_actions` 与页面交互或等待内容。+4. 调用 `browser_screenshot`,传入会话 ID。+5. 完成后调用 `close_session`。++例如,整页截图的参数如下:++```json+{+ "session_id": "my-session",+ "full_page": true+}+```++该工具的 `timeout` 现在限制的是截图操作的时长。该工具不会加载页面。要截取某个元素,请使用 `selector` 或 `ref`,且不要设置 `full_page=true`。++截图仍返回图像和文本内容块,文本块中包含当前页面的 URL。它们不会返回抓取使用的 `ResponseModel`。++完整的输入和输出结构见 [MCP 指南](ai/mcp-server.md)和 [API 参考](api-reference/mcp-server.md)。++## 爬虫和 HTTP 请求 {#spiders-and-http-requests}++### 跟随链接时重新传入请求数据 {#pass-request-data-again-when-following-a-link}++`response.follow()` 不再从上一个请求复制 `method`、`params`、`data`、`json`、`files` 或 `multipart`。它还会从 `headers` 和 `extra_headers` 中移除继承的 `Content-Length` 请求头。++跟随链接现在默认发起普通 GET 请求,除非显式传入请求数据。会话、代理和回调等其他共享设置仍遵循现有的继承规则。++如果旧代码依赖继承的 POST 数据,请将:++```python+yield response.follow("/next")+```++改为:++```python+yield response.follow("/next", method="POST", json={"page": 2})+```++如果下一个请求需要 `params`,也要显式传入。让 HTTP 客户端计算新的 `Content-Length`。++### 检查请求指纹和已保存的抓取状态 {#check-request-fingerprints-and-saved-crawl-state}++请求指纹是用于识别重复请求和查找缓存响应的键。现在有三种输入情况的处理方式发生变化:++- 构建键之前,`params` 会合并到 URL 中。默认情况下,同一 URL 使用不同查询参数的请求不再被视为重复请求。+- `{}`、`[]`、`false`、`0` 和 `""` 等 JSON 请求体会保留在键中。它们不再与没有请求体的情况共用同一个键。`None` 仍表示没有 JSON 请求体。+- 当 `fp_include_headers=True` 时,仅改变请求头的插入顺序不会再改变键。++如果抓取使用了这些输入,请在升级前完成抓取,或使用新的检查点和响应缓存目录开始新的抓取。旧的已保存键可能与新键不同。这是请求标识方式的变化,不是检查点文件格式的变化。++开发模式现在只会在检查响应是否被封锁之后,将响应写入缓存。封锁页面不会作为成功结果存入缓存。现有缓存文件不会自动清理;如果之前缓存过验证页面,请清除旧条目。++失败的抓取现在会保留检查点文件。如果清理代码假设这些文件会在出错后消失,请检查该代码。参见[暂停和恢复](spiders/advanced.md#pause-resume)及[开发模式](spiders/advanced.md#development-mode)。++### 检查 robots.txt 获取失败的情况 {#check-robotstxt-failures}++设置 `robots_txt_obey=True` 后,如果获取 robots.txt 时出现异常,或响应状态不是 HTTP 200 或 4xx,现在会阻止对该域名的请求。此前,这些失败情况会允许继续抓取。HTTP 200 仍提供规则,HTTP 4xx 仍允许访问。++该结果会在整个抓取期间缓存。请修复 robots.txt 的访问问题,然后开始新的抓取;同一次抓取中的后续请求不会重试失败的查询。默认值 `robots_txt_obey=False` 不变。++### 检查链接限制和站点地图回调 {#check-link-restrictions-and-sitemap-callbacks}++- `LinkExtractor` 的限制条件没有匹配项时,现在不会返回任何链接。它不再退回到整个页面。如果抓取找到的链接变少,请修正 `restrict_css` 或 `restrict_xpath` 表达式。+- 限制条件现在可以选中链接元素本身,而不只是父元素。这可能会增加之前遗漏的链接。请检查预期的 URL 集合。+- 当没有规则,或匹配规则的 `callback=None` 时,`SitemapSpider` 现在会把页面 URL 交给 `parse()`。它不再将这些 HTML 页面送回站点地图解析器。请为这些情况实现 `parse()`,并移除针对旧分发方式的变通代码。+- robots.txt 和 CSV 数据源开头的 Unicode 字节顺序标记会被移除。robots 的第一条指令现在会生效,CSV 的第一个列名也不再以 `\ufeff` 开头。如果设置了自定义 `headers`,则会改为从第一个字段值中移除该标记。请更新用于处理该隐藏前缀的代码。站点地图中的 XML 注释和处理指令也会被跳过,不再导致解析失败。++### 检查表单数据、请求头和 CLI JSON {#check-form-data-headers-and-cli-json}++字典形式的表单数据现在会将列表和元组值展开为重复的键。例如,`data={"tag": ["a", "b"]}` 会发送 `tag=a&tag=b`。空列表不会为该键发送任何条目。如果未提供 Content-Type,会添加默认值 `Content-Type: application/x-www-form-urlencoded`。++如果需要其他传输格式,请显式传入编码后的字符串或字节。`json`、原始 `content` 和 multipart 上传仍使用各自的请求体处理方式。表单数据或查询参数中的 `None` 值**不会被移除**;它们仍是字符串 `None`。++单个请求的 HTTP 请求头现在会覆盖会话请求头,不区分大小写。名为 `authorization` 的请求头会替换会话中的 `Authorization`,而不是同时发送两者。请移除用于处理重复请求头名称的代码。++CLI JSON 值 `{}`、`[]`、`false`、`0` 和 `""` 现在会被发送,不再被静默丢弃。此外,`curl2fetcher()` 现在会应用 curl 的 `-A` 用户代理,并将 `-x` 代理正确地作为 URL 字符串传入。显式指定的 curl 请求头 `-H 'User-Agent: ...'` 仍优先于 `-A`。++## 其他需要检查的输出变化 {#other-output-changes-to-check}++这些修复没有移除 API,但可能改变已保存的结果和精确输出测试:++- 生成的 CSS 和 XPath 选择器现在会在需要时包含 `:nth-of-type(1)` 或 `[1]`,以识别多个同标签兄弟元素中的第一个。请更新预期的选择器字符串,不要移除新的位置标记。+- AI 内容清理现在会保留具有 `opacity:0.95` 等值的可见元素,识别更多种隐藏内联样式并移除相应元素,同时移除 `<slot hidden>` 元素及所有匹配的干扰标签,包括嵌套的标签。请重新检查 Markdown、文本和净化后 HTML 的精确输出。+- 浏览器响应转换现在能读取包含不同大小写、空格或带引号值的 charset 声明,例如 `text/plain; CHARSET = "iso-8859-15"`。带有这些响应头的非 HTML 响应现在会使用声明的编码,不再回退到 UTF-8。请重新检查从这些响应中解码得到的文本。++## 验证升级结果 {#verify-your-upgrade}++在运行完整任务之前,先进行小规模抓取。检查提取的数据、跟随的 URL、发送的请求体、已保存文件的编码,以及所依赖的缓存或检查点行为。对于 MCP 集成,请对照当前结构检查工具输入和返回的数据。++更早版本的变化见[更新日志](changelog.md)。diff --git a/docs/migrating-to-v0.5.md b/docs/migrating-to-v0.5.mdnew file mode 100644index 0000000..1139265--- /dev/null+++ b/docs/migrating-to-v0.5.md@@ -0,0 +1,293 @@+---+title: "Migrating to v0.5"+description: "Move from Scrapling v0.4.15 to v0.5. Update browser imports, network capture, MCP tools, CLI commands, parser settings, and spider behavior."+---++# Migrating to v0.5 {#migrating-to-v05}++This guide covers the changes you need to check when moving from **v0.4.15 to v0.5**. It includes removed APIs, renamed tools, and fixes that can change your crawl results or saved files.++## Quick migration checklist {#quick-migration-checklist}++| If you use... | What to change |+| --- | --- |+| `DynamicFetcher`, `DynamicSession`, or `AsyncDynamicSession` | Use the matching stealthy class. |+| `capture_xhr` or `response.captured_xhr` | Use a browser session with `record_requests=True` and `session.network`. |+| `keep_cdata` | Remove it from parser and fetcher settings. |+| `scrapling extract stealthy-fetch` or the shell's `stealthy_fetch()` | Use `fetch` instead. |+| MCP tools | Update tool names, screenshot calls, and session creation response handling. |+| `response.follow()` after a POST or a request with query parameters | Pass the method, query, and body again when you need them. |+| Saved crawl checkpoints or response caches | Start a fresh crawl when your requests use the changed fingerprint inputs. |+| `robots_txt_obey=True` | Handle robots.txt fetch failures, which now block crawling for that domain. |++## Browser fetching {#browser-fetching}++### Replace the dynamic browser classes {#replace-the-dynamic-browser-classes}++The plain Playwright browser backend has been removed. All browser fetching now uses the Patchright-based stealthy backend.++| Removed API | Replacement |+| --- | --- |+| `scrapling.DynamicFetcher` | `scrapling.StealthyFetcher` |+| `scrapling.fetchers.DynamicFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.chrome.PlayWrightFetcher` | `scrapling.fetchers.StealthyFetcher` |+| `scrapling.fetchers.DynamicSession` | `scrapling.fetchers.StealthySession` |+| `scrapling.fetchers.AsyncDynamicSession` | `scrapling.fetchers.AsyncStealthySession` |++The `scrapling.fetchers.chrome` module and the private `_browsers._controllers` module are gone. Use the public imports above.++**Before:**++```python+from scrapling.fetchers import DynamicFetcher++page = DynamicFetcher.fetch("https://example.com", headless=True)+```++**Now:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", headless=True)+```++For sessions, replace `DynamicSession` with `StealthySession`, or `AsyncDynamicSession` with `AsyncStealthySession`. Make the same change in your spider's `configure_sessions()` method. The `fetch()` and `async with` patterns still apply.++If your callbacks import browser types or catch browser errors, change `playwright.sync_api` to `patchright.sync_api`, or `playwright.async_api` to `patchright.async_api`. This includes `Page`, `Locator`, `Error`, and `TimeoutError`.++Patchright evaluates JavaScript in an isolated context by default. If a callback reads the page's own JavaScript variables, use `page.evaluate(..., isolated_context=False)`.++This changes the browser's behavior as well as its import name. Review your browser flags and fingerprint settings. Cloudflare solving still requires `solve_cloudflare=True`; it is not enabled by default. Also, `extra_flags` now adds to the built-in stealth flags instead of replacing them.++See [Browser fetching](fetching/stealthy.md) for the current options.++### Replace XHR capture with session network history {#replace-xhr-capture-with-session-network-history}++The `capture_xhr` parameter and `Response.captured_xhr` attribute have been removed. Remove the parameter even when its value is `None`. A one-shot fetch no longer has an XHR list attached to its response.++Custom integrations that call `ResponseFactory.from_playwright_response()` or `ResponseFactory.from_async_playwright_response()` must also remove `xhr_captured`. Pass `collect_history` by name to avoid the changed positional argument order.++**Before:**++```python+from scrapling.fetchers import StealthyFetcher++page = StealthyFetcher.fetch("https://example.com", capture_xhr="/api/")+for response in page.captured_xhr:+ print(response.url, response.body)+```++**Now:**++```python+from scrapling.fetchers import StealthySession++with StealthySession(record_requests=True) as session:+ page = session.fetch("https://example.com", network_idle=True)+ for response in session.network.search(url_pattern=r"/api/", limit=None):+ print(response.url, response.body)+```++Use `AsyncStealthySession` and `await session.fetch(...)` for async code. Reading `session.network` does not need `await`.++There are a few important differences:++- Set `record_requests=True` when you create the session. It is a session setting, not a per-fetch setting.+- History belongs to the **whole session**, across tabs, page loads, and actions. Use `after_id`, filters, or `session.network.clear()` if you need a smaller scope.+- Move the old `capture_xhr` regular expression to `url_pattern` when you search the history.+- `search()` returns saved `Response` objects. Read `.url`, `.status`, `.headers`, `.body`, or `.json()` directly. The recording ID, resource type, and sent body are in `response.meta["network_id"]`, `response.meta["resource_type"]`, and `response.meta["request_body"]`.+- Python history includes all resource types by default. Use `resource_type="xhr"` or `resource_type="fetch"` to select one, or `include_static=False` for XHR/fetch requests plus HTTP errors.+- `search()` returns at most 100 matches by default. Pass `limit=None` for all retained matches. Sessions retain at most 1,000 requests by default; change this with `max_recorded_requests`.+- Only completed requests are saved. Body capture is limited to supported text content types, 1 MiB per response, and 20 MiB of total retained body data. Older records can be removed as limits are reached. Check `response.meta.get("body_note")` for the reason a body was skipped.+- Reading history or closing the session does not wait for pending captures. Wait for the data you need before reading it. Saved Python history remains readable after session close.++See [Network history](fetching/stealthy.md#network-history) for filters and limits.++## Parser settings {#parser-settings}++### Remove `keep_cdata` {#remove-keep_cdata}++`keep_cdata` has been removed from `Selector`, fetcher configuration, and the settings returned by `display_config()`. Remove it from direct parser calls, `Fetcher.configure(...)`, and `selector_config` dictionaries passed to fetchers or integrations.++**Before:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>", keep_cdata=True)+```++**Now:**++```python+from scrapling import Selector++page = Selector("<p>Hello</p>")+```++There is no replacement setting. It did not affect the HTML parser's output. If you passed parser options by position, remove the old `keep_cdata` argument and use names for `adaptive` and storage options.++## Command line and interactive shell {#command-line-and-interactive-shell}++### Use `fetch` for browser requests {#use-fetch-for-browser-requests}++The CLI now has one browser command: `scrapling extract fetch`. It uses `StealthyFetcher`.++**Before:**++```bash+scrapling extract stealthy-fetch "https://example.com" page.md+```++**Now:**++```bash+scrapling extract fetch "https://example.com" page.md+```++If you already use `scrapling extract fetch`, the command name stays the same, but its backend changes from `DynamicFetcher` to `StealthyFetcher`. Options such as `--solve-cloudflare` now belong to `fetch`.++In `scrapling shell`, replace `stealthy_fetch(...)` with `fetch(...)`. The existing `fetch(...)` shortcut now calls `StealthyFetcher.fetch`. The dynamic classes are no longer added to the shell namespace.++### Read Markdown and text files as UTF-8 {#read-markdown-and-text-files-as-utf-8}++The extract commands and `Convertor.write_content_to_file()` now write `.md` and `.txt` files as **UTF-8**, regardless of the source page's charset. Update any code that reads those files with the page's original encoding. `.html` output still uses `page.encoding`.++Markdown from multiple selected elements now has blank lines between elements. This applies to `Response.markdown()` and Markdown file output. Update exact output comparisons or stored hashes that depended on concatenated text.++## MCP server {#mcp-server}++Update saved prompts, tool allowlists, wrappers, and MCP client tool definitions. Restart or reconnect your MCP client after the server update so it reads the current tools.++### Update tool names and bulk calls {#update-tool-names-and-bulk-calls}++| v0.4.15 tool | v0.5 replacement |+| --- | --- |+| `fetch`, `stealthy_fetch` | `browser_fetch_once` |+| `open_session` | `browser_open` |+| `session_fetch` | `browser_fetch` |+| `screenshot` | `browser_screenshot` |+| `bulk_fetch`, `bulk_stealthy_fetch` | One `browser_fetch_once` call per URL, or repeated `browser_fetch` calls through an open session |+| `bulk_get` | One `make_request` or `session_make_request` call per URL |++All bulk tools have been removed. Single-URL fetch tools return one `ResponseModel` with `status`, `content`, and `url`, not a list of responses. `content` itself is still a list of strings.++All MCP browser tools now use the stealthy backend. Remove `session_type` from calls to `browser_open`; there is no dynamic-browser choice. Its result has `session_type="stealthy"`. HTTP sessions still use `open_request_session` and return `session_type="static"`.++Python integrations must also stop importing `BrowserSessionType`, which was removed. `SessionType` now accepts only `"stealthy"` and `"static"`.++Calls through one browser session must run in order because they share a page. Close sessions with `close_session` when you finish.++### Read settings through `list_sessions` {#read-settings-through-list_sessions}++`browser_open` and `open_request_session` now return only:++```json+{+ "session_id": "my-session",+ "session_type": "stealthy"+}+```++The creation result no longer includes `created_at`, `is_alive`, `settings`, or `message`. Call `list_sessions` for the first three fields. The confirmation `message` is gone. Code that assumed `SessionCreatedModel` had all the fields of `SessionInfo` must change too.++### Fetch before taking a screenshot {#fetch-before-taking-a-screenshot}++`browser_screenshot` captures the **current page without reloading it**. It no longer accepts a URL or the old navigation and wait options: `wait`, `wait_selector`, `wait_selector_state`, and `network_idle`.++Use this order:++1. Call `browser_open`.+2. Call `browser_fetch` with the URL and any page-load options.+3. If needed, call `browser_actions` to interact with the page or wait for content.+4. Call `browser_screenshot` with the session ID.+5. Call `close_session` when you finish.++For example, the arguments for a full-page screenshot are:++```json+{+ "session_id": "my-session",+ "full_page": true+}+```++`timeout` on this tool now limits the screenshot operation. It does not load a page. For an element screenshot, use either `selector` or `ref`, and do not set `full_page=true`.++Screenshots still return image and text content blocks, with the current page URL in the text block. They do not return a fetch `ResponseModel`.++See the [MCP guide](ai/mcp-server.md) and [API reference](api-reference/mcp-server.md) for the full schemas.++## Spiders and HTTP requests {#spiders-and-http-requests}++### Pass request data again when following a link {#pass-request-data-again-when-following-a-link}++`response.follow()` no longer copies `method`, `params`, `data`, `json`, `files`, or `multipart` from the previous request. It also removes inherited `Content-Length` headers from `headers` and `extra_headers`.++A followed link now starts as a plain GET unless you pass request data explicitly. Other shared settings, such as the session, proxy, and callbacks, still follow the existing inheritance rules.++If your old code relied on inherited POST data, change:++```python+yield response.follow("/next")+```++to:++```python+yield response.follow("/next", method="POST", json={"page": 2})+```++Pass `params` explicitly too when the next request needs them. Let the HTTP client calculate the new `Content-Length`.++### Check request fingerprints and saved crawl state {#check-request-fingerprints-and-saved-crawl-state}++A request fingerprint is the key used to detect duplicate requests and find cached responses. Its inputs now handle three cases differently:++- `params` are merged into the URL before the key is built. Requests to the same URL with different query parameters are no longer treated as duplicates by default.+- JSON bodies such as `{}`, `[]`, `false`, `0`, and `""` are kept in the key. They no longer share the key for a missing body. `None` still means no JSON body.+- When `fp_include_headers=True`, changing only the insertion order of headers no longer changes the key.++If your crawl uses these inputs, finish it before upgrading or start a new crawl with a fresh checkpoint and response cache directory. Old saved keys can differ from the new keys. This is a change to request identity, not a new checkpoint file format.++Development mode now writes responses to the cache only after the blocked-response check. Blocked pages are not saved as successful cached results. Existing cache files are not cleaned for you; clear stale entries if you previously cached a challenge page.++Failed crawls now retain their checkpoint files. Check your cleanup code if it assumed those files disappear after an error. See [Pause and resume](spiders/advanced.md#pause-resume) and [Development mode](spiders/advanced.md#development-mode).++### Check robots.txt failures {#check-robotstxt-failures}++With `robots_txt_obey=True`, a robots.txt fetch exception or a response other than HTTP 200 or 4xx now blocks requests to that domain. Previously, those failures allowed crawling. HTTP 200 still supplies the rules, and HTTP 4xx still allows access.++The result is cached for the whole crawl. Fix the robots.txt access problem and start a new crawl; later requests in the same crawl will not retry the failed lookup. This does not change the default `robots_txt_obey=False`.++### Check link restrictions and sitemap callbacks {#check-link-restrictions-and-sitemap-callbacks}++- A `LinkExtractor` restriction that matches nothing now returns no links. It no longer falls back to the whole page. Fix the `restrict_css` or `restrict_xpath` expression if your crawl now finds fewer links.+- A restriction can now select the link element itself, not just a parent. This can add links that were previously missed. Review expected URL sets.+- `SitemapSpider` now sends page URLs to `parse()` when there are no rules, or when a matching rule has `callback=None`. It no longer sends those HTML pages back to the sitemap parser. Implement `parse()` for those cases and remove workarounds for the old routing.+- A leading Unicode byte-order mark is removed from robots.txt and CSV feeds. The first robots directive now takes effect, and the first CSV header no longer starts with `\ufeff`. If you set custom `headers`, the mark is removed from the first field value instead. Update code that worked around that hidden prefix. Sitemap XML comments and processing instructions are also skipped instead of causing a parse failure.++### Check form data, headers, and CLI JSON {#check-form-data-headers-and-cli-json}++Dictionary form data now expands list and tuple values into repeated keys. For example, `data={"tag": ["a", "b"]}` sends `tag=a&tag=b`. An empty list sends no entry for that key. A default `Content-Type: application/x-www-form-urlencoded` is added when you have not supplied one.++If you need a different wire format, pass an explicitly encoded string or bytes. `json`, raw `content`, and multipart uploads keep their own body handling. `None` values are **not dropped** from form data or query parameters; they remain the string `None`.++Per-request HTTP headers now override session headers regardless of letter case. A request header named `authorization` replaces the session's `Authorization` instead of sending both. Remove code that worked around duplicate header names.++CLI JSON values `{}`, `[]`, `false`, `0`, and `""` are now sent instead of silently dropped. Also, `curl2fetcher()` now applies curl's `-A` user agent and correctly passes `-x` proxies as a URL string. An explicit curl `-H 'User-Agent: ...'` still takes priority over `-A`.++## Other output changes to check {#other-output-changes-to-check}++These fixes do not remove APIs, but they can change stored results and exact output tests:++- Generated CSS and XPath selectors now include `:nth-of-type(1)` or `[1]` when needed to identify the first of several same-tag siblings. Refresh expected selector strings; do not remove the new position marker.+- Cleaned AI content now keeps visible elements with values such as `opacity:0.95`, removes elements hidden by more forms of inline styles and `<slot hidden>` elements, and removes all matching noise tags even when they are nested. Recheck exact Markdown, text, and sanitized HTML output.+- Browser response conversion now reads charset declarations with different letter case, spaces, or quoted values, such as `text/plain; CHARSET = "iso-8859-15"`. Non-HTML responses with these headers now use the declared encoding instead of falling back to UTF-8. Recheck text decoded from those responses.++## Verify your upgrade {#verify-your-upgrade}++Run a small crawl before your full job. Check the extracted data, followed URLs, sent request bodies, saved file encoding, and any cache or checkpoint behavior you depend on. For MCP integrations, check both tool inputs and returned data against the current schemas.++For older release changes, see the [changelog](changelog.md).diff --git a/zensical.ar.yml b/zensical.ar.ymlindex e3d9796..b855d9e 100644--- a/zensical.ar.yml+++ b/zensical.ar.yml@@ -8,6 +8,7 @@ nav:- مقدمة: index.md- نظرة عامة: overview.md- اختبارات الأداء: benchmarks.md+- الانتقال إلى v0.5: migrating-to-v0.5.md- دليل الاستخدام:- تحليل الصفحات:- اختيار العناصر: parsing/selection.mddiff --git a/zensical.de.yml b/zensical.de.ymlindex 2ff653a..07d88be 100644--- a/zensical.de.yml+++ b/zensical.de.yml@@ -9,6 +9,7 @@ nav:- Einführung: index.md- Überblick: overview.md- Leistungstests: benchmarks.md+- Migration auf v0.5: migrating-to-v0.5.md- Anleitung:- Seiten auswerten:- Elemente auswählen: parsing/selection.mddiff --git a/zensical.es.yml b/zensical.es.ymlindex 547e24d..0c45bbb 100644--- a/zensical.es.yml+++ b/zensical.es.yml@@ -9,6 +9,7 @@ nav:- Introducción: index.md- Resumen: overview.md- Pruebas de rendimiento: benchmarks.md+- Migrar a v0.5: migrating-to-v0.5.md- Guía de uso:- Análisis de páginas:- Seleccionar elementos: parsing/selection.mddiff --git a/zensical.fr.yml b/zensical.fr.ymlindex 175f5e3..47baa7b 100644--- a/zensical.fr.yml+++ b/zensical.fr.yml@@ -9,6 +9,7 @@ nav:- Introduction: index.md- Vue d’ensemble: overview.md- Tests de performance: benchmarks.md+- Migrer vers la v0.5: migrating-to-v0.5.md- Guide d’utilisation:- Analyse de pages:- Sélection d’éléments: parsing/selection.mddiff --git a/zensical.ja.yml b/zensical.ja.ymlindex 3b60952..e9549ce 100644--- a/zensical.ja.yml+++ b/zensical.ja.yml@@ -9,6 +9,7 @@ nav:- 紹介: index.md- はじめに: overview.md- 性能テスト: benchmarks.md+- v0.5 への移行: migrating-to-v0.5.md- 使い方:- ページの解析:- 要素の選択: parsing/selection.mddiff --git a/zensical.ko.yml b/zensical.ko.ymlindex 5160619..a114637 100644--- a/zensical.ko.yml+++ b/zensical.ko.yml@@ -9,6 +9,7 @@ nav:- 소개: index.md- 시작하기: overview.md- 성능 테스트: benchmarks.md+- v0.5로 마이그레이션: migrating-to-v0.5.md- 사용 가이드:- 페이지 파싱:- 요소 찾기: parsing/selection.mddiff --git a/zensical.pt-BR.yml b/zensical.pt-BR.ymlindex debb1ec..cff0b76 100644--- a/zensical.pt-BR.yml+++ b/zensical.pt-BR.yml@@ -9,6 +9,7 @@ nav:- Introdução: index.md- Visão geral: overview.md- Testes de desempenho: benchmarks.md+- Migrar para a v0.5: migrating-to-v0.5.md- Guia de uso:- Análise de páginas:- Seleção de elementos: parsing/selection.mddiff --git a/zensical.ru.yml b/zensical.ru.ymlindex 3eba4aa..7392977 100644--- a/zensical.ru.yml+++ b/zensical.ru.yml@@ -9,6 +9,7 @@ nav:- Введение: index.md- Начало работы: overview.md- Тесты производительности: benchmarks.md+- Переход на v0.5: migrating-to-v0.5.md- Руководства:- Разбор страниц:- Поиск элементов: parsing/selection.mddiff --git a/zensical.yml b/zensical.ymlindex e8db0e9..723e223 100644--- a/zensical.yml+++ b/zensical.yml@@ -7,6 +7,7 @@ nav:- Introduction: index.md- Overview: overview.md- Performance Benchmarks: benchmarks.md+- Migrating to v0.5: migrating-to-v0.5.md- User Guide:- Parsing:- Querying elements: parsing/selection.mddiff --git a/zensical.zh.yml b/zensical.zh.ymlindex d799bbc..cc2ee28 100644--- a/zensical.zh.yml+++ b/zensical.zh.yml@@ -9,6 +9,7 @@ nav:- 简介: index.md- 入门: overview.md- 性能测试: benchmarks.md+- 迁移到 v0.5: migrating-to-v0.5.md- 使用指南:- 解析页面:- 选择元素: parsing/selection.md