核心API

本节记录了Scrapy核心API，旨在为扩展和中间件的开发者提供文档。

爬虫API

Scrapy API 的主要入口点是 Crawler 对象，通过 from_crawler 类方法传递给扩展。这个 对象提供了对所有 Scrapy 核心组件的访问，并且是扩展访问它们并将其功能集成到 Scrapy 中的唯一方式。

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

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

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

request_fingerprinter

此爬虫的请求指纹构建器。

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

settings

此爬虫的设置管理器。

这是由扩展和中间件用来访问此爬虫的Scrapy设置。

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

有关API，请参见Settings类。

signals

此爬虫的信号管理器。

这被扩展和中间件用来将它们自己挂接到Scrapy功能中。

有关信号的介绍，请参见 Signals。

有关API，请参见SignalManager类。

stats

此爬虫的统计收集器。

这是用于扩展和中间件记录它们行为的统计数据，或访问由其他扩展收集的统计数据。

有关统计收集的介绍，请参见 Stats Collection。

有关API，请参见StatsCollector类。

extensions

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

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

有关扩展的介绍以及Scrapy上可用扩展的列表，请参见扩展。

engine

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

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

spider

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

crawl(*args, **kwargs)

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

返回一个在爬取完成时触发的延迟对象。

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

启动爬虫的优雅停止，并返回一个延迟对象，该对象在爬虫停止时触发。

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 middleware的运行实例，如果未找到则返回None。

新版本2.12中新增。

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

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

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

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

这个类通常不需要使用（因为Scrapy负责根据需要使用它），除非编写手动处理爬取过程的脚本。有关示例，请参见从脚本运行Scrapy。

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

使用提供的参数运行爬虫。

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

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

返回一个在爬取完成时触发的延迟对象。

Parameters:

• crawler_or_spidercls (Crawler 实例, Spider 子类或字符串) – 已经创建的爬虫，或者项目内部的蜘蛛类或蜘蛛名称来创建它

• args – 初始化爬虫的参数

• kwargs – 用于初始化爬虫的关键字参数

property crawlers

由crawlers启动并由该类管理的crawl()的爬虫集合。

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

返回一个Crawler对象。

• 如果 crawler_or_spidercls 是一个 Crawler，它将原样返回。

• 如果 crawler_or_spidercls 是一个 Spider 子类，则会为其构造一个新的 Crawler。

• 如果 crawler_or_spidercls 是一个字符串，此函数会在 Scrapy 项目中（使用蜘蛛加载器）查找具有此名称的蜘蛛，然后为其创建一个 Crawler 实例。

join()

返回一个在所有管理的crawlers完成其执行时触发的延迟对象。

stop() → Deferred[Any]

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

返回一个在所有操作都结束时触发的延迟对象。

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

基础类：CrawlerRunner

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

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

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

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

Parameters:

install_root_handler – 是否安装根日志处理程序 (默认值: True)

这个类通常不需要使用（因为Scrapy负责根据需要使用它），除非编写手动处理爬取过程的脚本。有关示例，请参见从脚本运行Scrapy。

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

使用提供的参数运行爬虫。

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

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

返回一个在爬取完成时触发的延迟对象。

Parameters:

• crawler_or_spidercls (Crawler 实例, Spider 子类或字符串) – 已经创建的爬虫，或者项目内部的蜘蛛类或蜘蛛名称来创建它

• args – 初始化爬虫的参数

• kwargs – 用于初始化爬虫的关键字参数

property crawlers

由crawlers启动并由该类管理的crawl()的爬虫集合。

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

返回一个Crawler对象。

• 如果 crawler_or_spidercls 是一个 Crawler，它将原样返回。

• 如果 crawler_or_spidercls 是一个 Spider 子类，则会为其构造一个新的 Crawler。

• 如果 crawler_or_spidercls 是一个字符串，此函数会在 Scrapy 项目中（使用蜘蛛加载器）查找具有此名称的蜘蛛，然后为其创建一个 Crawler 实例。

join()

返回一个在所有管理的crawlers完成执行后被触发的延迟对象。

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()。

Parameters:

• stop_after_crawl (bool) – 当所有爬虫完成后是否停止反应器

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

stop() → Deferred[Any]

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

返回一个在所有操作都结束时触发的延迟对象。

设置API

scrapy.settings.SETTINGS_PRIORITIES

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

每个项目定义一个设置入口点，为其分配一个代码名称用于识别和一个整数优先级。在Settings类中设置和检索值时，较大的优先级比较小的优先级具有更高的优先权。

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

有关每个设置源的详细说明，请参见： Settings。

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() 方法及其值转换变体来访问这些设置。当请求存储的键时，将检索具有最高优先级的值。

copy() → Self

对当前设置进行深度复制。

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

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

copy_to_dict() → dict[Union[bool, float, int, str, NoneType], Any]

复制当前设置并转换为字典。

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

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

这个方法可以用于例如在Scrapy shell中打印设置。

freeze() → None

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

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

frozencopy() → Self

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

在由copy()返回的对象中，freeze()调用的别名。

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

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

Parameters:

• name (str) – 设置名称

• 默认值 (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。

Parameters:

• name (str) – 设置名称

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

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

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

Parameters:

• name (str) – 设置名称

• 默认值 (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。

如果设置已经是字典或列表，将返回其副本。

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

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

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

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

Parameters:

• name (string) – 设置名称

• 默认值 (任意类型) – 如果未找到设置，则返回此值

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

获取一个设置为浮点数的值。

Parameters:

• name (str) – 设置名称

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

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

获取一个设置值作为整数。

Parameters:

• name (str) – 设置名称

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

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

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

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

Parameters:

• name (str) – 设置名称

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

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

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

Parameters:

name (str) – 设置名称

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

获取一个类似字典的设置及其_BASE对应部分的组合。

Parameters:

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

maxpriority() → int

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

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

如果未找到键，则返回给定的d，否则引发KeyError。

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

存储一个具有给定优先级的键/值属性。

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

Parameters:

• name (str) – 设置名称

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

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

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

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

从具有给定优先级的模块中存储设置。

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

Parameters:

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

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

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

使用给定的优先级存储键/值对。

这是一个辅助函数，它为values的每个项目调用 set()，并使用提供的priority。

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

Parameters:

• values (字典或字符串或 BaseSettings) – 设置名称和值

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

SpiderLoader API

class scrapy.spiderloader.SpiderLoader

该类负责检索和处理项目中定义的爬虫类。

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

from_settings(settings)

这个类方法由Scrapy用于创建类的实例。 它使用当前项目设置调用，并加载在SPIDER_MODULES设置中的模块中递归找到的蜘蛛。

Parameters:

设置 (Settings 实例) – 项目设置

load(spider_name)

获取具有给定名称的Spider类。它将在先前加载的蜘蛛中查找名为spider_name的蜘蛛类，如果未找到，则会引发KeyError。

Parameters:

spider_name (str) – 爬虫类名称

list()

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

find_by_request(request)

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

Parameters:

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

信号API

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

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

将接收器函数连接到信号。

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

Parameters:

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

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

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

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

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

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

Parameters:

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。发送信号，捕获异常并记录它们。

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

统计收集器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)

仅当相同键的当前值低于给定值时，才为给定键设置给定值。如果给定键没有当前值，则始终设置该值。

min_value(key, value)

仅当相同键的当前值大于给定值时，才为给定键设置给定值。如果给定键没有当前值，则始终设置该值。

clear_stats()

清除所有统计信息。

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

open_spider(spider)

打开给定的蜘蛛以进行统计收集。

close_spider(spider)

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