摘要：在 Python 的世界里，你是否曾遇到这样的窘境：辛辛苦苦写好的工具函数，在 A 项目里用完，到了 B 项目又要重新复制粘贴一遍？更糟糕的是，当你想修复一个 bug 或更新一个功能时，不得不逐一打开所有项目，手动修改每一处代码。这种“复制-粘贴”的开发模式，
从零开始打造你的第一个专业级代码包
在 Python 的世界里，你是否曾遇到这样的窘境：辛辛苦苦写好的工具函数，在 A 项目里用完，到了 B 项目又要重新复制粘贴一遍？更糟糕的是，当你想修复一个 bug 或更新一个功能时，不得不逐一打开所有项目，手动修改每一处代码。这种“复制-粘贴”的开发模式，就像是在用手工打造汽车，效率低下，错误频发。
今天，我将向你揭示一个真正的“秘密武器”——Python 代码打包（Packaging）。这不仅仅是把文件简单地打包成一个压缩包那么简单，它更是一种将你的代码从“一次性脚本”提升为“可复用、可分发、可版本化”的专业级工具的艺术。掌握了这门艺术，你的项目将瞬间提升一个档次，从个人“作坊式”开发迈向工业化、专业化协作。
我第一次尝试打包时，也曾被setup.py、pyproject.toml这些陌生的文件搞得一头雾水，在发布到 PyPI（Python Package Index）的路上迷失了方向。但经过反复的摸索和实践，我意识到，Python 打包并非什么高深的魔法，它不过是一系列清晰、简单的步骤。一旦你掌握了这些步骤，你不仅能拥有自己的代码包，更能自信地与世界分享你的成果。
本文将手把手带你完成从零到一的整个过程。请准备好，我们即将踏上这段从“脚本小子”到“软件作者”的蜕变之旅。
很多开发者习惯于在不同项目间复制粘贴工具代码，我曾经也是其中一员。这种做法在项目初期似乎很方便，但随着项目的增长，它带来的问题会像滚雪球一样越来越大：
版本管理混乱：当你的代码在多个项目中以不同版本存在时，版本不匹配和 bug 修复会变成一场噩梦。你无法确定哪个项目正在使用哪个版本的代码，更不用说统一更新了。代码复用效率低下：你需要花费大量时间在文件系统里寻找并复制需要的代码，而不是简单地通过一个干净的import语句来调用。团队协作障碍：当团队成员需要共享代码时，你不得不依赖于邮件、即时通讯或共享文件夹，这不仅低效，而且难以追踪代码的最新状态。打包，正是解决这些问题的最佳方案。它将你的代码封装成一个正式的可分发格式，让你可以：
实现清晰的导入：你可以用import my_utils这样优雅的方式来调用你的代码，而不是通过复杂的相对路径或绝对路径。获得版本控制和升级路径：你的代码包有了明确的版本号，你可以轻松地发布新版本、管理旧版本，并为其他使用者提供清晰的升级路径。促进轻松协作和项目复用：任何项目都可以通过简单的pip install命令来安装你的代码包，实现无缝的代码共享和复用。可以这么说，你越早学会打包，你的项目就越早迈向专业化。打包将一次性脚本转化为可靠的工具，这才是真正的质变。
一个专业的 Python 代码包，首先需要一个干净、合理的项目结构。这就像建造房屋前要打好地基一样重要。我曾因为项目结构不规范而在测试时遇到奇怪的导入问题，这个教训让我意识到，好的结构能让你少走很多弯路。
以下是一个最小但完整的、符合现代实践的项目结构示例：
my_package/│├── src/│ └── my_package/│ ├── __init__.py│ └── core.py├── tests/│ └── test_core.py├── pyproject.toml└── README.md这个结构的核心要点是：
src/目录：这是你的实际代码所在的目录。采用src/布局可以有效避免在测试时出现导入混乱的问题。tests/目录：专门用于存放你的所有测试文件。将测试代码与源文件分开，有助于保持项目的整洁。pyproject.toml文件：这是你代码包的配置核心。现代 Python 打包已经放弃了老旧的setup.py，转而使用这个更规范、更强大的配置文件。README.md文件：项目的说明文件，用于向用户介绍你的代码包的功能和用法。既然项目结构已经搭建好了，我们来填充一些简单的代码，让这个包变得“活”起来。
首先，我们在src/my_package/目录下创建一个名为core.py的文件，并写入一个简单的问候函数：
# src/my_package/core.pydef greet(name: str) -> str: return f"Hello, {name}! Welcome to my_package."接下来，为了让这个函数能够被外部导入，我们需要在src/my_package/目录下的__init__.py文件中进行暴露：
# src/my_package/__init__.pyfrom .core import greet__init__.py的作用是告诉 Python，这个目录是一个包，并且在这里可以定义包的公开 API。通过这行代码，你就可以在安装你的包后，直接使用from my_package import greet来调用这个函数了。
当你的包安装完成后，你就可以在任何地方像这样使用它：
>>> from my_package import greet>>> greet("Alice")'Hello, Alice! Welcome to my_package.'恭喜你，你的第一个可用的包函数已经诞生了。
正如前面提到的，pyproject.toml是现代 Python 打包的“心脏”。它的出现，标志着 Python 打包进入了一个更规范、更易于管理的时代，彻底取代了过去复杂且充满陷阱的setup.py。
一个基础的pyproject.toml文件通常包含以下关键信息：
[build-system]requires = ["setuptools>=61.0"]build-backend = "setuptools.build_meta"[project]name = "my-package"version = "0.1.0"description = "A demo package for learning packaging"authors = [ { name="Your Name", email="you@example.com" }]dependencies =让我们来逐一解读这几个配置项的作用：
[build-system]：这一部分定义了用于构建你的代码包的工具。它告诉 Python 构建系统，你的项目需要setuptools来处理打包工作。[project]：这是存放所有包元数据的地方。name：你的包的名称，通常使用小写字母和连字符。version：你的包的版本号。遵循版本规范对于日后的维护至关重要。description：一个简短的描述，概括你的包的功能。authors：你的姓名和邮箱。dependencies：你的包所依赖的其他库。这些依赖会在安装你的包时自动被安装，确保所有功能都能正常运行。没有这个pyproject.toml文件，你的包将无法被正确构建和分发。
有了项目结构和配置文件，现在是时候将你的代码“打包”成一个可分发的格式了。
首先，你需要安装一个名为build的工具：
pip install build然后，在你的项目根目录下运行构建命令：
python -m build这个命令会执行以下操作：
它会根据pyproject.toml文件中的配置，自动处理所有依赖关系和打包过程。在项目根目录下创建一个名为dist/的新目录。在dist/目录中生成两个关键文件：一个.tar.gz文件（源码包）和一个.whl文件（二进制分发包）。.whl文件（也称为“wheel”）是 Python 分发的标准格式，它是一种预编译的包，可以更快地被安装。此时此刻，你手中的.whl文件，已经不再是简单的代码文件，而是一个真正的、可供他人安装和使用的“产品”了。
在将你的包发布到公共平台之前，至关重要的一步是本地安装测试。这可以确保你的包能够被正确安装，并且所有功能都能按预期工作，从而避免在发布后才发现问题。
你可以使用pip直接从本地的dist/目录安装你的.whl文件：
pip install dist/my_package-0.1.0-py3-none-any.whl安装成功后，你可以在任何一个新的 Python 项目中进行测试：
from my_package import greetprint(greet("Developer"))如果这段代码能够顺利运行并输出正确的结果，那么你的包已经可以被成功安装，并为接下来的公开发布做好了准备。
一个真正专业的代码包，离不开自动化测试。测试不仅仅是用来发现 bug 的，它更是一种信心的体现。有了完善的测试，你可以在每次修改代码后，快速验证你的改动没有破坏现有功能，这对于维护一个长期项目至关重要。
我们将使用pytest这个流行的测试框架来为我们的包添加测试。
首先，在tests/目录下创建test_core.py文件：
# tests/test_core.pyfrom my_package import greetdef test_greet: assert greet("Dev") == "Hello, Dev! Welcome to my_package."这段代码很简单，它断言（assert）greet("Dev")函数调用的结果是否与我们期望的字符串完全一致。
接下来，安装pytest并运行测试：
pip install pytestpytest如果测试通过，你将看到绿色的通过信息，这代表你的代码是健壮且可靠的。如果测试失败，它会提示你哪里出了问题，让你在发布之前就能修复 bug。
现在，我们终于来到了最令人兴奋的一步：将你的代码包发布到 PyPI，让全世界的 Python 开发者都能安装和使用它。
这是一个看似复杂但其实很简单的过程。
创建账户：在 PyPI 官方网站（https://pypi.org/）上注册一个账户。安装twine：twine是专门用于将包安全、可靠地上传到 PyPI 的工具。pip install twine上传你的包：使用twine命令，将dist/目录下的所有构建文件上传到 PyPI。twine upload dist/*twine会提示你输入 PyPI 的用户名和密码（或者 API 令牌），然后它会自动完成上传工作。
一旦上传成功，你的包就正式上线了。任何开发者现在都可以通过简单的命令来安装你的包：
pip install my-package这感觉就像是看着你亲手打造的作品，被更多人所看见和使用，那种成就感是无与伦比的。
一个好的项目，不会止步于一个版本。随着功能的增加和 bug 的修复，你的代码包会持续进化。而版本管理，正是这种进化的关键。
在你的pyproject.toml文件中，你需要更新版本号来标记每一次的变动：
[project]version = "0.2.0"版本号的更新通常遵循一定的规范：
0.1.1：通常用于小型的 bug 修复。0.2.0：用于新增了功能，但没有引入重大改变。1.0.0：用于发布一个稳定且功能完整的版本。其中一个非常酷的功能是为你的包添加**命令行接口（CLI）**支持。你可以使用click这样的库，轻松地为你的包添加一个可以直接在终端运行的命令。
首先，创建一个用于处理命令行逻辑的文件，比如src/my_package/cli.py：
# src/my_package/cli.pyimport clickfrom .core import greet@click.command@click.argument("name")def main(name): print(greet(name))if __name__ == "__main__": main然后，在pyproject.toml的[project]部分添加一个[project.scripts]配置项：
[project.scripts]greet = "my_package.cli:main"这个配置项告诉安装程序，当你的包被安装时，要创建一个名为greet的命令行命令，它会指向my_package.cli模块中的main函数。
现在，你的包不仅是一个代码库，它还是一个可以独立运行的工具：
greet Alice# 输出: Hello, Alice! Welcome to my_package.学习 Python 打包，就像是揭开了魔术的幕布。一开始，你可能会觉得这一切都充满了神秘感——pyproject.toml、轮子文件、构建流程、PyPI 等等。但当你亲手走过每一个步骤后，你会发现，这不过是一系列简单而有序的操作。
掌握这些步骤，你将从一个只知道写脚本的“代码修补匠”，成长为一个真正的“软件作者”。这种感觉，远胜过任何一时的成就感。
我向你发起一个挑战：找一个你之前写过的旧的工具脚本，按照本文的步骤，把它封装成一个完整的、可发布的 Python 包，并尝试上传到 PyPI。
当你最终在终端输入pip install your-package，并看到你的心血在全球范围内变得可用时，那种由衷的自豪感，将是学习路上最美的回报。
来源：高效码农
