发布你自己的轮子 - 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__.py
		heroSpider.py
	setup.py                    # setup.py, LICENSE, README.md 是我们要打包发布的辅助文件
	LICENSE
	README.md

编写setup.py

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

import setuptools

with 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="[email protected]",
    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 check setup.py

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

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

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

建议参考优秀项目的写法， 示例：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