下载和处理文件和图像¶

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

这两个 Pipeline 都实现了以下功能

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

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

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

这些 Pipeline 还维护一个内部队列，其中包含当前计划下载的媒体 URL，并将包含相同媒体的响应连接到该队列。这避免了当多个 Item 共享同一媒体时多次下载同一媒体。

使用 Files Pipeline¶

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

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

使用 Images Pipeline¶

使用 ImagesPipeline 非常类似于使用 FilesPipeline，除了使用的默认字段名称不同：您对 Item 的图像 URL 使用 image_urls，它将为下载的图像信息填充 images 字段。

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

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

启用媒体 Pipeline¶

要启用媒体 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 设置中，Pipeline 仍将保持禁用状态。

对于 Files Pipeline，请设置 FILES_STORE 设置

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

对于 Images Pipeline，请设置 IMAGES_STORE 设置

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

文件命名¶

默认文件命名¶

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

例如，以下图像 URL

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

其 SHA-1 哈希值 为

3afec3b4765f8f0a07b78f98c07b83f013567a0a

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

3afec3b4765f8f0a07b78f98c07b83f013567a0a.jpg

自定义文件命名¶

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

通过覆盖媒体 Pipeline 的 file_path 方法来自定义文件名。

例如，具有图像 URL 的图像 Pipeline

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 方法的更多信息，请参阅扩展媒体 Pipeline。

支持的存储¶

文件系统存储¶

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

<IMAGES_STORE>/full/<FILE_NAME>

其中

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

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 存储¶

如果安装了 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¶

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。

用法示例¶

为了使用媒体管道，首先启用它。

然后，如果蜘蛛返回一个带有 URLs 字段的项目对象（分别为文件或图像管道的 file_urls 或 image_urls），则管道将结果放在相应的字段（files 或 images）下。

当使用项目类型（其字段事先已定义）时，必须定义 URLs 字段和结果字段。例如，当使用图像管道时，项目必须同时定义 image_urls 和 images 字段。例如，使用 Item 类

import scrapy


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

如果要为 URLs 密钥或结果密钥使用其他字段名称，也可以覆盖它。

对于文件管道，请设置 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_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，您的自定义设置将被使用。

其他功能¶

文件过期¶

图像管道避免下载最近下载的文件。要调整此保留延迟，请使用 FILES_EXPIRES 设置（或图像管道的 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。

文件中的上次修改时间用于确定文件的天龄，然后将其与设置的过期时间进行比较以确定文件是否已过期。

图像缩略图生成¶

图像管道可以自动创建下载图像的缩略图。

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

例如

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

当您使用此功能时，图像管道将使用此格式创建每个指定大小的缩略图

<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

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

过滤掉小图像¶

使用图像管道时，您可以通过在 IMAGES_MIN_HEIGHT 和 IMAGES_MIN_WIDTH 设置中指定允许的最小尺寸来丢弃太小的图像。

例如

IMAGES_MIN_HEIGHT = 110
IMAGES_MIN_WIDTH = 110

注意

尺寸约束根本不影响缩略图生成。

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

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

允许重定向¶

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

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

MEDIA_ALLOW_REDIRECTS = True

扩展媒体管道¶

请参阅您可以在自定义文件管道中重写的方法

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 返回一个请求

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() 方法返回该项目。

请参阅您可以在自定义图像管道中重写的方法

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

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

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.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() 方法返回该项目。

自定义图像管道示例¶

这是一个完整示例，展示了上面举例说明的图像管道方法。

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}