打包Python项目¶

Packaging Python Projects

中文

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

小技巧

如果你在运行本教程中的命令时遇到问题，请复制命令及其输出，然后在 GitHub 上的 packaging-problems 仓库提交问题，我们会尽力提供帮助！

一些命令需要较新的 pip 版本，因此请首先确保你安装了最新版本：

Unix/macOS

python3 -m pip install --upgrade pip

Windows

py -m pip install --upgrade pip

英文

This tutorial walks you through how to package a simple Python project. It will show you how to add the necessary files and structure to create the package, how to build the package, and how to upload it to the Python Package Index (PyPI).

小技巧

If you have trouble running the commands in this tutorial, please copy the command and its output, then open an issue on the packaging-problems repository on GitHub. We'll do our best to help you!

Some of the commands require a newer version of pip, so start by making sure you have the latest version installed:

Unix/macOS

python3 -m pip install --upgrade pip

Windows

py -m pip install --upgrade pip

一个简单的项目¶

A simple project

中文

本教程使用一个简单的项目，名为 example_package_YOUR_USERNAME_HERE。如果你的用户名是 me，那么包名将是 example_package_me；这样可以确保你的包名唯一，不会与其他人上传的包发生冲突。我们建议在打包你自己的项目之前，先按照本教程使用该项目进行操作。

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

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

包含 Python 文件的目录应该与项目名称一致。这样做可以简化配置，并使得用户在安装包时更易于理解。

建议创建文件 __init__.py，因为该文件的存在允许用户将目录作为常规包导入，即使在本教程中， __init__.py 文件是空的。[1]

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

def add_one(number):
    return number + 1

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

创建好这个结构后，你需要在 packaging_tutorial 目录中运行本教程中的所有命令。

英文

This tutorial uses a simple project named example_package_YOUR_USERNAME_HERE. If your username is me, then the package would be example_package_me; this ensures that you have a unique package name that doesn't conflict with packages uploaded by other people following this tutorial. We recommend following this tutorial as-is using this project, before packaging your own project.

Create the following file structure locally:

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

The directory containing the Python files should match the project name. This simplifies the configuration and is more obvious to users who install the package.

Creating the file __init__.py is recommended because the existence of an __init__.py file allows users to import the directory as a regular package, even if (as is the case in this tutorial) __init__.py is empty. [1]

example.py is an example of a module within the package that could contain the logic (functions, classes, constants, etc.) of your package. Open that file and enter the following content:

def add_one(number):
    return number + 1

If you are unfamiliar with Python's modules and import packages, take a few minutes to read over the Python documentation for packages and modules.

Once you create this structure, you'll want to run all of the commands in this tutorial within the packaging_tutorial directory.

创建包文件¶

Creating the package files

中文

现在，你将添加一些文件来为项目的分发做准备。完成后，项目结构将如下所示：

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

英文

You will now add files that are used to prepare the project for distribution. When you're done, the project structure will look like this:

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

创建测试目录¶

Creating a test directory

中文

tests/ 是测试文件的占位符。暂时将其留空。

英文

tests/ is a placeholder for test files. Leave it empty for now.

创建 README.md¶

Creating README.md

中文

打开 README.md 文件并输入以下内容。你也可以根据需要进行自定义。

# Example Package

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

该 README.md 文件将作为你的包的详细描述，并在 PyPI 上显示。你可以在其中添加任何有用的信息，比如安装说明、使用示例、贡献指南等。

英文

Open README.md and enter the following content. You can customize this if you'd like.

# Example Package

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

创建 LICENSE¶

Creating a LICENSE

中文

对于上传到 Python 软件包索引的每个软件包来说，包含许可证非常重要。这会告诉安装软件包的用户他们可以使用软件包的条款。有关选择许可证的帮助，请参阅 https://choosealicense.com/ 。选择许可证后，打开 LICENSE 并输入许可证文本。例如，如果您选择了 MIT 许可证：

Copyright (c) 2018 The Python Packaging Authority

Permission 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.

大多数构建后端都会自动在包中包含许可证文件。请参阅后端的文档以了解更多详细信息。

英文

It's important for every package uploaded to the Python Package Index to include a license. This tells users who install your package the terms under which they can use your package. For help picking a license, see https://choosealicense.com/. Once you have chosen a license, open LICENSE and enter the license text. For example, if you had chosen the MIT license:

Copyright (c) 2018 The Python Packaging Authority

Permission 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.

Most build backends automatically include license files in packages. See your backend's documentation for more details.

包括其他文件¶

Including other files

中文

上述列出的文件将会自动包含在你的源代码分发中。如果你想包含额外的文件，请参考你所使用的构建后端的文档。

英文

The files listed above will be included automatically in your source distribution. If you want to include additional files, see the documentation for your build backend.

后续步骤¶

Next steps

中文

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

请记住，本教程展示的是如何将你的包上传到 Test PyPI，而 Test PyPI 不是一个永久的存储库。测试系统会偶尔删除包和账户。因此，最好将 Test PyPI 用于像本教程这样的测试和实验。

当你准备好将一个真实的包上传到 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。

英文

Congratulations, you've packaged and distributed a Python project! ✨ 🍰 ✨

Keep in mind that this tutorial showed you how to upload your package to Test PyPI, which isn't a permanent storage. The Test system occasionally deletes packages and accounts. It is best to use TestPyPI for testing and experiments like this tutorial.

When you are ready to upload a real package to the Python Package Index you can do much the same as you did in this tutorial, but with these important differences:

Choose a memorable and unique name for your package. You don't have to append your username as you did in the tutorial, but you can't use an existing name.
Register an account on https://pypi.org - note that these are two separate servers and the login details from the test server are not shared with the main server.
Use twine upload dist/* to upload your package and enter your credentials for the account you registered on the real PyPI. Now that you're uploading the package in production, you don't need to specify --repository; the package will upload to https://pypi.org/ by default.
Install your package from the real PyPI using python3 -m pip install [your-package].

At this point if you want to read more on packaging Python libraries here are some things you can do:

Read about advanced configuration for your chosen build backend: Hatchling, setuptools, Flit, PDM.
Look at the guides on this site for more advanced practical information, or the discussions for explanations and background on specific topics.
Consider packaging tools that provide a single command-line interface for project management and packaging, such as hatch, flit, pdm, and poetry.

Notes

打包Python项目¶

一个简单的项目¶

创建包文件¶

创建测试目录¶

选择构建后端¶

配置元数据¶

创建 README.md¶

创建 LICENSE¶

包括其他文件¶

生成分发档案¶

上传分发档案¶

安装新上传的包¶

后续步骤¶