Downloading and processing files and images (下载和处理文件和图像)

Scrapy 提供了可重用的项目管道，用于下载附加到特定项目的文件（例如，当您抓取产品并希望在本地下载其图像时）。这些管道共享一些功能和结构（我们称它们为媒体管道），但通常您会使用 Files Pipeline 或 Images Pipeline。

这两个管道都实现了以下功能：

避免重新下载最近下载的媒体
指定存储媒体的位置（文件系统目录、FTP 服务器、Amazon S3 存储桶、Google Cloud Storage 存储桶）

Images Pipeline 还有一些额外的图像处理功能：

将所有下载的图像转换为通用格式（JPG）和模式（RGB）
生成缩略图
检查图像宽度/高度以确保它们满足最小约束

这些管道还维护一个内部队列，其中包含当前正在调度下载的媒体 URL，并将包含相同媒体的到达响应连接到该队列。这可以避免当多个项目共享相同媒体时多次下载。

Using the Files Pipeline (使用文件管道)

使用 FilesPipeline 的典型工作流程如下：

在 Spider 中，您抓取一个项目并将所需文件的 URL 放入 file_urls 字段。
该项目从 Spider 返回并进入项目管道。
当项目到达 FilesPipeline 时，file_urls 字段中的 URL 将使用标准的 Scrapy 调度器和下载器进行调度下载（这意味着调度器和下载器中间件被重用），但优先级更高，在抓取其他页面之前处理它们。该项目在该特定管道阶段保持“锁定”状态，直到文件下载完成（或因某种原因失败）。
文件下载完成后，另一个字段（files）将填充结果。该字段将包含一个字典列表，其中包含有关下载文件的信息，例如下载路径、原始抓取 URL（取自 file_urls 字段）、文件校验和和文件状态。files 字段列表中的文件将保留 file_urls 字段的原始顺序。如果某些文件下载失败，将记录错误，并且该文件不会出现在 files 字段中。

Using the Images Pipeline (使用图像管道)

使用 ImagesPipeline 与使用 FilesPipeline 非常相似，只是使用的默认字段名称不同：您将 image_urls 用于项目的图像 URL，它将填充 images 字段以获取有关下载图像的信息。

使用 ImagesPipeline 处理图像文件的好处是，您可以配置一些额外的功能，例如生成缩略图和根据图像大小进行过滤。

Images Pipeline 需要 Pillow 8.0.0 或更高版本。它用于缩略图和将图像标准化为 JPEG/RGB 格式。

Enabling your Media Pipeline (启用您的媒体管道)

要启用您的媒体管道，您必须首先将其添加到您的项目 ITEM_PIPELINES 设置中。

对于 Images Pipeline，请使用：

ITEM_PIPELINES = {"scrapy.pipelines.images.ImagesPipeline": 1}

对于 Files Pipeline，请使用：

ITEM_PIPELINES = {"scrapy.pipelines.files.FilesPipeline": 1}

注意

您也可以同时使用 Files 和 Images Pipeline。

然后，将目标存储设置配置为用于存储下载图像的有效值。否则，即使您将其包含在 ITEM_PIPELINES 设置中，管道也将保持禁用状态。

对于 Files Pipeline，设置 FILES_STORE：

FILES_STORE = "/path/to/valid/dir"

对于 Images Pipeline，设置 IMAGES_STORE：

IMAGES_STORE = "/path/to/valid/dir"

File Naming (文件命名)

Default File Naming (默认文件命名)

默认情况下，文件使用其 URL 的 SHA-1 哈希值作为文件名存储。

例如，以下图像 URL：

http://www.example.com/image.jpg

其 SHA-1 哈希值为：

3afec3b4765f8f0a07b78f98c07b83f013567a0a

将使用您选择的存储方法和以下文件名进行下载和存储：

3afec3b4765f8f0a07b78f98c07b83f013567a0a.jpg

Custom File Naming (自定义文件命名)

您可能希望为保存的文件使用不同的计算文件名。例如，通过在文件名中包含元数据来对图像进行分类。

通过重写媒体管道的 file_path 方法来自定义文件名。

