setuptools详解

setuptools是什么?

简单点来说，setuptools是帮助我们进行构建分发包或者说是模块的一个工具，主要是面向开发者的，方便开发者将自己的模块或程序编译成package(包)并共享。例如在使用python进行开发过程中，我们pip install或者使用源码(python setup.py install)安装的模块。

setuptools的安装

归根结底，setuptools是python的一个模块，我们可以使用pip进行安装或者升级：

pip install setuptools  # 安装
pip install --upgrade setuptools # 升级

一般而言，当安装完python和pip后，默认会自带setuptools模块，无需再手动安装。

setuptools的使用

上述说到，setuptools方便了共享Python模块或者程序，那么共享Python库或程序的第一步是构建分发包。这包括添加一组包含元数据和配置的文件，以便指导setuptools如何构建发行版。
因此，setuptools的使用最关键的便是包含元数据及配置的文件，目前官方有三种类型的配置文件类型，分别为pyproject.toml、setup.cfg 、setup.py，目前比较常用的是setup.cfg 和setup.py，相比较setup.py，官方更推荐使用setup.cfg。下面将介绍一下setup.cfg配置文件中的源数据及配置:

file: 文件格式，一般以相对位置
list: 列表格式，示例如下:

 classifiers =
    Development Status :: 3 - Alpha
    Environment :: Console

section：从特定部分读取值，类似于ini文件格式，示例如下：

[options.extras_require]
test =
  flake8>=3.6.0
  flake8-blind-except
test2 = 
  pytest
  pytest-cov

参考：https://setuptools.pypa.io/en/latest/references/keywords.html，
https://setuptools.pypa.io/en/latest/userguide/declarative_config.html

metadata(元数据)

元数据中主要包含静态数据

name：项目名称，str
version：项目版本，file、str
url：项目的官方网站， str
download_url：项目的下载地址，str
project_urls：项目链接，主要包含项目的git地址(GitHub)、更新日志(Changelog)等， dict。示例如下：

project_urls =
    Changelog = https://github.com/**/changelog.rst
    GitHub = https://github.com/**

author：项目的作者名称，str
author_email：项目作者的邮箱，str
maintainer：项目维护者名称，str
maintainer_email：项目维护者邮箱，str
classifiers：程序所属的分类，主要包含程序的支持平台、所用语言、所用认证等，file，list。示例如下:

classifiers =
    Development Status :: 3 - Alpha
    Environment :: Console
    Intended Audience :: Developers
    License :: OSI Approved :: Apache Software License
    Operating System :: MacOS
    Operating System :: Microsoft :: Windows
    Operating System :: POSIX
    Programming Language :: Python
    Topic :: Software Development :: Build Tools

license：程序的授权信息， str
license_files：程序的授权文件（不常用），list
description：项目描述，file, str
long_description：项目的详细描述，file, str
long_description_content_type：项目的描述（不常用），str
keywords：项目的关键字，可为多个，list
platforms：所支持的平台，list
provides：指定可以为哪些模块提供依赖，list
requires：指定依赖的其他包，list
obsoletes：描述此包之前的包的字符串列表，适用于当包修改过名称 list

option(配置)

zip_safe：不压缩包，以目录的形式安装，bool，建议选择False
setup_requires：指定运行setup时所需的依赖
install_requires：安装时需要安装的依赖， list，示例如下：

install_requires =
  coloredlogs; sys_platform == 'win32'
  distlib
  EmPy

extras_require：当前包的额外特性需要依赖的包，file，section，示例如下:

[options.extras_require]
test =
  flake8>=3.6.0
  flake8-blind-except
  flake8-builtins

