Item Loader（项目加载器）

Item Loader 提供了一种便捷的机制来填充爬取到的 item。虽然 item 可以直接填充，但 Item Loader 提供了一个更方便的 API，可以通过自动化一些常见任务（例如在赋值之前解析原始提取数据）来从爬取过程中填充它们。

换句话说，item 提供爬取数据的容器，而 Item Loader 提供填充该容器的机制。

Item Loader 旨在提供一种灵活、高效且易于使用的机制，用于扩展和覆盖不同的字段解析规则，无论是按 spider 还是按源格式（HTML、XML 等），而不会变得难以维护。

注意

Item Loader 是 itemloaders 库的一个扩展，通过添加对 response（响应）的支持，使其更易于与 Scrapy 一起使用。

使用 Item Loader 填充 Item

要使用 Item Loader，您必须先实例化它。您可以带一个 item 对象实例化，或者不带，不带的情况下会在 Item Loader 的 __init__ 方法中，使用 ItemLoader.default_item_class 属性中指定的 item 类自动创建一个 item 对象。

然后，您开始将值收集到 Item Loader 中，通常使用 Selector（选择器）。您可以向同一个 item 字段添加多个值；Item Loader 知道以后如何使用适当的处理函数“连接”这些值。

注意

收集的数据在内部以列表形式存储，允许向同一个字段添加多个值。如果在创建加载器时传递了 item 参数，则 item 的每个值如果是可迭代的，将按原样存储；如果是单个值，则会被包装到列表中。

以下是在 Spider（爬虫）中使用 Item Loader 的典型示例，使用了在 Item 章节中声明的 Product item

from scrapy.loader import ItemLoader
from myproject.items import Product


def parse(self, response):
    l = ItemLoader(item=Product(), response=response)
    l.add_xpath("name", '//div[@class="product_name"]')
    l.add_xpath("name", '//div[@class="product_title"]')
    l.add_xpath("price", '//p[@id="price"]')
    l.add_css("stock", "p#stock")
    l.add_value("last_updated", "today")  # you can also use literal values
    return l.load_item()

快速查看该代码，我们可以看到 name 字段是从页面中的两个不同的 XPath 位置提取的

//div[@class="product_name"]
//div[@class="product_title"]

换句话说，数据是通过从两个 XPath 位置提取来收集的，使用了 add_xpath() 方法。这是之后将分配给 name 字段的数据。

之后，对 price 和 stock 字段使用了类似的方法调用（后者使用 CSS 选择器和 add_css() 方法），最后 last_update 字段直接使用字面值 (today) 通过另一种方法填充：add_value()。

最后，当所有数据收集完毕后，调用 ItemLoader.load_item() 方法，该方法会实际返回使用之前通过 add_xpath()、add_css() 和 add_value() 调用提取和收集的数据填充好的 item。

使用 Dataclass Item

默认情况下，dataclass item 在创建时要求传递所有字段。这在使用 dataclass item 和 item loader 时可能是一个问题：除非向加载器传递一个预先填充的 item，否则字段将使用加载器的 add_xpath()、add_css() 和 add_value() 方法增量填充。

解决这个问题的一种方法是使用 field() 函数并带有 default 参数来定义 item

from dataclasses import dataclass, field
from typing import Optional


@dataclass
class InventoryItem:
    name: Optional[str] = field(default=None)
    price: Optional[float] = field(default=None)
    stock: Optional[int] = field(default=None)

输入和输出处理器

一个 Item Loader 为每个 (item) 字段包含一个输入处理器和一个输出处理器。输入处理器在接收到提取的数据（通过 add_xpath()、add_css() 或 add_value() 方法）后立即处理数据，输入处理器的结果被收集并保存在 ItemLoader 内部。收集完所有数据后，调用 ItemLoader.load_item() 方法来填充并获取填充后的 item 对象。此时，输出处理器会接收到之前收集的数据（并经过输入处理器处理），输出处理器的结果就是最终分配给 item 的值。

我们来看一个例子，说明如何为一个特定字段调用输入和输出处理器（这同样适用于任何其他字段）

l = ItemLoader(Product(), some_selector)
l.add_xpath("name", xpath1)  # (1)
l.add_xpath("name", xpath2)  # (2)
l.add_css("name", css)  # (3)
l.add_value("name", "test")  # (4)
return l.load_item()  # (5)

所以发生的事情是