例如，带有图像 URL 的图像管道：

http://www.example.com/product/images/large/front/0000000004166

可以处理成包含压缩哈希和透视图 front 的文件名：

00b08510e4_front.jpg

通过像这样重写 file_path：

import hashlib

def file_path(self, request, response=None, info=None, *, item=None):
    image_url_hash = hashlib.shake_256(request.url.encode()).hexdigest(5)
    image_perspective = request.url.split("/")[-2]
    image_filename = f"{image_url_hash}_{image_perspective}.jpg"

    return image_filename

警告

如果您的自定义文件命名方案依赖于在不同抓取之间可能变化的元数据，则可能会导致使用新文件名意外重新下载现有媒体。

例如，如果您的自定义文件命名方案使用产品标题，并且网站在抓取之间更改了项目的产品标题，Scrapy 将使用更新的文件名重新下载相同的媒体。

有关 file_path 方法的更多信息，请参阅扩展媒体管道。

Supported Storage (支持的存储)

File system storage (文件系统存储)

文件系统存储会将文件保存到以下路径：

<IMAGES_STORE>/full/<FILE_NAME>

其中：

<IMAGES_STORE> 是 Images Pipeline 中 IMAGES_STORE 设置定义的目录。
full 是一个子目录，用于将完整图像与缩略图（如果使用）分开。有关更多信息，请参阅图像缩略图生成。
<FILE_NAME> 是分配给文件的文件名。有关更多信息，请参阅文件命名。

FTP server storage (FTP 服务器存储)

版本 2.0 新增。

FILES_STORE 和 IMAGES_STORE 可以指向 FTP 服务器。Scrapy 将自动将文件上传到服务器。

FILES_STORE 和 IMAGES_STORE 应该采用以下形式之一：

ftp://username:password@address:port/path
ftp://address:port/path

如果未提供 username 和 password，它们将分别从 FTP_USER 和 FTP_PASSWORD 设置中获取。

FTP 支持两种不同的连接模式：主动或被动。Scrapy 默认使用被动连接模式。要使用主动连接模式，请将 FEED_STORAGE_FTP_ACTIVE 设置为 True。

Amazon S3 storage (Amazon S3 存储)

如果安装了 botocore >= 1.4.87，FILES_STORE 和 IMAGES_STORE 可以表示 Amazon S3 存储桶。Scrapy 将自动将文件上传到存储桶。

例如，这是一个有效的 IMAGES_STORE 值：

IMAGES_STORE = "s3://bucket/images"

您可以修改用于存储文件的访问控制列表（ACL）策略，该策略由 FILES_STORE_S3_ACL 和 IMAGES_STORE_S3_ACL 设置定义。默认情况下，ACL 设置为 private。要使文件公开可用，请使用 public-read 策略：

IMAGES_STORE_S3_ACL = "public-read"

有关更多信息，请参阅 Amazon S3 开发人员指南中的预设 ACL。

您还可以使用其他类似 S3 的存储。例如自托管的 Minio 或 Zenko CloudServer。您只需在 Scrapy 设置中设置端点选项：

AWS_ENDPOINT_URL = "http://minio.example.com:9000"

对于自托管，您可能还需要不使用 SSL 并且不验证 SSL 连接：

AWS_USE_SSL = False  # or True (None by default)
AWS_VERIFY = False  # or True (None by default)

Google Cloud Storage (Google Cloud Storage)

FILES_STORE 和 IMAGES_STORE 可以表示 Google Cloud Storage 存储桶。Scrapy 将自动将文件上传到存储桶。（需要 google-cloud-storage）

例如，这些是有效的 IMAGES_STORE 和 GCS_PROJECT_ID 设置：

IMAGES_STORE = "gs://bucket/images/"
GCS_PROJECT_ID = "project_id"

有关身份验证的信息，请参阅此文档。

您可以修改用于存储文件的访问控制列表（ACL）策略，该策略由 FILES_STORE_GCS_ACL 和 IMAGES_STORE_GCS_ACL 设置定义。默认情况下，ACL 设置为 ''（空字符串），这意味着 Cloud Storage 将存储桶的默认对象 ACL 应用于对象。要使文件公开可用，请使用 publicRead 策略：

