核心 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 设置的介绍，请参阅 设置。

有关 API，请参阅 Settings 类。

signals

此爬虫的信号管理器。

扩展和中间件使用它将自身挂钩到 Scrapy 功能中。

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

有关 API，请参阅 SignalManager 类。

stats

此爬虫的统计收集器。

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

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

有关 API，请参阅 StatsCollector 类。

extensions

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

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

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

engine

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

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

spider

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

crawl(*args, **kwargs)

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

返回一个延迟，在爬取完成时触发。

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

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

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

返回指定类或其子类的附加组件的运行时实例，如果未找到则返回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

返回指定类或其子类的项目管道的运行时实例，如果未找到则返回None。

版本 2.12 中的新功能。

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

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

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

版本 2.12 中的新功能。

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

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

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

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

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

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

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

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

如果crawler_or_spidercls不是Crawler实例，则此方法将尝试使用此参数作为传递给它的爬虫类来创建一个。

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

参数：

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

• args – 初始化爬虫的参数

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

property crawlers

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

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 项目中（使用 spider loader）查找具有此名称的 spider，然后为其创建一个 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 对象实例化。

参数：

**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实例，则此方法将尝试使用此参数作为传递给它的爬虫类来创建一个。

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

参数：

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

• args – 初始化爬虫的参数

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

property crawlers

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

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 项目中（使用 spider loader）查找具有此名称的 spider，然后为其创建一个 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() 停止 reactor。

参数：

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

• **install_signal_handlers** (bool) – 是否安装来自 Twisted 和 Scrapy 的 OS 信号处理程序（默认值：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,
}

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

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

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

参数：

• 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, 删除指定的键并返回对应值。

如果未找到键，则返回 d（如果已给出），否则引发 KeyError。

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

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

设置应在配置爬虫对象（通过 configure() 方法）之前填充，否则它们将没有任何效果。

参数：

• 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

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

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

参数：

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

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

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

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

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

如果 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 项目设置中指定其路径来使用自定义 Spider 加载器。它们必须完全实现 scrapy.interfaces.ISpiderLoader 接口以确保执行无错误。

from_settings(settings)

Scrapy 使用此类方法来创建类的实例。它使用当前项目设置调用，并加载在 SPIDER_MODULES 设置的模块中递归找到的 Spider。

参数：

settings (Settings 实例) – 项目设置

load(spider_name)

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

参数：

spider_name (str) – Spider 类名称

list()

获取项目中可用 Spider 的名称。

find_by_request(request)

列出可以处理给定请求的 Spider 的名称。将尝试将请求的 url 与 Spider 的域匹配。

参数：

request (Request 实例) – 查询请求

Signals API

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

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

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

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

参数：

• 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，一旦所有信号处理程序的 deferreds 完成后就会触发。发送信号，捕获异常并记录它们。

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

统计收集器 API

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

class scrapy.statscollectors.StatsCollector

get_value(key, default=None)

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

get_stats()

以字典形式获取当前正在运行的 spider 的所有统计信息。

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)

打开给定的 spider 以进行统计数据收集。

close_spider(spider)

关闭给定的 spider。调用此方法后，将无法再访问或收集任何特定的统计数据。