【python打包分发工具】setuptools详解
转自：https://zhuanlan.zhihu.com/p/460233022，仅作学习记录。
文章目录
- 一、背景
-
- 1. 为什么需要对项目分发打包？
- 2. 源码包与二进制包什么区别？
- 3. eggs与wheels有什么区别？
- 二、详解
-
- 1. 源码包sdist
-
- 1.1 打包分发源码包命令
- 1.2 安装源码包命令
- 2. 二进制包bdist
-
- 2.1 打包分发二进制包命令
- 2.2 安装二进制包命令
- 3. python库基本信息
- 4. 需要打包的文件
-
- 4.1 package参数
- 4.2 include_package_data(MANIFEST.in)
- 4.3 package_data
- 4.4 exclude_package_data
- 5. 依赖包安装与版本管理
- 6. python环境限制
- 7. 生成脚本
- 8.C/C++扩展
-
- 8.1 宏预处理
- 9. 自定义命令行为
一、背景
1. 为什么需要对项目分发打包？
平常我们习惯了使用 pip 来安装一些第三方模块，这个安装过程之所以简单，是因为模块开发者为我们默默地为我们做了所有繁杂的工作，而这个过程就是 打包。
打包，就是将你的源代码进一步封装，并且将所有的项目部署工作都事先安排好，这样使用者拿到后即装即用，不用再操心如何部署的问题（如果你不想对照着一堆部署文档手工操作的话）。
你是否也想写一个python库，想向社会开源或者企业内部使用，想让别人通过简单的命令pip install 安装你的库。那么setuptools绝对是最好用的python打包与分发工具。
setuptools库的前身是distutils（一个python标准库），setuptools本身不是标准库，所以需要自行安装。
setuptools提供的主要的功能有：
- python库的打包分发
- 依赖包安装与版本管理
- python环境限制
- 生成脚本
- c/c++ 拓展
首先python库的打包分发方式有两种：源码包source dist（简称sdist）、二进制包binary dist（简称bdist）。
2. 源码包与二进制包什么区别？
Python 包的分发可以分为两种：
- 以源码包的方式发布
源码包安装的过程，是先解压，再编译，最后才安装，所以它是跨平台的，由于每次安装都要进行编译，相对二进包安装方式来说安装速度较慢。
源码包的本质是一个压缩包，其常见的格式有：
- 以二进制包形式发布
二进制包的安装过程省去了编译的过程，直接进行解压安装，所以安装速度较源码包来说更快。
由于不同平台的编译出来的包无法通用，所以在发布时，需事先编译好多个平台的包。
二进制包的常见格式有：
3. eggs与wheels有什么区别？
Egg 格式是由 setuptools 在 2004 年引入，而 Wheel 格式是由 PEP427 在 2012 年定义。Wheel 的出现是为了替代 Egg，它的本质是一个zip包，其现在被认为是 Python 的二进制包的标准格式。
以下是 Wheel 和 Egg 的主要区别：
- Wheel 有一个官方的 PEP427 来定义，而 Egg 没有 PEP 定义
- Wheel 是一种分发格式，即打包格式。而 Egg 既是一种分发格式，也是一种运行时安装的格式，并且是可以被直接 import
- Wheel 文件不会包含 .pyc 文件
- Wheel 使用和 PEP376 兼容的 .dist-info 目录，而 Egg 使用 .egg-info 目录
- Wheel 有着更丰富的命名规则。
- Wheel 是有版本的。每个 Wheel 文件都包含 wheel 规范的版本和打包的实现
- Wheel 在内部被 sysconfig path type 管理，因此转向其他格式也更容易
wheel 包可以通过 pip 来安装，只不过需要先安装 wheel 模块，然后再使用 pip 的命令。
$ pip install wheel
$ pip wheel --wheel-dir=/local/wheels pkg
二、详解
1. 源码包sdist
源码包sdist就是我们熟悉的 .zip 、.tar.gz 等后缀文件。就是一个压缩包，里面包含了所需要的的所有源码文件以及一些静态文件（txt文本、css、图片等）。
1.1 打包分发源码包命令
$ python setup.py sdist --formats=gztar
setup.py后面会介绍，总之setup.py指定了打包分发的配置信息。
--formats 参数用来指定压缩格式，若不指定format格式，那么 sdist 将根据当前平台创建默认格式。在类 Unix 平台上，将创建后缀名为.tar.gz分发包，而在Windows上为 .zip 文件。
执行完该命令，我们可以看到文件夹下多了dist文件夹（包含压缩源码的分发包）和egg-info文件夹（中间临时配置信息）。
1.2 安装源码包命令
安装源码包有两种方法，先解压缩源码包，或者直接安装源码包。
- 先解压缩源码包，再执行setup.py
$ python setup.py install
等价于
$ python setup.py build
$ python setup.py install
'''
python setup.py install包括两步：python setup.py build python setup.py install。
这两步可分开执行， 也可只执行python setup.py install, 因为python setup.py install总是会先build后install.
'''
- 直接pip安装源码包
$ pip install xxx.zip
如果是开发阶段，可以用下面两个命令，该命令不会真正的安装包，而是在系统环境中创建一个软链接指向包实际所在目录。 这样在修改包之后不用再安装就能生效，便于调试。
$ pip install -e .
等价于
$ python setup.py develop
或者
$ python setup.py build develop
2. 二进制包bdist
python目前主流的二进制包格式是wheel（.whl后缀），它的前身是egg。wheel本质也还是一个压缩包，可以像像zip一样解压缩。与源码包相比，二进制包的特点是不用再编译，也就是安装更快！在使用wheel之前，需要先安装wheel：$ pip install wheel 。
2.1 打包分发二进制包命令
和 sdist 一样，可以通过 formats 参数指定包格式。如：
$ python setup.py bdist --formats=rpm
等价于
$ python setup.py build_rpm
此外setuptools还提供了其他命令，起到和formats参数一样的效果，如下：
2.2 安装二进制包命令
直接pip就可以了
$ pip install xxx.whl
上面我们讲述了python打包分发的两种方法，很容易发现整个打包过程最重要的就是setup.py，它指定了重要的配置信息。setup.py的内容如下：
from setuptools import setup
setup(
name = 'myapp',
…………
)
可见最关键的就是setuptools.setup这个函数，由它来控制打包分发，包含以下信息：
- python库的基本信息（作者、联系方式、当前库的版本等）
- 需要打包的文件
- 依赖包安装与版本管理
- python环境限制
- 生成脚本
- c/c++ 拓展
- cmdclass自定义命令行为
3. python库基本信息
from setuptools import setup
def readme():
with open('README.md', encoding='utf-8') as f:
content = f.read()
return content
setup(
name = 'myapp', # 包名称
version = '1.0', # 版本
author = 'xxx', # 作者
author_email = '[email protected]', # 作者邮箱
description='a example for pack python', # 描述
long_description=readme(), # 长文描述
long_description_content_type='text/markdown', # 长文描述的文本格式
keywords='pack', # 关键词
url='https://github.com/lihua/myapp', # 项目主页
classifiers=[ # 包的分类信息，见https://pypi.org/pypi?%3Aaction=list_classifiers
'Development Status :: 5 - Production/Stable',
'License :: OSI Approved :: Apache Software License',
'Operating System :: OS Independent',
'Programming Language :: Python :: 3',
'Programming Language :: Python :: 3.6',
'Programming Language :: Python :: 3.7',
'Programming Language :: Python :: 3.8',
'Programming Language :: Python :: 3.9',
],
packages=find_packages(),
include_package_data=True,
license='Apache License 2.0', # 许可证
)
4. 需要打包的文件
通过setup函数的这些参数packages、include_package_data（其实就是MANIFEST.in文件）、exclude_package_data、package_data、data_files来指定需要打包的文件。
包含的文件如下：
- py_modules和packages 参数中所有 Python 源文件
- ext_modulesorlibraries 参数中提到的所有 C 源文件
- scripts 参数指定的脚本
- package_data和data_files 参数指定的所有文件
- setup.cfg和setup.py
- 类似于readme的文件（如README、README.txt、 README.rst、README.md）
- MANIFEST.in 中指定的所有文件
4.1 package参数
packages参数就是用来指示打包分发时需要包含的package，type为list[str]。
举个例子：
└── D:\workplace\python\pack_test
├──setup.py
├──debug
│ ├──debug.py
├──src
│ ├──__init__.py
│ ├──pack1
│ ├──__init__.py
│ ├──main.py
│ ├──config.txt
│ ├──data
│ │ ├──main.py
│ │ ├──a.dat
其中setup.py文件内容为
from setuptools import setup
setup(packages=['src'])
运行$ python setup.py sdist --formats=zip打包命令后，发现只打包了src和旗下的__init__.py，pack1不见踪影。
├──src
│ ├──__init__.py
说明packages参数时，
不会递归的打包子package！只打包当前package！
改为 setup(packages=['src','src.pack1','src.pack1.data']) 这样就可以了。
但每次都这样写也太费时费力了。所以setuptools提供了两个函数find_namespace_packages, find_packages来快速找到所有的package。
首先明白一点，python中的packages有两种，
- 一种是
包含__init__.py的文件夹（姑且叫做普通package）， - 一种是
不含__init__.py的文件夹（这是python3引入的Namespace Packages命名空间包）。
改为 setup(packages=find_packages()) 发现没有打包data和debug文件夹！
原来是因为
find_packages只会打包内含__init__.py的package，而data和debug文件夹正好没有__init__.py。
改为setup(packages=find_namespace_packages()) 就可以打包data和debug文件夹。
此外如果不想打包debug文件夹，可以给find_namespace_packages传递参数以指定在哪个文件夹下进行搜索，比如
setup(packages=find_namespace_packages('src'))，这样就不会打包debug文件夹。
上面这些例子中都没有包含非源码文件（如.dat和.txt文件），需要通过别的参数include_package_data（其实就是http://MANIFEST.in文件）、exclude_package_data、package_data来打包非源码文件。
4.2 include_package_data(MANIFEST.in)
include_package_data是bool类型，默认值为True。当为True时，将根据http://MANIFEST.in文件来打包分发库。
http://MANIFEST.in文件指定了一些语法规则，主要是用来打包非源码文件的，语法规则如下：
还是以之前的例子为例，加入http://MANIFEST.in文件
└── D:\workplace\python\pack_test
├──setup.py
├──MANIFEST.in
├──debug
│ ├──debug.py
├──src
│ ├──__init__.py
│ ├──pack1
│ ├──__init__.py
│ ├──main.py
│ ├──config.txt
│ ├──data
│ │ ├──main.py
│ │ ├──a.dat
http://MANIFEST.in文件内容为：
recursive-include . *.txt *.dat # 递归遍历当前文件夹，找到符合*.dat、*.txt的文件
或者
include src/pack1/*.txt
include src/pack1/data/*.dat
4.3 package_data
除了通过http://MANIFEST.in的方法来指定，还可以通过package_data参数来指定，这边建议还是统一用http://MANIFEST.in文件的方式，免得造成不一致性。
# setup.py
from setuptools import setup
setup(package_data={'':['*.txt'],'src.pk1':['*.dat']} # 其中''表示所有文件夹下
4.4 exclude_package_data
顾名思义就是去除文件
exclude_package_data={'src.pk1':['*.txt']}
5. 依赖包安装与版本管理
一个项目库可能会依赖于很多其他库，比如我们安装pandas，该库依赖于numpy。那我们用pip conda这些命令安装时，从来不用操心哪些依赖包需要安装，它们的版本限制是怎么样的，而这些信息是setuptools打包分发库时就确定的。所以当setuptools打包分发库时，要指定依赖包有哪些，它们又有什么限制。
针对依赖包安装与版本管理这项功能，setup函数提供了一些参数install_requires、 setup_requires、tests_require 、extras_require 。
from setuptools import setup, find_packages
setup(
...
# 表明当前模块依赖哪些包，若环境中没有，则会从pypi中自动下载安装！！！
install_requires=['docutils>=0.3'],
# setup.py 本身要依赖的包，这通常是为一些setuptools的插件准备的配置，这里列出的包，不会自动安装。
setup_requires=['pbr'],
# 仅在测试时需要使用的依赖，在正常发布的代码中是没有用的。
# 在执行python setup.py test时，可以自动安装这三个库，确保测试的正常运行。
tests_require=[
'pytest>=3.3.1',
'pytest-cov>=2.5.1',
],
# install_requires 在安装模块时会自动安装依赖包
# 而 extras_require 不会，这里仅表示该模块会依赖这些包
# 但是这些包通常不会使用到，只有当你深度使用模块时，才会用到，这里需要你手动安装
extras_require={
'PDF': ["ReportLab>=1.2", "RXP"],
'reST': ["docutils>=0.3"],
}
)
关于 install_requires， 有以下四种常用的表示方法：
- ‘argparse’，只包含包名。 这种形式只检查包的存在性，不检查版本。 方便，但不利于控制风险。
- ‘setuptools==38.2.4’，指定版本。 这种形式把风险降到了最低，确保了开发、测试与部署的版本一致，不会出现意外。 缺点是不利于更新，每次更新都需要改动代码。
- ‘docutils >= 0.3’，这是比较常用的形式。 当对某个库比较信任时，这种形式可以自动保持版本为最新。
- ‘Django >= 1.11, != 1.11.1, <= 2’，这是比较复杂的形式。 如这个例子，保证了Django的大版本在1.11和2之间，也即1.11.x；并且，排除了已知有问题的版本1.11.1（仅举例）。 对于一些大型、复杂的库，这种形式是最合适的。
6. python环境限制
有时我们也需要对python的版本进行限制，可以通过参数python_requires 来实现。
setup(python_requires='>=2.7, <=3')
7. 生成脚本
有时候我们的库包含了一些非常重要的功能，每次都提供python XXX.py来运行不太方便，最好是把脚本放入系统环境path，以命令行的形式来执行。比如tensorRT就提供了trtexec命令。
那么setup函数提供了entry_points和scripts这两个参数。它们的区别在于：
- entry_points是
把python文件中的函数自动生成为可执行脚本 - scripts是
把.sh、.py等可执行脚本生成到系统path中
from setuptools import setup
setup(
…………
# 把python中的函数自动生成为一个可执行的脚本
# 如下：把fool.main文件中的main函数自动生成为一个可执行脚本，可以通过命令foo执行该脚本
entry_points={
'console_scripts': [ # key值为console_scripts
'foo = foo.main:main' # 格式为'命令名 = 模块名:函数名'
]
},
# 将 bin/foo.sh 和 bar.py 脚本，生成到系统 PATH中
# 执行 python setup.py install 后
# 会生成 如 /usr/bin/foo.sh 和 如 /usr/bin/bar.py
scripts=['bin/foo.sh', 'bar.py']
)
8.C/C++扩展
python开发成本低，但运行速度堪忧，c/c++速度无人能敌，但内存管理、模板编程等对程序猿来说，开发成本太高。那么python+c的混合编程的解决方案应运而生，博采众长，python就像前端，简单的语言赏心悦目，c就像后端，适合做计算密集型任务。而且c/c++还可以有效规避掉python的GIL锁，速度更上一层楼。
python+c/c++混合编程的技术路径有很多，如：
- 原生的Python.h
- cython
- ctypes、cffi
- SWIG
- Boost.Python：逐渐被pybind11取代
- pybind11：目前比较流行推荐的方法，学习成本低，pytorch也采用了该方法。
本文还是主要介绍setuptools是如何进行c/c++ 扩展。
编译c/c++拓展源码的命令为：
python setup.py build_ext --inplace。
或者直接python setup.py build该命令包括了build_ext步骤。
那么我们该如何指导编译器编译c/c++源码呢。
本质上setuptools是根据setup.py配置来指导生成gcc命令行，当然你也可以粗暴地直接用gcc命令行来编译c/c++拓展源码，但工程量太大，setuptools支持很多混合编程技术cython、SWIG等等。所以甭管你采用什么混合编程技术，绕不开setuptools。setuptools编译c/c++拓展源码的过程主要是把源代码编译成动态连接库（linux下是.so，windows下是.pyd）。这样就可以在.py中愉快import并使用拓展模块了。
主要看setup函数的ext_modules参数，该参数type为list[setuptools.Extension]。所以编译核心就在于这个setuptools.Extension类，该类只支持c/c++拓展，要实现cuda拓展需要自定义Extension类，如pytorch的CUDAExtension。
setuptools.Extension类有几个重要的构造参数（详见API文档）
- name：在python中import该拓展的名称
- sources：源代码文件名
- language：默认’c’，如果要用C++，改成’c++’
- include_dirs：其实就是传递给 gcc 的 -I(大写i)指定include的头文件目录
- library_dirs：其实就是传递给 gcc 的 -L 指定连接文件的目录
- libraries：其实就是传给 gcc 的 -l(小写的L)指定连接文件，在L指定的位置找
- extra_compile_args：其实传给 gcc 的额外的编译参数，比方’-std=c++11’
- extra_link_args：其实传给 gcc 的额外的链接参数（生成动态链接库）
- define_macros：定义宏
- undef_macros：取消定义宏
举个例子：
from setuptools import setup,Extension
setup(
ext_modules=[
Extension(
name='foo', # type=str。并且还支持层级命名，如myapp.foo
sources=['foo/csrc/foo1.c','foo/csrc/foo2.c'], # type=list[str]。源代码的文件名，可以用glob.glob查找所有.c文件
include_dirs=['foo'], # type=list[str]。拓展include头文件，相当于传递给gcc -I
)]
)
8.1 宏预处理
setuptools.Extension用define_macros 和 undef_macros构造参数来定义或取消定义宏。define_macros的type为list[tuple( name:str , value:str|None )] 。值为 None 的宏 FOO 等价于#define FOO ，否则等价于# define FOO value值 。undef_macros 同理，等价于#undef FOO 。
举个例子：陈鸣：来编写你的 setup 脚本（二）
Extension(define_macros=[('NDEBUG', '1'),('HAVE_STRFTIME', None)],
undef_macros=['HAVE_FOO', 'HAVE_BAR'])
上面的代码相当于在每个C文件前加上了：
#define NDEBUG 1
#define HAVE_STRFTIME
#undef HAVE_FOO
#undef HAVE_BAR
9. 自定义命令行为
自定义命令行为是setuptools进阶知识。setuptools包括许多命令，如下：
Standard commands:
build build everything needed to install
build_py "build" pure Python modules (copy to build directory)
build_ext build C/C++ extensions (compile/link to build directory)
build_clib build C/C++ libraries used by Python extensions
build_scripts "build" scripts (copy and fixup #! line)
clean clean up temporary files from 'build' command
install install everything from build directory
install_lib install all Python modules (extensions and pure Python)
install_headers install C/C++ header files
install_scripts install scripts (Python or otherwise)
install_data install data files
sdist create a source distribution (tarball, zip file, etc.)
register register the distribution with the Python package index
bdist create a built (binary) distribution
bdist_dumb create a "dumb" built distribution
bdist_rpm create an RPM distribution
bdist_wininst create an executable installer for MS Windows
upload upload binary package to PyPI
Extra commands:
见：https://pythonhosted.org/an_example_pypi_project/setuptools.html
这些命令具体是由定义在setuptools.command中的类执行的。比如python setup.py bdist由setuptools.command.bdist类来执行。因此我们可以继承于setuptools.command中的类来执行自定义的命令行为。
比如pytorch的Build.Extension就继承于setuptools.command.build_ext。具体怎么继承并改写这个command类就需要阅读源码了。
继承完command类后，需要通过cmdclass参数告诉setuptools，该参数为一个字典，key为str命令名，value为继承于command类。
from setuptools import setup
import setuptools.command.build_ext as build_ext
class BuildExtension(build_ext,object):
…………
setup( cmdclass={'build_ext': BuildExtension} )