IMAGES_STORE_GCS_ACL = "publicRead"

有关更多信息，请参阅 Google Cloud Platform 开发人员指南中的预定义 ACL。

Usage example (使用示例)

要使用媒体管道，请先启用它。

然后，如果一个 spider 返回一个带有 URL 字段（对于 Files Pipeline 是 file_urls，对于 Images Pipeline 是 image_urls）的项目对象，管道将把结果放在相应的字段（files 或 images）下。

当使用预先定义字段的项目类型时，您必须同时定义 URL 字段和结果字段。例如，当使用图像管道时，项目必须同时定义 image_urls 和 images 字段。例如，使用 Item 类：

import scrapy

class MyItem(scrapy.Item):
    # ... other item fields ...
    image_urls = scrapy.Field()
    images = scrapy.Field()

如果您想为 URL 键或结果键使用其他字段名称，也可以覆盖它。

对于 Files Pipeline，设置 FILES_URLS_FIELD 和/或 FILES_RESULT_FIELD：

FILES_URLS_FIELD = "field_name_for_your_files_urls"
FILES_RESULT_FIELD = "field_name_for_your_processed_files"

对于 Images Pipeline，设置 IMAGES_URLS_FIELD 和/或 IMAGES_RESULT_FIELD：

IMAGES_URLS_FIELD = "field_name_for_your_images_urls"
IMAGES_RESULT_FIELD = "field_name_for_your_processed_images"

如果您需要更复杂的功能并希望覆盖自定义管道行为，请参阅扩展媒体管道。

如果您有多个图像管道继承自 ImagePipeline，并且您希望在不同的管道中设置不同的设置，则可以使用您的管道类的大写名称作为前缀来设置设置键。例如，如果您的管道名为 MyPipeline，并且您想要自定义 IMAGES_URLS_FIELD，您可以定义设置 MYPIPELINE_IMAGES_URLS_FIELD，并且将使用您的自定义设置。

Additional features (附加功能)

File expiration (文件过期)

Image Pipeline 避免下载最近下载的文件。要调整此保留延迟，请使用 FILES_EXPIRES 设置（或者对于 Images Pipeline，使用 IMAGES_EXPIRES），它以天数指定延迟：

# 120 days of delay for files expiration
FILES_EXPIRES = 120
# 30 days of delay for images expiration
IMAGES_EXPIRES = 30

这两个设置的默认值都是 90 天。

如果您有一个继承自 FilesPipeline 的管道，并且您希望为其设置不同的设置，则可以使用大写类名作为设置键的前缀。例如，给定名为 MyPipeline 的管道类，您可以设置键：

MYPIPELINE_FILES_EXPIRES = 180

并且管道类 MyPipeline 的过期时间将设置为 180。

文件的最后修改时间用于确定文件的天数，然后与设置的过期时间进行比较，以确定文件是否过期。

Thumbnail generation for images (图像缩略图生成)

Images Pipeline 可以自动创建下载图像的缩略图。

要使用此功能，您必须将 IMAGES_THUMBS 设置为字典，其中键是缩略图名称，值是它们的尺寸。

例如：

IMAGES_THUMBS = {
    "small": (50, 50),
    "big": (270, 270),
}

当您使用此功能时，Images Pipeline 将以这种格式创建每个指定大小的缩略图：

<IMAGES_STORE>/thumbs/<size_name>/<image_id>.jpg

其中：

<size_name> 是 IMAGES_THUMBS 字典键中指定的名称（small、big 等）
<image_id> 是图像 URL 的 SHA-1 哈希值

使用 small 和 big 缩略图名称存储的图像文件示例：

<IMAGES_STORE>/full/63bbfea82b8880ed33cdb762aa11fab722a90a24.jpg
<IMAGES_STORE>/thumbs/small/63bbfea82b8880ed33cdb762aa11fab722a90a24.jpg
<IMAGES_STORE>/thumbs/big/63bbfea82b8880ed33cdb762aa11fab722a90a24.jpg

第一个是完整图像，从网站下载。

Filtering out small images (过滤掉小图像)

