Python算法Toolbox打包\分发完整学习笔记

Python算法Toolbox打包分发完整学习笔记一、核心目标将本地零散的Python算法代码封装为可直接 import、可离线分发、可多人复用的标准化Toolbox工具库实现效果任意Python环境中执行import 包名即可调用自定义算法无需复制源码文件。以本人OWBE算法工具箱为例适配所有自定义Python算法项目。二、标准项目目录结构核心基础必须遵循Python包规范否则无法正常打包和导入标准结构如下项目根目录/ ├─ pyproject.toml # 打包核心配置文件现代Python标准 ├─ 包名/ # 核心代码文件夹最终import的名称必须统一 │ ├─ __init__.py # 包标识文件对外API出口必填 │ ├─ 模块1/ # 算法子模块如models、estimation、plotting │ │ └─ __init__.py │ └─ 模块2/ └─ experiments/ # 示例调用脚本不参与打包仅给用户参考关键文件作用说明__init__.py标识文件夹为Python可导入包同时统一导出对外接口简化用户调用方式避免冗长导入语句。pyproject.toml定义包名、版本、依赖、Python版本要求是打包的唯一配置文件。experiments文件夹存放测试、示例代码仅作演示不会被打包进工具库。三、关键配置文件编写1. pyproject.toml打包核心配置统一采用现代Python打包方案废弃老旧setup.py最小完整可复用模板[build-system] requires [setuptools64, wheel] build-backend setuptools.build_meta [project] name owbe # 包名必须和源码文件夹名完全一致 version 0.1.0 # 版本号迭代更新必须递增 authors [{name自定义名称}] description 自定义算法工具箱 requires-python 3.10 # 适配的最低Python版本 dependencies [ # 项目所有依赖库 numpygt;1.24, scipygt;1.10, matplotlibgt;3.7 ] [tool.setuptools] packages [owbe, owbe.models, owbe.estimation, owbe.plotting]2. 包入口 __init__.py优化用户调用核心作用收拢所有对外算法接口用户无需关心内部文件结构直接顶层导入。示例配置# 从各子模块导入核心算法/类 from .models.lorenz96 import Lorenz96Model from .estimation.owbe import overlapping_window_batch_estimator from .plotting.plots import plot_result # 定义公开接口IDE可智能补全 __all__ [ Lorenz96Model, overlapping_window_batch_estimator, plot_result, ]四、本地开发安装调试模式适用于开发者本地调试代码修改源码无需重新安装实时生效。操作步骤打开终端cd 到项目根目录pyproject.toml所在目录执行可编辑安装命令pip install -e .验证新开终端任意路径执行导入无报错即成功import owbe from owbe import overlapping_window_batch_estimator特性-eeditable 可编辑模式仅创建源码链接不复制文件修改算法源码后无需重装直接生效仅当前激活的虚拟环境生效五、正式打包生成分发文件开发调试完成后打包生成可离线分发的工具包供他人使用。1. 打包前置清理必做删除旧缓存文件避免版本冲突手动删除dist/、build/、*.egg-info文件夹。2. 执行打包命令# 安装打包工具 pip install build # 执行打包 python -m build3. 打包产物说明dist文件夹内执行成功后生成两个文件作用完全不同文件类型作用使用场景.whlwheel包预编译二进制包安装速度快、无需本地编译日常分发给他人首选通用场景全部用此文件.tar.gzsdist源码包原始源码压缩包无编译处理版本备份、开源上传兜底内部分发无需使用六、两种分发使用方案方案1离线whl分发推荐仅使用算法适合使用者只调用算法、不修改源码的场景。将打包生成的.whl文件 experiments示例文件夹发给他人对方激活虚拟环境cd到whl文件所在目录执行安装pip install 包名-0.1.0-py3-none-any.whl对方任意位置可直接 import 使用方案2源码分发可修改源码适合团队协作、需要二次开发修改算法的场景。发送完整项目源码文件夹对方进入根目录执行可编辑安装pip install -e .支持修改源码实时生效七、包卸载方法无论可编辑安装、whl安装卸载命令统一pip uninstall owbe验证卸载干净pip show owbe提示Package(s) not found即彻底卸载成功。八、常见报错与解决方案1. 报错-e option requires 1 argument原因命令缺失路径参数解决方案严格执行pip install -e .-e 后带空格和英文点且终端处于项目根目录。2. 报错package directory xxx does not exist原因配置/代码中引用了不存在的子模块如utils解决方案删除无效导入、删除配置中不存在的包路径或新建对应文件夹__init__.py。3. 导入失败ModuleNotFoundError原因目录结构不规范、缺失__init__.py、虚拟环境不匹配解决方案检查包文件夹名与配置一致确保所有子模块含__init__.py激活对应安装环境。九、版本迭代规范修改算法代码后更新pyproject.toml中的 version 版本号必须递增清理旧dist、egg-info缓存文件重新执行python -m build生成新版whl包本地先卸载旧包、安装新whl测试无误后再分发十、核心总结标准化结构 pyproject.toml __init__.py 是打包成功的核心三要素本地开发用pip install -e .分发用户用whl包tar.gz仅作备份兜底日常分发无需使用示例代码统一放在experiments不参与打包单独分发版本迭代必须清理旧缓存、递增版本号避免冲突