Air
2022年7月12日

如何将本地的Python项目发布到PyPI

Python的优势之一是有大量的第三方研发工程师为其生态做贡献，他们编写各种库，用于解决各个行业遇到的问题。借助这些库，我们通常能减少重复劳动，提高研发效率。为了让使用Python的人能够使用这些三方库，那么需要为第三方研发工程师提供一个公共的地方：一个既能为第三方工程师提供存储三方库的地方，又能让使用Python的人下载这些三方库。也就是这篇文章要介绍的主题-PyPI(the Python Packaging Index)。

接下来，我将从以下几个方面来介绍：如何将你研发的三方库发布到PyPI，以便互联网上的任何一个人都能使用它。

编写一个简单的三方库
文件 pyproject.toml
指定LICENSE和README.md文件
打包非源码文件
在本地安装你研发好的三方库
将三方库发布到PyPI

编写一个简单的三方库

在这一节，我们需要编写一个简单的三方库，它只提供一个访问digolds.cn的接口，同时依赖于三方库requests，主要的源代码在文件index.py中，如下所示：

import json
import os
import requests

def visit_digolds():
    current_file_dir = os.path.dirname(__file__)
    f = open(os.path.join(current_file_dir,'host.json'))
    domain = json.load(f).get('domain')
    html = requests.get(domain)
    return html

这个三方库的目录结构如下所示：

digolds-cn
├── LICENSE
├── MANIFEST.in
├── README.md
├── pyproject.toml
├── setup.py
├── src
│   └── visitor
│       ├── __init__.py
│       ├── __main__.py
│       ├── host.json
│       └── index.py
└── tests
    ├── __init__.py
    └── test_index.py

除了目录src和tests中包含源代码文件之外，其它文件则包含了描述该三方库的基本信息。接下来，让我们花一点时间来看看每一个非源码文件的内容，以及这些非源码文件的作用。你可以到这里获取完整的文件，关于如何编写测试，你可以参考这篇文章。

文件 pyproject.toml

每一个Python三方库都应该准备文件pyproject.toml，它有许多作用。

作用一：指定生成三方库的方式。比如，如果你想使用setuptools来打包，那么你可以在该文件中指定以下内容，如下所示：

[build-system]
requires      = ["setuptools>=61.0.0", "wheel"]
build-backend = "setuptools.build_meta"

作用二：向读者展示三方库的基本信息。比如：如何使用三方库、编写这个三方库的作者是谁、三方库的名字和版本等等。常用的基本信息如下所示：

[project]
name = "digolds-cn"
version = "1.0.0"
description = "Visit digolds's home page"
readme = "README.md"
authors = [{ name = "digolds.cn", email = "founders@digolds.cn" }]
license = { file = "LICENSE" }
classifiers = [
    "License :: OSI Approved :: MIT License",
    "Programming Language :: Python :: 3",
]
keywords = ["digolds", "digolds.cn"]

以上信息会出现在PyPI中，以便读者能快速了解到你的三方库。

作用三：指定依赖库和依赖的Python版本。你可以在该文件中指定依赖的三方库和该库所依赖的Python版本，如下所示：

dependencies = ["requests >= 2.24.0"]
requires-python = ">=3.7"

作用四：指定外链。你可以为三方库指定外部链接，比如该三方库的源码链接或者详细的使用文档链接，如下所示：

[project.urls]
repository    = "https://github.com/digolds/visitor"
documentation = "https://www.digolds.cn/article/001657582121249b1a45f4cf3b7468483136c61ac159786000"

作用五：指定命令行的执行入口。如果你希望三方库可以直接在命令行里使用，那么需要指定命令行执行的入口，如下所示：

[project.scripts]
digolds = "visitor.__main__:main"

也就是说，当你在命令行里执行digolds的时候，那么执行的入口在文件 __main__.py 中的main函数。

指定LICENSE和README.md文件

你编写的三方库一般会提供2个文件，一个是LICENSE文件，用于告诉使用的人，要使用你的三方库，你必须遵守的协议；另外一个是README.md文件，里面写了一些如何快速使用你的三方库的用户指南。它们的内容如下所示：

文件LICENSE

MIT License

Copyright (c) 2022 Digolds

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.

文件README.md

# Digolds.cn visitor

...

## Installation

...

## How to use

...

打包非源码文件

有时候，你的源代码会依赖一些非源码文件，比如图片、模版、可执行性文件等等。为了让这些文件与源码文件一起打包，你需要借助文件MANIFEST.in。比如这个简单的三方库依赖文件host.json，且它不是源代码文件，那么你可以在文件MANIFEST.in中添加以下指令：

