Skip to content

🕷️ 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

docs(spiders): document checkpoint data requirements in all languages

Karim shoaird62e5b985458
diff --git a/agent-skill/Scrapling-Skill.zip b/agent-skill/Scrapling-Skill.zip
index 3b1f285..ab905e2 100644
Binary files a/agent-skill/Scrapling-Skill.zip and b/agent-skill/Scrapling-Skill.zip differ
diff --git a/agent-skill/Scrapling-Skill/references/spiders/advanced.md b/agent-skill/Scrapling-Skill/references/spiders/advanced.md
index ea4aeff..c393990 100644
--- a/agent-skill/Scrapling-Skill/references/spiders/advanced.md
+++ b/agent-skill/Scrapling-Skill/references/spiders/advanced.md
@@ -130,7 +130,17 @@ You can change the interval as follows:
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-The writing to the disk is atomic, so it's totally safe.
+Checkpoint writes use a temporary file and replace the previous checkpoint only after the write succeeds.
+
+**Warning: Checkpoint data**
+
+When you enable `crawldir`, values in pending requests, including `meta` and request arguments, must be saveable with Python's `pickle` module. If a value cannot be saved, the checkpoint fails and the crawl stops. A `Selector` can work in a callback but cannot be saved this way.
+
+Store extracted values, such as strings or numbers, instead of `Selector` objects. Lists and dictionaries must also contain only saveable values:
+
+```python
+yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+```
**Tip:**
diff --git a/docs/locales/ar/spiders/advanced.md b/docs/locales/ar/spiders/advanced.md
index 752f7ce..5c1c6df 100644
--- a/docs/locales/ar/spiders/advanced.md
+++ b/docs/locales/ar/spiders/advanced.md
@@ -143,7 +143,17 @@ else:
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-تتم الكتابة على القرص كعملية واحدة لا تترك ملفًا مكتوبًا جزئيًا، ولذلك تكون آمنة.
+تستخدم كتابة نقطة الاستكمال ملفًا مؤقتًا، ولا تُستبدل نقطة الاستكمال السابقة إلا بعد نجاح الكتابة.
+
+!!! warning "بيانات نقطة الاستكمال"
+
+ عند تفعيل `crawldir`، يجب أن تكون القيم في الطلبات المعلّقة، بما فيها `meta` ومعاملات الطلب، قابلة للحفظ باستخدام وحدة `pickle` في Python. إذا تعذّر حفظ إحدى القيم، يفشل حفظ نقطة الاستكمال ويتوقف الزحف. يمكن استخدام كائن `Selector` داخل دالة callback، لكن لا يمكن حفظه بهذه الطريقة.
+
+ احفظ القيم المستخرجة، مثل النصوص أو الأرقام، بدلًا من كائنات `Selector`. ويجب أن تحتوي القوائم والقواميس أيضًا على قيم قابلة للحفظ فقط:
+
+ ```python
+ yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+ ```
!!! tip "نصيحة"
diff --git a/docs/locales/de/spiders/advanced.md b/docs/locales/de/spiders/advanced.md
index 0340ff5..b644bf9 100644
--- a/docs/locales/de/spiders/advanced.md
+++ b/docs/locales/de/spiders/advanced.md
@@ -143,7 +143,17 @@ So ändern Sie den Abstand:
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-Das Schreiben auf die Festplatte ist atomar und verhindert dadurch unvollständige Dateien.
+Beim Speichern eines Checkpoints wird eine temporäre Datei verwendet. Der vorherige Checkpoint wird erst ersetzt, wenn das Schreiben erfolgreich war.
+
+!!! warning "Checkpoint-Daten"
+
+ Wenn Sie `crawldir` aktivieren, müssen sich die Werte in offenen Anfragen, einschließlich `meta` und Anfrageargumenten, mit Pythons Modul `pickle` speichern lassen. Kann ein Wert nicht gespeichert werden, schlägt das Speichern des Checkpoints fehl und der Crawl stoppt. Ein `Selector` kann in einem Callback verwendet werden, lässt sich aber nicht auf diese Weise speichern.
+
+ Speichern Sie extrahierte Werte wie Zeichenfolgen oder Zahlen statt `Selector`-Objekten. Auch Listen und Dictionaries dürfen nur Werte enthalten, die sich speichern lassen:
+
+ ```python
+ yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+ ```
!!! tip
diff --git a/docs/locales/es/spiders/advanced.md b/docs/locales/es/spiders/advanced.md
index 12bb24e..1cc7783 100644
--- a/docs/locales/es/spiders/advanced.md
+++ b/docs/locales/es/spiders/advanced.md
@@ -143,7 +143,17 @@ Puedes cambiar el intervalo así:
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-La escritura en disco es atómica, para evitar archivos incompletos.
+Para escribir un punto de guardado, se usa un archivo temporal. El punto anterior solo se reemplaza cuando la escritura termina correctamente.
+
+!!! warning "Datos del punto de guardado"
+
+ Al activar `crawldir`, los valores de las solicitudes pendientes, incluidos `meta` y los argumentos de las solicitudes, deben poder guardarse con el módulo `pickle` de Python. Si un valor no se puede guardar, falla la creación del punto de guardado y el rastreo se detiene. Un `Selector` puede funcionar en un callback, pero no se puede guardar de esta forma.
+
+ Guarda los valores extraídos, como cadenas de texto o números, en lugar de objetos `Selector`. Las listas y los diccionarios también deben contener solo valores que se puedan guardar:
+
+ ```python
+ yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+ ```
!!! tip "Consejo"
diff --git a/docs/locales/fr/spiders/advanced.md b/docs/locales/fr/spiders/advanced.md
index 650cb04..c87b2e6 100644
--- a/docs/locales/fr/spiders/advanced.md
+++ b/docs/locales/fr/spiders/advanced.md
@@ -143,7 +143,17 @@ Vous pouvez changer l’intervalle ainsi :
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-L’écriture sur disque est atomique pour éviter les fichiers incomplets.
+L’enregistrement d’un point de reprise utilise un fichier temporaire et ne remplace le point précédent qu’une fois l’écriture réussie.
+
+!!! warning "Données du point de reprise"
+
+ Quand vous activez `crawldir`, les valeurs des requêtes en attente, y compris `meta` et les arguments des requêtes, doivent pouvoir être enregistrées avec le module Python `pickle`. Si une valeur ne peut pas être enregistrée, l’enregistrement du point de reprise échoue et l’exploration s’arrête. Un `Selector` peut fonctionner dans un callback, mais ne peut pas être enregistré de cette manière.
+
+ Enregistrez les valeurs extraites, comme des chaînes de caractères ou des nombres, au lieu d’objets `Selector`. Les listes et les dictionnaires doivent aussi contenir uniquement des valeurs qui peuvent être enregistrées :
+
+ ```python
+ yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+ ```
!!! tip "Conseil"
diff --git a/docs/locales/ja/spiders/advanced.md b/docs/locales/ja/spiders/advanced.md
index 3c89013..7469e89 100644
--- a/docs/locales/ja/spiders/advanced.md
+++ b/docs/locales/ja/spiders/advanced.md
@@ -143,7 +143,17 @@ else:
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-ディスクへの書き込みはアトミックに行い、不完全なファイルが残ることを防ぎます。
+チェックポイントの書き込みには一時ファイルを使い、書き込みに成功した場合だけ前のチェックポイントを置き換えます。
+
+!!! warning "チェックポイントのデータ"
+
+ `crawldir` を有効にすると、未処理のリクエストに含まれる値(`meta` やリクエストの引数を含む)は、Python の `pickle` モジュールで保存できる必要があります。保存できない値があると、チェックポイントの保存に失敗し、クロールが停止します。`Selector` はコールバック内で使えても、この方法では保存できません。
+
+ `Selector` オブジェクトではなく、文字列や数値などの抽出した値を保存してください。リストや辞書にも、保存できる値だけを含める必要があります。
+
+ ```python
+ yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+ ```
!!! tip
diff --git a/docs/locales/ko/spiders/advanced.md b/docs/locales/ko/spiders/advanced.md
index 0368900..0e2d1cc 100644
--- a/docs/locales/ko/spiders/advanced.md
+++ b/docs/locales/ko/spiders/advanced.md
@@ -143,7 +143,17 @@ else:
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-디스크에 원자적으로 쓰므로 일부만 기록되는 일을 막습니다.
+체크포인트를 쓸 때는 임시 파일을 사용하고, 쓰기에 성공한 경우에만 이전 체크포인트를 교체합니다.
+
+!!! warning "체크포인트 데이터"
+
+ `crawldir`를 사용하면 `meta`와 요청 인수를 포함한 대기 요청의 값은 Python의 `pickle` 모듈로 저장할 수 있어야 합니다. 저장할 수 없는 값이 있으면 체크포인트 저장에 실패하고 크롤링이 중지됩니다. `Selector`는 콜백에서 사용할 수 있지만 이 방식으로 저장할 수는 없습니다.
+
+ `Selector` 객체 대신 문자열이나 숫자처럼 추출한 값을 저장하세요. 리스트와 딕셔너리에도 저장할 수 있는 값만 담아야 합니다.
+
+ ```python
+ yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+ ```
!!! tip
diff --git a/docs/locales/pt-BR/spiders/advanced.md b/docs/locales/pt-BR/spiders/advanced.md
index 9b3d550..9c23a5d 100644
--- a/docs/locales/pt-BR/spiders/advanced.md
+++ b/docs/locales/pt-BR/spiders/advanced.md
@@ -143,7 +143,17 @@ Você pode mudar o intervalo assim:
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-A gravação em disco é atômica, para evitar arquivos incompletos.
+A gravação de um checkpoint usa um arquivo temporário e só substitui o checkpoint anterior após a gravação terminar com sucesso.
+
+!!! warning "Dados do checkpoint"
+
+ Quando você ativa `crawldir`, os valores das solicitações pendentes, incluindo `meta` e os argumentos das solicitações, devem poder ser salvos com o módulo `pickle` do Python. Se um valor não puder ser salvo, a gravação do checkpoint falha e o rastreamento para. Um `Selector` pode funcionar em um callback, mas não pode ser salvo dessa forma.
+
+ Salve os valores extraídos, como strings ou números, em vez de objetos `Selector`. As listas e os dicionários também devem conter apenas valores que possam ser salvos:
+
+ ```python
+ yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+ ```
!!! tip "Dica"
diff --git a/docs/locales/ru/spiders/advanced.md b/docs/locales/ru/spiders/advanced.md
index e2928d8..82a3ec7 100644
--- a/docs/locales/ru/spiders/advanced.md
+++ b/docs/locales/ru/spiders/advanced.md
@@ -143,7 +143,17 @@ else:
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-Запись на диск атомарная, что защищает файл от частичной записи.
+При записи контрольной точки используется временный файл. Предыдущая контрольная точка заменяется только после успешной записи.
+
+!!! warning "Данные контрольной точки"
+
+ При включении `crawldir` модуль `pickle` в Python должен уметь сохранять значения ожидающих запросов, включая `meta` и аргументы запросов. Если сохранить значение невозможно, сохранение контрольной точки завершается ошибкой и обход останавливается. Объект `Selector` может работать в обработчике, но его нельзя сохранить таким способом.
+
+ Храните извлечённые значения, например строки или числа, вместо объектов `Selector`. Списки и словари также должны содержать только значения, которые можно сохранить:
+
+ ```python
+ yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+ ```
!!! tip
diff --git a/docs/locales/zh/spiders/advanced.md b/docs/locales/zh/spiders/advanced.md
index 71d0542..baadbe1 100644
--- a/docs/locales/zh/spiders/advanced.md
+++ b/docs/locales/zh/spiders/advanced.md
@@ -143,7 +143,17 @@ else:
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-磁盘写入采用原子操作,避免产生不完整的文件。
+检查点先写入临时文件,仅在写入成功后才替换之前的检查点。
+
+!!! warning "检查点数据"
+
+ 启用 `crawldir` 时,待处理请求中的值(包括 `meta` 和请求参数)必须能用 Python 的 `pickle` 模块保存。如果某个值无法保存,检查点保存就会失败,抓取也会停止。`Selector` 可以在回调中使用,但不能以这种方式保存。
+
+ 保存提取出的字符串或数字等值,而不是 `Selector` 对象。列表和字典也必须只包含可保存的值:
+
+ ```python
+ yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+ ```
!!! tip
diff --git a/docs/spiders/advanced.md b/docs/spiders/advanced.md
index ffa6548..f1814e8 100644
--- a/docs/spiders/advanced.md
+++ b/docs/spiders/advanced.md
@@ -143,7 +143,17 @@ You can change the interval as follows:
spider = MySpider(crawldir="crawl_data/my_spider", interval=120.0)
```
-The writing to the disk is atomic, so it's totally safe.
+Checkpoint writes use a temporary file and replace the previous checkpoint only after the write succeeds.
+
+!!! warning "Checkpoint data"
+
+ When you enable `crawldir`, values in pending requests, including `meta` and request arguments, must be saveable with Python's `pickle` module. If a value cannot be saved, the checkpoint fails and the crawl stops. A `Selector` can work in a callback but cannot be saved this way.
+
+ Store extracted values, such as strings or numbers, instead of `Selector` objects. Lists and dictionaries must also contain only saveable values:
+
+ ```python
+ yield response.follow("/details", meta={"title": str(response.css("h1::text").get(""))})
+ ```
!!! tip
@@ -427,4 +437,4 @@ class MySpider(Spider):
yield {"title": response.css("title::text").get("")}
```
-The log file directory is created automatically if it doesn't exist. Both console and file output use the same format.
\ No newline at end of file
+The log file directory is created automatically if it doesn't exist. Both console and file output use the same format.