Sioyek双页模式脚本在macOS 14上的兼容性问题解析

近期有用户反馈，在macOS 14系统上运行Sioyek阅读器的双页处理脚本dual_panelify.py时遇到了兼容性问题。该脚本原本用于将PDF文档自动转换为适合双栏阅读的格式，但在新环境下出现了PyPDF2库的API变更导致的运行错误。

问题现象分析

当用户在终端执行脚本时，系统抛出了一个关键错误信息：

PyPDF2.errors.DeprecationError: reader.numPages is deprecated and was removed in PyPDF2 3.0.0. Use len(reader.pages) instead.

这个错误明确指出了问题的根源：脚本中使用的PyPDF2库API接口在新版本中已被弃用。具体来说，旧版本中通过pdf_reader.numPages获取PDF页数的方式，在PyPDF2 3.0.0及更高版本中已被len(reader.pages)替代。

技术背景

PyPDF2作为Python处理PDF文件的主流库，在版本迭代过程中会对部分API进行优化和重构。这种变更虽然提高了代码的规范性和可维护性，但也可能导致依赖旧API的脚本出现兼容性问题。

在Sioyek的脚本生态中，dual_panelify.py是一个实用工具，它能够：

1. 自动将单页PDF转换为双页布局
2. 优化漫画或学术论文的阅读体验
3. 与Sioyek阅读器深度集成

解决方案

对于遇到此问题的用户，有以下几种解决途径：

1. 升级脚本版本： 项目维护者已在新版本的sioyek-python-extensions中修复了此兼容性问题。用户应该：

   • 卸载旧版脚本
   • 按照官方文档重新安装最新版扩展
   • 使用新版脚本接口

2. 临时降级PyPDF2： 如果急需使用旧脚本，可以通过以下命令安装兼容版本：

   pip install PyPDF2==2.12.1
   

   但这不是推荐做法，可能会影响其他Python项目的正常运行。

3. 手动修改脚本： 对于有Python开发经验的用户，可以自行修改脚本中的相关代码：

   # 将原来的
   for i in range(pdf_reader.numPages // 2):
   
   # 修改为
   for i in range(len(pdf_reader.pages) // 2):
   

最佳实践建议

1. 定期更新项目依赖
2. 关注开源项目的变更日志
3. 对于生产环境的关键脚本，建议锁定依赖版本
4. 考虑使用虚拟环境隔离不同项目的Python依赖

总结

这次兼容性问题反映了开源生态中常见的API演进现象。对于Sioyek用户而言，及时更新相关组件是最稳妥的解决方案。同时，这也提醒开发者需要建立完善的版本兼容性测试机制，特别是在跨平台应用场景下。

未来，随着Sioyek生态的持续发展，建议用户关注官方渠道的更新通知，以获得最佳的使用体验和最新的功能特性。