Python 打包秘籍：让你的代码更易用 – wiki词典

作者： /

Python 打包秘籍：让你的代码更易用

在 Python 的世界里，编写出色的代码只是第一步。要让这些代码真正发挥价值，被他人（或未来的自己）轻松使用、复用和分享，打包是不可或缺的环节。一个精心打包的 Python 项目，不仅能清晰地定义依赖，还能标准化安装流程，大大提升代码的易用性和专业度。

这篇秘籍将深入探讨 Python 打包的核心概念、常用工具和最佳实践，助你打造出更健壮、更受欢迎的 Python 项目。

一、为何要进行 Python 打包？

你可能会问，我直接分享.py文件不就行了吗？当然可以，但在以下场景中，你会发现打包的巨大优势：

  1. 代码复用与模块化： 将相关功能组织成一个包，便于在不同项目中导入和使用。
  2. 依赖管理： 明确声明项目所需的第三方库及其版本，避免“在我的机器上运行良好”的问题。
  3. 简化安装： 用户只需通过 pip install your_package 就能轻松安装你的代码及其所有依赖。
  4. 版本控制与发布： 方便地发布到 PyPI（Python Package Index）等平台，让全世界的 Python 开发者都能发现和使用你的作品。
  5. 命令行工具： 创建可执行的命令行脚本，提升用户体验。

二、核心概念与关键文件

Python 打包主要围绕几个核心概念和文件展开：

1. setuptools 与 distutils

早期 Python 使用 distutils 进行打包，但功能有限。现在，setuptools 是事实上的标准，它在 distutils 的基础上提供了更多高级功能，如声明依赖、处理入口点、生成轮子 (wheels) 等。几乎所有的现代 Python 包都依赖于 setuptools。

2. setup.py 文件：打包的“心脏”

setup.py 是传统 setuptools 打包的核心配置文件。它是一个 Python 脚本，通过调用 setuptools.setup() 函数来定义包的所有元数据和配置。

一个典型的 setup.py 包含以下关键信息：

  • name: 包的名称 (如 my-awesome-package)。
  • version: 包的版本号 (遵循 语义化版本规范)。
  • author, author_email: 作者信息。
  • description: 包的简短描述。
  • long_description: 包的详细描述，通常从 README.md 读取。
  • url: 项目主页或代码仓库地址。
  • packages: 要包含在包中的 Python 包（目录）列表。find_packages() 函数通常用于自动发现。
  • install_requires: 生产环境依赖的第三方库列表，例如 ['requests>=2.20.0', 'numpy']。
  • classifiers: 包的分类标签，帮助用户在 PyPI 上搜索。
  • python_requires: 包所需的 Python 版本范围 (如 '>3.6')。
  • entry_points: 定义命令行脚本或插件入口点。

setup.py 示例：

“`python
from setuptools import setup, find_packages

with open(‘README.md’, ‘r’, encoding=’utf-8′) as f:
long_description = f.read()

setup(
name=’my-awesome-package’,
version=’0.1.0′,
author=’Your Name’,
author_email=’[email protected]’,
description=’一个用于演示 Python 打包的超棒包’,
long_description=long_description,
long_description_content_type=’text/markdown’,
url=’https://github.com/yourusername/my-awesome-package’,
packages=find_packages(), # 自动发现当前目录下的所有Python包
install_requires=[
‘requests>=2.25.0’,
‘click>=7.0.0’,
],
classifiers=[
‘Programming Language :: Python :: 3’,
‘License :: OSI Approved :: MIT License’,
‘Operating System :: OS Independent’,
],
python_requires=’>=3.7′,
entry_points={
‘console_scripts’: [
‘mycli=my_awesome_package.cli:main’, # 定义命令行工具
],
},
)
“`

3. pyproject.toml：现代打包的新标准 (PEP 517/518)

