核心 API

本节介绍 Scrapy 核心 API，旨在供扩展和中间件开发者参考。

Crawler API

Scrapy API 的主要入口点是 Crawler 对象，组件 可以获取它进行初始化。它提供了访问所有 Scrapy 核心组件的途径，并且是组件访问它们并将功能挂接到 Scrapy 的唯一方式。

扩展管理器（Extension Manager）负责加载和跟踪已安装的扩展，并通过 EXTENSIONS 设置进行配置，该设置包含一个字典，列出了所有可用的扩展及其顺序，类似于你配置下载器中间件的方式。

class scrapy.crawler.Crawler(spidercls: type[Spider], settings: dict[str, Any] | Settings | None = None, init_reactor: bool = False)

Crawler 对象必须使用 scrapy.Spider 子类和一个 scrapy.settings.Settings 对象进行实例化。

request_fingerprinter

此 crawler 的请求指纹构建器。

供扩展和中间件用于构建请求的简短唯一标识符。参见请求指纹。

settings

此 crawler 的设置管理器。

供扩展和中间件用于访问此 crawler 的 Scrapy 设置。

有关 Scrapy 设置的介绍，请参阅设置。

有关 API，请参阅 Settings 类。

signals

此 crawler 的信号管理器。

供扩展和中间件用于将自身挂接到 Scrapy 功能中。

有关信号的介绍，请参阅信号。

有关 API，请参阅 SignalManager 类。

stats

此 crawler 的统计信息收集器。

供扩展和中间件用于记录其行为统计信息，或访问其他扩展收集的统计信息。

有关统计信息收集的介绍，请参阅统计信息收集。

有关 API，请参阅 StatsCollector 类。

extensions

跟踪已启用扩展的扩展管理器。

大多数扩展无需访问此属性。

有关 Scrapy 扩展的介绍和可用扩展列表，请参阅扩展。

engine

执行引擎，协调调度器、下载器和爬虫之间的核心爬取逻辑。

某些扩展可能需要访问 Scrapy 引擎，以检查或修改下载器和调度器的行为，尽管这是一个高级用法，且此 API 尚未稳定。

spider

当前正在爬取的 Spider。这是在构建 crawler 时提供的 spider 类的一个实例，并在 crawl() 方法中给出参数后创建。

crawl(*args, **kwargs)

通过使用给定的 args 和 kwargs 参数实例化其 spider 类来启动 crawler，同时启动执行引擎。应只调用一次。

返回一个 deferred 对象，该对象在爬取完成时触发。

stop() → Generator[Deferred[Any], Any, None]

开始优雅地停止 crawler，并返回一个 deferred 对象，该对象在 crawler 停止时触发。

get_addon(cls: type[_T]) → _T | None

返回指定类或其子类的 add-on 运行时实例，如果未找到则返回 None。

添加到 2.12 版本。

get_downloader_middleware(cls: type[_T]) → _T | None

返回指定类或其子类的 下载器中间件 运行时实例，如果未找到则返回 None。

添加到 2.12 版本。

此方法只能在爬取引擎创建后调用，例如在 engine_started 或 spider_opened 信号时。

get_extension(cls: type[_T]) → _T | None

返回指定类或其子类的 扩展 运行时实例，如果未找到则返回 None。

添加到 2.12 版本。

此方法只能在扩展管理器创建后调用，例如在 engine_started 或 spider_opened 信号时。

get_item_pipeline(cls: type[_T]) → _T | None

返回指定类或其子类的 item pipeline 运行时实例，如果未找到则返回 None。

添加到 2.12 版本。

此方法只能在爬取引擎创建后调用，例如在 engine_started 或 spider_opened 信号时。

get_spider_middleware(cls: type[_T]) → _T | None

返回指定类或其子类的 spider 中间件 运行时实例，如果未找到则返回 None。

添加到 2.12 版本。

此方法只能在爬取引擎创建后调用，例如在 engine_started 或 spider_opened 信号时。

class scrapy.crawler.CrawlerRunner(settings: dict[str, Any] | Settings | None = None)

这是一个方便的辅助类，用于在已设置的 reactor 中跟踪、管理和运行 crawlers。

CrawlerRunner 对象必须使用 Settings 对象进行实例化。

除非编写手动处理爬取过程的脚本，否则不需要此类（因为 Scrapy 会相应地负责使用它）。有关示例，请参阅从脚本运行 Scrapy。

crawl(crawler_or_spidercls: type[Spider] | str | Crawler, *args: Any, **kwargs: Any) → Deferred[None]

