Pillow 图像格式插件体系完全参考从 44 个格式插件的源码解读到实战配置【免费下载链接】PillowPython Imaging Library (fork)项目地址: https://gitcode.com/gh_mirrors/pi/Pillow本文以 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, acceptNone)注册一个图像打开工厂accept是用于快速拒识其他格式的可选谓词返回True/False或警告字符串ID、OPENregister_mime(id, mimetype)将格式标识符映射到 MIME 类型供Image.MIME查询MIMEregister_save(id, driver)注册单帧保存函数SAVEregister_save_all(id, driver)注册多帧格式的保存全部帧函数GIF/APNG/TIFF 等多帧格式使用SAVE_ALLregister_extension(id, extension)/register_extensions(id, extensions)把扩展名映射到格式标识符驱动Image.open的按扩展名导入优化EXTENSIONregister_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.pypreinit()只导入最常用的五个格式插件——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 核心位图与光栅格式插件模块格式说明典型扩展名BmpImagePluginWindows 位图 BMP兼容 DIB.bmp、.dibDdsImagePluginDirectDraw Surface含 BC1–BC7 等压缩块格式.ddsPcxImagePluginZSoft PC Paintbrush.pcxPpmImagePluginPBM/PGM/PPM含 ASCII 与二进制变体.pbm、.pgm、.ppmPngImagePlugin便携网络图形 PNG 及 APNG 动画见下文专题.png、.apngTgaImagePluginTruevision TGA.tgaTiffImagePluginTIFF/TIFF 多页与 libtiff 深度集成.tif、.tiffWebPImagePluginGoogle WebP含有损/无损/动画/元数据.webpAvifImagePluginAVIF基于 libavif支持 HDR 与深色模式.avif、.avifsJpegImagePlugin经典 JPEG支持 EXIF、ICC、量化表、渐进式.jpg、.jpeg、.jpeJpeg2KImagePluginJPEG 2000依赖 OpenJPEG.j2k、.jp2、.jpx、.j2cXbmImagePlugin/XpmImagePluginX BitMap / X PixMap.xbm、.xpm4.2 动画与多帧格式插件模块格式说明典型扩展名GifImagePluginGIF支持帧动画、调色板、透明与循环控制.gifFliImagePluginAutodesk FLI/FLC 动画.fli、.flcMngImagePlugin在文档中由PngImagePlugin承担见 PNG 插件对 APNG 的Blend/Disposal支持—MpoImagePlugin多画面对象多镜头相机输出基于 JPEG.mpoMpegImagePluginMPEG 视频首帧提取只读.mpg、.mpeg4.3 Stub 占位插件容器格式的门卫BufrStubImagePlugin、GribStubImagePlugin、Hdf5StubImagePlugin属于特殊的Stub 插件它们本身不解析图像数据而是识别容器格式的文件头BUFR 气象数据、GRIB 气象网格、HDF5 科学数据把文件占位包装成ImageFile并延迟到真正需要时再交给外部解析。其行为由 ImageFile.py 中的StubImageFile基类定义。它们与CurImagePluginWindows 光标、IcoImagePluginWindows 图标读取多尺寸帧、IcnsImagePluginApple 图标集一起构成了系统资源类格式家族。4.4 科学与专用数据格式插件模块格式说明典型扩展名FitsImagePlugin天文学 FITS 图像.fitsFpxImagePluginFlashPix依赖_imaging与 IOCA 解码.fpxMcIdasImagePluginMcIDAS 卫星图像.mcidas、.araMicImagePluginMicrosoft Image Composer.micPalmImagePluginPalm OS 位图.palmPcdImagePluginKodak PhotoCD仅基础读取.pcdPixarImagePluginPixar 工作站格式.pxrSgiImagePluginSilicon Graphics RGB.sgi、.rgbSpiderImagePluginSPIDER 科学图像附带SpiderImagePlugin系列辅助函数.spiderSunImagePluginSun Rasterfile.rasImImagePluginIFUNC Image 内部格式伴随Image.py的历史格式.imImtImagePluginIM Tools 内部格式.imtMspImagePluginMicrosoft Paint老式 MSP.msp4.5 矢量、页面描述与其他插件模块格式说明典型扩展名EpsImagePluginEncapsulated PostScript通过 Ghostscript 栅格化.epsPdfImagePluginPDF 页面栅格化经 Ghostscript 或pdf2image.pdfPsdImagePluginAdobe Photoshop PSD含图层与合并图像读取.psdWmfImagePluginWindows 图元文件仅提取元信息供外部渲染.wmf、.emfDcxImagePluginDCX 多页 PCX 容器.dcxGbrImagePluginGIMP brush 文件.gbrIptcImagePluginIPTC/NAA 头信息常嵌入 JPEG嵌入场景使用XVThumbImagePluginXV 缩略图格式.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] bMYFM 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源码都是最佳起点。【免费下载链接】PillowPython Imaging Library (fork)项目地址: https://gitcode.com/gh_mirrors/pi/Pillow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 Pillow 图像格式插件体系完全参考：从 44 个格式插件的源码解读到实战配置
Pillow 图像格式插件体系完全参考从 44 个格式插件的源码解读到实战配置【免费下载链接】PillowPython Imaging Library (fork)项目地址: https://gitcode.com/gh_mirrors/pi/Pillow本文以 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, acceptNone)注册一个图像打开工厂accept是用于快速拒识其他格式的可选谓词返回True/False或警告字符串ID、OPENregister_mime(id, mimetype)将格式标识符映射到 MIME 类型供Image.MIME查询MIMEregister_save(id, driver)注册单帧保存函数SAVEregister_save_all(id, driver)注册多帧格式的保存全部帧函数GIF/APNG/TIFF 等多帧格式使用SAVE_ALLregister_extension(id, extension)/register_extensions(id, extensions)把扩展名映射到格式标识符驱动Image.open的按扩展名导入优化EXTENSIONregister_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.pypreinit()只导入最常用的五个格式插件——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 核心位图与光栅格式插件模块格式说明典型扩展名BmpImagePluginWindows 位图 BMP兼容 DIB.bmp、.dibDdsImagePluginDirectDraw Surface含 BC1–BC7 等压缩块格式.ddsPcxImagePluginZSoft PC Paintbrush.pcxPpmImagePluginPBM/PGM/PPM含 ASCII 与二进制变体.pbm、.pgm、.ppmPngImagePlugin便携网络图形 PNG 及 APNG 动画见下文专题.png、.apngTgaImagePluginTruevision TGA.tgaTiffImagePluginTIFF/TIFF 多页与 libtiff 深度集成.tif、.tiffWebPImagePluginGoogle WebP含有损/无损/动画/元数据.webpAvifImagePluginAVIF基于 libavif支持 HDR 与深色模式.avif、.avifsJpegImagePlugin经典 JPEG支持 EXIF、ICC、量化表、渐进式.jpg、.jpeg、.jpeJpeg2KImagePluginJPEG 2000依赖 OpenJPEG.j2k、.jp2、.jpx、.j2cXbmImagePlugin/XpmImagePluginX BitMap / X PixMap.xbm、.xpm4.2 动画与多帧格式插件模块格式说明典型扩展名GifImagePluginGIF支持帧动画、调色板、透明与循环控制.gifFliImagePluginAutodesk FLI/FLC 动画.fli、.flcMngImagePlugin在文档中由PngImagePlugin承担见 PNG 插件对 APNG 的Blend/Disposal支持—MpoImagePlugin多画面对象多镜头相机输出基于 JPEG.mpoMpegImagePluginMPEG 视频首帧提取只读.mpg、.mpeg4.3 Stub 占位插件容器格式的门卫BufrStubImagePlugin、GribStubImagePlugin、Hdf5StubImagePlugin属于特殊的Stub 插件它们本身不解析图像数据而是识别容器格式的文件头BUFR 气象数据、GRIB 气象网格、HDF5 科学数据把文件占位包装成ImageFile并延迟到真正需要时再交给外部解析。其行为由 ImageFile.py 中的StubImageFile基类定义。它们与CurImagePluginWindows 光标、IcoImagePluginWindows 图标读取多尺寸帧、IcnsImagePluginApple 图标集一起构成了系统资源类格式家族。4.4 科学与专用数据格式插件模块格式说明典型扩展名FitsImagePlugin天文学 FITS 图像.fitsFpxImagePluginFlashPix依赖_imaging与 IOCA 解码.fpxMcIdasImagePluginMcIDAS 卫星图像.mcidas、.araMicImagePluginMicrosoft Image Composer.micPalmImagePluginPalm OS 位图.palmPcdImagePluginKodak PhotoCD仅基础读取.pcdPixarImagePluginPixar 工作站格式.pxrSgiImagePluginSilicon Graphics RGB.sgi、.rgbSpiderImagePluginSPIDER 科学图像附带SpiderImagePlugin系列辅助函数.spiderSunImagePluginSun Rasterfile.rasImImagePluginIFUNC Image 内部格式伴随Image.py的历史格式.imImtImagePluginIM Tools 内部格式.imtMspImagePluginMicrosoft Paint老式 MSP.msp4.5 矢量、页面描述与其他插件模块格式说明典型扩展名EpsImagePluginEncapsulated PostScript通过 Ghostscript 栅格化.epsPdfImagePluginPDF 页面栅格化经 Ghostscript 或pdf2image.pdfPsdImagePluginAdobe Photoshop PSD含图层与合并图像读取.psdWmfImagePluginWindows 图元文件仅提取元信息供外部渲染.wmf、.emfDcxImagePluginDCX 多页 PCX 容器.dcxGbrImagePluginGIMP brush 文件.gbrIptcImagePluginIPTC/NAA 头信息常嵌入 JPEG嵌入场景使用XVThumbImagePluginXV 缩略图格式.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] bMYFM 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源码都是最佳起点。【免费下载链接】PillowPython Imaging Library (fork)项目地址: https://gitcode.com/gh_mirrors/pi/Pillow创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考