随着 Python 生态的发展，pyproject.toml 逐渐成为定义项目构建系统和元数据的新标准。它使用 TOML 格式，旨在统一不同工具（如 setuptools, poetry, flit）的配置方式，并更好地分离构建依赖和运行时依赖。

虽然 setuptools 仍然在幕后工作，但你可以用 pyproject.toml 来配置它，取代大部分 setup.py 的内容，让配置更加声明式和统一。

pyproject.toml 示例 (使用 setuptools 作为构建后端):

“`toml
[build-system]
requires = [“setuptools>=61.0”]
build-backend = “setuptools.build_meta”

[project]
name = “my-awesome-package”
version = “0.1.0”
authors = [
{ name=”Your Name”, email=”[email protected]” },
]
description = “一个用于演示 Python 打包的超棒包”
readme = “README.md”
requires-python = “>=3.7”
classifiers = [
“Programming Language :: Python :: 3”,
“License :: OSI Approved :: MIT License”,
“Operating System :: OS Independent”,
]
dependencies = [
“requests>=2.25.0”,
“click>=7.0.0”,
]

[project.urls]
“Homepage” = “https://github.com/yourusername/my-awesome-package”
“Bug Tracker” = “https://github.com/yourusername/my-awesome-package/issues”

[project.scripts]
mycli = “my_awesome_package.cli:main”

[options] # setuptools特有的配置，如果使用pyproject.toml管理setuptools，可以放在此处

package_dir = {“” = “src”} # 如果你的包代码在 src/ 目录下

packages = [“my_awesome_package”] # 也可以手动指定

“`

4. MANIFEST.in：包含非代码文件

setup.py 或 pyproject.toml 默认只包含 Python 源文件。如果你的包需要包含数据文件（如配置文件、模板、图片等），你需要创建一个 MANIFEST.in 文件来指示 setuptools 包含这些非代码文件。

MANIFEST.in 示例：

include README.md LICENSE
recursive-include my_awesome_package/data *
global-exclude *.pyc *.bak *.swp

这会包含 README.md 和 LICENSE 文件，以及 my_awesome_package/data 目录下所有文件，并排除所有 .pyc, .bak, .swp 文件。

5. requirements.txt：开发环境依赖

尽管 install_requires 用于声明包的运行时依赖，但对于开发、测试和特定部署环境，通常会使用 requirements.txt。这个文件可以列出所有依赖，包括开发工具（如 pytest, flake8）和精确的版本锁定。

requirements.txt 示例：

requests==2.25.1
click==7.1.2
pytest==6.2.2
flake8==3.8.4

通常，install_requires 中的版本范围会比较宽松（如 >=2.25.0），而 requirements.txt 中的版本则会被精确锁定 (==2.25.1)，以确保环境的可复现性。

三、项目结构与最佳实践

一个良好的项目结构是成功打包的基础：

my-awesome-package/
├── my_awesome_package/ # 你的Python包目录 (重要!)
│ ├── __init__.py # 标识这是一个Python包
│ ├── module1.py
│ ├── module2.py
│ └── cli.py # 命令行工具的入口
├── tests/ # 单元测试
│ └── test_module1.py
├── README.md # 项目说明，markdown格式
├── LICENSE # 许可证文件
├── setup.py # 打包配置 (传统方式)
├── pyproject.toml # 打包配置 (现代方式，推荐)
├── MANIFEST.in # 非代码文件包含列表
├── requirements.txt # 开发/测试依赖
└── .gitignore # Git忽略文件

关键点：

  • 包目录与项目根目录分离： 将实际的 Python 模块代码放在一个与项目同名的子目录中（例如 my_awesome_package/my_awesome_package/），这样可以避免命名冲突，并确保在安装后能正确导入。
  • __init__.py： 即使是空文件，它也告诉 Python 解释器这是一个包目录。
  • README.md 和 LICENSE： 提供项目说明和许可信息，是任何开源项目的必备。

四、构建与发布你的包