当使用 Images Pipeline 时，您可以通过在 IMAGES_MIN_HEIGHT 和 IMAGES_MIN_WIDTH 设置中指定允许的最小尺寸来删除过小的图像。

例如：

IMAGES_MIN_HEIGHT = 110
IMAGES_MIN_WIDTH = 110

注意

尺寸约束完全不影响缩略图生成。

可以只设置一个尺寸约束或同时设置两个。当同时设置这两个约束时，只有满足这两个最小尺寸的图像才会被保存。对于上面的示例，尺寸为 (105 x 105) 或 (105 x 200) 或 (200 x 105) 的图像都将被删除，因为至少有一个维度短于约束。

默认情况下，没有尺寸约束，因此所有图像都会被处理。

Allowing redirections (允许重定向)

默认情况下，媒体管道会忽略重定向，即 HTTP 重定向到媒体文件 URL 请求将意味着媒体下载被视为失败。

要处理媒体重定向，请将此设置设置为 True：

MEDIA_ALLOW_REDIRECTS = True

Extending the Media Pipelines (扩展媒体管道)

以下是您可以在自定义 Files Pipeline 中覆盖的方法：

`class scrapy.pipelines.files.FilesPipeline[source]`

`file_path(self, request, response=None, info=None, *, item=None)[source]`

此方法为每个下载的项目调用一次。它返回源自指定 response 的文件的下载路径。

除了 response 之外，此方法还接收原始 request、info 和 item。

您可以覆盖此方法以自定义每个文件的下载路径。

例如，如果文件 URL 像常规路径一样结尾（例如 https://example.com/a/b/c/foo.png），您可以使用以下方法将所有文件下载到 files 文件夹中并使用其原始文件名（例如 files/foo.png）：

from pathlib import PurePosixPath
from scrapy.utils.httpobj import urlparse_cached
from scrapy.pipelines.files import FilesPipeline

class MyFilesPipeline(FilesPipeline):
    def file_path(self, request, response=None, info=None, *, item=None):
        return "files/" + PurePosixPath(urlparse_cached(request).path).name

同样，您可以使用 item 根据某些项目属性确定文件路径。

默认情况下，file_path() 方法返回 full/<request URL hash>.<extension>。

版本 2.4 新增：item 参数。

`get_media_requests(item, info)[source]`

如工作流程所示，管道将从项目中获取要下载的图像 URL。为了实现这一点，您可以覆盖 get_media_requests() 方法并为每个文件 URL 返回一个 Request：

from itemadapter import ItemAdapter

def get_media_requests(self, item, info):
    adapter = ItemAdapter(item)
    for file_url in adapter["file_urls"]:
        yield scrapy.Request(file_url)

这些请求将由管道处理，当它们下载完成后，结果将作为 2 元素元组列表发送到 item_completed() 方法。每个元组将包含 (success, file_info_or_error)，其中：

success 是一个布尔值，如果图像成功下载则为 True，如果因某种原因失败则为 False。
file_info_or_error 是一个字典，包含以下键（如果 success 为 True），或者如果出现问题则为 Failure。
- url - 文件下载自的 URL。这是从 get_media_requests() 方法返回的请求的 URL。
- path - 文件存储的路径（相对于 FILES_STORE）。
- checksum - 图像内容的 MD5 哈希值。
- status - 文件状态指示。

版本 2.2 新增。

它可以是以下之一：

downloaded - 文件已下载。
uptodate - 文件未下载，因为它最近已下载，根据文件过期策略。
cached - 文件已由共享相同文件的另一个项目调度下载。

item_completed() 接收到的元组列表保证与 get_media_requests() 方法返回的请求顺序保持一致。

以下是 results 参数的典型值：

[
    (
        True,
        {
            "checksum": "2b00042f7481c7b056c4b410d28f33cf",
            "path": "full/0a79c461a4062ac383dc4fade7bc09f1384a3910.jpg",
            "url": "http://www.example.com/files/product1.pdf",
            "status": "downloaded",
        },
    ),
    (False, Failure(...)),
]

默认情况下，get_media_requests() 方法返回 None，这意味着该项目没有要下载的文件。

