下载处理器

下载处理器是 Scrapy 的组件，用于下载请求并从中生成响应。

使用下载处理器

DOWNLOAD_HANDLERS_BASE 和 DOWNLOAD_HANDLERS 设置告诉 Scrapy 哪个处理器负责给定的 URL 方案。它们的值被合并成一个从方案名称到处理器类的映射。当 Scrapy 初始化时，它会创建所有已配置的下载处理器实例（惰性处理器除外），并将它们存储在一个类似的映射中。当 Scrapy 需要下载一个请求时，它会从 URL 中提取方案，找到该方案的处理器，将请求传递给它并从中获取响应。如果没有针对该方案的处理器，则不会下载请求，并会引发一个 NotSupported 异常。

DOWNLOAD_HANDLERS_BASE 设置包含处理器的默认映射。您可以使用 DOWNLOAD_HANDLERS 设置来添加额外方案的处理器，以及替换或禁用默认处理器

DOWNLOAD_HANDLERS = {
    # disable support for ftp:// requests
    "ftp": None,
    # replace the default one for http://
    "http": "my.download_handlers.HttpHandler",
    # http:// and https:// are different schemes,
    # even though they may use the same handler
    "https": "my.download_handlers.HttpHandler",
    # support for any custom scheme can be added
    "sftp": "my.download_handlers.SftpHandler",
}

另请参阅

请参阅未加密协议和本地和非网络资源，了解默认 http、ftp、file 和 data 处理器带来的安全隐患。

替换 HTTP(S) 下载处理器

尽管 Scrapy 为 http 和 https 方案提供了默认处理器，但用户可能希望使用由 Scrapy 或某些第三方包提供的不同处理器。对此，有几个注意事项需要牢记。

首先，由于 http 和 https 是独立的方案，它们需要在 DOWNLOAD_HANDLERS 设置中分别配置条目，即使很可能对这两种方案使用相同的处理器类。

此外，Scrapy 的一些设置，例如 DOWNLOAD_MAXSIZE，默认的 HTTP(S) 处理器会遵守，但替代处理器不一定。同样的情况也可能适用于其他 Scrapy 功能，例如 bytes_received 和 headers_received 信号。

下载处理器的惰性实例化

通过将其 lazy 类属性设置为 True，可以将下载处理器标记为“惰性”。此类处理器仅在需要下载其第一个请求时才会被实例化。当实例化速度较慢或需要不总是可用的依赖项，并且处理器不需要在每次爬虫运行时都使用时，这可能会很有用。例如，内置的 S3 处理器是惰性的。

编写自己的下载处理器

下载处理器是定义以下 API 的组件

class SampleDownloadHandler

lazy: bool

如果为 False，则处理器将在 Scrapy 初始化时被实例化。

如果为 True，则处理器仅在它需要下载其处理的第一个请求时才会被实例化。

async download_request(request: Request) → Response:: 下载给定请求并返回响应。

async close() → None: 清理处理器使用的任何资源。

提供了一个用于自定义处理器的可选基类

class scrapy.core.downloader.handlers.base.BaseDownloadHandler(crawler: Crawler)[来源]

下载处理器的可选基类。

lazy: bool = False

classmethod from_crawler(crawler: Crawler) → Self[来源]

abstractmethod async download_request(request: Request) → Response[来源]

async close() → None[来源]

下载处理器引发的异常

2.15.0 版本中新增。

内置下载处理器引发的是 Scrapy 特定的异常，而不是特定于实现的异常，这样处理这些异常的代码可以以通用方式编写。我们建议自定义下载处理器也使用这些异常。

exception scrapy.exceptions.CannotResolveHostError[来源]: 表示无法解析提供的主机名。

exception scrapy.exceptions.DownloadCancelledError[来源]: 表示请求下载被取消。

exception scrapy.exceptions.DownloadConnectionRefusedError[来源]: 表示连接被服务器拒绝。

exception scrapy.exceptions.DownloadFailedError[来源]: 表示请求下载失败。

exception scrapy.exceptions.DownloadTimeoutError[来源]: 表示请求下载超时。

exception scrapy.exceptions.ResponseDataLossError[来源]: 表示 Scrapy 无法获得完整的响应。

exception scrapy.exceptions.UnsupportedURLSchemeError[来源]: 表示 URL 方案不受支持。

内置 HTTP 下载处理器参考

Scrapy 提供了多个用于 HTTP 和 HTTPS 请求的处理器。尽管它们都支持基本功能，但在对特定 Scrapy 功能、设置和 HTTP 协议功能的支持方面可能有所不同。有关更多信息，请参阅特定处理器和特定设置的文档。此外，由于底层 HTTP 客户端实现在不同处理器之间存在差异，当使用相同的 Scrapy 请求但使用不同处理器时，特定网站的行为可能会有所不同。

以下是内置 HTTP 处理器的一些功能比较，有关更多差异，请参阅各个处理器文档

特性	H2DownloadHandler	HTTP11DownloadHandler	HttpxDownloadHandler
需要 asyncio	否	否	是
需要 reactor	是	是	否
HTTP/1.1	否	是	是
HTTP/2	是	否	是
TLS 实现	`cryptography`	`cryptography`	Stdlib `ssl`
HTTP 代理	否	是	是
SOCKS 代理	否	否	是

您可以在 scrapy-download-handlers-incubator 包中找到额外的 HTTP 下载处理器。此包由 Scrapy 开发者制作，包含实验性处理器，这些处理器可能会在将来的 Scrapy 版本中包含，但现在已经可以使用。有关更多信息，请参阅此包的文档。

H2DownloadHandler

