Scrapy SEP-008 深度解读：Item Parsers 提案如何演变为 Item Loaders 加载器机制

SEP-008 是 Scrapy 增强提案（Scrapy Enhancement Proposal）中编号为 8 的一份历史提案，标题为 “Item Parsers”，由 Pablo Hoffman 于 2009-08-11 提出，最终状态为 “Final (implemented with variations)”，并取代了 sep-001、sep-002、sep-003、sep-005 四份早期提案。它奠定了 Scrapy 中“Item 数据填充”这一核心子系统的 API 形态：提案中设计的 ItemParser 类、输入/输出解析器（input/output parser）概念、*_in/*_out 字段声明语法，最终以 “Item Loaders” 之名（配合少量 API 方法名与语义的微调）落地为今天 scrapy.loader.ItemLoader 的底层机制。读完本文，你将理解 Item Loader “收集值 → 输入处理 → 存储 → 输出处理 → 写回 Item” 的数据流是如何设计出来的，以及提案中的每个 API 名词（如 populate_item、MapConcat、get_collected_values）与当前仓库源码（scrapy/loader/__init__.py、itemloaders 依赖、tests/test_loader.py）中实现的一一对应关系。

一、提案背景：从 RobustItem 到 ItemBuilder 再到 ItemParser

要理解 SEP-008 的动机，需要回看它取代的前序提案。在 0.7 版本之前，Scrapy 用已废弃的 RobustItem 及其 attribute() 方法来填充 Item 字段，把 add=True 之类的修饰符和适配器参数混在关键字参数里，提案作者称之为 “ugly”。sep-001 则对两套候选 API 做了逐项对比：

• ItemForm：用下标赋值风格 ia["url"] = ...、ia["headline"] += ...，优点是 API 与 Item 本身一致、风格简洁；缺点是运行时参数无法在赋值时传入，只能通过为每个 Spider 覆写适配器来定制。
• ItemBuilder：用方法风格 il.add_value("url", ...)、il.replace_value("headline", ...)，允许在赋值时向适配器传递运行时参数（如 il.add_value("width", x, default_unit="cm")），还支持通过 get_value() 检查中间提取结果。

SEP-001 的结论方向是把 ItemBuilder 的方法式 API 定为 Scrapy 0.7 的推荐机制。此后 sep-002、sep-003、sep-005 继续细化了这套 “Item Builders/Loader” 方案，而 SEP-008 给出的 “Item Parser” 是这条演进线上的最终 API 形态——提案文档开头的 Obsoletes 行明确声明它终结了上述四份提案。

SEP-008 自身还带有一段关键注释，说明最终实现与提案名的差异：

This is the API that was finally implemented with the name "Item Loaders", instead of "Item Parsers" along with some other minor fine tuning to the API methods and semantics.

也就是说，提案里的“parser”最终统一改称为“processor”，类名从 ItemParser 改为 ItemLoader，这是阅读本提案时最重要的映射关系。

二、数据流（Dataflow）：三段式处理模型

SEP-008 用一段极简的编号列表定义了每个字段值的完整生命周期，这是整个机制的骨架：

1. ItemParser.add_value()
   1. input_parser（先经输入解析器）
   2. store（存入内部存储）
2. ItemParser.add_xpath()（仅 XPathItemParser 提供）
   1. selector.extract()（先用选择器提取）
   2. input_parser
   3. store
3. ItemParser.populate_item()（如 get_item）
   1. output_parser（再经输出解析器）
   2. assign field（写回 Item 字段）

这条数据流有三个设计要点，在当前实现中均被完整保留：

• 同一字段可累积多个值：add_value 与 add_xpath 的产物都追加到内部存储（“store”），而不是覆盖；只有 replace_value 才清空重存。这与 sep-001 中 “Adding a value to a list attribute/field” 场景一脉相承。
• 输入处理发生在收集时，输出处理发生在加载时：input parser 在每次 add_* 调用时立即执行；output parser 只在 populate_item()（即现在的 load_item()）被调用、Item 即将写回时才执行。
• XPath 提取只是输入源的一种：add_xpath 比 add_value 多一步 selector.extract()，但两条路径在“经过 input parser 后入 store”这一点上完全对称。

当前仓库中 docs/topics/loaders.rst 对同一模型给出了更详细的运行时描述：收集的数据内部以列表存储；add_value 传入的非迭代值会被包装成单元素迭代器后再交给输入处理器；输出处理器的返回值才是最终写入 Item 的值。

三、模块与类设计：从 scrapy.contrib.itemparser 到 scrapy.loader

SEP-008 提议的模块结构为：

• scrapy.contrib.itemparser.ItemParser
• scrapy.contrib.itemparser.XPathItemParser
• scrapy.contrib.itemparser.parsers.MapConcat（由早期的 TreeExpander 改名而来）
• scrapy.contrib.itemparser.parsers.TakeFirst
• scrapy.contrib.itemparser.parsers.Join
• scrapy.contrib.itemparser.parsers.Identity

对照当前仓库，这些模块和类的实际落点是：

提案中的设计	当前实现
scrapy.contrib.itemparser 模块	核心逻辑抽取到独立的 itemloaders 包，pyproject.toml 声明依赖 itemloaders>=1.0.1；仓库内仅保留薄封装 scrapy/loader/init.py
ItemParser / XPathItemParser	统一为 itemloaders.ItemLoader，Scrapy 侧子类为 scrapy.loader.ItemLoader，通过 add_xpath/add_css 提供选择器提取能力
parsers.MapConcat	itemloaders.processors.MapConcat
parsers.TakeFirst / Join / Identity	itemloaders.processors.TakeFirst / Join / Identity

在 scrapy/loader/init.py 中可以看到，Scrapy 的 ItemLoader 直接继承自 itemloaders.ItemLoader，只追加了与 Scrapy 生态相关的部分：

class ItemLoader(itemloaders.ItemLoader):
    default_item_class: type = Item
    default_selector_class = Selector

即默认 Item 类为 scrapy/item.py 中的 scrapy.item.Item，默认选择器类为 scrapy.Selector。scrapy/item.py 中的 Field 是字段元数据容器（class Field(dict)），Item 的字段声明与处理器元数据正是 SEP-008 “在 Fields 中声明 parser” 一节在当下的载体。

四、Public API：提案原文、替代提案与最终实现的三方对照

SEP-008 最有价值的部分是它同时列出了“正式公共 API”与“替代公共 API 提案”两个版本——后者正是最终落地的命名。逐条对照如下：

4.1 提案原文 API（ItemParser 命名）

• ItemParser.add_value()
• ItemParser.replace_value()
• ItemParser.populate_item()（返回填充后的 item）
• ItemParser.get_collected_values()（注意 values 带 “s”）
• ItemParser.parse_field()
• ItemParser.get_input_parser()
• ItemParser.get_output_parser()
• ItemParser.context
• ItemParser.default_item_class
• ItemParser.default_input_parser
• ItemParser.default_output_parser
• ItemParser.*field*_in
• ItemParser.*field*_out

4.2 替代提案 API（ItemLoader 命名，最终采用）

• ItemLoader.add_value()
• ItemLoader.replace_value()
• ItemLoader.load_item()（返回加载后的 item）
• ItemLoader.get_stored_values() 或 ItemLoader.get_values()
• ItemLoader.get_output_value()
• ItemLoader.get_input_processor() 或 ItemLoader.get_in_processor()（短名）
• ItemLoader.get_output_processor() 或 ItemLoader.get_out_processor()（短名）
• ItemLoader.context
• ItemLoader.default_item_class
• ItemLoader.default_input_processor 或 ItemLoader.default_in_processor()（短名）
• ItemLoader.default_output_processor 或 ItemLoader.default_out_processor（短名）
• ItemLoader.*field*_in
• ItemLoader.*field*_out

4.3 与当前实现的映射

对照 scrapy/loader/init.py 的 docstring 与 itemloaders 暴露的方法，最终保留下来的名称为：

提案（ItemParser）	替代提案（ItemLoader）	当前实际方法/属性
add_value()	add_value()	add_value()，另有 add_xpath() / add_css()
replace_value()	replace_value()	replace_value() / replace_xpath() / replace_css()
populate_item()	load_item()	load_item()
get_collected_values()	get_stored_values()	get_stored_values()
parse_field()	get_output_value()	由 get_stored_values() + 输出处理器组合承担
get_input_parser()	get_input_processor()	get_input_processor()
get_output_parser()	get_output_processor()	get_output_processor()
context	context	context
default_item_class	default_item_class	default_item_class（源码 L89）
default_input_parser	default_input_processor	default_input_processor
default_output_parser	default_output_processor	default_output_processor
*field*_in / *field*_out	*field*_in / *field*_out	同左，声明语法完全继承

可见提案中的命名分歧（parser vs processor、populate_item vs load_item、get_collected_values vs get_stored_values）最终全部收敛到替代提案的命名上，而 *_in/*_out 声明语法与 context、default_item_class 等类属性则一字未改地保留了下来。

五、使用示例：声明 Item Parsers（Loaders）

SEP-008 给出的第一个使用示例展示了如何在类上声明字段级解析器：

#!python
from scrapy.contrib.itemparser import XPathItemParser, parsers


class ProductParser(XPathItemParser):
    name_in = parsers.MapConcat(removetags, filterx)
    price_in = parsers.MapConcat(...)

    price_out = parsers.TakeFirst()

其中 name_in 表示 name 字段的输入解析器：MapConcat（前身 TreeExpander）把输入的可迭代数据逐个展开、分别经过 removetags 与 filterx 处理后重新合并；price_out 表示 price 字段的输出解析器 TakeFirst，即从累积值中只取第一个。

同样的代码在今天的 Scrapy 中写作（导入路径与类名按最终实现调整）：

from itemloaders.processors import MapCompose, TakeFirst
from scrapy.loader import ItemLoader
from myproject.items import Product


class ProductLoader(ItemLoader):
    default_output_processor = TakeFirst()

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

典型的使用流程在 Spider 回调中（摘自 docs/topics/loaders.rst）：

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")  # 也可以直接塞字面量
    return l.load_item()

这里 name 从两个 XPath 位置收集（对应数据流中 add_xpath 的多次调用，结果在 store 中累积），stock 走 CSS 选择器，last_updated 走 add_value 字面量路径（对应数据流第 1 步），最后 load_item() 触发各字段的输出处理器并写回 Item（对应第 3 步）。

注意 scrapy/loader/init.py 中 __init__ 的参数签名 (item, selector, response, parent, **context)：若只给 response 而不给 selector，会用 default_selector_class 自动构造选择器；其余关键字参数会并入 context。这正是提案 ItemParser.context 属性在实现层面的入口——**context 键值对被存进上下文供处理器使用。

六、在 Field 中声明解析器：从 Field(output_parser=...) 到字段元数据

SEP-008 的第二个示例展示了把解析器声明放在 Field 上，而不是 Loader 上：

#!python
class Product(Item):
    name = Field(output_parser=parsers.Join(), ...)
    price = Field(output_parser=parsers.TakeFirst(), ...)

    description = Field(input_parser=parsers.MapConcat(removetags))

这一设计的意义在于：解析规则跟着字段走，而不是跟着 Loader 走，使得不同 Loader 处理同一 Item 时行为保持一致。当前仓库中这条路径依然存在——scrapy/item.py 的 Field 是一个 dict 子类，专门用来携带元数据，Item 类创建时由 ItemMeta 元类把所有 Field 属性收集进 fields 字典（scrapy/item.py）。

对于 dataclass 风格的 Item（现代写法），元数据通过 field(metadata=...) 传入，docs/topics/loaders.rst 给出了现行示例：

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()
Product(name='Welcome to my website', price='1000')

处理器优先级（Precedence）

提案中同时存在“Loader 上声明 *field*_in”和“Field 上声明 parser”两种位置，由此产生优先级问题。当前官方文档明确了统一规则（对输入和输出处理器均适用）：

1. Item Loader 的字段级属性：field_in 与 field_out（优先级最高）；
2. 字段元数据中的 input_processor / output_processor 键；
3. Item Loader 默认值：default_input_processor 与 default_output_processor（优先级最低）。

也就是说，SEP-008 中“Loader 级声明”与“Field 级声明”两套机制不仅都保留了下来，还形成了清晰的覆盖顺序。

七、Context：让处理器可配置的设计

提案 API 中的 ItemParser.context 属性解决的是“同一个处理器函数在不同场景下需要不同参数”的问题。官方文档中的示例是：

def parse_length(text, loader_context):
    unit = loader_context.get("unit", "m")
    # ... 解析长度值的代码 ...
    return parsed_length

处理器函数只要接受 loader_context 参数，Item Loader 就会在调用时把当前上下文传进去。上下文的三种注入方式（均源自提案 context 属性 + __init__ 关键字参数的设计）：

1. 直接修改 loader.context 字典：loader.context["unit"] = "cm"；
2. 实例化时传关键字参数（__init__ 的 **context 会并入上下文，见 scrapy/loader/init.py）：ItemLoader(product, unit="cm")；
3. 声明时用支持上下文的处理器包装，如 length_out = MapCompose(parse_length, unit="cm")。

从源码结构看，**context: Any 参数被原样透传给 itemloaders.ItemLoader.__init__，因此 Scrapy 侧不需要任何额外处理，上下文机制完全由基类承担。

八、嵌套 Loader 与扩展机制：提案之外的后续演进

值得说明的是，当前实现中有两个能力超出了 SEP-008 提案文本本身：

• 嵌套 Loader（Nested Loaders）：通过 nested_xpath() / nested_css() 创建以文档子区域为作用域的 Loader，避免在每条 add_xpath 中重复写完整前缀。例如解析页脚社交链接时：

loader = ItemLoader(item=Item())
footer_loader = loader.nested_xpath("//footer")
footer_loader.add_xpath("social", 'a[@class = "social"]/@href')
footer_loader.add_xpath("email", 'a[@class = "email"]/@href')
loader.load_item()

对应测试见 tests/test_loader.py 的 test_nested_xpath。从源码结构看，这利用了 __init__ 签名中的 parent 参数（scrapy/loader/init.py），嵌套 Loader 共享同一 Item 与上下文。

• 通过类继承扩展/覆盖处理器：官方文档给出的典型模式是把父 Loader 的处理器包进 MapCompose 再前置一步新逻辑：

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

提案中 *field*_in/*field*_out 作为类属性的设计（而非实例配置）正是为了让 Python 继承天然可用——这与 SEP-001 里 “Using different adaptors per Spider/Site” 的场景诉求直接呼应。

九、测试用例佐证：数据流设计的行为契约

tests/test_loader.py 中的用例可以直接对应到 SEP-008 数据流的三个环节：

• store 的追加语义（数据流第 1、2 步）：InitializationTestMixin 中，初始 Item 值为 name="foo" 的 Loader，add_value("name", "bar") 后 load_item() 得到 {"name": ["foo", "bar"]}；若初始值是列表 ["foo", "bar"] 且追加单值，则得到三元素列表——证明“store 内部用列表累积、单值自动包装”的契约（tests/test_loader.py）。
• load_item 的原地写回（数据流第 3 步）：test_load_item_using_default_loader 断言 load_item() 返回的是传入的同一个 item 对象，且未加载的字段保持原值（tests/test_loader.py）。
• 字段白名单校验：test_add_value_on_unknown_field 验证对未声明字段调用 add_value 抛出 KeyError，这与 scrapy/item.py 中 Item.__setitem__ 的行为一致——Item 只允许写入 fields 中已声明的字段。
• 输入处理器介入时机：ProcessorItemLoader 声明 name_in = MapCompose(lambda v: v.title()) 后，add_value("name", "marta") 加载得到 ["Marta"]，证明输入处理器在收集阶段就已执行（tests/test_loader.py）。

十、总结：一份 2009 年提案留下的完整遗产

SEP-008 虽然只有一页篇幅，但它定型的几个设计决策至今未变：

1. 数据流三段式：add_*（提取 + 输入处理 + 存储）与 populate_item/load_item（输出处理 + 写回）的分离，使“收集”与“定型”两个阶段解耦，同一 Loader 可以反复检查（get_stored_values）、延迟加载；
2. parser → processor 的命名统一：提案正文用 “parser”，替代提案改用 “processor”，最终实现全部采用后者，读者阅读旧版 Scrapy 0.9/1.x 资料时遇到 input_parser、TreeExpander、get_item 等词，都应对应到今天的 input_processor、MapConcat/MapCompose、load_item；
3. 双位置声明 + 优先级：处理器既可声明在 Loader 类属性（*_in/*_out），也可声明在 Field 元数据，Loader 级优先；
4. context 机制：以 __init__ 关键字参数、context 字典、处理器构造参数三种方式注入运行时配置；
5. 核心逻辑外置：提案设想 scrapy.contrib.itemparser 内置于 Scrapy，实际演进为独立的 itemloaders 包（pyproject.toml 中 itemloaders>=1.0.1），Scrapy 仅以 scrapy/loader/init.py 一个薄子类桥接 Selector 与 Item。

对于想深入本主题的读者，建议按此路径继续研读仓库：sep/sep-008.rst 提案原文 → sep/sep-001.rst 的 API 对比 → docs/topics/loaders.rst 现行完整文档 → scrapy/loader/init.py 与 tests/test_loader.py 的源码及行为契约。需要说明的是，SEP 文档中的示例代码使用的是 2009 年时期的 scrapy.contrib.itemparser 导入路径，该路径在当前仓库中已不存在，仅作历史 API 考证用途；实际编码请以 scrapy.loader 与 itemloaders 包为准。