核心 API

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

爬虫 API

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

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

class scrapy.crawler.Crawler(spidercls: typeSpider, settings: dictstr, Any | Settings | None = None, init_reactor: bool = False)source

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)[source]`

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

返回一个在抓取完成时触发的 deferred。

`stop() -> Generator[Deferred[Any], Any, None][source]`

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

`get_addon(cls: type[_T]) -> _T | None[source]`

返回指定类或子类的附加组件的运行时实例，如果未找到则返回 None。

版本 2.12 新增。

`get_downloader_middleware(cls: type[_T]) -> _T | None[source]`

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

版本 2.12 新增。

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

`get_extension(cls: type[_T]) -> _T | None[source]`

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

版本 2.12 新增。

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

`get_item_pipeline(cls: type[_T]) -> _T | None[source]`

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

版本 2.12 新增。

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

`get_spider_middleware(cls: type[_T]) -> _T | None[source]`

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

版本 2.12 新增。

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

`CrawlerRunner` API

class scrapy.crawler.CrawlerRunner(settings: dictstr, Any | Settings | None = None)source

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

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

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

`crawl(crawler_or_spidercls: type[Spider] | str | Crawler, *args: Any, **kwargs: Any) -> Deferred[None][source]`

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

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

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

返回一个在抓取完成时触发的 deferred。

参数：

crawler_or_spidercls (Crawler 实例、Spider 子类或字符串) – 已创建的爬虫，或项目中的爬虫类或爬虫名称以创建它
args – 初始化爬虫的参数
kwargs – 初始化爬虫的关键字参数

`property crawlers`

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

`create_crawler(crawler_or_spidercls: type[Spider] | str | Crawler) -> Crawler[source]`

返回一个 Crawler 对象。

如果 crawler_or_spidercls 是 Crawler，则按原样返回。

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

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

`join()[source]`

返回一个在所有管理的爬虫完成执行时触发的 deferred。

`stop() -> Deferred[Any][source]`

同时停止所有正在进行的抓取作业。

返回一个在它们全部结束后触发的 deferred。

`CrawlerProcess` API

class scrapy.crawler.CrawlerProcess(settings: dictstr, Any | Settings | None = None, install_root_handler: bool = True)source

基类： CrawlerRunner

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

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

如果你未在应用程序中运行另一个 reactor，此实用程序应比 CrawlerRunner 更适合。

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

参数：

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

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

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

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

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

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

返回一个在抓取完成时触发的 deferred。

参数：

crawler_or_spidercls (Crawler 实例、Spider 子类或字符串) – 已创建的爬虫，或项目中的爬虫类或爬虫名称以创建它
args – 初始化爬虫的参数
kwargs – 初始化爬虫的关键字参数

`property crawlers`

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

`create_crawler(crawler_or_spidercls: type[Spider] | str | Crawler) -> Crawler`

返回一个 Crawler 对象。

如果 crawler_or_spidercls 是 Crawler，则按原样返回。

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

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

`join()`

返回一个在所有管理的爬虫完成执行时触发的 deferred。

`start(stop_after_crawl: bool = True, install_signal_handlers: bool = True) -> None[source]`

此方法启动一个 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]`

同时停止所有正在进行的抓取作业。

