diff --git a/docs/topics/items.rst b/docs/topics/items.rst index f05746934..7a1c1f907 100644 --- a/docs/topics/items.rst +++ b/docs/topics/items.rst @@ -136,6 +136,45 @@ Example: another_field = attr.ib() +.. _pydantic-items: + +Pydantic models +--------------- + +`Pydantic `_ models allow the defining of item +classes with field names, so that :ref:`item exporters ` can +export all fields by default even if the first scraped object does not have +values for all of them. + +Additionally, ``pydantic`` items also allow you to: + +* define the type and default value of each defined field with run-time type + validation. + +* define custom field metadata through `pydantic.Field + `_, which can be used to + :ref:`customize serialization `. + +* benefit from automatic data validation and conversion based on type + annotations. + +In order to use this type, the `pydantic package `_ +needs to be installed. + +Example: + +.. code-block:: python + + from pydantic import BaseModel, Field + + + class CustomItem(BaseModel): + one_field: str = Field(default="", description="First field") + another_field: int = Field(default=0, description="Second field") + +.. note:: Unlike other item types, Pydantic models enforce field types at + run time and will raise validation errors for invalid data types. + Working with Item objects =========================