手把手教你打包Python库并创建自己的PyPI项目

太过爱你忘了你带给我的痛 2022-03-31 07:50 718阅读 0赞

# 摘要 #

本文将以[py3PortScanner][]为例，带大家了解如何将已经完成的python package打包，在README中添加[travis-ci][]的\_\_build passing\_\_图标，并将package整体上传至PyPI(Python Package Index)从而使得其他用户可以通过`pip`命令来直接安装这个package。

# 背景知识需求 #

本文需要读者拥有一定的python编程经验和开源软件相关知识，已经了解python package定义并了解如何使用pip进行python库管理。同时需要读者已经对python单元测试以及软件测试有所了解。

# 创建生成软件包所需的文件 #

首先，我们需要确保我们的package中已经包含了`README.md`, `LICENSE`和`setup.py`文件。三者分别包含该package的说明文档，许可证和python [setuptools][]所用来安装该package的构建脚本(build script)。

## [setup.py][] ##

`setup.py`中包含了该package对应的信息(例如该package的名称，版本，作者)以及该package应当包含的程序文件和数据。

参考py3PortScanner的[setup.py][setup.py 1]文件，我们首先读入了README文件和CHANGELOG文件。紧着这我们通过`dev_requires`关键字指定了开发环境所需要的一些依赖。接着便是最重要的`setup()`函数。在setup函数中我们指定了该package的作者，版本，描述，描述文件格式，分类，package链接(大多数情况)，package所应当包含的程序文件和数据文件，和程序可以额外安装的运行环境(需要通过`python3 -m pip install [.dev_requires]`来安装)。同时在此处还应当注意另一个非常重要但在示例中没有用到的关键字：[`install_requires`][install_requires]。该关键字用来指定当前package所依赖的其他python类库。各关键字详细含义如下：

*  `name`是该package的名字。该名字可以由字母，数字，`_`和`-`组成。并且这个名字不能与其他已经上传至pypi.org的项目相同。
 *  `version`是当前package的版本。关于版本的详细信息请参考[PEP440][]。
 *  `author`以及`author_email`可以用来指定该package的作者信息。
 *  `description`对当前package的较短的总结。
 *  `long_description`是对当前package的详细说明。这一详细说明将被展示在Python Package Index上当前项目的主页，如[py3PortScanner主页][py3PortScanner 1]所示。当前例子中README的内容被直接作为`long_description`。这也是一个常用的方法。
 *  `long_description_content_type`指定了`long_description`内容的格式。在当前情况下为markdown。
 *  `url`是当前package的主页链接。大多数情况下这是一个GitHub, GitLab, Bitbucket或者其他代码存储服务的链接。
 *  `packages`是一系列应当包含在发布软件包文件(distribution package)中的可被import的python包文件。我们可以手动在此处罗列所有文件。或者如本例中一样使用`find_packages()`函数自动包含所有的python包文件以及子包文件。
 *  `classifiers`指定了当前package的其他元信息(metadata)。例如当前package兼容的python版本和操作系统，当前package提供的功能的类型，当前package的许可证等等。我们应当总是至少包括当前package所支持的python版本，操作系统和许可证。注意此处定义的`classifiers`关键字所包含的信息应当符合[PyPI的规定][PyPI]。
 *  `install_requires`指定了当前package所依赖的其他python类库。这些指定的python类库将会在本package被安装的时候一并被安装。

除去我们此处提到的关键字，尚有很多其他的关键字可以使用。具体可以参考[相关的官方文档][Link 1]。

## README ##

README文件包含了该python package的详细说明以及相关信息。

## LICENSE ##

LICENSE文件指定了当前python package的使用许可证。上传至Python Package Index的python package应当包含一个许可证文件。这一文件指定了使用当前python package的用户应当遵守怎样的使用协议。关于如何选择开源软件许可证，读者可以参考[这一文档][Link 2]。

# 使用travis-ci进行build test #

当我们写好相应的软件测试代码之后，[travis-ci][]可以被用来对我们的package进行自动测试。这一测试将会在每一次push时自动运行。

## .travis.yml ##

`.travis.yml`文件是travis-ci的配置文件，travis-ci将依据这一配置文件来创建测试环境并运行测试脚本。具体的配置文档可以参考[travis-ci官方python文档][travis-ci_python]。  
参考[py3PortScanner的配置][py3PortScanner 2]，我们逐条分析如下：

*  `language`指定了编程语言为python。
 *  `python`指定了测试python版本为`3.4`，`3.5`以及`3.6`。
 *  `matrix`用来指定build相关的信息，具体可以参考[相关文档][Link 3]。此处的`fast_finish: true`可以使得travis-ci进行的build测试尽可能早地被标记为结束。
 *  `install`用来指定build测试前用来安装所依赖的python类库的命令，例如[travis-ci官方文档的这一部分][travis-ci 1]。此处我们使用`install: true`来表示没有需要安装的依赖库。
 *  `script`用来指定运行测试的命令或者脚本。此处我们使用了python默认的测试框架，故指定测试命令为`pytest`，既默认运行所有以`test_`开头的测试文件。详情可以参考[相关文档][Link 4]。