python_requires：指定项目依赖的 Python 版本，str
entry_points：接入点，主要用于发现服务和插件，也可用于生成控制台脚本，比较重要的，file，section
scripts：指定可执行的脚本，简单点说就是让项目变成一个工具，是entry_points的基础版本，list
eager_resources：list
dependency_links：指定依赖包的下载地址，list
tests_require：测试所需的依赖包，list
include_package_data：是否安装包中包含的数据文件，bool
packages：列出项目内需要被打包的所有 package。一般使用 find:自动发现，find:，find_namespace:，list，find:代表自发现包，默认会自动发现当前目录的包
package_dir：指定哪些目录下的文件被映射到哪个源码包，dict
package_data：指定包内包含的数据文件，section
exclude_package_data：排除的安装包中的数据文件，section
namespace_packages：list
py_modules：需要打包的 Python 单文件列表，list
data_files：打包时需要打包的数据文件，如图片，配置文件等，section,已弃用
ext_modules：指定扩展的模块，针对的是使用 C/C++ 底层语言所写的模块

setup.cfg常用模板

[metadata]
name = my_package
version = attr: my_package.VERSION
description = My package description
long_description = file: README.rst, CHANGELOG.rst, LICENSE.rst
keywords = one, two
license = BSD 3-Clause License
classifiers =    
    Framework :: Django        
    Programming Language :: Python :: 3

[options]
zip_safe = False
include_package_data = True
packages = find:
install_requires =    
    requests    
    importlib-metadata;python_version<"3.8"
    
[options.package_data]
* = *.txt, *.rst
hello = *.msg

[options.entry_points]
console_scripts =    
    executable-name = my_package.module:function
    
[options.extras_require]
pdf = ReportLab>=1.2; RXP
rest = docutils>=0.3; pack ==1.1, ==1.3

[options.packages.find]
exclude =    
    examples*    
    tools*    
    docs*    
    my_package.tests*

setuptools最佳实践

开启包的自发现功能
它会发现本目录下的所有Python包。正常使用第一种即可, 需要注意包中需要__init__.py。

第一种

[options]
packages = find:

第二种
另外include和exclude也可以使用正则
下面这种方式是针对于特定设置

[options.packages.find]
where=src  # 查找的位置 默认为.,代表当前目录
include=mypackage*  # 位于查找的位置包含的包 默认为*,代表全部的包
exclude=mypackage.tests*  # 位于查找的位置去除的包 默认为空，不加载的包

注意：包需要在文件夹内包含__init__.py文件，如果包中没有__init__.py文件，find自发现包时将会忽略，使用find_namespace:可以识别自发现的包，不过建议使用find:。
当需要发现的包不在根目录时，可以使用package_dir指定某个包位于哪个文件夹，示例如下：

[options]
package_dir =    
    = src   # 代表所有的包位于src文件夹下，与上述的where参数类似

[options]
package_dir =    
    mypkg = lib # 代表mypkg包位于lib文件夹下
    mypkg.subpkg1 = lib1 # 代表mypkg.subpkg1位于lib1文件夹下

支持生成控制台脚本
如果将脚本指定为入口点，则会执行相应包中的内容，一大部分可以替代python -m module的操作，示例如下，打包完成后会生成cli-name可执行程序，执行此可执行程序将会调用mypkg.mymodule包中的some_func：

[options.entry_points]
console_scripts =    
    hello-world = timmins:hello_world

setuptools生成控制台脚本示例
此处以hello, world为例，如图是hello，world示例的目录结构

│  setup.cfg
│  setup.py
│  
└─hello
        hello_impl.py
        __init__.py

setup.cfg：setup打包需要的声明式配置文件。
setup.py: 打包脚本，在打包时会自动加载setup.cfg中的相关配置。
hello：需要打包的package。
hello_impl.py：实际的hello，world函数所在
init.py：被主动识别为包必须，不可省略。
其中代码内容分别如下:

setup.cfg

[metadata]
name = hello-world
version = "1.0.0"
description = "helloworld description"

[option]
python_requires = >=3.6
packages = find:
zip_safe = false

# 此处申明了一个可执行程序名为hello-world，指向hello.hello_impl包中的say函数
[options.entry_points]
console_scripts =
    hello-world = hello.hello_impl:say

setup.py

from setuptools import setup

setup()
hello_impl.py

