一个演示如何制作包的示例
项目描述
这是一个演示如何为PyPI上的分发打包您的代码的示例。这是2022年秋季的一种可能的方法。我不会讨论其他可能的方法。打包生态系统很复杂。讨论所有选项只会让人困惑。
这个仓库并不打算展示一个典型项目中所有的配置。例如，它没有测试，没有文档，也不使用linters或类型检查器。这些都是好事，你应该研究它们，但这个仓库只关注如何打包项目进行分发，省略了这些其他的好事，这样我们就可以专注于打包。
这个仓库中的文件中包含注释，以帮助您了解每个部分的作用，这样您就可以创建自己的文件，包含您需要的部分和细节。
如何使用此仓库
您有想要分发的代码。这个仓库是您如何配置项目的模型。复制这里的文件，取您需要的部分，省略您不需要的部分。
决策
在开始之前，您需要做出一些决定。
项目名称
您必须为项目选择一个名称。在这个仓库中，它是“pkgsample”，但您将选择一个不同的名称。您的项目名称将发挥几个不同的作用：它是导入的模块名称，仓库名称，也是PyPI上的名称。任何您看到“pkgsample”的地方，您都将将其更改为您的项目名称。
由于项目名称将是PyPI上的名称，您在做出决定之前应该检查您想要的名称是否已经存在。在PyPI上搜索您的名称以查看是否已被占用。
版本号
您软件包的版本号位于src/pkgsample/__init__.py文件中的__version__变量处。您在制作发行版时将更新此值。有关最初使用.devN后缀的说明，请参阅下文“上传测试”中的备注。
可选功能
此布局将安装您的模块，以便人们可以导入它们。还包括一个额外可能性。
您可能需要安装一些命令，以便您的用户有新的命令行工具。这些部分用COMMANDS:标记。
在查看文件时注意观察，以了解如果不使用此选项可以省略什么。
项目详情
还有一些其他细节您可能想更改，但您不必这样做。
许可协议：此仓库使用Apache许可证，但您可以选择不同的许可证。
最低Python版本：此仓库需要Python 3.9或更高版本。也许您需要支持更多版本（选择更低的要求）或您希望使用一些较新的Python特性（选择更高的要求）。
文件中的注释，尤其是pyproject.toml文件，显示了您可以在哪里做出这些选择，并链接到可以帮助您的资源。
仓库中的内容
此仓库是制作可分发软件包的演示。您应检查这里的文件，决定哪些适合您，并将它们根据您的需求进行修改。
src/
此目录是您放置代码的地方。它应该有一个以您的项目命名的子目录，所有工作都放在该子目录中。
此仓库在src/pkgsample中包含一些小文件，只是为了构建和分发。您将删除该目录并为您自己的文件创建一个新子目录。
pyproject.toml
这是整个流程的核心。您将在该文件中进行很多更改。关于您项目的信息（名称、描述、作者等）以及许多其他细节都在这里指定。
README.rst
(此文件！) 您将用您自己的README.rst替换此文件，描述您的项目、如何安装它、如何使用它、如何获取帮助、变更日志等。
零散物品
.gitignore是一个标准的git文件，用于防止不感兴趣的文件被存储在git中。
LICENSE.txt是您选择的许可证的文本。
这里的一些文件对于分发项目不是必需的，但对我在这仓库中的工作很有用，您也可能觉得有用。
Makefile：组织在仓库中工作所需的命令。此README中显示的命令也在Makefile中作为目标提供。您可以使用make help来查看目标及其功能。
.editorconfig：指定简单的格式化规则，您的编辑器可以强制执行。
准备您的环境
为自己获取一个Python 3.9环境。使用virtualenv是推荐的，但不是必需的。
您需要一些工具来构建可安装的文件（称为发行版）。它们在dev-requirements.txt文件中指定。使用pip安装它们。
python -m pip install -r dev-requirements.txt # or: make tools
进行更改
如果您准备好了，您可以对项目进行所有更改。如果您愿意，您也可以跳过此步骤，使用pkgsample仓库的当前状态尝试一些后续步骤，看看会发生什么。
从此仓库复制文件，然后进行所有更改
将您的项目源文件放在src/目录中。确保删除所有pkgsample代码的痕迹。
使用所有选择的信息更新pyproject.toml文件。完成后，“pkgsample”一词不应在该文件中任何地方出现。
完全重写README.rst文件，包括您项目的描述和详细信息。
本地安装
您可以通过在当前环境中作为“可编辑安装”安装项目来对项目进行一些初步测试。
python -m pip install -e .
这将使您的项目能够在当前Python环境中导入，您可以尝试运行代码。以下是一个使用pkgsample代码的示例
% python Python 3.9.15 (main, Oct 24 2022, 17:23:01) >>> from pkgsample.add import add >>> add(17, 42) 59
如果您正在创建命令行命令，现在就可以运行它们了
% pkgsample_add 1 2 3 4 5 Your numbers are: [1, 2, 3, 4, 5] They add up to: 15
顺便说一句，这种可编辑的安装方式也是进行开发的好方法，因为Python将直接从您工作树中编辑的文件导入，所以修改代码并查看其效果非常快。
一旦您这样做，您将开始在代码附近看到 __pycache__ 目录。这些目录包含编译的字节码文件，名为 something.something.pyc。您可以安全地删除这些文件，.gitignore 文件将防止它们被存储在 git 中。
制作发行版
您现在已经准备好制作可安装的工件，称为发行版。
创建文件
这些命令将创建文件并检查它们的正确性
python -m build --sdist --wheel
python -m twine check dist/*
# or: make clean dist
如果一切顺利，现在您将有一个包含两个文件的 dist/ 目录
pkgsample-0.1.0-py3-none-any.whl pkgsample-0.1.0.tar.gz
.whl 文件是“轮”。这是发行版的首选文件格式。.tar.gz 文件是“源发行版”（sdist），它也易于提供，并且某些用户更喜欢。
如果出现问题，twine check 命令将报告错误以修复。查看文件内容可能会有所帮助，或者您只是出于好奇。您可以检查内容
% tar tvfz dist/*.tar.gz drwxr-xr-x 0 user group 0 Nov 15 06:25 pkgsample-0.1.0/ -rw-r--r-- 0 user group 10177 Nov 15 05:07 pkgsample-0.1.0/LICENSE.txt -rw-r--r-- 0 user group 19222 Nov 15 06:25 pkgsample-0.1.0/PKG-INFO -rw-r--r-- 0 user group 6866 Nov 15 06:24 pkgsample-0.1.0/README.rst -rw-r--r-- 0 user group 2860 Nov 15 05:28 pkgsample-0.1.0/pyproject.toml -rw-r--r-- 0 user group 38 Nov 15 06:25 pkgsample-0.1.0/setup.cfg drwxr-xr-x 0 user group 0 Nov 15 06:25 pkgsample-0.1.0/src/ drwxr-xr-x 0 user group 0 Nov 15 06:25 pkgsample-0.1.0/src/pkgsample/ -rw-r--r-- 0 user group 246 Nov 15 06:25 pkgsample-0.1.0/src/pkgsample/__init__.py -rw-r--r-- 0 user group 166 Nov 15 05:07 pkgsample-0.1.0/src/pkgsample/add.py -rw-r--r-- 0 user group 410 Nov 15 05:07 pkgsample-0.1.0/src/pkgsample/add_cli.py drwxr-xr-x 0 user group 0 Nov 15 06:25 pkgsample-0.1.0/src/pkgsample.egg-info/ -rw-r--r-- 0 user group 19222 Nov 15 06:25 pkgsample-0.1.0/src/pkgsample.egg-info/PKG-INFO -rw-r--r-- 0 user group 333 Nov 15 06:25 pkgsample-0.1.0/src/pkgsample.egg-info/SOURCES.txt -rw-r--r-- 0 user group 1 Nov 15 06:25 pkgsample-0.1.0/src/pkgsample.egg-info/dependency_links.txt -rw-r--r-- 0 user group 113 Nov 15 06:25 pkgsample-0.1.0/src/pkgsample.egg-info/entry_points.txt -rw-r--r-- 0 user group 5 Nov 15 06:25 pkgsample-0.1.0/src/pkgsample.egg-info/requires.txt -rw-r--r-- 0 user group 10 Nov 15 06:25 pkgsample-0.1.0/src/pkgsample.egg-info/top_level.txt
发行版包含所有文件，以及包装过程中创建的新支持文件。
测试发行版
您可以测试安装发行版文件。创建一个新的虚拟环境，并直接从其中一个文件安装
python -m pip install /path/to/pkgsample-0.1.0-py3-none-any.whl
现在您应该能够导入并运行您的模块。
清理
dist/ 和 build/ 目录是此过程的组成部分。它们不会被存储在 git 中，并且您可以在想要清理时随时删除它们。Makefile 包含一个目标，可以为您执行此操作
make clean
上传到 PyPI
制作完整可安装包的最终一步是将您的发行版上传到 Python Package Index, PyPI。这是 pip 寻找要安装的包的地方。
（如果您一直在使用未更改的 pkgsample 存储库尝试这些步骤，您将无法这样做，因为您无法上传新的 pkgsample 发行版。）
实际上有两个 PyPI 实例：一个是真正的 https://pypi.ac.cn，还有一个测试实例 https://test.pypi.org/，您可以在将发行版实际发布之前尝试它们。
创建账户
在 https://pypi.ac.cn/account/register/ 和 https://test.pypi.org/account/register/ 上注册两个 PyPI 账户。PyPI 有许多选项来保护您的账户安全，但一个简单的用户名和密码就可以开始。
上传测试版
将您的发行版上传到 test.pypi.org。twine 工具执行此操作
python -m twine upload --verbose --repository testpypi dist/* # or: make clean dist test_pypi
您将需要输入用户名和密码，进度将显示，最后您将获得一个网址，可以查看您发布的包页面将看起来像什么
% python -m twine upload --verbose --repository testpypi dist/*
Uploading distributions to https://test.pypi.org/legacy/
INFO dist/pkgsample-0.1.1.dev0-py3-none-any.whl (10.4 KB)
INFO dist/pkgsample-0.1.1.dev0.tar.gz (10.6 KB)
INFO Querying keyring for username
Enter your username: your_username
INFO Querying keyring for password
Enter your password:
INFO username: your_username
INFO password: <hidden>
Uploading pkgsample-0.1.1.dev0-py3-none-any.whl
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 26.6/26.6 kB • 00:00 • 13.1 MB/s
INFO Response from https://test.pypi.org/legacy/:
200 OK
Uploading pkgsample-0.1.1.dev0.tar.gz
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 26.7/26.7 kB • 00:00 • 27.1 MB/s
INFO Response from https://test.pypi.org/legacy/:
200 OK
View at:
https://test.pypi.org/project/pkgsample/0.1.1.dev0/
注意：一旦您将文件上传到 PyPI（即使是测试服务器），您就不能修复问题并重新上传。您必须以某种方式增加版本号，才能上传更新的文件。在进行包装的第一轮测试时，使用 .devN 后缀是一个好主意，同时您在努力使其正确：__version__ = "0.1.0.dev0"。
检查您的页面。确保一切看起来如您所愿，包括左侧侧栏中的元数据以及README的格式。如果需要修复某些内容，请增加版本号中的.devN后缀，重新制作发行版，并重新上传。
实际上传
一旦您的软件包在测试PyPI服务器上看起来正确，您就可以实际上传您的软件包了！
将版本号修正以去除.devN后缀，然后制作新的发行版，并将它们上传到PyPI。
rm -fr build/ dist/ src/*.egg-info python -m build --sdist --wheel python -m twine check dist/* python -m twine upload --verbose dist/* # or: make clean dist pypi
您的软件包现在可用
现在任何人都可以使用pip安装您的软件包
pip install pkgsample
你做到了！
下载文件
下载适合您平台的文件。如果您不确定选择哪个，请了解更多关于安装软件包的信息。
