Item 加载器

Item 加载器提供了一种方便的机制来填充抓取的 item。尽管 item 可以直接填充，但 Item 加载器提供了一个更方便的 API，通过自动化一些常见任务（例如在分配之前解析原始提取数据），从抓取过程中填充它们。

换句话说，item 提供了抓取数据的容器，而 Item 加载器提供了填充该容器的机制。

Item 加载器旨在提供一种灵活、高效且易于使用的机制，用于扩展和覆盖不同的字段解析规则，无论是按爬虫还是按源格式（HTML、XML 等），而不会成为维护的噩梦。

注意

Item 加载器是 itemloaders 库的扩展，通过增加对响应的支持，使其更易于与 Scrapy 配合使用。

使用 Item 加载器填充 item

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

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

注意

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

以下是 Spider 中 Item 加载器的典型用法，使用了 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"]

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

之后，类似调用用于 price 和 stock 字段（后者使用 add_css() 方法的 CSS 选择器），最后 last_update 字段使用不同的方法 add_value() 直接用字面值 (today) 填充。

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

使用数据类 item

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

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

from dataclasses import dataclass, field


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

输入和输出处理器

一个 Item 加载器为每个（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 加载器中（但尚未分配给 item）。
从 xpath2 提取数据，并通过与 (1) 中相同的 输入处理器。输入处理器的结果被附加到 (1) 中收集的数据（如果有的话）。
这种情况与前几种情况类似，不同之处在于数据是从 css CSS 选择器中提取的，并通过与 (1) 和 (2) 中相同的 输入处理器。输入处理器的结果被附加到 (1) 和 (2) 中收集的数据（如果有的话）。
这种情况也与前几种情况类似，不同之处在于要收集的值是直接分配的，而不是从 XPath 表达式或 CSS 选择器中提取的。但是，该值仍然会通过输入处理器。在这种情况下，由于该值不可迭代，因此在将其传递给输入处理器之前，会将其转换为包含单个元素的 iterable，因为输入处理器总是接收 iterable。
步骤 (1)、(2)、(3) 和 (4) 中收集的数据会通过 name 字段的 输出处理器。输出处理器的结果是分配给 item 中 name 字段的值。

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

注意

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

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

最后但同样重要的是，itemloaders 内置了一些常用处理器以方便使用。

声明 Item 加载器

Item 加载器使用类定义语法声明。下面是一个例子

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 加载器定义中声明，并且以这种方式声明输入处理器非常常见。然而，还有一个地方可以指定要使用的输入和输出处理器：在 Item 字段元数据中。下面是一个例子

from dataclasses import dataclass, field

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


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


@dataclass
class Product:
    name: str | None = field(
        default=None,
        metadata={
            "input_processor": MapCompose(remove_tags),
            "output_processor": Join(),
        },
    )
    price: str | None = field(
        default=None,
        metadata={
            "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 加载器字段特定属性：field_in 和 field_out（最高优先级）
字段元数据（input_processor 和 output_processor 键）
Item 加载器默认值：ItemLoader.default_input_processor() 和 ItemLoader.default_output_processor()（最低优先级）

另请参阅：重用和扩展 Item 加载器。

Item 加载器上下文

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

例如，假设您有一个函数 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 加载器它能够接收 Item 加载器上下文，因此 Item 加载器在调用它时会传递当前活动的上下文，处理器函数（在本例中为 parse_length）因此可以使用这些上下文。

有几种方法可以修改 Item 加载器上下文值

通过修改当前活动的 Item 加载器上下文（context 属性）
```
loader = ItemLoader(product)
loader.context["unit"] = "cm"
```
在 Item 加载器实例化时（Item 加载器 __init__ 方法的关键字参数存储在 Item 加载器上下文中）
```
loader = ItemLoader(product, unit="cm")
```
在 Item 加载器声明时，对于那些支持使用 Item 加载器上下文实例化的输入/输出处理器。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 实例化时，它支持使用选择器从网页中提取数据。

参数:

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

如果没有给出 item，则会自动使用 default_item_class 中的类实例化一个。

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

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

context: 此 Item 加载器当前活动的上下文。

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

default_input_processor: 为那些未指定输入处理器的字段使用的默认输入处理器。

default_output_processor: 为那些未指定输出处理器的字段使用的默认输出处理器。

default_selector_class: 用于构造此 ItemLoader 的 selector 的类，如果 __init__ 方法中只给出了一个响应。如果 __init__ 方法中给出了选择器，则此属性将被忽略。此属性有时会在子类中被覆盖。

selector: 用于从中提取数据的 Selector 对象。它要么是 __init__ 方法中给出的选择器，要么是使用 default_selector_class 从 __init__ 方法中给出的响应创建的选择器。此属性旨在只读。

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 字符串列表。

请参阅 get_css() 了解 kwargs。

参数:: 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

类似于 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

处理并为给定字段添加给定 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

类似于 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]: 返回给定字段的已收集值。

get_css(css: str | Iterable[str], *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Any

类似于 ItemLoader.get_value()，但接收 CSS 选择器而不是值，用于从与此 ItemLoader 关联的选择器中提取 Unicode 字符串列表。

参数:

css (str) – 用于从中提取数据的 CSS 选择器
re (str 或 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

类似于 ItemLoader.get_value()，但接收 JMESPath 选择器而不是值，用于从与此 ItemLoader 关联的选择器中提取 Unicode 字符串列表。

参数:

jmes (str) – 用于从中提取数据的 JMESPath 选择器
re (str 或 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: 返回使用输出处理器解析的给定字段的已收集值。此方法根本不会填充或修改 item。

get_value(value: Any, *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Any

通过给定 processors 和关键字参数处理给定 value。

可用关键字参数

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

示例

>>> 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

类似于 ItemLoader.get_value()，但接收 XPath 而不是值，用于从与此 ItemLoader 关联的选择器中提取 Unicode 字符串列表。

参数:

xpath (str) – 用于从中提取数据的 XPath
re (str 或 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: 用迄今为止收集到的数据填充 item，并返回它。收集到的数据首先通过输出处理器，以获取分配给每个 item 字段的最终值。

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

nested_xpath(xpath: str, **context: Any) → Self: 使用 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

类似于 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

类似于 add_jmes()，但替换而不是添加已收集的数据。

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

replace_value(field_name: str | None, value: Any, *processors: Callable[..., Any], re: str | Pattern[str] | None = None, **kw: Any) → Self

类似于 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[来源]

类似于 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 加载器

随着项目越来越大，爬虫越来越多，维护成为一个基本问题，特别是当您必须处理每个爬虫的许多不同解析规则，存在大量例外，但也希望重用通用处理器时。

Item 加载器旨在减轻解析规则的维护负担，同时不失灵活性，并提供方便的机制来扩展和覆盖它们。因此，Item 加载器支持传统的 Python 类继承，以处理特定爬虫（或爬虫组）的差异。

例如，假设某个特定网站将其产品名称用三个破折号括起来（例如 ---等离子电视---），而您不希望最终产品名称中包含这些破折号。

下面是如何通过重用和扩展默认的 Product Item 加载器（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 加载器非常有帮助的另一个场景是当您有多种源格式时，例如 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 加载器，不同的 Item 加载器层级可能更适合不同的项目。Scrapy 只提供了机制；它不强制您的加载器集合采用任何特定的组织方式——这取决于您和您项目的需求。