def say():
    print("hello world")

__init__.py：此处是个空文件，仅作识别包用。
正常情况下我们需要输出的话需要写main方法并调用say方法，并且使用python hello_impl.py来输出，当我们设置了entry_points的console_scripts后，在此目录中执行python setup.py install会生成对应程序的exe文件并自动添加到python所在文件夹的Scripts文件夹中，之后可以直接在命令行中输入exe名称即可，此处就为hello-world。
注意: 在python中一个文件夹想要被识别为包，必须要加__init__.py文件，哪怕是空文件也必须要添加，否则将无法正常识别到包及包中的函数。

setuptools打包命令

可通过如下命令查看到详细帮助

python setup.py --help-commands

详细参数:

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
  check             perform some checks on the package
  upload            upload binary package to PyPI

Extra commands:
  build_sphinx      Build Sphinx documentation
  alias             define a shortcut to invoke one or more commands
  bdist_egg         create an "egg" distribution
  develop           install package in 'development mode'
  dist_info         create a .dist-info directory
  easy_install      Find/get/install Python packages
  egg_info          create a distribution's .egg-info directory
  install_egg_info  Install an .egg-info directory for the package
  rotate            delete older distributions, keeping N newest files
  saveopts          save supplied options to setup.cfg or other config file
  setopt            set an option in setup.cfg or another config file
  test              run unit tests after in-place build (deprecated)
  upload_docs       Upload documentation to sites other than PyPi such as devpi
  compile_catalog   compile message catalogs to binary MO files
  extract_messages  extract localizable strings from the project code
  init_catalog      create a new catalog based on a POT file
  update_catalog    update message catalogs from a POT file

usage: setup.py [global_opts] cmd1 [cmd1_opts] [cmd2 [cmd2_opts] ...]
   or: setup.py --help [cmd1 cmd2 ...]
   or: setup.py --help-commands
   or: setup.py cmd --help

基于setuptools的entry_points如何进行扩展？

我们接着之前的hello，world示例，之前say方法仅仅是说了hello,world，我们希望之后可以说一些其他的内容，例如我们需要支持第三方开发者进行扩展，让第三方开发者可以在不修改源码的情况下可以自定义内容。

下面首先介绍一下entry_points:

entry_points中文名为入口点，是一种元数据，可以在安装时由包公开，可以通过如下两种方式获取所有的entry_points：

使用importlib.metadata中的entry_points获取当前电脑中安装的所有entry_points，一般来说，一个python模块至少有一个entry_points。具体使用如下:
from importlib.metadata import entry_points
display_eps = entry_points()
for item in display_eps:
print(item)
使用pkg_resources的iter_entry_points方法获取特定entry_points，需要注意的是返回的是一个生成器，需要使用遍历或者转换为列表、集合等才可以正常显示。
from pkg_resources import iter_entry_points
display_eps = list(iter_entry_points(group))
entry_points在python生态系统中有着非常重要的作用，尤其如下两点:
支持生成控制台脚本，希望直接在命令行中执行的命令，例如上方的hello,world示例中将hello,world包装成一个可执行程序，方便直接在命令行中运行。
支持软件包的自定义插件。也可以作为软件包的解耦，例如ROS2官方推荐的编译工具colcon，colcon中的build过程，源代码包为colcon-core，其中只包含了基础的操作命令，其他的例如discovery、 package selection，详细参考：https://colcon.readthedocs.io/en/released/reference/verb/build.html?highlight=colcon-core#build-build-packages，均是通过entrypoints动态加载的。
介绍完entry_points后，下来进行对于hello-world示例的升级。
假设存在如下hello,world目录结构，此包就是提供给其他人进行扩展，核心就在于它本身基于entry_points获取所有的接入点及对应调用函数。

│  setup.cfg
│  setup.py
│  
├─hello
│  │  hello_impl.py
│  │  __init__.py

setup.cfg

[metadata]
name = hello-world
version = "1.0.0"
description = "helloworld description"