使用提供的参数运行 crawler。

它将调用给定的 Crawler 的 crawl() 方法，同时跟踪它以便稍后停止。

如果 crawler_or_spidercls 不是 Crawler 实例，此方法将尝试使用此参数作为传入的 spider 类来创建一个 Crawler 实例。

返回一个 deferred 对象，该对象在爬取完成时触发。

参数:

• crawler_or_spidercls (Crawler 实例、Spider 子类或字符串) – 已创建的 crawler，或项目中用于创建它的 spider 类或 spider 名称

• args – 初始化 spider 的参数

• kwargs – 初始化 spider 的关键字参数

property crawlers

由 crawl() 启动并由本类管理的 crawlers 集合。

create_crawler(crawler_or_spidercls: type[Spider] | str | Crawler) → Crawler

返回一个 Crawler 对象。

• 如果 crawler_or_spidercls 是一个 Crawler 实例，则按原样返回。

• 如果 crawler_or_spidercls 是一个 Spider 子类，则为其构建一个新的 Crawler 实例。

• 如果 crawler_or_spidercls 是一个字符串，此函数将在 Scrapy 项目中（使用 spider loader）查找同名 spider，然后为其创建一个 Crawler 实例。

join()

返回一个 deferred 对象，该对象在所有受管的 crawlers 完成执行时触发。

stop() → Deferred[Any]

同时停止所有正在进行的爬取任务。

返回一个 deferred 对象，该对象在所有任务结束时触发。

class scrapy.crawler.CrawlerProcess(settings: dict[str, Any] | Settings | None = None, install_root_handler: bool = True)

基类: CrawlerRunner

一个类，用于在同一进程中同时运行多个 scrapy crawlers。

此类扩展了 CrawlerRunner，增加了启动 reactor 和处理关闭信号（例如键盘中断命令 Ctrl-C）的支持。它还配置了顶层日志记录。

如果你没有在应用程序中运行另一个 reactor，则此工具比 CrawlerRunner 更适合。

CrawlerProcess 对象必须使用 Settings 对象进行实例化。

参数:

install_root_handler – 是否安装根日志处理程序（默认值：True）

除非编写手动处理爬取过程的脚本，否则不需要此类（因为 Scrapy 会相应地负责使用它）。有关示例，请参阅从脚本运行 Scrapy。

crawl(crawler_or_spidercls: type[Spider] | str | Crawler, *args: Any, **kwargs: Any) → Deferred[None]

使用提供的参数运行 crawler。

它将调用给定的 Crawler 的 crawl() 方法，同时跟踪它以便稍后停止。

如果 crawler_or_spidercls 不是 Crawler 实例，此方法将尝试使用此参数作为传入的 spider 类来创建一个 Crawler 实例。

返回一个 deferred 对象，该对象在爬取完成时触发。

参数:

• crawler_or_spidercls (Crawler 实例、Spider 子类或字符串) – 已创建的 crawler，或项目中用于创建它的 spider 类或 spider 名称

• args – 初始化 spider 的参数

• kwargs – 初始化 spider 的关键字参数

property crawlers

由 crawl() 启动并由本类管理的 crawlers 集合。

create_crawler(crawler_or_spidercls: type[Spider] | str | Crawler) → Crawler

返回一个 Crawler 对象。

• 如果 crawler_or_spidercls 是一个 Crawler 实例，则按原样返回。

• 如果 crawler_or_spidercls 是一个 Spider 子类，则为其构建一个新的 Crawler 实例。

• 如果 crawler_or_spidercls 是一个字符串，此函数将在 Scrapy 项目中（使用 spider loader）查找同名 spider，然后为其创建一个 Crawler 实例。

join()

返回一个延迟对象，该对象在所有托管的 爬虫 完成执行时触发。

start(stop_after_crawl: bool = True, install_signal_handlers: bool = True) → None

此方法启动一个 reactor，调整其线程池大小为 REACTOR_THREADPOOL_MAXSIZE，并根据 DNSCACHE_ENABLED 和 DNSCACHE_SIZE 安装 DNS 缓存。

如果 stop_after_crawl 为 True，则在所有爬虫完成后，使用 join() 停止 reactor。

参数:

• stop_after_crawl (bool) – 当所有爬虫完成时是否停止 reactor

• install_signal_handlers (bool) – 是否安装来自 Twisted 和 Scrapy 的操作系统信号处理器 (默认值: True)

stop() → Deferred[Any]

同时停止所有正在进行的爬取任务。

返回一个 deferred 对象，该对象在所有任务结束时触发。

