当前位置：首页 > news >正文

打包Python项目

news 2025/7/2 15:42:20

打包Python项目

本教程将指导您如何打包一个简单的Python项目。它将向您展示如何添加必要的文件和结构来创建包，如何构建包，以及如何将其上传到Python包索引（PyPI）。

尖端

如果您在运行本教程中的命令时遇到问题，请复制命令及其输出，然后在packaging-problems存储库上打开一个issue， GitHub.我们会尽力帮助你！

有些命令需要较新版本的pip，因此，确保您安装了最新版本：

Unix/macOS Windows

py -m pip install --upgrade pip

一个简单的项目

本教程使用一个名为 example_package_YOUR_USERNAME_HERE.如果您的用户名是me，则包将是example_package_me;这确保您有一个唯一的与其他人上传的软件包不冲突的软件包名称遵循本教程。我们建议按照本教程的原样使用此在打包你自己的项目之前。

在本地创建以下文件结构：

packaging_tutorial/
└── src/└── example_package_YOUR_USERNAME_HERE/├── __init__.py└── example.py

包含Python文件的目录应该与项目名称匹配。这简化了配置，并且对于安装软件包的用户来说更加明显。

__init__.py建议将目录作为常规包导入，即使像我们在本教程中的情况那样，该文件是空的[1]。

example.py是包中的一个模块的示例，包含逻辑（函数、类、常量等）你的包裹。打开该文件并输入以下内容：

def add_one(number):return number + 1

如果你不熟悉Python 导入软件包，请花几分钟时间阅读 Python包和模块的文档。

创建此结构后，您需要运行此 packaging_tutorial目录中的教程。

创建包文件

现在将添加用于准备项目以进行分发的文件。完成后，项目结构将如下所示：

packaging_tutorial/
├── LICENSE
├── pyproject.toml
├── README.md
├── src/
│   └── example_package_YOUR_USERNAME_HERE/
│       ├── __init__.py
│       └── example.py
└── tests/

创建测试目录

tests/是测试文件的占位符。先把它空着。

选择构建后端

像pip和build这样的工具实际上并不转换你的源代码进入一个分发包（像一个轮子）; 该作业由构建后端执行。构建后端确定如何您的项目将指定其配置，包括元数据（信息例如，PyPI上显示的名称和标记）和输入文件。构建后端具有不同级别的功能，例如是否支持构建扩展模块，以及你应该选择一个适合你的需要和喜好。

您可以从许多后端中进行选择;本教程默认使用Hatchling，但它与Setuptools的工作方式相同， Flit、PDM和其他支持[project] 元数据表。

注意

一些构建后端是提供命令行的大型工具的一部分具有项目初始化和版本等附加功能的接口管理，以及构建，上传和安装软件包。这教程使用独立工作的单一用途工具。

pyproject.toml告诉构建前端工具，如pip和构建用于项目的后端。下面是一些常见构建后端的示例，但请检查后端自己的文档的双曲余切值。

hatchling