[option]
python_requires = >=3.6
packages = find:
zip_safe = false
include_package_data = True

[options.entry_points]
console_scripts =
    hello-world = hello.hello_impl:main

setup.py：与上述生成控制台脚本示例的setup一致，仅作安装导入setup.cfg配置使用。
__init__.py：作为识别包用，空文件。
hello_impl.py

from pkg_resources import iter_entry_points

def get_entry_points():
    ret = {}
    group = "hello_world.hello"
    # 获取此电脑python环境中的接入点为hello_world.hello的所有接入点
    for entry_point in iter_entry_points(group):
        # 对entry_point的load是获取注册接入点对应的function
        ret[entry_point.name] = entry_point.load()
    return ret

def main():
    # 获取所有的接入点的方法并执行
    for func in get_entry_points().values():
        func()

基于上述的hello,world使用python setup.py develop进行编译后可以产生一个hello-world可执行程序，执行时会发现没有任何的输出，因为没有相应的接入点导入。
下面注册一个接入点为hello_world.hello的hello-world2项目，目录结构与hello-world类似，如下：

│  setup.cfg
│  setup.py
│  
└─hello2
        hello_impl_custom.py
        __init__.py

setup.cfg：与setup.cfg类似，区别在于项目名称。最主要的是注册了一个hello_world.hello的接入点，并且调用的是包hello2.hello_impl_custom的say方法。

[metadata]
name = hello-world2
version = "1.0.0"
description = "helloworld description"

[option]
python_requires = >=3.6
packages = find:
zip_safe = false

[options.entry_points]
hello_world.hello = 
    hello-world_custom_say2 = hello2.hello_impl_custom:say
console_scripts =
    hello-world2 = hello2.hello_impl_custom:main

setup.py：与上述生成控制台脚本示例的setup一致，仅作安装导入setup.cfg配置使用。
__init__.py：作为识别包用，空文件
hello_impl_custom.py

def say():
    print("hello_impl_custom say2")

def main():
    say()

使用python setup.py develop编译完后，会生成hello-world2程序，这时电脑中会有一个接入点：

hello-world_custom_say2 = hello2.hello_impl_custom:say

这时，再次使用hello-world时会输出hello_impl_custom say2，由此可见，虽然hello-world中没有对应输出内容，通过entry_points动态加载了hello-world2的对应内容。
对于entry_points来说，当你注册了一个接入点时，会在当前python环境下的新增一个新的接入点，所有的接入点会形成一个集合，当你需要使用接入点时，只需使用pkg_resources 获取符合自己的接入点，一般而言，所有python模块均有权限获取对应的接入点内容，获取结果的成功与否取决于包名是否正确，接入点的格式如下：

<user_defined_key> = <python_package:object_name>"

<user_defined_key> 是开发者定义的跟业务高度相关的 Key，正常保证不重复即可，<python_package:object_name> python_package：为python的包名，注意是相对路径，object_name：为对象名，一般为函数名或者类名。
接入点的操作示意图如下：接入点可以被多个模块所添加，当然获取接入点也可以被多个模块所获取。第三方扩展支持其实就相当于添加接入点的新程序，支持扩展的程序则会在执行时每次从当前python环境中获取对应包的所有接入点，从而进行相应处理。

setup进行打包时如何添加除python文件外的资源文件

需要使用MANIFEST.in文件，与setup.py文件同级，其中存放需要添加的资源文件，主要使用include参数，详细参数可见MANIFEST.in参数介绍
需要注意的是添加资源文件以MANIFEST.in作为开始的路径，且需要到达资源文件的上级目录，例如需要添加hello/test/test.ini文件，则可以进行如下配置:

include hello/test/*

如何打包成whl包？

安装wheel模块

pip install wheel

在setup.py所在路径进行打包

python .\setup.py sdist bdist_wheel

posted @ 2022-12-20 14:25 形同陌路love 阅读(3089) 评论(0) 编辑收藏举报

刷新页面返回顶部

xy-bot