本篇文章由 VeriMake 旧版论坛中备份出的原帖的 Markdown 源码生成
原帖标题为:在 PyPI 上发布你的 Python 项目
原帖网址为:https://verimake.com/topics/236 (旧版论坛网址,已失效)
原帖作者为:dawdler(旧版论坛 id = 236,注册于 2020-08-17 14:01:22)
原帖由作者初次发表于 2021-06-05 14:55:40,最后编辑于 2021-06-05 14:55:40(编辑时间可能不准确)
截至 2021-12-18 14:27:30 备份数据库时,原帖已获得 606 次浏览、1 个点赞、0 条回复
#在PyPI上发布你的Python项目
<本教程是在Windows操作系统中完成的,如果你使用的是Linux或MacOS系统,可以点击文末的链接,官方指南上有对应的指令~>
<如果你也是Windows操作系统,但是输入以下指令出现报错,可以尝试把py改成python试一试~>
(比如将py -m pip install build
换成python -m pip install build
)
1. 创建项目
1.1 首先确认你可以在自己的机器上正常安装第三方包,然后安装twine
:
py -m pip install twine
1.2 然后开始编写除代码外的配置文件:
1.2.1 setup.py
setup.py是一个用来描述项目的文件,PyPI会通过该文件获取项目名称、版本号、依赖的库、支持的Python版本等信息。
以下是一些必填项,其他可选项可以在官方给出的示例中查看:
https://github.com/pypa/sampleproject/blob/main/setup.py
"""A setuptools based setup module.
See:
https://packaging.python.org/guides/distributing-packages-using-setuptools/
https://github.com/pypa/sampleproject
"""
from setuptools import setup, find_packages
import pathlib
here = pathlib.Path(__file__).parent.resolve()
# 获取README
long_description = (here / 'README.md').read_text(encoding='utf-8')
setup(
# 首先要为这个项目命名
# 这个名字就是上传成功后其他用户下载是键入的包名
# 并确保名称合法,可以参考这个网址
# https://packaging.python.org/specifications/core-metadata/#name
name='sampleproject',
# 输入此次上传的版本
# 以后每次更新后上传都需要更新版本号哦
# 版本号需要符合规定,具体可参考:
# https://www.python.org/dev/peps/pep-0440/
# https://packaging.python.org/en/latest/single_source_version.html
version='0.0.1',
# 源代码包
packages=find_packages(where='src'), # Required
# 支持的Python版本
# 具体可查看
# https://packaging.python.org/guides/distributing-packages-using-setuptools/#python-requires
python_requires='>=3.6, <4',
)
1.2.2 setup.cfg
setup.cfg是一个配置信息文件,会在运行setup.py程序打包时用到这里的配置。
[metadata]
# This includes the license file(s) in the wheel.
# https://wheel.readthedocs.io/en/stable/user_guide.html#including-license-files-in-the-generated-wheel-file
license_files = LICENSE.txt
1.2.3 README.md
README.md是一个用来描述项目的文件,使用markdown语法填写即可。因为这个文件的内容是依据项目本身的功能和特性来写的,这里就不给具体的示例了。
如果不了解markdown语法,以下是一个简单的markdown教程的连接:
https://www.runoob.com/markdown/md-tutorial.html
1.2.4 MANIFEST.in
我们在这份文件中记录需要放在包中的除了代码之外的其他文件。
include pyproject.toml
# Include the README file
include *.md
# Include the license file
include LICENSE.txt
# Include setup.py
include setup.py
# Include the data files
recursive-include data *
1.2.5 LICENSE.txt
在这份文件中我们需要声明这个项目要用什么开源License,以下是官方给出的一个示例:
Copyright (c) 2016 The Python Packaging Authority (PyPA)
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.6 pyproject.toml
在配置文件中,我们需要一个[build-system]
表来储存于构建相关数据:
[build-system]
# These are the assumed default build requirements from pip:
# https://pip.pypa.io/en/stable/reference/pip/#pep-517-and-518-support
requires = ["setuptools>=40.8.0", "wheel"]
build-backend = "setuptools.build_meta"
2. 打包项目
打包项目需要先下载build
库:
py -m pip install build
然后运行以下命令进行打包:
py -m build --sdist
现在你应该可以看到你的dist/目录下生成了一个.tar.gz后缀的源码包,然后我们需要为项目创建一个wheel:
py -m build --wheel
注意:这个是纯Python项目的wheel指令,如果你的代码中还包含其他语言的部分,请拉到文末,点击链接查看官方指南~
3. 发布项目
在完成打包后,我们就可以在PyPI上发布项目啦!
在这里,我们强烈建议大家先在官方的测试平台上模拟上传一次,因为正式的上传过程中如果出现什么问题,再想重新上传的话很可能会面临包名已经占坑成功,需要重新命名的问题~
3.1 测试
3.1.1 注册测试账户
首先,我们需要在测试平台上注册一个PyPI账户:
https://test.pypi.org/account/register/
记得在记事本上备份一下你的用户名和密码那个页面一旦关掉就再也找不到密码了。
然后确认你已经在第一步的时候安装好twine
包了~
3.1.2 上传到TestPyPI
可以使用以下指令上传:
twine upload --repository testpypi dist/*
然后会出现
[pypi]
username = <username>
password = <password>
这里的username就是__token__
,密码需要从PyPI上复制粘贴过来。密码是盲打的,所以需要你确认输入状态后直接粘贴并回车~
等你看到上传成功的信息之后,就可以在https://test.pypi.org/project/<sampleproject>上查看一下能不能找到你的包,如果有,就可以尝试一下能不能正常下载。(<sampleproject>就是你的项目名)
3.1.3 安装你的项目包
这个时候我们在prompt输入以下指令就可以下载你的包了:
pip install --index-url https://test.pypi.org/simple/ your-package
如果可以成功安装,就说明步骤都没有问题了,然后就可以开始正式上传啦!
3.2 正式上传
按照惯例,我们需要先在PyPI注册一个账户,记得验证邮箱。链接如下:
https://pypi.org/account/register/
注册完成之后,记得备份一下用户名和密码,然后在终端运行以下命令将包上传:
py -m twine upload dist/*
与测试过程很类似地,我们需要输入用户名和密码:
[pypi]
repository: https://upload.pypi.org/legacy/
username = <username>
password = <password>
这里的username还是__token__
,密码依然需要从PyPI上复制粘贴过来。上传成功后不要忘记在你的prompt尝试安装一下:
pip install package-name
3.3 几个常见的报错信息处理
3.3.1 Upload failed (403):
a. 名称不合法,可能是包名已被占用,需要你重新起名;
b. 用户名或密码错误,可能是你的复制粘贴出了问题,可以试一试这两个办法: i. Clicking Edit > Paste
from the Command Prompt
menu;
ii. Enabling Properties > Options > Use Ctrl+Shift+C/V as Copy/Paste
in the Command Prompt
menu;
3.3.2 Upload failed (400):
文件已经存在,需要更新你的版本号。(对同一个包的每一次上传都需要更新版本号)
3.3.3 Upload failed (499):
一般来说是网络问题,检查网络,多重试几次就好。
以上就是在PyPI上发布个人项目的一般流程,其他细节问题请参考:
官方发布的完整教程
https://packaging.python.org/guides/distributing-packages-using-setuptools/
官方给出的示例
https://github.com/pypa/sampleproject/blob/main/setup.py