[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"

setuptools 微片 PDM

requires键是构建包所需的包列表。前端应该在构建包时自动安装它们。前端通常在隔离的环境中运行构建，因此忽略依赖项可能会导致构建时错误。这应该总是包括你的后端的包，并可能有其他的构建时间个依赖项

build-backend键是前端将使用的Python对象的名称来执行构建。

这两个值都将由构建的文档提供后端，或由其命令行界面生成。应该没有必要您可以自定义这些设置。

构建工具的其他配置将在tool部分中或者在构建工具定义的特殊文件中。为例如，当使用pyproject.toml作为构建后端时，可以添加到setuptools或setup.py文件中，并指定 setup.cfg在你的构建中允许工具定位和使用这些的自动

配置元数据

打开pyproject.toml，输入以下内容。更改name 以包含您的用户名;这可确保您拥有唯一的与其他人上传的软件包不冲突的软件包名称遵循本教程。

[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [{ name="Example Author", email="author@example.com" },
]
description = "A small example package"
readme = "README.md"
requires-python = ">=3.8"
classifiers = ["Programming Language :: Python :: 3","License :: OSI Approved :: MIT License","Operating System :: OS Independent",
][project.urls]
Homepage = "https://github.com/pypa/sampleproject"
Issues = "https://github.com/pypa/sampleproject/issues"

name是您的软件包的分发名称。它可以是任何名称，只要它只包含字母、数字、.、_和-。它还不能在PyPI上使用。请务必更新此与您的本教程的用户名，因为这可以确保您不会尝试上传与已存在的包同名的包。
version是包的版本号。(Some构建后端允许它成为以其他方式指定，例如从文件或Git标签。
authors用于标识包的作者;您指定一个名称每个作者的电子邮件。您也可以在同一个列表中列出maintainers 格式.
description是一个简短的，一句话的总结包。
readme是一个文件的路径，该文件包含包.这显示在PyPI上的包详细信息页面上。在这种情况下，描述从README.md加载（这是一个共同模式）。中还描述了一种更高级的表格形式， pyproject.toml guide.
requires-python给出了您的项目像pip这样的安装程序将通过旧版本的包，直到找到一个具有匹配Python版本的包。
classifiers给出索引和pip一些额外的元数据关于你的包裹在这种情况下，该包仅与Python兼容 3，根据MIT许可证授权，并且独立于操作系统。你应该总是至少包括你的包工作在哪个版本的Python上，您的软件包在哪个许可证下可用，以及哪些操作系统有关分类器的完整列表，请参见 https：//pypi.org/classifiers/.
urls允许您列出任何数量的额外链接以在PyPI上显示。一般来说，这可能是源代码，文档，问题跟踪器等。

有关详细信息，请参阅pyproject.toml指南在这些和其他领域，可以定义在[project] 表.其他常用字段为keywords，以提高可扩展性

创建README.md

打开README.md，输入以下内容。您可以自定义此如果你愿意的话

# Example PackageThis is a simple example package. You can use
[GitHub-flavored Markdown](https://guides.github.com/features/mastering-markdown/)
to write your content.

创建许可证

上传到Python包索引的每个包都必须包含一张执照。这会告诉安装您的软件包的用户，可以使用你的包裹。有关选择许可证的帮助，请参见 https：//sealicense.com/.选择许可证后，打开 LICENSE并输入许可证文本。例如，如果您选择了 MIT许可证：

Copyright (c) 2018 The Python Packaging AuthorityPermission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.

大多数构建后端会自动在包中包含许可证文件。看到你 backend的文档了解更多详情。

包括其他文件

上面列出的文件将自动包含在您的源分布如果你想包括其他文件，请参阅构建后端的文档。

正在生成分发存档

下一步是生成分发包为了包裹这些是上传到Python的存档，软件包索引，可以通过pip安装。

确保你安装了最新版本的PyPA

py -m pip install --upgrade build

尖端

如果在安装这些组件时遇到问题，请参阅安装软件包教程。

现在从pyproject.toml所在的同一目录运行此命令：

py -m build

此命令应输出大量的文本，一旦完成应生成两个 dist目录中的文件：

dist/
├── example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
└── example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz

tar.gz文件是一个源代码发行版而.whl文件是一个构建的发行版。较新的pip版本优先安装已构建的发行版，但如果需要的话，回退到源代码分发。你应该总是上传一个源发行版，并为您的项目所在的平台提供构建的发行版。兼容。在这种情况下，我们的示例包与Python兼容，任何平台，因此只需要一个构建的发行版。

分发档案

最后，是时候把你的包上传到Python包索引了！

你需要做的第一件事是在TestPyPI上注册一个帐户，是用于测试的包装索引的单独实例，实验这对于像本教程这样的东西来说是很好的，一定要上传到真实的索引。要注册帐户，请转到 https：//test.pypi.org/account/register/并完成该页面上的步骤。您还需要验证您的电子邮件地址，然后才能上传任何包裹。有关更多详细信息，请参阅使用TestPyPI。

要安全地上传项目，您创建一个在 https：//test.pypi.org/manage/account/#api-tokens，将“范围”设置为“整个账户”。在复制并保存令牌之前，请不要关闭页面-您再也见不到那个信物了

现在您已注册，您可以使用GoogleChrome上载分销包。你需要安装Twine：

py -m pip install --upgrade twine

安装完成后，运行Twine上传dist下的所有归档文件：

py -m twine upload --repository testpypi dist/*

请输入用户名和密码对于用户名，使用__token__。对于密码，使用令牌值，包括 pypi-前缀。

命令完成后，您应该看到类似于以下内容的输出：

Uploading distributions to https://test.pypi.org/legacy/
Enter your username: __token__
Uploading example_package_YOUR_USERNAME_HERE-0.0.1-py3-none-any.whl
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 8.2/8.2 kB • 00:01 • ?
Uploading example_package_YOUR_USERNAME_HERE-0.0.1.tar.gz
100% ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━ 6.8/6.8 kB • 00:00 • ?

上传后，您的包应该可以在TestPyPI上查看;例如： https://test.pypi.org/project/example_package_YOUR_USERNAME_HERE.

安装新上传的软件包

您可以使用pip安装您的软件包并验证它是否工作。创建虚拟环境然后从TestPyPI安装你的包：

py -m pip install --index-url https://test.pypi.org/simple/ --no-deps example-package-YOUR-USERNAME-HERE

请确保在软件包名称中指定您的用户名！

pip应该安装来自TestPyPI的包，输出应该是就像这样：

Collecting example-package-YOUR-USERNAME-HEREDownloading https://test-files.pythonhosted.org/packages/.../example_package_YOUR_USERNAME_HERE_0.0.1-py3-none-any.whl
Installing collected packages: example_package_YOUR_USERNAME_HERE
Successfully installed example_package_YOUR_USERNAME_HERE-0.0.1

注意

本例使用--index-url标志指定TestPyPI，而不是 Live PyPI。此外，它还指定了--no-deps。由于TestPyPI不有与PyPI相同的包，尝试安装依赖项可能会失败或安装一些意外的东西。虽然我们的示例包没有任何依赖项，这是一个很好的做法，以避免使用TestPyPI时安装依赖项。

您可以通过导入软件包来测试它是否正确安装。确保你仍然在虚拟环境中，然后运行Python：

py

然后导入包：

from example_package_YOUR_USERNAME_HERE import example

example.add_one(2)
3

后续步骤

恭喜你，你已经打包并发布了一个Python项目！ ✨ 🍰 ✨

请记住，本教程向您展示了如何将包上传到Test PyPI，它不是永久存储。测试系统偶尔会删除包和账户。最好使用TestPyPI进行测试和实验就像这个教程。

当您准备好将一个真实的包上传到Python包索引时，您可以执行与本教程中相同的操作，但使用这些重要的差异：

为您的包裹选择一个难忘且独特的名称。你不必附加您的用户名，就像您在教程中所做的那样，但您不能使用现有的名称。
在https：//pypi.org上注册一个帐户-请注意，这是两个独立的服务器和来自测试服务器的登录详细信息不与主服务器
使用twine upload dist/*上传包并输入凭据你在真实的PyPI上注册的账户既然你上传了在生产环境中，您不需要指定--repository; 默认情况下，包将上传到https：//pypi.org/。
使用python3 -m pip install [your-package]从真实的PyPI安装您的软件包。

在这一点上，如果你想关于打包Python库的信息，请点击这里。你可以做的一些事情：

阅读有关您选择的构建后端的高级配置： Hatchling, setuptools, Flit, PDM.。
查看本网站上的指南，了解更多高级实用信息或讨论了解有关特定主题的解释和背景。
考虑打包工具，这些工具提供单个命令行界面，项目管理和包装，如hatch, flit, pdm, 和poetry。

注意到

[1]

从技术上讲，你也可以创建没有__init__.py文件的Python包，但它们被称为命名空间包并将其视为高级主题（本教程中未涉及）。如果您刚刚开始使用Python打包，建议您坚持使用常规包和__init__.py（即使文件是空的）。