一旦你的项目结构就绪，并且 setup.py 或 pyproject.toml 配置完毕，就可以开始构建和发布了。

1. 安装构建工具

bash
pip install setuptools wheel twine

  • setuptools：负责实际的打包逻辑。
  • wheel：用于生成 Wheel 格式的二进制分发包。
  • twine：安全地上传包到 PyPI。

2. 构建分发包

在项目根目录下运行：

“`bash
python setup.py sdist bdist_wheel

或者如果使用现代构建工具，直接

python -m build
“`

这会在项目根目录下生成一个 dist/ 目录，其中包含：

  • your_package-X.Y.Z.tar.gz (Source Distribution, sdist): 源码分发包，包含所有源代码、元数据和 MANIFEST.in 中指定的文件。它需要在安装时由 pip 重新构建。
  • your_package-X.Y.Z-py3-none-any.whl (Wheel Distribution, bdist_wheel): 预编译的二进制分发包，通常包含了所有 Python 字节码和必要的数据文件。Wheel 包安装速度更快，也更可靠，因为无需在用户机器上进行编译步骤。

3. 发布到 PyPI

PyPI (Python Package Index) 是 Python 社区官方的第三方包仓库。发布到 PyPI 意味着你的包可以被全世界的开发者通过 pip install 安装。

  1. 注册 PyPI 账号： 在 pypi.org 或 test.pypi.org (测试环境) 注册账号。
  2. 生成 API Token： 登录 PyPI 后，在账户设置中生成一个 API Token，它将用于 twine 进行认证。
  3. 上传包： 使用 twine 将 dist/ 目录下的所有分发包上传到 PyPI。

bash
twine upload dist/*

如果你想先测试上传过程，可以使用 TestPyPI：

bash
twine upload --repository testpypi dist/*

成功上传后，你的包就可以通过 pip install your_package 来安装了。

五、让你的包更易用：进阶技巧

1. 命令行入口点 (entry_points)

通过在 setup.py 或 pyproject.toml 的 entry_points 中定义 console_scripts，你可以让你的包在安装后自动生成一个可执行的命令行脚本。

例如，如果你的 my_awesome_package/cli.py 中有一个 main() 函数，你可以这样定义：

“`python

setup.py

entry_points={
‘console_scripts’: [
‘mycli=my_awesome_package.cli:main’,
],
},

pyproject.toml

[project.scripts]
mycli = “my_awesome_package.cli:main”
“`

安装后，用户可以直接在终端运行 mycli 命令。

2. 可选依赖 (extras_require)

有时你的包某些功能需要额外的依赖。你可以使用 extras_require 来定义这些可选依赖。

“`python

setup.py

extras_require={
‘pdf’: [‘reportlab’], # my_awesome_package[pdf] 会安装 reportlab
‘gui’: [‘PyQt5’], # my_awesome_package[gui] 会安装 PyQt5
},
“`

用户可以通过 pip install my-awesome-package[pdf] 来安装包含额外依赖的版本。

3. 虚拟环境 (venv / conda)

强调使用虚拟环境对于 Python 项目的易用性至关重要。虚拟环境能够隔离不同项目的依赖，避免版本冲突。

  • 创建虚拟环境： python -m venv .venv
  • 激活虚拟环境：
    • Windows: .venv\Scripts\activate
    • macOS/Linux: source .venv/bin/activate
  • 安装依赖： pip install -r requirements.txt

六、结语

Python 打包是软件工程实践中一个至关重要的环节。它将你的代码从单个脚本提升为可分发、可维护、可复用的软件产品。掌握 setuptools (或 pyproject.toml)、理解 sdist 与 wheel 的区别，并遵循良好的项目结构和发布流程，将大大提升你的 Python 代码的易用性和专业度。

现在，是时候将你的 Python 秘籍付诸实践，让你的代码在更广阔的舞台上闪耀光芒了！

滚动至顶部