include src/visitor/*.json

这句指令的作用是告诉打包程序，将目录src/visitor下文件扩展名为json的所有文件添加最终的安装包。

在本地安装你研发好的三方库

通常，你研发好的三方库需要经过本地安装并测试好，才能发布到PyPI。那么Python提供了本地安装的机制。你可以在三方库的根目录下运行以下指令：

python -m pip install -e .

其中命令参数-e是指--editable，而.是指当前目录，在这个例子中也就是digolds-cn目录。

安装好之后，你可以直接在命令行里输入以下指令：

digolds

回车执行之后，将得到以下结果：

<!DOCTYPE html>
...
</html>

将三方库发布到PyPI

当三方库在本地测试没有问题之后，你需要将其发布到PyPI。为了能顺利地将三方库发布到PyPI，你需要执行3步。

步骤一：准备build和twine工具。前者用于打包三方库，而后者用于发布三方库。执行以下指令来安装它们：

python -m pip install build twine

安装成功之后，需要调用以下指令来生成三方库的安装包。

python -m build

执行成功之后，你将看到以下2个文件：

digolds-cn/
│
└── dist/
    ├── digolds_cn-1.0.0-py3-none-any.whl
    └── digolds_cn-1.0.0.tar.gz

其中.tar.gz文件包含了源码文件，而.whl则是wheel文件，本质上.whl文件也是一个压缩文件.zip，里面包含了安装包所有信息，包括描述给读者的信息，目录结构如下所示：

digolds_cn-1.0.0-py3-none-any
├── digolds_cn-1.0.0.dist-info
│   ├── LICENSE
│   ├── METADATA
│   ├── RECORD
│   ├── WHEEL
│   ├── entry_points.txt
│   └── top_level.txt
└── visitor
    ├── __init__.py
    ├── __main__.py
    ├── host.json
    └── index.py

步骤二：使用twine工具将生成的安装包发布到testpypi。testpypi类似于PyPI，你应该先将三方库上传到testpypi，用于验证即将发布的三方库是正确的，确定没有问题之后再把三方库发布到正式的PyPI中。

为了将三方库上传到testpypi，你需要执行以下指令：

twine upload -r testpypi dist/*

以上命令会让你输入用户名和密码，因此执行以上命令之前，你需要到这里注册一个账号。如果能顺利将三方库发布到testpypi，那么你可以到这里查看三方库的信息。你也可以基于以下命令来安装三方库：

python -m pip install -i https://test.pypi.org/simple digolds-cn

如果一切顺利，你就可以在本地使用命令digolds了。以上过程均是在testpypi中完成的，因此为了切换到正式的PyPI，你需要按照步骤三来实现。

步骤三：使用twine工具将生成的安装包发布到PyPI。PyPI是Python官方正式对外公开的Python三方库托管服务，你可以将三方库发布到上面，剩下的就交给想要使用该三方库的Python研发人员。

为了将三方库发布到PyPI，你只需要执行以下指令：

twine upload dist/*

当你发布成功之后，别忘了到另外一台机器，或者让你的朋友用他/她的电脑来执行以下命令来安装你的三方库：

python -m pip install digolds-cn

如果一切顺利，你就可以在本地使用命令digolds了。看着自己研发的三方库能够被别人使用，你或许会有动力继续研发更好的Python三方库。最后，你可以直接点击这里，在线浏览这个三方库的基本信息。

总结

这篇文章介绍了PyPI，如果你需要发布自己研发的三方库，那么按照以上步骤，你便可以将三方库发布到PyPI，供大家使用。

{{ c.user.name }}
- {{ c.display_datetime }}
{{ c.content }}

请登录购买（{{ selected_gold.price }}元），即可解锁剩余教程

点击购买

{{ s.title }}
{{ a.title }}
{{ a.title }}

{{ title }}

如何将本地的Python项目发布到PyPI

编写一个简单的三方库

文件 pyproject.toml

指定LICENSE和README.md文件

打包非源码文件

在本地安装你研发好的三方库

将三方库发布到PyPI

总结

{{ c.user.name }}

{{ title }}

{{ selected_gold.title }}

{{ title }}

如何将本地的Python项目发布到PyPI

编写一个简单的三方库

文件 pyproject.toml

指定LICENSE和README.md文件

打包非源码文件

在本地安装你研发好的三方库

将三方库发布到PyPI

总结

创建新文章

删除文章或章节

{{ title }}