下载和处理文件和图片

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

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

  • 避免重新下载最近下载的媒体

  • 指定媒体存储位置（文件系统目录、FTP 服务器、Amazon S3 存储桶、Google Cloud Storage 存储桶）

图片管道有几个额外的图片处理功能

  • 将所有下载的图片转换为通用格式（JPG）和模式（RGB）

  • 缩略图生成

  • 检查图片宽度/高度以确保它们满足最小限制

管道还会维护一个内部队列，用于存放当前正在计划下载的媒体URL，并将包含相同媒体的响应连接到该队列。这避免了当多个项目共享同一媒体时重复下载。

使用文件管道

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

  1. 在爬虫中，您抓取一个项目，并将所需文件的 URL 放入 file_urls 字段中。

  2. 项目从爬虫返回，并进入项目管道。

  3. 当项目到达 FilesPipeline 时，file_urls 字段中的 URL 将使用标准的 Scrapy 调度器和下载器（这意味着调度器和下载器中间件会被重用）进行计划下载，但优先级更高，在抓取其他页面之前进行处理。项目在该特定管道阶段会保持“锁定”状态，直到文件下载完成（或因某种原因失败）。

  4. 文件下载完成后，另一个字段（files）将填充下载结果。此字段将包含一个字典列表，其中包含有关下载文件的信息，例如下载路径、原始抓取URL（取自 file_urls 字段）、文件校验和以及文件状态。files 字段列表中的文件将保留原始 file_urls 字段的相同顺序。如果某些文件下载失败，将记录错误，并且该文件将不会出现在 files 字段中。

使用图片管道

使用 ImagesPipeline 与使用 FilesPipeline 非常相似，只是使用的默认字段名不同：您使用 image_urls 作为项目的图片 URL，它将填充一个 images 字段，用于存储下载图片的有关信息。

使用 ImagesPipeline 处理图片文件的优势在于，您可以配置一些额外的功能，例如生成缩略图和根据图片大小过滤图片。

图片管道需要 Pillow 8.3.2 或更高版本。它用于生成缩略图并将图片规范化为 JPEG/RGB 格式。

启用您的媒体管道

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

对于图片管道，请使用

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

对于文件管道，请使用

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

注意

您也可以同时使用文件管道和图片管道。

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

对于文件管道，请设置 FILES_STORE 设置

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

对于图片管道，请设置 IMAGES_STORE 设置

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

文件命名

默认文件命名

默认情况下，文件使用其 URL 的 SHA-1 散列作为文件名进行存储。

例如，以下图片 URL

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

其 SHA-1 hash 为

3afec3b4765f8f0a07b78f98c07b83f013567a0a

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

3afec3b4765f8f0a07b78f98c07b83f013567a0a.jpg

自定义文件命名

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

通过覆盖媒体管道的 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 方法的更多信息，请参阅 扩展媒体管道。

支持的存储

文件系统存储

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

<IMAGES_STORE>/full/<FILE_NAME>

其中

  • <IMAGES_STORE> 是图片管道的 IMAGES_STORE 设置中定义的目录。

  • full 是一个子目录，用于将完整图片与缩略图（如果使用）分开。有关更多信息，请参阅 图片缩略图生成。

  • <FILE_NAME> 是分配给文件的文件名。有关更多信息，请参阅 文件命名。

FTP 服务器存储

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.13.45，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。

使用示例

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

然后，如果爬虫返回一个带有 URL 字段（file_urls 或 image_urls，分别用于文件管道或图片管道）的 项目对象，管道会将结果放在相应的字段（files 或 images）下。

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

from dataclasses import dataclass, field


@dataclass
class MyItem:
    # ... other item fields ...
    image_urls: list[str] = field(default_factory=list)
    images: list[dict] = field(default_factory=list)

如果您想为 URL 键或结果键使用另一个字段名，也可以覆盖它。

对于文件管道，设置 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_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) 的图片都将被丢弃，因为至少有一个维度短于约束。

默认情况下，没有尺寸限制，因此所有图片都会被处理。

允许重定向

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

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

MEDIA_ALLOW_REDIRECTS = True

扩展媒体管道

在此处查看您可以在自定义文件管道中覆盖的方法

class scrapy.pipelines.files.FilesPipeline[源码]
file_path(self, request, response=None, info=None, *, item=None)[源码]

此方法为每个下载的项目调用一次。它返回源自指定 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>。

get_media_requests(item, info)[源码]

如工作流程所示，管道将从项目中获取要下载的图片 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 - 文件状态指示。

      它可以是以下之一

      • 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)[源码]

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

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

以下是 item_completed() 方法的示例，我们将在其中存储下载的文件路径（在结果中传递）到 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[源码]

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

file_path(self, request, response=None, info=None, *, item=None)[源码]

此方法为每个下载的项目调用一次。它返回源自指定 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>。

thumb_path(self, request, thumb_id, response=None, info=None, *, item=None)[源码]

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

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

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

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

get_media_requests(item, info)[源码]

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

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

item_completed(results, item, info)[源码]

当单个项目的所有图片请求都已完成（无论是下载完成还是因某种原因失败）时，会调用 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}

基于内容的图片过滤管道

此示例覆盖 get_images() 以使用分类器（例如 TensorFlow 模型）过滤图片。使用您的分类逻辑覆盖 is_valid_image()

from scrapy.pipelines.images import ImagesPipeline, ImageException


class ImageClassifierPipeline(ImagesPipeline):
    def is_valid_image(self, image):
        raise NotImplementedError

    def get_images(self, response, request, info, *, item=None):
        for path, image, buf in super().get_images(response, request, info, item=item):
            if not self.is_valid_image(image):
                raise ImageException("Image does not match criteria")
            yield path, image, buf