发布你自己的轮子 - PyPI打包上传实践

文章目录

发布 Python 包
- 准备
- 创建用户验证文件
- 创建项目结构
- 编写setup.py
- 编写README.md
- 编写LICENSE
- 生成发布包
- 本地测试（可选）
- 上传到PyPI
- 安装测试
- 常见错误
- 参考

作为一门流行的编程语言，Python有着世界上首屈一指的开发者社区，使得大家可以有效地进行共享和协作。正所谓 “ 人生苦短，我用Python”，Python 的一大优势就是有着丰富且易用的第三方模块。无论你做什么，几乎都能找到扩展包达到你的目的。而这一切，都是完全开源免费的！

既然 Python 的核心是第三方扩展包，那么你想不想自己写一个并发布呢？无论是将自己的优秀项目开源出来，还是写一些可以经常复用的小工具，都是一件很棒的事情

发布 Python 包

PyPI（Python Package Index）是一个开源许可的软件包公共存储库，可供所有 Python 用户使用。Python包管理工具 pip，就是从 PyPI 上下载源码并编译安装的。如果你想要你的包能够通过网络安装，那么 PyPI 是你的不二选择

准备

前往 PyPI 官网注册账号并验证邮箱
使用 Github 托管项目（可选）

创建用户验证文件

创建 .pypirc 文件，放置到操作系统 ~ 目录下，在类 linux 系统中就是 ~/ 目录，windows 下则是 C:\Users\<用户名>\，内容如下：

[distutils]
index-servers = pypi[pypi]
username:你的PyPi用户名
password:你的PyPi密码

创建项目结构

zzzzls-project/loler-spider/               # 这个包是我们 Python项目的主体文件__init__.pyheroSpider.pysetup.py                    # setup.py, LICENSE, README.md 是我们要打包发布的辅助文件LICENSEREADME.md

编写setup.py

这里重点说明一下 setup.py 文件，因为整个 pip项目的发布和上传都是基于这个文件完成的

import setuptoolswith open("README.md", "r", encoding='utf-8') as fh:long_description = fh.read()setuptools.setup(name="loler-spider",version="1.0.1",author="zzzzls",author_email="245129129@qq.com",description="A spider to download lol-hero image",long_description=long_description,long_description_content_type="text/markdown",url="https://github.com/zzzzls/",packages=setuptools.find_packages(),license='MIT',keywords=['lol', 'image', 'spider', 'download'],install_requires=["requests","tqdm"]
)

name

软件包的发行名称。只能由 字母，数字，下划线(_)，横杠(-)，句点(.)构成，不区分大小写，需要确保其唯一性，不能和其他软件包重名。
version

软件包的版本。后续更新软件包需要修改为更高的版本号
author & author_email

作者信息
description

软件包的简单描述
long_description

软件包的详细描述
long_description_content_type

设置 long_description 的文本类型，可以是 text/plain，text/x-rst，text/markdown
url

项目主页 URL，这里指向 Github 项目地址
packages

项目包的列表，我们可以使用 find_packages() 来自动发现所有包和子包。在当前项目中，包的列表将是 loler-spider
license

项目许可证，见下文描述
keywords

项目的关键字
install_requires

软件包运行需要的其他依赖，用户通过 pip 安装当前软件包时，会自动安装这些依赖

检测 setup.py 文件语法是否正确 python setup.py check

出现 running check 表示正确，可以进行下一步

更多参数简介：https://packaging.python.org/guides/distributing-packages-using-setuptools/

编写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.

建议参考优秀项目的写法，示例：requests

编写LICENSE

如下列举 5 种最常用的开源协议（BSD, MIT, Apache2.0, GNU GPL, LGPL）及它们的适用范围，供那些准备开源或者使用开源产品的开发人员/厂家参考

当你确定使用的协议后，前往 choosealicense 复制对应的协议内容粘贴至 LICENSE 文件即可

注意: 需要同步修改 setup.py 文件中 license 字段！

生成发布包

python setup.py sdist bdist_wheel

正确执行后的目录结构：

├── build
│   ├── bdist.win-amd64
│   └── lib
│       └── loler_spider
│           ├── __init__.py
│           ├── HeroSpider.py
├── dist
│   ├── loler_spider-1.0.1-py3-none-any.whl
│   └── loler_spider-1.0.1.tar.gz
├── loler_spider
│   ├── __init__.py
│   ├── HeroSpider.py
├── loler_spider.egg-info
│   ├── dependency_links.txt
│   ├── PKG-INFO
│   ├── requires.txt
│   ├── SOURCES.txt
│   └── top_level.txt
├── LICENSE
├── README.md
└── setup.py

本地测试（可选）

建议在将包上传到 PyPI 之前先在本地完成测试工作，方法是先进入 dist 文件夹，然后使用 pip 命令安装本地的二进制包，安装完成后测试其中的方法是否可用

cd dist
pip install loler_spider-1.0.1.tar.gz

上传到PyPI

安装发布需要的工具 twine
```
pip install twine
```
开始上传
```
twine upload dist/*
```
出现如下结果即为上传成功

访问上图中的 URL 即可到达项目 PyPI主页

安装测试

pip install loler-spider

国内源收录需要一段时间，若安装失败建议使用官方源进行安装测试

pip install loler-spider -i https://pypi.python.org/simple

常见错误

Upload failed (403): Invalid or non-existent authentication information

错误的用户验证信息，你需要创建一个用户校验文件 ~/.pypirc，请参阅上文
Server response (401): Incomplete registration; check your email

你的 PyPI 账户还没有完成邮箱验证
error: Upload failed (499): Client Disconnected

网络问题，多重试几次
Upload failed (400): File already exists

文件已经存在了，每一次上传都应该更新版本号

参考

打包 Python 项目
PyPI打包上传实践
Python-OpenSource-Project-Developer-Guide