class scrapy.core.downloader.handlers.http2.H2DownloadHandler(crawler: Crawler)[来源]

支持的方案：https。
惰性：是。
需要 asyncio 支持：否。
需要 Twisted reactor：是。

此处理器支持 https://host/path URL 并为其使用 HTTP/2 协议。

它使用 twisted.web.client 和 h2 库实现。

要使此处理器工作，您需要安装 Twisted[http2] 额外依赖项。

如果您想使用此处理器，您需要替换 https 方案的默认处理器

DOWNLOAD_HANDLERS = {
    "https": "scrapy.core.downloader.handlers.http2.H2DownloadHandler",
}

特性与限制

警告

此处理器是实验性的，目前不推荐用于生产环境。未来的 Scrapy 版本可能会在没有弃用期或警告的情况下引入相关更改。

HTTP 代理	否（未实现）
SOCKS 代理	否（库不支持）
HTTP/2	是
`response.certificate`	`twisted.internet.ssl.Certificate` 对象
每个请求的 `bindaddress`	是
TLS 实现	`pyOpenSSL`/`cryptography`

其他限制

不支持 HTTP/1.1。
IPv6 支持需要将 TWISTED_DNS_RESOLVER 设置为 scrapy.resolver.CachingHostnameResolver。
不支持 bytes_received 和 headers_received 信号。

HTTP/2 支持的已知限制

不支持 HTTP/2 明文 (h2c)，因为没有主流浏览器支持未加密的 HTTP/2（请参阅 http2 faq）。
没有设置可以指定大于默认值 16384 的最大帧大小。连接到发送更大帧的服务器将失败。
不支持服务器推送，服务器推送将被忽略。

HTTP11DownloadHandler

class scrapy.core.downloader.handlers.http11.HTTP11DownloadHandler(crawler: Crawler)[来源]

支持的方案：http, https。
惰性：否。
需要 asyncio 支持：否。
需要 Twisted reactor：是。

此处理器支持 http://host/path 和 https://host/path URL 并为其使用 HTTP/1.1 协议。

它使用 twisted.web.client 实现。

特性与限制

HTTP 代理	是
SOCKS 代理	否（库不支持）
HTTP/2	否（作为单独的处理器实现）
`response.certificate`	`twisted.internet.ssl.Certificate` 对象
每个请求的 `bindaddress`	是
TLS 实现	`pyOpenSSL`/`cryptography`

其他限制

IPv6 支持需要将 TWISTED_DNS_RESOLVER 设置为 scrapy.resolver.CachingHostnameResolver。
不支持 HTTPS 代理到 HTTPS 目标。

HttpxDownloadHandler

2.15.0 版本中新增。

class scrapy.core.downloader.handlers._httpx.HttpxDownloadHandler(crawler: Crawler)[来源]

支持的方案：http, https。
惰性：否。
需要 asyncio 支持：是。
需要 Twisted reactor：否。

此处理器支持 http://host/path 和 https://host/path URL，并为其使用 HTTP/1.1 或 HTTP/2 协议。

它使用 httpx 库实现，并且需要安装该库。

如果您想使用此处理器，您需要替换 http 和 https 方案的默认处理器

DOWNLOAD_HANDLERS = {
    "http": "scrapy.core.downloader.handlers._httpx.HttpxDownloadHandler",
    "https": "scrapy.core.downloader.handlers._httpx.HttpxDownloadHandler",
}

特性与限制

警告

此处理器是实验性的，目前不推荐用于生产环境。未来的 Scrapy 版本可能会在没有弃用期或警告的情况下引入相关更改，甚至完全移除它。

HTTP 代理	是
SOCKS 代理	是 (SOCKS5；需要 `httpx[socks]`)
HTTP/2	是（需要 `httpx[http2]`）
`response.certificate`	DER 字节
每个请求的 `bindaddress`	否（库不支持）
TLS 实现	标准库 `ssl`

其他限制

该处理器为每个代理 URL 创建一个单独的连接池（由于 httpx 的限制），这在使用代理轮换时可能导致更高的资源使用。

HTTPX_HTTP2_ENABLED

在 2.17.0 版本中添加。

默认值：False

是否在此处理器中启用 HTTP/2 支持。如果要启用此设置，需要安装 httpx[http2] 额外依赖项。

内置非 HTTP 下载处理器参考

DataURIDownloadHandler

class scrapy.core.downloader.handlers.datauri.DataURIDownloadHandler(crawler: Crawler)[来源]

支持的方案：data。
惰性：否。
需要 asyncio 支持：否。
需要 Twisted reactor：否。

此处理器支持 RFC 2397 data:content/type;base64, 数据 URI。

FileDownloadHandler

class scrapy.core.downloader.handlers.file.FileDownloadHandler(crawler: Crawler)[来源]

支持的方案：file。
惰性：否。
需要 asyncio 支持：否。
需要 Twisted reactor：否。

此处理器支持 file:///path 本地文件 URI。它不支持远程文件。

FTPDownloadHandler

class scrapy.core.downloader.handlers.ftp.FTPDownloadHandler(crawler: Crawler)[来源]

支持的方案：ftp。
惰性：否。
需要 asyncio 支持：否。
需要 Twisted reactor：是。

此处理器支持 ftp://host/path FTP URI。

它使用 twisted.protocols.ftp 实现。

S3DownloadHandler

class scrapy.core.downloader.handlers.s3.S3DownloadHandler(crawler: Crawler)[来源]

支持的方案：s3。
惰性：是。
需要 asyncio 支持：否。
需要 Twisted reactor：否。

此处理器支持 s3://bucket/path S3 URI。

它使用 botocore 库实现，并且需要安装该库。