borb项目中使用PyInstaller打包时的AFM字体目录问题解析

在使用Python PDF处理库borb开发控制台应用时，开发者可能会遇到一个常见问题：当使用PyInstaller将应用打包为可执行文件后，运行时出现"AssertionError: AFM directory not found"错误。这个问题主要与borb的字体处理机制和PyInstaller的打包特性有关。

问题背景

borb在处理PDF文档时，默认会使用一些标准字体(如Helvetica)。这些字体的度量信息存储在AFM(Adobe Font Metrics)文件中，这些文件随borb库一起分发。当使用TrueType字体(.ttf)时，虽然不直接需要AFM文件，但borb内部仍会尝试访问这些标准字体的度量信息。

问题根源

问题的核心在于PyInstaller打包时未能正确包含borb的AFM字体目录。具体来说，在borb的代码中，font_type_1.py文件会尝试定位afm目录：

afm_directory: pathlib.Path = pathlib.Path(__file__).parent / "afm"
assert afm_directory.exists(), "AFM directory not found"

当使用PyInstaller打包后，这个相对路径查找会失败，因为PyInstaller的打包机制改变了文件系统的组织结构。

解决方案

要解决这个问题，需要在PyInstaller的配置中明确包含AFM目录。具体方法是在PyInstaller的spec文件中添加数据文件：

datas = [
    (
        'venv\\Lib\\site-packages\\borb\\pdf\\canvas\\font\\simple_font\\afm',
        'borb\\pdf\\canvas\\font\\simple_font\\afm'
    ),
]

这个配置告诉PyInstaller将源路径中的afm目录复制到打包后的可执行文件的相应位置。

深入理解

1. AFM文件的作用：AFM文件包含了字体的度量信息，如字符宽度、高度等，对于PDF文档的精确排版至关重要。

2. PyInstaller打包机制：PyInstaller会将Python代码和依赖打包成独立的可执行文件，但默认不会包含所有数据文件，特别是那些通过相对路径访问的资源。

3. 版本变化影响：这个问题在borb 2.1.17到2.1.22版本之间出现，可能是因为字体处理逻辑的改动使得AFM目录成为必需而非可选。

最佳实践建议

1. 即使使用自定义字体，也建议包含AFM目录，因为borb内部可能仍会引用标准字体。

2. 对于生产环境，考虑将字体文件(包括AFM和TTF)作为应用程序资源统一管理。

3. 在开发过程中，可以使用try-except块捕获这个异常，并给出更友好的错误提示。

4. 定期检查borb的版本更新，关注字体处理相关的变更日志。

通过理解这个问题的本质和解决方案，开发者可以更顺利地使用borb库创建PDF处理应用，并确保打包后的可执行文件能够正常运行。