共计 8899 个字符，预计需要花费 23 分钟才能阅读完成。
最近把 pyenv、pipenv 这种都研究了一下，然后我发现一个严重的问题：就是我虽然看了半天这些工具，但是我对 Python 自己的打包系统却完全没有了解。所以这篇文章就来研究一下 Python 自带的打包系统。
pip
先来详细介绍一下 pip 的用法，平时基本上我们用 pip 的时候也就是一个 pip install。其实 pip 也有很多特性，在此先介绍一下常用的一些特性。此部分参考了 pip 文档，想了解更多的话可以看原文。
安装
最常用的命令就是安装了，除此以外还可以指定版本号：
$ pip install SomePackage # 不指定版本号，安装最新版
$ pip install SomePackage==1.0.4 # 指定版本号
$ pip install ‘SomePackage>=1.0.4’ # 指定最小版本号
$ pip install -r requirements.txt # 从需求文件安装
$ pip install -e . # 从本地项目 setup.py 安装
使用代理服务器
当从官方的 PyPI 源安装比较慢的时候，可以考虑使用代理服务器，指定代理服务器的方法有三种：
使用 –proxy 参数在命令行指定，代理格式为 [user:passwd@]proxy.server:port。
在配置文件中指定。
设置 http_proxy, https_proxy 和 no_proxy 环境变量。
使用需求文件（requirements.txt）
在需要很多 pip 包的项目中，用 pip 一个个安装包不是一个好办法，这时候可以考虑使用需求文件。
如果要生成需求文件，用下面的命令。这会将当前 Python 环境中的所有包的当前版本状态保存下来，将来安装的时候会精确还原到冻结的那个状态。
pip freeze > requirements.txt
要从需求文件中安装，则是用下面的命令：
pip install -r requirements.txt
官方文档还给出了一个带注释的实例需求文件：
#
####### example-requirements.txt #######
#
###### 没有版本标识符的包，会安装最新版 ######
nose
nose-cov
beautifulsoup4
#
###### 带版本标识符的包 ######
# 版本标识符的资料 https://www.python.org/dev/peps/pep-0440/#version-specifiers
docopt == 0.6.1 # Version Matching. Must be version 0.6.1
keyring >= 4.1.1 # Minimum version 4.1.1
coverage != 3.5 # Version Exclusion. Anything except version 3.5
Mopidy-Dirble ~= 1.1 # Compatible release. Same as >= 1.1, == 1.*
#
###### 还可以指定其他的需求文件 ######
-r other-requirements.txt
#
#
###### 还可以指定本地货网络上的特定包 ######
./downloads/numpy-1.9.2-cp34-none-win32.whl
http://wxpython.org/Phoenix/snapshot-builds/wxPython_Phoenix-3.0.3.dev1820+49a8884-cp34-none-win_amd64.whl
#
###### Additional Requirements without Version Specifiers ######
# 和第一部分一样，这里这些部分没有顺序需求，可以随意改变位置
rejected
green
#
版本标识符用来指定包的版本，有以下几个例子：
SomeProject
SomeProject == 1.3
SomeProject >=1.2,<.2.0
SomeProject[foo, bar]
SomeProject~=1.4.2
从 6.0 版本开始，pip 也支持环境标记（也就是分号后面跟 Python 版本或者系统类型）：
SomeProject ==5.4 ; python_version < ‘2.7’
SomeProject; sys_platform == ‘win32’
卸载
卸载某个包使用下面的命令：
$ pip uninstall SomePackage
列出包
要列出所有已安装的包：
$ pip list
docutils (0.9.1)
Jinja2 (2.6)
Pygments (1.5)
Sphinx (1.1.2)
要列出过时的包：
$ pip list –outdated
docutils (Current: 0.9.1 Latest: 0.10)
Sphinx (Current: 1.1.2 Latest: 1.1.3)
要列出某个已安装的包的详细信息：
$ pip show sphinx
—
Name: Sphinx
Version: 1.1.3
Location: /my/env/lib/pythonx.x/site-packages
Requires: Pygments, Jinja2, docutils
搜索
要搜索一个包，用下面的命令，搜索结果可能有很多：
$ pip search “query”
更新
要更新一个包，使用 - U 或者 –upgrade 参数：
pip install -U <pkg>
如果想更新所有的包，很遗憾，pip 并没有提供该功能，我在 StackOverFlow 上找到一个看起来比较简单的解决办法，就是在 Python 解释器中执行下面的代码：
import pkg_resources
from subprocess import call
packages = [dist.project_name for dist in pkg_resources.working_set]
call(“pip install –upgrade ” + ‘ ‘.join(packages), shell=True)
以上就是 pip 的一些简单用法，详情可参考官方文档。
打包项目
下面就进入本文的正题，Python 的打包系统上。基本上我们不需要完全了解打包系统，只要学会简单的几个点就可以打包自己的类库了。打包需要 distutils、setuptools、wheel 等类库，不过基本上我们只需要写好其中最重要的 setup.py，就可以完成打包工作了。distutils 是官方的类库，在当年有很广泛的使用，不过到了现在很难用。distutuils 类库的核心就是 setup 函数，我们需要将项目的各种信息作为参数传递给 setup 函数，然后就可以用相关命令创建项目分发包了。关于 distutils 的用法，可以参考官方文档。
当然现在项目基本都不用 distutils 了，有更好用的第三方替代品，那就是 setuptools，它可以算作是 distutils 的加强版，功能更加强大、使用更加简单，这就是这里要介绍的。其实从文档就可以看出来，distutils 毕竟时间比较早，有些接口设计的不太合理甚至有些反人类，setuptools 的文档就简单多了。
准备项目
为了做演示，首先需要准备一个项目，一个项目应该包括 README 和 LICENSE 等文件，README 文件是 Markdown 格式的文本文件，用于描述项目自身；LICENSE 文件是授权文件，列出项目使用者应该遵循的各种条款。下图是我的项目结构。
此外还可能存在几个文件：
setup.cfg。对应的配置文件，一般情况下可以不要。
MANIFEST.in。清单文件，当项目中需要一些没办法自动包括到源代码分发包的文件时，可能需要用到它。
具体文件内容就不列出了。需要注意 my_package/__init__.py 文件中应该有如下一行标识包名：
name = ‘yitian_first_package’
编写 setup.py 文件
用 setuptools 来编写 setup.py 文件是一件非常简单的事情，而且有很多例子可供参考，我挑选了 Kenneth Reitz（requests、pipenv 等类库的作者）写的例子，做了一些修改并翻译了一些注释：
#!/usr/bin/env python
# -*- coding: utf-8 -*-
# 注意 如果要使用上传功能，需要安装 twine 包:
# $ pip install twine
import io
import os
import sys
from shutil import rmtree
from setuptools import find_packages, setup, Command
# 包的元信息
NAME = ‘yitian_first_package’
DESCRIPTION = ‘ 项目的简短描述，不超过 200 字符 ’
URL = ‘https://github.com/techstay/python-study’
EMAIL = ‘lovery521@gmail.com’
AUTHOR = ‘ 易天 ’
REQUIRES_PYTHON = ‘>=3.6.0’
VERSION = ‘0.1.0’
KEYWORDS = ‘sample setuptools development’
# 项目依赖，也就是必须安装的包
REQUIRED = [
‘requests-html’
]
# 项目的可选依赖，可以不用安装
EXTRAS = {
# ‘fancy feature’: [‘django’],
}
# 剩下部分不用怎么管 :)
# ————————————————
# 除了授权和授权文件标识符!
# 如果你改了 License, 记得也相应修改 Trove Classifier!
here = os.path.abspath(os.path.dirname(__file__))
# 导入 README 文件作为项目长描述.
# 注意 这需要 README 文件存在!
try:
with io.open(os.path.join(here, ‘README.md’), encoding=’utf-8′) as f:
long_description = ‘\n’ + f.read()
except FileNotFoundError:
long_description = DESCRIPTION
# 当前面没指定版本号的时候，将包的 __version__.py 模块加载进来
about = {}
if not VERSION:
with open(os.path.join(here, NAME, ‘__version__.py’)) as f:
exec(f.read(), about)
else:
about[‘__version__’] = VERSION
class UploadCommand(Command):
“”” 上传功能支持 ”””
description = ‘Build and publish the package.’
user_options = []
@staticmethod
def status(s):
“””Prints things in bold.”””
print(‘\033[1m{0}\033[0m’.format(s))
def initialize_options(self):
pass
def finalize_options(self):
pass
def run(self):
try:
self.status(‘Removing previous builds…’)
rmtree(os.path.join(here, ‘dist’))
except OSError:
pass
self.status(‘Building Source and Wheel (universal) distribution…’)
os.system(‘{0} setup.py sdist bdist_wheel –universal’.format(sys.executable))
self.status(‘Uploading the package to PyPI via Twine…’)
os.system(‘twine upload dist/*’)
self.status(‘Pushing git tags…’)
os.system(‘git tag v{0}’.format(about[‘__version__’]))
os.system(‘git push –tags’)
sys.exit()
# 神奇的操作，一个函数完事
setup(
name=NAME,
version=about[‘__version__’],
description=DESCRIPTION,
long_description=long_description,
long_description_content_type=’text/markdown’,
author=AUTHOR,
author_email=EMAIL,
python_requires=REQUIRES_PYTHON,
url=URL,
keywords=KEYWORDS,
# 项目中要包括和要排除的文件，setuptools 可以自动搜索__init__.py 文件来找到包
packages=find_packages(exclude=(‘tests’,)),
# 如果项目中包含任何不在包中的单文件模块，需要添加 py_modules 让 setuptools 能找到它们:
# py_modules=[‘yitian_first_package’],
# entry_points={
# ‘console_scripts’: [‘mycli=mymodule:cli’],
# },
install_requires=REQUIRED,
extras_require=EXTRAS,
# 老旧的 distutils 需要手动添加项目中需要的非代码文件，setuptools 可以用下面参数自动添加 (仅限包目录下)
include_package_data=True,
# 如果是包的子目录下，则需要手动添加
package_data={
‘yitian_first_package’: [‘static/*.html’]
},
license=’MIT’,
classifiers=[
# Trove classifiers
# Full list: https://pypi.python.org/pypi?%3Aaction=list_classifiers
‘License :: OSI Approved :: MIT License’,
‘Programming Language :: Python’,
‘Programming Language :: Python :: 3’,
‘Programming Language :: Python :: 3.7’,
‘Programming Language :: Python :: Implementation :: CPython’,
‘Programming Language :: Python :: Implementation :: PyPy’
],
# $ setup.py publish support.
cmdclass={
‘upload’: UploadCommand,
},
)
下面再讲一些在注释里没法详细解释的东西，官方文档的内容更丰富，有需要的可以查看。示例文件中其实还有几个 setup 参数没写全，这里再补充一下。
project_urls
project_urls 参数可以列出一些相关项目的 URL。
project_urls={
‘Documentation’: ‘https://packaging.python.org/tutorials/distributing-packages/’,
‘Funding’: ‘https://donate.pypi.org’,
‘Say Thanks!’: ‘http://saythanks.io/to/example’,
‘Source’: ‘https://github.com/pypa/sampleproject/’,
‘Tracker’: ‘https://github.com/pypa/sampleproject/issues’,
},
python_requires 参数格式就是 pip 中指定包版本的标识符，，指定我们项目支持的 Python 版本，这里再补充几个例子。
# 大版本号大于等于 3
python_requires=’>=3′,
# 版本号大于等于 3.3，但是不能超过 4
python_requires=’~=3.3′,
# 支持 2.6 2.7 以及所有以 3.3 开头的 Python 3 版本
python_requires=’>=2.6, !=3.0.*, !=3.1.*, !=3.2.*, <4′,
package_data 和 data_file
package_data 和 data_file 参数用于指定数据文件，也就是在项目中使用到的非代码文件，一般情况下通过设置 include_package_data=True 自动搜索就够用了，如果需要细粒度的控制，就要使用它们了，详情见 setuptools 文档 – Including Data Files。
package_data 指定包括在包中的数据文件，也就是“包数据文件”，这些文件会复制到包的相应目录。
package_data={
‘package_name’: [‘package_data.dat’],
},
data_files 指定放在包外的数据文件，这些文件会被复制到项目根目录下指定的相对目录中。
data_files=[(‘my_data’, [‘data/data_file’])],
entry_points
entry_points 参数指定一些入口点，可以看做是项目提供的一些额外功能，其中最常见的就是 console_scripts，用于注册脚本接口。setuptools 提供的工具链可以在安装项目分发包的时候将这些接口转化为真正的可执行脚本，更多信息参考 setuptools 文档 – Automatic Script Creation。
entry_points={
‘console_scripts’: [
‘sample=sample:main’,
],
},
版本号
下面是开发、A 测、B 测、发布候选、最终发布等情况的版本号实例。
1.2.0.dev1 # Development release
1.2.0a1 # Alpha Release
1.2.0b1 # Beta Release
1.2.0rc1 # Release Candidate
1.2.0 # Final Release
1.2.0.post1 # Post Release
15.10 # Date based release
23 # Serial release
开发模式
setup.py 文件写完之后，项目就算是可打包状态了。当然也可以继续在项目上进行工作，这时候一般希望项目既可以作为包来安装，又希望项目是可以编辑的，这时候就可以进入开发模式。这种情况下需要用下面的命令来安装包，- e 选项全称是 –editable，也就是可编辑的意思；. 表示当前目录，也就是 setup.py 存在的那个目录：
pip install -e .
该命令会安装 install_requires 中指定的所有包，以及 console_scripts 部分指定的脚本。依赖项会作为普通包来安装，而项目本身会以可编辑状态来安装。特别的，如果只希望安装项目本身而不安装所有依赖包，用下面的命令：
pip install -e . –no-deps
如果有需要的话，还可以安装 VCS 或者本地目录中保存的包来替代官方索引中的包。详情请查看文档。
打包项目
终于到了观看成果的时候了，项目可以被打包成各种类型的可分发包，这里只介绍几种最常用的。
源码分发包（sdist）
这是最低等级的一种，基本上就是复制源代码，不过因此在安装的时候有一个必须的构建（可能包括编译）过程来生成各种元信息，哪怕项目是纯的 Python 项目。用下面的命令来生成：
python setup.py sdist
Wheels（轮子）
在编程界各种第三方包不是被形象地称作轮子吗（著名梗：不要重复造轮子），这里就是这个意思。轮子是一种二进制分发包，是现在最推荐的分发包格式，轮子又可以分为好几种轮子。当然，在构建轮子之前，还需要安装 wheel 包来提供支持。
pip install wheel
通用轮子。也就是项目中只存在 Python 代码，同时兼容 Python 2 和 Python 3 的轮子，用下面的命令生成。
python setup.py bdist_wheel –universal
当然也可以在 setup.cfg 配置文件中指定：
[bdist_wheel]
universal=1
纯 Python 轮子。和通用轮子差不多，不过只支持 Python 2 或者 Python 3.
python setup.py bdist_wheel
平台轮子。这种轮子中不仅有 Python 代码，一般还包括但不限于 C 代码写成的扩展等，因此它们只支持特定平台。
python setup.py bdist_wheel
运行以上命令之后，会在 dist 文件夹中生成打包好的可发布包。
发布项目
项目打包完毕，生成可可分发包之后，最后一步就是发布项目了。几乎所有的项目都被发布到了 Python Package Index（简称 PyPI）上了，当然如果有需求的话还可以搭建自己的私人索引，不过这就是另一个话题了。
很有意思的是，Python 官方还提供了一个测试索引，它是一个和 PyPI 完全一样的测试网站，定期清理，可以让我们方便的练习上传项目，同时不用担心会污染官方仓库。使用方法很简单，先注册一个账户。
上传项目需要用到另一个类库 twine：
pip install twine
然后用下面的命令将包上传到测试索引中，该命令会提示输入刚才注册用的用户名和密码：
twine upload –repository-url https://test.pypi.org/legacy/ dist/*
稍等片刻，上传应该就完成了。然后就可以在测试索引中找到我的项目了。当然由于测试索引会定期清理的缘故，可能过段时间项目和我的账户就都不存在了。
全部流程都熟悉之后，就可以在官方索引上注册账号，并将项目上传上去，这样一来，全世界的开发者都能用到你的项目了！