设置 API

scrapy.settings.SETTINGS_PRIORITIES

一个字典，设置 Scrapy 中使用的默认设置优先级的键名和优先级级别。

每个条目定义一个设置入口点，给它一个用于标识的代码名称和一个整数优先级。在 Settings 类中设置和检索值时，较高的优先级比低的优先级具有更高的优先权。

SETTINGS_PRIORITIES = {
    "default": 0,
    "command": 10,
    "addon": 15,
    "project": 20,
    "spider": 30,
    "cmdline": 40,
}

关于每个设置来源的详细解释，请参阅：设置。

scrapy.settings.get_settings_priority(priority: int | str) → int

小型辅助函数，用于在 SETTINGS_PRIORITIES 字典中查找给定的字符串优先级并返回其数值，或者直接返回给定的数值优先级。

class scrapy.settings.Settings(values: _SettingsInputT = None, priority: int | str = 'project')

基类： BaseSettings

此对象存储用于配置内部组件的 Scrapy 设置，并可用于任何进一步的自定义。

它是 BaseSettings 的直接子类并支持其所有方法。此外，在此类实例化后，新对象将已填充 内置设置参考 中描述的全局默认设置。

class scrapy.settings.BaseSettings(values: _SettingsInputT = None, priority: int | str = 'project')

此类的实例表现得像字典，但除了存储其 (key, value) 对之外，还存储优先级，并且可以被冻结 (即标记为不可变)。

键值条目可以在初始化时通过 values 参数传入，并且它们将采用 priority 级别 (除非 values 已是 BaseSettings 的一个实例，在这种情况下将保留现有的优先级级别)。如果 priority 参数是字符串，优先级名称将在 SETTINGS_PRIORITIES 中查找。否则，应提供一个特定的整数。

对象创建后，新的设置可以通过 set() 方法加载或更新，并且可以通过字典的方括号表示法访问，或者通过实例的 get() 方法及其值转换变体访问。当请求存储的键时，将检索具有最高优先级的那个值。

add_to_list(name: bool | float | int | str | None, item: Any) → None

将 item 追加到指定 name 的 list 设置中，如果 item 不在该列表中。

此更改无论 name 设置的优先级如何都将应用。设置优先级也不受此更改的影响。

copy() → Self

创建当前设置的深拷贝。

此方法返回 Settings 类的新实例，填充了相同的值及其优先级。

对新对象的修改不会反映在原始设置上。

copy_to_dict() → dict[bool | float | int | str | None, Any]

创建当前设置的副本并转换为字典。

此方法返回一个新字典，填充了与当前设置相同的值及其优先级。

对返回字典的修改不会反映在原始设置上。

此方法很有用，例如在 Scrapy shell 中打印设置时。

freeze() → None

禁用对当前设置的进一步更改。

调用此方法后，设置的当前状态将变为不可变。尝试通过 set() 方法及其变体更改值将不可能，并会收到警告。

frozencopy() → Self

返回当前设置的不可变副本。

是 copy() 返回的对象中 freeze() 调用的别名。

get(name: bool | float | int | str | None, default: Any = None) → Any

获取设置值而不影响其原始类型。

参数:

• name (str) – 设置名称

• default (object) – 如果未找到设置，则返回的值

getbool(name: bool | float | int | str | None, default: bool = False) → bool

将设置值作为布尔值获取。