## [使用github账号登录travis-ci.com][github_travis-ci.com] ##

打开[travis-ci][]网页之后，选择使用Github账号登录，根据提示步骤选择你需要添加travis-ci build测试的repository并继续，我们就可以方便地将github repository添加到travis-ci个人项目中了。

## 将测试图标添加至README ##

当个人主页上对应项目开始进行built test之后，我们就可以将\_\_build passing\_\_图标添加到README中了。步骤如下：

1.  点击页面上的build图标：  
    ![build图标][build]
2.  在弹出窗口的下拉菜单中选择相应的branch和链接格式，例如本例中我们需要master branch的markdown格式的图标：  
    ![markdown build图标链接][markdown build]
3.  将上图所示的连接直接拷贝到README中，我们的项目Github主页README就有一个bling bling的\_\_build passing\_\_图标啦！

# 生成发布软件包文件 #

当我们完成上述步骤后，我们需要打包我们的python package并生成python软件分发包(distribution packages)。这些文件可以被上传至Python Package Index并由其他用户通过`pip`命令安装。

首先我们需要安装最新版的`setuptools`和`wheel`。

python3 -m pip install --user --upgrade setuptools wheel

然后我们运行如下命令来打包程序(确保`setup.py`存在于当前路径下)。

python3 setup.py sdist bdist_wheel

当这个命令运行结束后，确保在生成的`dist/`文件夹下存在相应的`.whl`文件和`.tar.gz`文件。其中`.tar.gz`文件是我们的python package的源文件文档，而`.whl`是一个软件分发包(build distribution)。新版本的`pip`将会首先尝试安装软件分发包，但在失败情况下会接着尝试采用源文件包安装。

# 将打包好的项目上传至PyPI #

## 上传项目 ##

首先我们需要注册一个[PyPI][PyPI 1]的账号。如果仅仅为练习使用，则应当注册[test.PyPI][]。任何上传至test.PyPI的项目将会在一段时间之后被删除。

接着我们需要安装最新版的`twine`。

python3 -m pip install --user --upgrade twine

安装成功之后我们就可以使用twine来上传项目了。注意在使用`twine`上传项目的时候需要输入相应的PyPI或test.PyPI的账号和密码。

# upload to test PyPI
    python3 -m twine upload --repository-url https://test.pypi.org/legacy/ dist/*
    
    # upload to real PyPI
    python3 -m twine upload dist/*

上传完毕后，我们就可以前往PyPI个人主页上在`your projects`栏目下查看我们的项目。

## 使用`pip`安装项目 ##

如果我们的项目被上传至test.PyPI，则需要通过相应的index-url来安装。其中的`$your_package_name`为我们在`setup.py`中通过`name`关键字指定的项目名称。

python3 -m pip install --index-url https://test.pypi.org/simple/ $your_package_name

如果我们的项目被上传至PyPI，则可以按通常情况直接使用`pip`命令和包名称安装。同样地，`$your_package_name`为我们在`setup.py`中通过`name`关键字指定的项目名称。

python3 -m pip install $your_package_name

?现在我们就拥有一个全新的python项目啦！

[py3PortScanner]: https://github.com/YaokaiYang-assaultmaster/py3PortScanner
[travis-ci]: https://travis-ci.com
[setuptools]: https://packaging.python.org/key_projects/#setuptools
[setup.py]: http://setup.py
[setup.py 1]: https://github.com/YaokaiYang-assaultmaster/py3PortScanner/blob/master/setup.py
[install_requires]: https://packaging.python.org/discussions/install-requires-vs-requirements/#id5
[PEP440]: https://www.python.org/dev/peps/pep-0440/
[py3PortScanner 1]: https://pypi.org/project/pyportscanner/
[PyPI]: https://pypi.org/pypi?%3Aaction=list_classifiers
[Link 1]: https://packaging.python.org/guides/distributing-packages-using-setuptools/
[Link 2]: https://choosealicense.com/
[travis-ci_python]: https://docs.travis-ci.com/user/languages/python/
[py3PortScanner 2]: https://github.com/YaokaiYang-assaultmaster/py3PortScanner/blob/master/.travis.yml
[Link 3]: https://docs.travis-ci.com/user/customizing-the-build/#build-matrix
[travis-ci 1]: https://docs.travis-ci.com/user/languages/python/#pypy-support
[Link 4]: https://docs.travis-ci.com/user/languages/python/#default-build-script
[github_travis-ci.com]: http://xn--githubtravis-ci-2e8x396cui2czw8e6sf0x7k.com
[build]: /images/20220331/c1ccdd62c2ee4481a8635f9cecbfe672.png
[markdown build]: /images/20220331/1d7d3a582bd04140940fe48e117e20ed.png
[PyPI 1]: https://pypi.org
[test.PyPI]: https://test.pypi.org