`item_completed(results, item, info)[source]`

当单个项目的所有文件请求都已完成（已完成下载或因某种原因失败）时，调用 FilesPipeline.item_completed() 方法。

item_completed() 方法必须返回将发送到后续项目管道阶段的输出，因此您必须返回（或丢弃）项目，就像在任何管道中一样。

以下是 item_completed() 方法的示例，其中我们将下载的文件路径（在 results 中传递）存储在 file_paths 项目字段中，如果项目不包含任何文件，则丢弃该项目：

from itemadapter import ItemAdapter
from scrapy.exceptions import DropItem

def item_completed(self, results, item, info):
    file_paths = [x["path"] for ok, x in results if ok]
    if not file_paths:
        raise DropItem("Item contains no files")
    adapter = ItemAdapter(item)
    adapter["file_paths"] = file_paths
    return item

默认情况下，item_completed() 方法返回项目。

以下是您可以在自定义 Images Pipeline 中覆盖的方法：

`class scrapy.pipelines.images.ImagesPipeline[source]`

ImagesPipeline 是 FilesPipeline 的扩展，自定义了字段名称并为图像添加了自定义行为。

`file_path(self, request, response=None, info=None, *, item=None)[source]`

此方法为每个下载的项目调用一次。它返回源自指定 response 的文件的下载路径。

除了 response 之外，此方法还接收原始 request、info 和 item。

您可以覆盖此方法以自定义每个文件的下载路径。

from pathlib import PurePosixPath
from scrapy.utils.httpobj import urlparse_cached
from scrapy.pipelines.images import ImagesPipeline

class MyImagesPipeline(ImagesPipeline):
    def file_path(self, request, response=None, info=None, *, item=None):
        return "files/" + PurePosixPath(urlparse_cached(request).path).name

同样，您可以使用 item 根据某些项目属性确定文件路径。

默认情况下，file_path() 方法返回 full/<request URL hash>.<extension>。

版本 2.4 新增：item 参数。

`thumb_path(self, request, thumb_id, response=None, info=None, *, item=None)[source]`

此方法为每个下载的项目为 IMAGES_THUMBS 的每个项目调用。它返回源自指定 response 的图像的缩略图下载路径。

除了 response 之外，此方法还接收原始 request、thumb_id、info 和 item。

您可以覆盖此方法以自定义每个图像的缩略图下载路径。您可以使用 item 根据某些项目属性确定文件路径。

默认情况下，thumb_path() 方法返回 thumbs/<size name>/<request URL hash>.<extension>。

`get_media_requests(item, info)[source]`

工作方式与 FilesPipeline.get_media_requests() 方法相同，但图像 URL 使用不同的字段名称。

必须为每个图像 URL 返回一个 Request。

`item_completed(results, item, info)[source]`

当单个项目的所有图像请求都已完成（已完成下载或因某种原因失败）时，调用 ImagesPipeline.item_completed() 方法。

工作方式与 FilesPipeline.item_completed() 方法相同，但存储图像下载结果使用不同的字段名称。

默认情况下，item_completed() 方法返回项目。

Custom Images pipeline example (自定义图像管道示例)

以下是上面示例化的 Images Pipeline 的完整示例：

import scrapy
from itemadapter import ItemAdapter
from scrapy.exceptions import DropItem
from scrapy.pipelines.images import ImagesPipeline

class MyImagesPipeline(ImagesPipeline):
    def get_media_requests(self, item, info):
        for image_url in item["image_urls"]:
            yield scrapy.Request(image_url)

    def item_completed(self, results, item, info):
        image_paths = [x["path"] for ok, x in results if ok]
        if not image_paths:
            raise DropItem("Item contains no images")
        adapter = ItemAdapter(item)
        adapter["image_paths"] = image_paths
        return item

要启用您的自定义媒体管道组件，您必须将其类导入路径添加到 ITEM_PIPELINES 设置中，如下例所示：

ITEM_PIPELINES = {"myproject.pipelines.MyImagesPipeline": 300}

Debugging memory leaks (调试内存泄漏)

Deploying Spiders (部署爬虫)