从 xpath1 中提取数据，并传递给 name 字段的输入处理器。输入处理器的结果被收集并保存在 Item Loader 中（但尚未分配给 item）。
从 xpath2 中提取数据，并传递给与 (1) 中相同的输入处理器。输入处理器的结果被追加到 (1) 中收集的数据（如果存在）中。
这种情况与之前的情况类似，不同之处在于数据是从 css CSS 选择器中提取的，并传递给与 (1) 和 (2) 中相同的输入处理器。输入处理器的结果被追加到 (1) 和 (2) 中收集的数据（如果存在）中。
这种情况也与之前的情况类似，不同之处在于要收集的值是直接分配的，而不是从 XPath 表达式或 CSS 选择器中提取的。然而，该值仍然会通过输入处理器。在这种情况下，由于该值不是可迭代的，因此在传递给输入处理器之前会被转换为包含单个元素的可迭代对象，因为输入处理器总是接收可迭代对象。
在步骤 (1)、(2)、(3) 和 (4) 中收集的数据会通过 name 字段的输出处理器。输出处理器的结果就是分配给 item 中 name 字段的值。

值得注意的是，处理器只是可调用对象，它们接收待解析的数据并返回解析后的值。因此，您可以使用任何函数作为输入或输出处理器。唯一的要求是它们必须接受一个（且仅一个）位置参数，该参数将是可迭代的。

2.0 版本更新：处理器不再必须是方法。

注意

输入和输出处理器都必须将一个可迭代对象作为它们的第一个参数。这些函数的输出可以是任何类型。输入处理器的结果将被添加到内部列表（在 Loader 中），该列表包含收集到的值（用于该字段）。输出处理器的结果是最终将分配给 item 的值。

您需要记住的另一件事是，输入处理器返回的值会在内部收集（在列表中），然后传递给输出处理器来填充字段。

最后但同样重要的是，itemloaders 库自带了一些方便的常用处理器。

声明 Item Loader

Item Loader 使用类定义语法进行声明。以下是一个示例

from itemloaders.processors import TakeFirst, MapCompose, Join
from scrapy.loader import ItemLoader


class ProductLoader(ItemLoader):
    default_output_processor = TakeFirst()

    name_in = MapCompose(str.title)
    name_out = Join()

    price_in = MapCompose(str.strip)

    # ...

如您所见，输入处理器使用 _in 后缀声明，而输出处理器使用 _out 后缀声明。您还可以使用 ItemLoader.default_input_processor 和 ItemLoader.default_output_processor 属性声明默认的输入/输出处理器。

声明输入和输出处理器

如上一节所示，输入和输出处理器可以在 Item Loader 定义中声明，并且通常以这种方式声明输入处理器。然而，还有另一个地方可以指定要使用的输入和输出处理器：在 Item 字段元数据中。以下是一个示例

import scrapy
from itemloaders.processors import Join, MapCompose, TakeFirst
from w3lib.html import remove_tags


def filter_price(value):
    if value.isdigit():
        return value


class Product(scrapy.Item):
    name = scrapy.Field(
        input_processor=MapCompose(remove_tags),
        output_processor=Join(),
    )
    price = scrapy.Field(
        input_processor=MapCompose(remove_tags, filter_price),
        output_processor=TakeFirst(),
    )

>>> from scrapy.loader import ItemLoader
>>> il = ItemLoader(item=Product())
>>> il.add_value("name", ["Welcome to my", "<strong>website</strong>"])
>>> il.add_value("price", ["&euro;", "<span>1000</span>"])
>>> il.load_item()
{'name': 'Welcome to my website', 'price': '1000'}

输入和输出处理器的优先级顺序如下

Item Loader 字段特定属性：field_in 和 field_out（最高优先级）
字段元数据（input_processor 和 output_processor 键）
Item Loader 默认值：ItemLoader.default_input_processor() 和 ItemLoader.default_output_processor()（最低优先级）

另请参阅：重用和扩展 Item Loader。

Item Loader 上下文

Item Loader 上下文是一个包含任意键/值的字典，在 Item Loader 中的所有输入和输出处理器之间共享。它可以在声明、实例化或使用 Item Loader 时传递。它们用于修改输入/输出处理器的行为。

例如，假设您有一个函数 parse_length，它接收一个文本值并从中提取长度

def parse_length(text, loader_context):
    unit = loader_context.get("unit", "m")
    # ... length parsing code goes here ...
    return parsed_length

通过接受 loader_context 参数，函数明确告诉 Item Loader 它可以接收 Item Loader 上下文，因此 Item Loader 在调用时会传递当前活动的上下文，处理器函数（在本例中是 parse_length）因此可以使用它们。

修改 Item Loader 上下文值有几种方法

