Python项目打包与分发全攻略

### Python项目打包与分发全攻略 #### 1. 变更日志的重要性与内容 变更日志在项目管理中起着关键作用，它能提供项目版本的重要信息，具体如下： - 最新发布的版本号 - 最新版本是否向后兼容 - 上一版本的发布日期 - 该版本包含的变更内容 变更日志文件无需特定格式，只要内容连贯且信息丰富即可。虽然自动生成变更日志很诱人，但不建议完全自动化，因为精心编写的关于错误修复或功能添加的记录无可替代。使用版本控制提交记录生成的变更日志并非好做法，因为通过列出提交记录就能获取相同信息。 #### 2. 选择合适的打包策略 选择打包策略时，需要考虑项目的分发类型和可用的基础设施服务。以下是不同类型项目适合的打包方式： | 项目类型 | 适合的打包方式 | | ---- | ---- | | 为其他Python项目扩展功能的纯Python库 | 作为原生Python包，托管在Python Package Index (PyPI) 或本地索引上 | | 独立脚本和长期运行的进程 | 适合作为系统包，如RPM或Debian，但最终取决于可用的系统类型以及是否能够托管和管理存储库 | 一般来说，脚本或进程与系统交互越多，越适合使用系统包或容器；而仅使用Python编写的脚本，传统的Python打包方式是正确的选择。选择策略没有严格要求，需根据实际情况而定，不同类型的打包方式并不相互排斥，一个项目可以同时提供多种打包格式。 #### 3. 原生Python打包 为了简化代码示例，假设一个名为`hello-world`的小型Python项目，其结构如下： ```plaintext hello-world └── hello_world ├── __init__.py └── main.py ``` 以下是原生Python打包的具体步骤： 1. **创建并激活虚拟环境** ```bash python3 -m venv /tmp/packaging source /tmp/packaging/bin/activate ``` 2. **安装依赖** ```bash pip install setuptools twine ``` 3. **添加必要文件** 在项目的顶级目录添加`setup.py`文件，内容如下： ```python from setuptools import setup, find_packages setup( name="hello-world", version="0.0.1", author="Example Author", author_email="[email protected]", url="example.com", description="A hello-world example package", packages=find_packages(), classifiers=[ "Programming Language :: Python :: 3", "License :: OSI Approved :: MIT License", "Operating System :: OS Independent", ], ) ``` 为避免运行命令时出现警告，在顶级目录添加一个空的`README`文件： ```bash touch README ``` 此时项目目录结构如下： ```plaintext hello-world ├── hello_world │ ├── __init__.py │ └── main.py └── README └── setup.py ``` 4. **生成源分发包** 运行以下命令生成源分发包： ```bash python3 setup.py sdist ``` 运行该命令后，项目顶级目录会出现一个`dist`目录，其中包含源分发文件`hello-world-0.0.1.tar.gz`。此时项目目录结构变为： ```plaintext hello-world ├── dist │ └── hello-world-0.0.1.tar.gz ├── hello_world │ ├── __init__.py │ └── main.py ├── hello_world.egg-info │ ├── dependency_links.txt │ ├── PKG-INFO │ ├── SOURCES.txt │ └── top_level.txt ├── README └── setup.py ``` 5. **安装源分发包** 使用`pip`安装生成的源分发包： ```bash pip install dist/hello-world-0.0.1.tar.gz ``` #### 4. Python Package Index (PyPI) 的使用 PyPI是一个Python软件仓库，允许用户托管和安装Python包。以下是将包上传到PyPI测试实例的步骤： 1. **注册测试实例账户** 确保已经拥有PyPI测试实例的账户，或者在线注册。上传包时需要使用账户的用户名和密码。 2. **更新`setup.py`文件** 如果要将包发布到索引，需要更新`setup.py`文件中的字段，如作者、URL、描述等，以准确反映项目信息。 3. **使用`twine`上传包** 使用之前安装的`twine`工具将包上传到PyPI测试实例： ```bash twine upload --repository-url https://test.pypi.org/legacy/ dist/hello-world-0.0.1.tar.gz ``` 4. **测试安装包** 使用`pip`从测试实例安装包： ```bash python3 -m pip install --index-url https://test.pypi.org/simple/ hello-world ``` #### 5. 托管内部包索引 在某些情况下，托管内部PyPI是更好的选择。内部PyPI可以加快安装速度，保护包的隐私，并且实现起来并不复杂。以下是创建内部PyPI的步骤： 1. **创建目录结构** ```bash mkdir -p pypi/hello-worl ```