详细步骤 | 打包制作自己的 Python 模块包并上传到 Pip 源 PyPI_pypi 创建api token

---

前言

本文介绍如何打包一个简单的 Python 项目，以及如何将其上传到Python包索引平台(PyPI)，供他人使用 pip install xxx 指令安装。

一、准备构建包的文件

文件目录结构：

packaging_tutorial/
├── pyproject.toml
├── src/
│   └── example_package_YOUR_USERNAME_HERE/
│       ├── __init__.py
│       └── example.py
├── LICENSE 
├── MANIFEST.in
└── README.md
1
2
3
4
5
6
7
8
9

说明：packaging_tutorial 可以是任意的目录名，pyproject.toml 是打包配置文件，src 里面存放的就是你的程序代码，example_package_YOUR_USERNAME_HERE 需要改成你期望发布的模块包名（官方建议是在包名后面加上自己的用户名，防止和现有库名重复），LICENSE 是许可信息，MANIFEST.in 是非必需的，如果需要打包代码文件夹以外的文件要在这里面配置，README.md 就是 readme 文件，也是非必需。

1.1 pyproject.toml

pyproject.toml 里可以配置包名、项目依赖等信息：

[project]
name = "example_package_YOUR_USERNAME_HERE"
version = "0.0.1"
authors = [
  { name = "Example Author", email = "author@example.com" },
]
dependencies = []
description = "A small example package"
readme = "README.md"
requires-python = ">=3.7"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: MIT License",
    "Operating System :: OS Independent",
]

[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"

[project.urls]
"Homepage" = "https://github.com/pypa/sampleproject"
"Bug Tracker" = "https://github.com/pypa/sampleproject/issues"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23

其中，name 和前面的“目录结构”里的 example_package_YOUR_USERNAME_HERE 一致，该成你的模块包名。version 是待构建模块包的版本号。authors 是作者信息，可以添加多个作者。dependencies 可以添加项目依赖的第三方库的信息，在安装时会自动安装这些依赖库。description 是模块描述。readme 指定readme文件，较长的描述可以写在 readme 文件里。requires-python 是模块依赖的 Python 版本号。classifiers 指定 编程语言、许可证、操作系统的信息，基本就只用改 License，有严格的写法要求，具体可以查看：https://pypi.org/classifiers/。

build-system 选择构建后端，支持 Hatchling、setuptools、Flit、PDM

# Hatchling
[build-system]
requires = ["hatchling"]
build-backend = "hatchling.build"
# setuptools
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
# Flit
[build-system]
requires = ["flit_core>=3.4"]
build-backend = "flit_core.buildapi"
# PDM
[build-system]
requires = ["pdm-backend"]
build-backend = "pdm.backend"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16

project.urls 里可以添加一些链接，如bug反馈、文档等…

例如：

[project]
name = "bhsenti"
version = "0.0.1"
authors = [
    { name = "bhnw", email = "bhshare.cn@gmail.com" },
]
dependencies = ['transformers>=4.27.1', 'onnxruntime']
description = "基于三分类的中文情感分析"
readme = "README.md"
requires-python = ">=3"
classifiers = [
    "Programming Language :: Python :: 3",
    "License :: OSI Approved :: GNU General Public License v3 (GPLv3)",
    "Operating System :: OS Independent",
]
[build-system]
requires = ["setuptools>=61.0"]
build-backend = "setuptools.build_meta"
[project.urls]
"Homepage" = "https://github.com/yaokui2018"
"Bug Tracker" = "https://github.com/yaokui2018/bhsenti/issues"
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

1.2 MANIFEST.in

可以在里面配置需要 添加 或者 排除 的Python代码以外的文件。格式示例如下：

# 包含所有文件和目录
include *

# 排除不需要的文件和目录
exclude some_directory/
exclude *.txt
1
2
3
4
5
6

1.3 LICENSE

LICENSE 用来告诉安装软件包的用户，他们可以根据条款使用你的软件包。请参阅https://choosealicense.com/。选择许可后，复制许可文本到 LICENSE 文件。

• MIT License
  简短而直接，允许他人对你的项目几乎做任何事情，包括制作和分发闭源版本。
  对共享改进非常友好，因为它允许他人自由地使用、修改和分发你的代码。
• GNU GPLv3
  允许他人几乎做任何事情，但不允许分发闭源版本，要求任何基于你的项目构建的派生作品必须使用相同的许可证发布。
  与 MIT 许可证相比更加强调对开源共享的支持，鼓励共享改进并保证了代码的开放性。
• Apache License 2.0
  允许他人几乎做任何事情，包括制作、使用和分发闭源版本，但在使用你的专利时提供了一些额外的保护。
  要求在派生作品中包含原始许可和免责声明。
• …

例如：选择 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.
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19

1.4 README.md

就是 readme 文件了…没啥好解释的

# 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.
1
2
3
4
5

二、构建包

2.1 安装 build 库

pip install --upgrade build
1

2.2 打包构建

终端里切换到 pyproject.toml 文件所在目录，运行下面的指令：

python -m build
1

等待构建完成，提示 Successfully built 的提示，当前目录即会多出一个 dist 文件夹，里面有两个文件，即是打包好的文件。

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

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

如果本地使用，就可以直接 pip install xxxxxx.whl 安装模块包进行测试了。

三、上传模块包到PyPI

3.1 注册 PyPI 账号

在 PyPI 上注册一个帐号：https://pypi.org/account/register/。
按提示完成电子邮件地址验证、以及一些安全设置。

3.2 创建 API Token

访问：https://pypi.org/manage/account/token/，按下图步骤创建 PyPI API token.。

3.3 创建 .pypirc 文件

在系统 HOME 目录创建 .pypirc 配置文件:

• Linux : ~/.pypirc
• Windows： C:\Users\用户名\.pypirc

文件内容如下：

[distutils]
index-servers=pypi

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = <Token>
1
2
3
4
5
6
7

其中，<Token> 改成上一步创建的 token（以pypi-开头的）。如果觉得不安全也可以 username 和 password 两行删除，在后面的上传过程中会提示让手动输入。

3.4 安装 twine 库

pip install --upgrade twine
1

3.5 上传模块包

终端里运行下面指令上传 dist 目录的模块包到 PyPI 平台。

twine upload dist/*
1

访问下面的链接就可以… 剩下的应该都懂了 over

---

附录：
本文构建的模块包源码：https://github.com/yaokui2018/bhsenti
官方详细教程：https://packaging.python.org/en/latest/tutorials/packaging-projects/