Pillow 图像格式插件体系完全参考:从 44 个格式插件的源码解读到实战配置
Pillow 图像格式插件体系完全参考:从 44 个格式插件的源码解读到实战配置
本文以 docs/reference/plugins.rst 为骨架,系统梳理 Python Imaging Library (Pillow) 的图像格式插件(Image Plugin)注册机制与全部内置格式模块。你将掌握 Pillow 的插件注册 API、懒加载初始化流程、
Image.open的格式探测原理,以及 AVIF、BMP、GIF、JPEG、PNG、TIFF、WebP 等 44 个格式插件的职责划分与典型用法,并能据此判断在何种场景下该选用哪个插件模块。
一、插件参考文档的性质:Pillow 格式扩展的地图
docs/reference/plugins.rst 是 Pillow 文档站中针对"格式插件"这一层级的自动生成式 API 参考页。它本身不包含长篇教程,而是通过 Sphinx 的 automodule 指令,把 src/PIL 目录下 44 个 *ImagePlugin.py 模块的公开成员(类、函数、常量)逐一生成为可检索的 API 文档,并支持 :members:、:undoc-members:、:show-inheritance: 等选项展示继承关系与未文档化成员。
这份文档的价值在于:它精确刻画了 Pillow 的架构分层——核心库(Image、ImageFile、ImageDraw 等)与格式扩展(*ImagePlugin)之间通过"插件注册表"解耦。读懂这份参考,等于拿到了一张 Pillow 全部内置格式能力的地图:哪些格式可以打开、哪些可以保存、哪些只是"Stub 占位插件"。
值得注意的是,文档对 PNG 插件 使用了显式成员白名单:
:members: ChunkStream, PngImageFile, PngStream, getchunks, is_cid, putchunk,
Blend, Disposal, MAX_TEXT_CHUNK, MAX_TEXT_MEMORY
:member-order: groupwise
这意味着 PNG 插件是整个体系中最复杂、最值得单独研读的模块——它既有流式块解析器(ChunkStream、PngStream)、帧混合枚举(Blend、Disposal),又有面向 APNG 动画与文本块(iTXt/zTXt)的安全常量(MAX_TEXT_CHUNK、MAX_TEXT_MEMORY)。
二、插件注册机制:一切格式能力的源头
所有格式插件的接入点都在 src/PIL/Image.py 的"Plugin registry"区块。Pillow 维护了 ID、OPEN、SAVE、SAVE_ALL、MIME、EXTENSION、DECODERS、ENCODERS 等多张注册表,并提供以下注册函数(这些函数在官方文档中被明确标注"不应在应用代码中直接调用",它们是供插件模块自身在导入时调用的基础设施):
| 函数 | 作用 | 写入的注册表 |
|---|---|---|
register_open(id, factory, accept=None) |
注册一个图像打开工厂,accept 是用于快速拒识其他格式的可选谓词(返回 True/False 或警告字符串) |
ID、OPEN |
register_mime(id, mimetype) |
将格式标识符映射到 MIME 类型,供 Image.MIME 查询 |
MIME |
register_save(id, driver) |
注册单帧保存函数 | SAVE |
register_save_all(id, driver) |
注册多帧格式的"保存全部帧"函数(GIF/APNG/TIFF 等多帧格式使用) | SAVE_ALL |
register_extension(id, extension) / register_extensions(id, extensions) |
把扩展名映射到格式标识符,驱动 Image.open 的按扩展名导入优化 |
EXTENSION |
register_decoder(name, decoder) / register_encoder(name, encoder) |
注册 Python 侧编解码器(ImageFile.PyDecoder / PyEncoder),自 4.1.0 版本引入 |
DECODERS、ENCODERS |
所有 id 都会被统一转为大写。以 GifImagePlugin.py 的注册收尾为例,一个完整插件模块的注册代码通常长这样:
Image.register_open(GifImageFile.format, GifImageFile, _accept)
Image.register_save(GifImageFile.format, _save)
Image.register_save_all(GifImageFile.format, _save_all)
Image.register_extension(GifImageFile.format, ".gif")
Image.register_mime(GifImageFile.format, "image/gif")
可以看到:GIF 是"打开 + 单帧保存 + 多帧保存 + 扩展名 + MIME"五项齐全的完整插件;而像 MpegImagePlugin 这类只读格式则只注册打开与扩展名,不注册任何保存函数。
三、懒加载初始化:preinit 与 init 的两级策略
插件模块不会被 Pillow 启动时全部导入,而是采用两级懒加载,这是 plugins.rst 所描述能力能保持轻量的关键设计,实现在 src/PIL/Image.py:
preinit():只导入最常用的五个格式插件——BMP、GIF、JPEG、PPM、PNG。它在打开或保存图像时被调用,保证常见格式的极速可用。init():通过_plugins列表(由 src/PIL/__init__.py 维护)遍历导入全部*ImagePlugin模块。由于每个插件模块导入时会自动调用自己的register_*,因此init()之后注册表即被填满。
Image.open 在 src/PIL/Image.py 中实际执行了这样的调度逻辑:
prefix = fp.read(16) # 读取 16 字节文件头
ext = os.path.splitext(filename)[1] if filename else ""
if not _import_plugin_for_extension(ext): # 先按扩展名只导入对应插件
preinit() # 兜底加载五个常见插件
随后 _open_core 按 formats 顺序遍历注册表:先调用插件的 accept(prefix) 快速嗅探文件头魔数,命中后 fp.seek(0) 并调用工厂构造 ImageFile.ImageFile 实例,再做 _decompression_bomb_check(im.size) 解压炸弹防护。若 accept 返回字符串,则该字符串作为警告消息被收集(用于 WARN_POSSIBLE_FORMATS 诊断模式)。
formats 参数允许调用方显式限定尝试的格式集合;不传则默认使用全部 ID。查看当前环境实际可用的格式列表,可运行 python3 -m PIL,或调用 features.pilinfo() 打印详细报告。
四、44 个格式插件全景清单
按 plugins.rst 的编排顺序,Pillow 内置插件可分为以下五类(模块均位于 src/PIL 目录):
4.1 核心位图与光栅格式
| 插件模块 | 格式说明 | 典型扩展名 |
|---|---|---|
BmpImagePlugin |
Windows 位图 BMP,兼容 DIB | .bmp、.dib |
DdsImagePlugin |
DirectDraw Surface,含 BC1–BC7 等压缩块格式 | .dds |
PcxImagePlugin |
ZSoft PC Paintbrush | .pcx |
PpmImagePlugin |
PBM/PGM/PPM(含 ASCII 与二进制变体) | .pbm、.pgm、.ppm |
PngImagePlugin |
便携网络图形 PNG 及 APNG 动画,见下文专题 | .png、.apng |
TgaImagePlugin |
Truevision TGA | .tga |
TiffImagePlugin |
TIFF/TIFF 多页,与 libtiff 深度集成 | .tif、.tiff |
WebPImagePlugin |
Google WebP(含有损/无损/动画/元数据) | .webp |
AvifImagePlugin |
AVIF(基于 libavif),支持 HDR 与深色模式 | .avif、.avifs |
JpegImagePlugin |
经典 JPEG,支持 EXIF、ICC、量化表、渐进式 | .jpg、.jpeg、.jpe |
Jpeg2KImagePlugin |
JPEG 2000,依赖 OpenJPEG | .j2k、.jp2、.jpx、.j2c |
XbmImagePlugin / XpmImagePlugin |
X BitMap / X PixMap | .xbm、.xpm |
4.2 动画与多帧格式
| 插件模块 | 格式说明 | 典型扩展名 |
|---|---|---|
GifImagePlugin |
GIF,支持帧动画、调色板、透明与循环控制 | .gif |
FliImagePlugin |
Autodesk FLI/FLC 动画 | .fli、.flc |
MngImagePlugin(在文档中由 PngImagePlugin 承担) |
见 PNG 插件对 APNG 的 Blend/Disposal 支持 |
— |
MpoImagePlugin |
多画面对象(多镜头相机输出,基于 JPEG) | .mpo |
MpegImagePlugin |
MPEG 视频首帧提取(只读) | .mpg、.mpeg |
4.3 Stub 占位插件:容器格式的门卫
BufrStubImagePlugin、GribStubImagePlugin、Hdf5StubImagePlugin 属于特殊的 Stub 插件:它们本身不解析图像数据,而是识别容器格式的文件头(BUFR 气象数据、GRIB 气象网格、HDF5 科学数据),把文件"占位"包装成 ImageFile 并延迟到真正需要时再交给外部解析。其行为由 ImageFile.py 中的 StubImageFile 基类定义。它们与 CurImagePlugin(Windows 光标)、IcoImagePlugin(Windows 图标,读取多尺寸帧)、IcnsImagePlugin(Apple 图标集)一起构成了"系统资源类格式"家族。
4.4 科学与专用数据格式
| 插件模块 | 格式说明 | 典型扩展名 |
|---|---|---|
FitsImagePlugin |
天文学 FITS 图像 | .fits |
FpxImagePlugin |
FlashPix(依赖 _imaging 与 IOCA 解码) |
.fpx |
McIdasImagePlugin |
McIDAS 卫星图像 | .mcidas、.ara |
MicImagePlugin |
Microsoft Image Composer | .mic |
PalmImagePlugin |
Palm OS 位图 | .palm |
PcdImagePlugin |
Kodak PhotoCD(仅基础读取) | .pcd |
PixarImagePlugin |
Pixar 工作站格式 | .pxr |
SgiImagePlugin |
Silicon Graphics RGB | .sgi、.rgb |
SpiderImagePlugin |
SPIDER 科学图像(附带 SpiderImagePlugin 系列辅助函数) |
.spider |
SunImagePlugin |
Sun Rasterfile | .ras |
ImImagePlugin |
IFUNC Image 内部格式(伴随 Image.py 的历史格式) |
.im |
ImtImagePlugin |
IM Tools 内部格式 | .imt |
MspImagePlugin |
Microsoft Paint(老式 MSP) | .msp |
4.5 矢量、页面描述与其他
| 插件模块 | 格式说明 | 典型扩展名 |
|---|---|---|
EpsImagePlugin |
Encapsulated PostScript,通过 Ghostscript 栅格化 | .eps |
PdfImagePlugin |
PDF 页面栅格化(经 Ghostscript 或 pdf2image) |
.pdf |
PsdImagePlugin |
Adobe Photoshop PSD(含图层与合并图像读取) | .psd |
WmfImagePlugin |
Windows 图元文件,仅提取元信息供外部渲染 | .wmf、.emf |
DcxImagePlugin |
DCX 多页 PCX 容器 | .dcx |
GbrImagePlugin |
GIMP brush 文件 | .gbr |
IptcImagePlugin |
IPTC/NAA 头信息(常嵌入 JPEG) | 嵌入场景使用 |
XVThumbImagePlugin |
XV 缩略图格式 | .xv |
说明:仓库 src/PIL 中还包含
BlpImagePlugin、FtexImagePlugin、GdImageFile、QoiImagePlugin、WalImageFile等模块,但它们未出现在plugins.rst的参考列表中,本文从略,仅提示读者留意。
五、PNG 插件专题:plugins.rst 中唯一显式列成员的模块
文档对 PNG 插件单独指定了成员清单,这背后是 PngImagePlugin.py 中值得深入的三组设计:
5.1 魔数与模式映射表
_MAGIC = b"\211PNG\r\n\032\n"
_accept 正是据此嗅探。而 _MODES 表(PngImagePlugin.py)把 PNG 的"位深 × 颜色类型"组合映射到 Pillow 模式与 rawmode,例如 (16, 0) 灰度 16 位映射到 ("I;16", "I;16B")、(8, 6) 真彩带透明映射到 ("RGBA", "RGBA")。这份表决定了 PNG 解码后你会拿到什么模式的图像对象。
5.2 文本块的解压炸弹防护
MAX_TEXT_CHUNK = ImageFile.SAFEBLOCK # 单个 iTXt/zTXt 块最大解压尺寸
MAX_TEXT_MEMORY = 64 * MAX_TEXT_CHUNK # 全部文本块累计上限
这是针对"压缩文本块可膨胀 1000 倍"的拒绝服务攻击的防御常量:MAX_TEXT_CHUNK 限制单个块,MAX_TEXT_MEMORY 限制总和。API 文档把二者显式暴露,正是为了让高级用户能在必要时调整阈值。
5.3 APNG 动画与块级工具
Blend、Disposal 两个枚举定义了 APNG 帧的混合与清除策略;ChunkStream/PngStream 实现面向流的块读取;getchunks/putchunk 提供块级读写工具,is_cid 是块类型标识符的正则谓词。配合 Tests/test_file_apng.py 与 Tests/test_file_png.py 中的用例,可以完整还原 APNG 帧序列的处理路径。
六、插件与 Image 核心的协作流程
一个典型的打开操作,其完整调用链为:
Image.open(fp)读取 16 字节前缀;- 按扩展名调用
_import_plugin_for_extension,命中则只导入该插件; - 否则
preinit()加载五个常见插件;若formats中还有未注册格式,_open_core内会触发init()全量导入; - 依次调用各插件
accept(prefix)嗅探,命中后构造ImageFile子类并执行解压炸弹检查; - 真正的像素解码被推迟到
.load()(懒加载),对应ImageFile.py中的PyDecoder/PyEncoder编解码工厂与core层的 C 实现(见 src/libImaging 目录下的decode.c、encode.c)。
这一流程解释了为何 plugins.rst 中所有模块都以 ImagePlugin 命名:它们通过统一的 register_* 协议与 Image 核心交互,用户侧几乎不需要直接 import 任何插件模块——Image.open 自动完成格式识别。
七、如何验证插件能力与编写自定义格式
7.1 查看可用格式
python3 -m PIL # 打印支持的格式、扩展名与特性
或在代码中:
from PIL import Image, features
Image.registered_extensions() # {'bmp': 'BMP', 'gif': 'GIF', ...}
features.pilinfo() # 详细特性与依赖报告
7.2 自定义插件的最小形态
虽然文档强调 register_* 不应在应用代码中使用,但第三方格式包正是通过它们接入 Pillow 的。一个最小插件需要:
from PIL import Image, ImageFile
class MyFormatImageFile(ImageFile.ImageFile):
format = "MYFMT"
format_description = "My custom format"
def _open(self):
# 解析文件头,设置 self._mode 与 self._size,注册 raw decoder
self.tile = [("raw", (0, 0) + self.size, self.fp.tell(), (self.mode, 0, 1))]
def _accept(prefix: bytes) -> bool:
return prefix[:4] == b"MYFM"
Image.register_open(MyFormatImageFile.format, MyFormatImageFile, _accept)
Image.register_extension(MyFormatImageFile.format, ".myfmt")
将文件放入 sys.path 并确保其被 init() 的 _plugins 扫描路径覆盖,或直接在应用启动时导入该模块完成注册。
八、测试佐证与进一步阅读
每个插件模块在 Tests 目录下都有对应的回归测试文件,例如:
- test_file_gif.py、test_file_apng.py 验证多帧与动画语义;
- test_file_tiff.py、test_file_tiff_metadata.py 验证 TIFF 标签与元数据;
- test_file_webp.py、test_file_webp_animated.py 验证 WebP 各编码路径;
- test_file_jpeg.py、test_file_jpeg2k.py 验证 JPEG 家族;
- 安全相关测试见 test_decompression_bomb.py,与
MAX_TEXT_CHUNK等常量直接呼应。
若需深入底层,可继续阅读:
- Image.py 插件注册表与 open 调度
- ImageFile.py 的懒加载与编解码工厂
- src/libImaging 的 C 层解码/编码实现
- docs/reference/internal_design.rst 的架构总览
结语
plugins.rst 虽然只是一份自动生成的索引,却是理解 Pillow 扩展性的钥匙:44 个格式插件通过统一注册协议接入核心库,两级懒加载保证了轻量启动,accept 嗅探 + formats 限定提供了可控的格式探测,而 PNG 插件中显式暴露的成员则展示了深度集成(APNG 动画、文本块安全限制)可以做到什么程度。无论是排查"为什么某格式打不开"、评估"自定义格式如何接入",还是研究"多帧格式如何设计保存 API",这份参考与 src/PIL 源码都是最佳起点。