Python-oracledb 在 PyInstaller 打包时遇到 cryptography 模块问题的解决方案

Python-oracledb 在 PyInstaller 打包时遇到 cryptography 模块问题的解决方案

在使用 Python-oracledb 2.4.1 版本时，开发者可能会遇到一个特殊问题：当应用通过 PyInstaller 打包后运行时，会出现错误提示"DPY-3016: python-oracledb thin mode cannot be used because the cryptography package is not installed"，尽管 cryptography 模块确实已经安装。

这个问题主要出现在 Windows 环境下，使用 Python 3.11.9 和 cryptography 43.0.1 及以上版本时。经过深入分析，我们发现这是由于 PyInstaller 在打包过程中未能正确识别和包含 cryptography 模块的所有必要子组件所致。

问题的根源在于 python-oracledb 在 thin 模式下需要 cryptography 模块的多个子组件，包括 x509 证书处理和 PBKDF2 密钥派生功能。当这些子组件没有被正确打包时，虽然主 cryptography 包存在，但关键功能仍然无法使用，导致连接失败。

解决方案有以下几种：

1. 显式声明隐藏导入：在 PyInstaller 打包命令中明确指定需要包含的 cryptography 子模块：

   --hidden-import cryptography.hazmat.primitives.kdf.pbkdf2 
   --hidden-import cryptography.x509
   

2. 在代码中直接导入：在应用程序的主代码文件中显式导入这些子模块，确保 PyInstaller 能够识别它们：

   from cryptography import x509
   from cryptography.hazmat.primitives.kdf import pbkdf2
   

3. 降级 cryptography 版本：作为临时解决方案，可以将 cryptography 降级到 42.0.8 版本，但这可能带来其他依赖问题，不推荐长期使用。

4. 配置 Oracle 客户端路径：设置环境变量指向 Oracle 客户端目录，但这会限制应用的可移植性。

对于开发者来说，最佳实践是采用第一种或第二种方案，确保所有必要的加密组件都被正确打包。这也提醒我们在使用 PyInstaller 打包依赖复杂加密功能的应用程序时，需要特别注意检查所有必要的子模块是否被正确包含。

python-oracledb 团队已注意到这个问题，并考虑在未来的版本中改进错误提示信息，使其更准确地反映"加密组件未正确安装"而非简单的"未安装"，这将帮助开发者更快地定位问题。