通过修改当前活动的 Item Loader 上下文（context 属性）
```
loader = ItemLoader(product)
loader.context["unit"] = "cm"
```
在 Item Loader 实例化时（Item Loader __init__ 方法的关键字参数存储在 Item Loader 上下文中）
```
loader = ItemLoader(product, unit="cm")
```
在声明 Item Loader 时，对于那些支持使用 Item Loader 上下文进行实例化的输入/输出处理器。MapCompose 就是其中之一
```
class ProductLoader(ItemLoader):
    length_out = MapCompose(parse_length, unit="cm")
```

ItemLoader 对象

class scrapy.loader.ItemLoader(item: Any = None, selector: Selector | None = None, response: TextResponse | None = None, parent: itemloaders.ItemLoader | None = None, **context: Any)[source]

一种用户友好的抽象，用于通过将字段处理器应用于爬取的数据来填充 item。当使用 selector 或者 response 实例化时，它支持使用 selector（选择器）从网页中提取数据。

参数：

item (scrapy.item.Item) – 要填充的 item 实例，通过后续调用 add_xpath()、add_css() 或 add_value() 来填充。
selector (Selector 对象) – 使用 add_xpath()、add_css()、replace_xpath() 或 replace_css() 方法时，用于提取数据的选择器。
response (Response 对象) – 用于使用 default_selector_class 构造选择器的响应，除非给定了 selector 参数，在这种情况下此参数将被忽略。

如果未提供 item，将使用 default_item_class 中的类自动实例化一个。

item、selector、response 和剩余的关键字参数会被分配到 Loader 上下文（通过 context 属性访问）。

item: 此 Item Loader 正在解析的 item 对象。这主要用作属性，因此，当尝试覆盖此值时，您可能首先需要查看 default_item_class。

context: 此 Item Loader 当前活动的 Context（上下文）。

default_item_class: 一个 item 类（或工厂），用于在 __init__ 方法中未提供 item 时实例化 item。

default_input_processor: 对于未指定输入处理器的字段，使用的默认输入处理器。

default_output_processor: 对于未指定输出处理器的字段，使用的默认输出处理器。

default_selector_class: 用于构造此 ItemLoader 的 selector 的类，如果在 __init__ 方法中仅提供了 response。如果提供了 selector，则忽略此属性。此属性有时在子类中被覆盖。

selector: 用于提取数据的 Selector 对象。它要么是在 __init__ 方法中给定的 selector，要么是使用 default_selector_class 从 __init__ 方法中给定的 response 创建的。此属性是只读的。