1、'1'、True` 和 'True' 返回 True，而 0、'0'、False、'False' 和 None 返回 False。

例如，通过设置为 '0' 的环境变量填充的设置，在使用此方法时将返回 False。

参数:

• name (str) – 设置名称

• default (object) – 如果未找到设置，则返回的值

getdict(name: bool | float | int | str | None, default: dict[Any, Any] | None = None) → dict[Any, Any]

将设置值作为字典获取。如果设置的原始类型是字典，将返回它的一个副本。如果它是字符串，则会将其评估为 JSON 字典。如果它本身是 BaseSettings 实例，它将被转换为字典，包含其所有当前设置值，就像通过 get() 返回的一样，并丢失所有关于优先级和可变性的信息。

参数:

• name (str) – 设置名称

• default (object) – 如果未找到设置，则返回的值

getdictorlist(name: bool | float | int | str | None, default: dict[Any, Any] | list[Any] | tuple[Any] | None = None) → dict[Any, Any] | list[Any]

将设置值作为 dict 或 list 获取。

如果设置已经是 dict 或 list，将返回它的一个副本。

如果它是字符串，则会将其评估为 JSON，或者作为逗号分隔的字符串列表作为备用。

例如，从命令行填充的设置将返回

• {'key1': 'value1', 'key2': 'value2'} 如果设置为 '{"key1": "value1", "key2": "value2"}'

• ['one', 'two'] 如果设置为 '["one", "two"]' 或 'one,two'

参数:

• name (string) – 设置名称

• default (any) – 如果未找到设置，则返回的值

getfloat(name: bool | float | int | str | None, default: float = 0.0) → float

获取浮点数类型的设置值。

参数:

• name (str) – 设置名称

• default (object) – 如果未找到设置，则返回的值

getint(name: bool | float | int | str | None, default: int = 0) → int

获取整数类型的设置值。

参数:

• name (str) – 设置名称

• default (object) – 如果未找到设置，则返回的值

getlist(name: bool | float | int | str | None, default: list[Any] | None = None) → list[Any]

获取列表类型的设置值。如果设置的原始类型是列表，则返回其副本。如果是字符串，将按“,”分割。如果为空字符串，将返回空列表。

例如，通过环境变量设置为 'one,two' 的设置在使用此方法时将返回列表 [‘one’, ‘two’]。

参数:

• name (str) – 设置名称

• default (object) – 如果未找到设置，则返回的值

getpriority(name: bool | float | int | str | None) → int | None

返回设置当前的数字优先级值，如果给定的 name 不存在，则返回 None。

参数:

name (str) – 设置名称

getwithbase(name: bool | float | int | str | None) → BaseSettings

获取一个字典型设置与其对应的 _BASE 部分的组合。

参数:

name (str) – 字典型设置的名称

maxpriority() → int

返回所有设置中存在的最高优先级的数值，如果没有任何设置存储，则返回 SETTINGS_PRIORITIES 中 default 的数值。

pop(k[, d]) → v, remove specified key and return the corresponding value.

如果未找到键，若指定了 d 则返回 d，否则引发 KeyError。

remove_from_list(name: bool | float | int | str | None, item: Any) → None

从指定名称的 list 设置中移除 item。

如果 item 不存在，则引发 ValueError。

此更改无论 name 设置的优先级如何都将应用。设置优先级也不受此更改的影响。

replace_in_component_priority_dict(name: bool | float | int | str | None, old_cls: type, new_cls: type, priority: int | None = None) → None

在 name 组件优先级字典 中用 new_cls 替换 old_cls。

如果 old_cls 不存在，或其值为 None，则引发 KeyError。

如果 old_cls 作为导入字符串存在，即使存在多次，这些键也会被删除并替换为 new_cls。

如果指定了 priority，则将其值赋给组件优先级字典中的 new_cls。否则，使用 old_cls 的值。如果 old_cls 以不同值存在多次（导入字符串可能出现这种情况），则赋给 new_cls 的值是其中的一个，但不保证是哪一个。

此更改无论 name 设置的优先级如何都将应用。设置优先级也不受此更改的影响。

set(name: bool | float | int | str | None, value: Any, priority: int | str = 'project') → None

以给定优先级存储键/值属性。

设置应在配置 Crawler 对象之前（通过 configure() 方法）填充，否则不会生效。

参数:

• name (str) – 设置名称

• value (object) – 与设置关联的值

• priority (str 或 int) – 设置的优先级。应为 SETTINGS_PRIORITIES 的键或整数

set_in_component_priority_dict(name: bool | float | int | str | None, cls: type, priority: int | None) → None

以 priority 设置 name 组件优先级字典 中的 cls 组件。

如果 cls 已存在，其值将被更新。

如果 cls 作为导入字符串存在，即使存在多次，这些键也会被删除并替换为 cls。

此更改无论 name 设置的优先级如何都将应用。设置优先级也不受此更改的影响。

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

setdefault_in_component_priority_dict(name: bool | float | int | str | None, cls: type, priority: int | None) → None

如果 cls 组件尚未定义（即使作为导入字符串），则以 priority 设置 name 组件优先级字典 中的 cls 组件。

如果 cls 尚未定义，则无论 name 设置的优先级如何，都会进行设置。此更改也不会影响设置优先级。

setmodule(module: ModuleType | str, priority: int | str = 'project') → None

以给定优先级存储模块中的设置。

这是一个辅助函数，它会调用 set()，为 module 中每个全局声明的大写变量设置提供的 priority。

参数:

• module (types.ModuleType 或 str) – 模块或模块的路径

• priority (str 或 int) – 设置的优先级。应为 SETTINGS_PRIORITIES 的键或整数

update(values: _SettingsInputT, priority: int | str = 'project') → None

以给定优先级存储键/值对。

这是一个辅助函数，它会调用 set()，为 values 中的每个项设置提供的 priority。

如果 values 是一个字符串，则假定它是 JSON 编码的，并首先使用 json.loads() 解析为字典。如果它是一个 BaseSettings 实例，则将使用每个键的优先级，并忽略 priority 参数。这允许使用一个命令插入/更新具有不同优先级的设置。

参数:

• values (dict 或 string 或 BaseSettings) – 设置名称和值

• priority (str 或 int) – 设置的优先级。应为 SETTINGS_PRIORITIES 的键或整数

SpiderLoader API

class scrapy.spiderloader.SpiderLoader

此类别负责检索和处理项目中定义的 spider 类。

自定义爬虫加载器可以通过在SPIDER_LOADER_CLASS项目设置中指定其路径来使用。它们必须完全实现scrapy.interfaces.ISpiderLoader接口，以确保无差错执行。

from_settings(settings)

Scrapy使用这个类方法来创建类的实例。它会使用当前项目设置被调用，并且会递归加载在SPIDER_MODULES设置的模块中找到的爬虫。

参数:

settings (Settings实例) – 项目设置

load(spider_name)

获取指定名称的Spider类。它会在之前加载的爬虫中查找名称为spider_name的爬虫类，如果找不到则会引发KeyError。

参数:

spider_name (str) – 爬虫类名称

list()

获取项目中可用爬虫的名称。

find_by_request(request)

列出可以处理给定请求的爬虫名称。它将尝试将请求的url与爬虫的域名进行匹配。

参数:

request (Request实例) – 查询的请求

信号API

class scrapy.signalmanager.SignalManager(sender: Any = _Anonymous)

connect(receiver: Any, signal: Any, **kwargs: Any) → None

将接收函数连接到信号。

信号可以是任何对象，尽管Scrapy自带了一些预定义信号，这些信号已在信号部分进行了文档说明。

参数:

• receiver (collections.abc.Callable) – 要连接的函数

• signal (object) – 要连接的信号

disconnect(receiver: Any, signal: Any, **kwargs: Any) → None

将接收函数与信号断开连接。这与connect()方法的效果相反，并且参数相同。

disconnect_all(signal: Any, **kwargs: Any) → None

断开给定信号的所有接收器。

参数:

signal (object) – 要断开连接的信号

send_catch_log(signal: Any, **kwargs: Any) → list[tuple[Any, Any]]

发送信号，捕获异常并记录日志。

关键字参数会传递给信号处理器（通过connect()方法连接）。

send_catch_log_deferred(signal: Any, **kwargs: Any) → Deferred[list[tuple[Any, Any]]]

类似于send_catch_log()，但支持从信号处理器返回Deferred对象。

返回一个Deferred，当所有信号处理器的Deferred都完成后会被触发。发送信号，捕获异常并记录日志。

关键字参数会传递给信号处理器（通过connect()方法连接）。

async wait_for(signal)

等待下一个信号。

有关示例，请参见延迟启动请求迭代。

统计收集器API

在scrapy.statscollectors模块下有几个可用的统计收集器，它们都实现了由StatsCollector类（它们都继承自该类）定义的统计收集器API。

class scrapy.statscollectors.StatsCollector

get_value(key, default=None)

返回给定统计键的值，如果不存在则返回默认值。

get_stats()

将当前运行的爬虫的所有统计信息作为一个字典获取。

set_value(key, value)

为给定统计键设置给定值。

set_stats(stats)

使用stats参数中传入的字典覆盖当前统计信息。

inc_value(key, count=1, start=0)

将给定统计键的值增加给定的计数，如果未设置起始值，则假定为给定的起始值。

max_value(key, value)

仅当给定键的当前值小于value时，才为给定键设置给定值。如果给定键没有当前值，则总是设置该值。

min_value(key, value)

仅当给定键的当前值大于value时，才为给定键设置给定值。如果给定键没有当前值，则总是设置该值。

clear_stats()

清除所有统计信息。

以下方法不属于统计收集API，而是在实现自定义统计收集器时使用。

open_spider(spider)

打开给定的爬虫以进行统计收集。

close_spider(spider)

关闭给定的爬虫。调用此方法后，无法再访问或收集特定统计信息。

引擎API

class scrapy.core.engine.ExecutionEngine

needs_backout() → bool

如果目前无法发送更多请求，则返回True，否则返回False。

有关示例，请参见延迟启动请求迭代。