返回一个在它们全部结束后触发的 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[source]`

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

`Settings` 类

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

基类： BaseSettings

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

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

`BaseSettings` 类

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

此类的实例行为类似于字典，但除了它们的 (key, value) 对之外，还存储优先级，并且可以被冻结（即标记为不可变）。

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

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

`Notes(name: bool | float | int | str | None, item: Any) -> None[source]`

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

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

`copy() -> Self[source]`

深度复制当前设置。

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

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

`copy_to_dict() -> dict[bool | float | int | str | None, Any][source]`

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

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

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

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

`freeze() -> None[source]`

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

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

`frozencopy() -> Self[source]`

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

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

`get(name: bool | float | int | str | None, default: Any = None) -> Any[source]`

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

参数：

name (str) – 设置名称
default (对象) – 如果未找到设置，则返回的值

`getbool(name: bool | float | int | str | None, default: bool = False) -> bool[source]`

获取布尔类型的设置值。

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

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

参数：

name (str) – 设置名称
default (对象) – 如果未找到设置，则返回的值

`getdict(name: bool | float | int | str | None, default: dict[Any, Any] | None = None) -> dict[Any, Any][source]`

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

参数：

name (str) – 设置名称
default (对象) – 如果未找到设置，则返回的值

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

获取字典或列表类型的设置值。

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

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

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

{'key1': 'value1', 'key2': 'value2'} 如果设置为 '{"key1": "value1", "key2": "value2"}'
['one', 'two'] 如果设置为 '["one", "two"]' 或 'one,two'

参数：：

name (字符串) – 设置名称
default (任意) – 如果未找到设置，则返回的值

`getfloat(name: bool | float | int | str | None, default: float = 0.0) -> float[source]`

获取浮点类型的设置值。

参数：

name (str) – 设置名称
default (对象) – 如果未找到设置，则返回的值

`getint(name: bool | float | int | str | None, default: int = 0) -> int[source]`

获取整数类型的设置值。

参数：

name (str) – 设置名称
default (对象) – 如果未找到设置，则返回的值

`getlist(name: bool | float | int | str | None, default: list[Any] | None = None) -> list[Any][source]`

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

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

参数：

name (str) – 设置名称
default (对象) – 如果未找到设置，则返回的值

`getpriority(name: bool | float | int | str | None) -> int | None[source]`

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

参数：

name (str) – 设置名称

`getwithbase(name: bool | float | int | str | None) -> BaseSettings[source]`

获取字典类设置及其 _BASE 对应项的组合。

参数：

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

`maxpriority() -> int[source]`

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

`pop(k[, d]) -> v, remove specified key and return the corresponding value.[source]`

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

`remove_from_list(name: bool | float | int | str | None, item: Any) -> None[source]`

从指定 name 的列表设置中删除 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[source]`

在 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[source]`

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

设置应在配置 Crawler 对象（通过 configure() 方法）之前填充，否则它们将不起作用。

参数：

name (str) – 设置名称
value (对象) – 与设置关联的值
priority (str 或 int) – 设置的优先级。应为 SETTINGS_PRIORITIES 的键或整数

`set_in_component_priority_dict(name: bool | float | int | str | None, cls: type, priority: int | None) -> None[source]`

在 name 组件优先级字典设置中将 cls 组件设置为 priority。

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

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

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

`setdefault(k[, d]) -> D.get(k,d), also set D[k]=d if k not in D[source]`

`setdefault_in_component_priority_dict(name: bool | float | int | str | None, cls: type, priority: int | None) -> None[source]`

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

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

`setmodule(module: ModuleType | str, priority: int | str = 'project') -> None[source]`

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

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

参数：

module (types.ModuleType 或 str) – 模块或模块的路径
priority (str 或 int) – 设置的优先级。应为 SETTINGS_PRIORITIES 的键或整数

`update(values: _SettingsInputT, priority: int | str = 'project') -> None[source]`

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

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

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

参数：

values (字典、字符串或 BaseSettings) – 设置名称和值
priority (str 或 int) – 设置的优先级。应为 SETTINGS_PRIORITIES 的键或整数

settings (Settings 实例) – 项目设置

`load(spider_name)[source]`

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

参数：

spider_name (str) – 爬虫类名称

`list()[source]`

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

`find_by_request(request)[source]`

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

参数：

request (Request 实例) – 查询请求

参数：：

receiver (collections.abc.Callable) – 要连接的函数
signal (对象) – 要连接的信号

`disconnect(receiver: Any, signal: Any, **kwargs: Any) -> None[source]`

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

`disconnect_all(signal: Any, **kwargs: Any) -> None[source]`

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

参数：

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

`send_catch_log(signal: Any, **kwargs: Any) -> list[tuple[Any, Any]][source]`

发送信号，捕获异常并记录它们。

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

`send_catch_log_deferred(signal: Any, **kwargs: Any) -> Deferred[list[tuple[Any, Any]]][source]`

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

返回一个在所有信号处理程序 deferreds 被触发后触发的 Deferred。发送信号，捕获异常并记录它们。

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

组件

开始

快速入门