add_css(field_name: str | None, css: str | Iterable[str], *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Self
类似于 ItemLoader.add_value()，但接收的是 CSS 选择器而不是值，该选择器用于从与此 ItemLoader 关联的选择器中提取 unicode 字符串列表。
有关 kwargs，请参阅 get_css()。

参数：
css (str) – 用于提取数据的 CSS 选择器

返回：
当前 ItemLoader 实例，用于方法链式调用。

返回类型：
ItemLoader


示例
# HTML snippet: <p class="product-name">Color TV</p>
loader.add_css('name', 'p.product-name')
# HTML snippet: <p id="price">the price is $1200</p>
loader.add_css('price', 'p#price', re='the price is (.*)')






add_jmes(field_name: str | None, jmes: str, *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Self[source]
类似于 ItemLoader.add_value()，但接收 JMESPath 选择器而不是值，用于从与此 ItemLoader 关联的选择器中提取 unicode 字符串列表。
参见 get_jmes() 以了解 kwargs。

参数：
jmes (str) – 用于提取数据的 JMESPath 选择器

返回：
当前 ItemLoader 实例，用于方法链式调用。

返回类型：
ItemLoader


示例
# HTML snippet: {"name": "Color TV"}
loader.add_jmes('name')
# HTML snippet: {"price": the price is $1200"}
loader.add_jmes('price', TakeFirst(), re='the price is (.*)')






add_value(field_name: str | None, value: Any, *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Self[source]
处理然后添加给定的 value 到给定字段。
该值首先通过 get_value()，提供 processors 和 kwargs，然后通过 字段输入处理器 并将其结果附加到该字段已收集的数据中。如果该字段已包含收集到的数据，则添加新数据。
给定的 field_name 可以为 None，在这种情况下可以添加多个字段的值。处理后的值应为一个将 field_name 映射到值的字典。

返回：
当前 ItemLoader 实例，用于方法链式调用。

返回类型：
ItemLoader


示例
loader.add_value('name', 'Color TV')
loader.add_value('colours', ['white', 'blue'])
loader.add_value('length', '100')
loader.add_value('name', 'name: foo', TakeFirst(), re='name: (.+)')
loader.add_value(None, {'name': 'foo', 'sex': 'male'})






add_xpath(field_name: str | None, xpath: str | Iterable[str], *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Self[source]
类似于 ItemLoader.add_value()，但接收 XPath 而不是值，用于从与此 ItemLoader 关联的选择器中提取字符串列表。
参见 get_xpath() 以了解 kwargs。

参数：
xpath (str) – 用于提取数据的 XPath

返回：
当前 ItemLoader 实例，用于方法链式调用。

返回类型：
ItemLoader


示例
# HTML snippet: <p class="product-name">Color TV</p>
loader.add_xpath('name', '//p[@class="product-name"]')
# HTML snippet: <p id="price">the price is $1200</p>
loader.add_xpath('price', '//p[@id="price"]', re='the price is (.*)')






get_collected_values(field_name: str) → List[Any][source]
返回给定字段的已收集值。




get_css(css: str | Iterable[str], *processors: Callable[[...], Any], re: str | Pattern[str] | None = None, **kw: Any) → Any[source]
类似于 ItemLoader.get_value()，但接收 CSS 选择器而不是值，用于从与此 ItemLoader 关联的选择器中提取 unicode 字符串列表。

参数：

css (str) – 用于提取数据的 CSS 选择器
re (str or Pattern[str]) – 用于从选定的 CSS 区域提取数据的正则表达式



示例
# HTML snippet: <p class="product-name">Color TV</p>
loader.get_css('p.product-name')
# HTML snippet: <p id="price">the price is $1200</p>
loader.get_css('p#price', TakeFirst(), re='the price is (.*)')






get_jmes(jmes: str | Iterable[str], *processors: Callable[[...], Any], re: str | Pattern[str] | None = None, **kw: Any) → Any[source]
类似于 ItemLoader.get_value()，但接收 JMESPath 选择器而不是值，用于从与此 ItemLoader 关联的选择器中提取 unicode 字符串列表。

参数：

jmes (str) – 用于提取数据的 JMESPath 选择器
re (str or Pattern) – 用于从选定的 JMESPath 提取数据的正则表达式



示例
# HTML snippet: {"name": "Color TV"}
loader.get_jmes('name')
# HTML snippet: {"price": the price is $1200"}
loader.get_jmes('price', TakeFirst(), re='the price is (.*)')






get_output_value(field_name: str) → Any[source]
返回使用 输出处理器 解析的给定字段的已收集值。此方法不会填充或完全修改 item。




get_value(value: Any, *processors: Callable[[...], Any], re: str | Pattern[str] | None = None, **kw: Any) → Any[source]
使用给定的 processors 和关键字参数处理给定的 value。
可用的关键字参数

参数：
re (str or Pattern[str]) – 用于使用 extract_regex() 方法从给定值中提取数据的正则表达式，在 processors 之前应用


示例
>>> from itemloaders import ItemLoader
>>> from itemloaders.processors import TakeFirst
>>> loader = ItemLoader()
>>> loader.get_value('name: foo', TakeFirst(), str.upper, re='name: (.+)')
'FOO'






get_xpath(xpath: str | Iterable[str], *processors: Callable[[...], Any], re: str | Pattern[str] | None = None, **kw: Any) → Any[source]
类似于 ItemLoader.get_value()，但接收 XPath 而不是值，用于从与此 ItemLoader 关联的选择器中提取 unicode 字符串列表。

参数：

xpath (str) – 用于提取数据的 XPath
re (str or Pattern[str]) – 用于从选定的 XPath 区域提取数据的正则表达式



示例
# HTML snippet: <p class="product-name">Color TV</p>
loader.get_xpath('//p[@class="product-name"]')
# HTML snippet: <p id="price">the price is $1200</p>
loader.get_xpath('//p[@id="price"]', TakeFirst(), re='the price is (.*)')






load_item() → Any[source]
用迄今为止收集到的数据填充 item，并返回它。收集到的数据首先通过 输出处理器 以获取分配给每个 item 字段的最终值。




nested_css(css: str, **context: Any) → Self[source]
创建一个带有 CSS 选择器的嵌套加载器。提供的选择器相对于与此 ItemLoader 关联的选择器应用。嵌套加载器与父级 ItemLoader 共享 item，因此对 add_xpath()、add_value()、replace_value() 等的调用将按预期运行。




nested_xpath(xpath: str, **context: Any) → Self[source]
使用 xpath 选择器创建一个嵌套加载器。提供的选择器将相对于与此 ItemLoader 关联的选择器应用。嵌套加载器与父级 ItemLoader 共享 item，因此调用 add_xpath()、add_value()、replace_value() 等将按预期运行。




replace_css(field_name: str | None, css: str | Iterable[str], *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Self[source]
类似于 add_css()，但会替换收集到的数据而不是添加它。

返回：
当前 ItemLoader 实例，用于方法链式调用。

返回类型：
ItemLoader






replace_jmes(field_name: str | None, jmes: str | Iterable[str], *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Self[source]
类似于 add_jmes()，但会替换收集到的数据而不是添加它。

返回：
当前 ItemLoader 实例，用于方法链式调用。

返回类型：
ItemLoader






replace_value(field_name: str | None, value: Any, *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Self[source]
类似于 add_value()，但使用新值替换收集到的数据而不是添加它。

返回：
当前 ItemLoader 实例，用于方法链式调用。

返回类型：
ItemLoader






replace_xpath(field_name: str | None, xpath: str | Iterable[str], *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Self[source]
类似于 add_xpath()，但会替换收集到的数据而不是添加它。

返回：
当前 ItemLoader 实例，用于方法链式调用。

返回类型：
ItemLoader



嵌套加载器
从文档的子部分解析相关值时，创建嵌套加载器会很有用。想象一下，您正在从页面底部（看起来类似于）提取详细信息：
示例
<footer>
    <a class="social" href="https://facebook.com/whatever">Like Us</a>
    <a class="social" href="https://twitter.com/whatever">Follow Us</a>
    <a class="email" href="mailto:whatever@example.com">Email Us</a>
</footer>


没有嵌套加载器，您需要为要提取的每个值指定完整的 xpath（或 css）。
示例
loader = ItemLoader(item=Item())
# load stuff not in the footer
loader.add_xpath("social", '//footer/a[@class = "social"]/@href')
loader.add_xpath("email", '//footer/a[@class = "email"]/@href')
loader.load_item()


相反，您可以创建一个带有页脚选择器的嵌套加载器，并相对于页脚添加值。功能是相同的，但您避免重复页脚选择器。
示例
loader = ItemLoader(item=Item())
# load stuff not in the footer
footer_loader = loader.nested_xpath("//footer")
footer_loader.add_xpath("social", 'a[@class = "social"]/@href')
footer_loader.add_xpath("email", 'a[@class = "email"]/@href')
# no need to call footer_loader.load_item()
loader.load_item()


您可以任意嵌套加载器，它们适用于 xpath 或 css 选择器。一般来说，当嵌套加载器使您的代码更简单时使用它们，但不要过度嵌套，否则您的解析器可能会变得难以阅读。


重用和扩展 Item Loaders
随着您的项目越来越大，爬虫越来越多，维护成为一个根本问题，特别是当您必须处理针对每个爬虫的许多不同的解析规则，存在大量例外，但同时又想重用通用处理器时。
Item Loaders 旨在减轻解析规则的维护负担，同时不损失灵活性，并提供一种方便的机制来扩展和覆盖它们。因此，Item Loaders 支持传统的 Python 类继承，以处理特定爬虫（或爬虫组）的差异。
例如，假设某个特定网站将其产品名称用三个破折号括起来（例如 ---Plasma TV---），并且您不想在最终的产品名称中抓取这些破折号。
以下是您如何通过重用和扩展默认的产品 Item Loader（ProductLoader）来移除这些破折号：
from itemloaders.processors import MapCompose
from myproject.ItemLoaders import ProductLoader


def strip_dashes(x):
    return x.strip("-")


class SiteSpecificLoader(ProductLoader):
    name_in = MapCompose(strip_dashes, ProductLoader.name_in)


扩展 Item Loaders 的另一种非常有用的情况是当您有多种源格式时，例如 XML 和 HTML。在 XML 版本中，您可能希望删除 CDATA 出现的内容。以下是演示如何执行此操作的示例：
from itemloaders.processors import MapCompose
from myproject.ItemLoaders import ProductLoader
from myproject.utils.xml import remove_cdata


class XmlProductLoader(ProductLoader):
    name_in = MapCompose(remove_cdata, ProductLoader.name_in)


这就是您通常扩展输入处理器的方式。
至于输出处理器，更常见的是在字段元数据中声明它们，因为它们通常仅取决于字段，而不取决于每个特定网站的解析规则（输入处理器则不同）。另请参见：声明输入和输出处理器。
还有许多其他可能的扩展、继承和覆盖 Item Loaders 的方法，不同的 Item Loaders 层次结构可能更适合不同的项目。Scrapy 只提供机制；它不强制要求您的 Loaders 集合采用任何特定的组织方式——这取决于您和您的项目的需求。