Python打包指南2021

大家圣诞快乐,雕虫小技栏目又和大家见面了,谁让咱不会那些个屠龙之技,只好捉几个虫子玩玩了。 写这篇文章是因为过去的两年关于 pip 和 Python 包管理有几个重要的 PEP 发布,然而网上(中文世界)的打包发布教程很少有针对此的更新。 再加上我成为 PyPA 的成员已经尸位素餐快一年了,还是应该来做点贡献。

setup.py 真难写

似乎从有 Python 打包以来就有了 setuptools 这个库,你能搜到的教程,涉及打包发布的,都会让你编写那个可怕的 setup.py 。 不知道谁能完全掌握那个东西的写法,我到现在都还不太会。说几个常用的配置:

  1. 指定依赖和可选依赖

    setup(
    install_requires=["flask", "flask-migrate", "sqlalchemy"],
    extras_require={"mysql": ["mysqlclient"], "pgsql": ["psycopg2"]}
    )

    注意那两个 key 分别是 install_requiresextras_require ,别写错了。此外,如果你需要根据条件增减依赖的话,不要用

    INSTALL_REQUIRES = ["flask"]
    if sys.platform == "win32":
    INSTALL_REQUIRES.append("pywin32")
    setup(install_requires=INSTALL_REQUIRES)

    而应该使用 Environment Markers

    INSTALL_REQUIRES = [
    "flask",
    "pywin32; sys_platform == 'win32'"
    ]
    setup(install_requires=INSTALL_REQUIRES)
  2. 发布可执行程序到 /bin

    setup(
    entry_points={
    "console_scripts": ["mybin=mypackage.main:cli"]
    }
    )

    或者 ini 写法

    setup(
    entry_points="""[console_scripts]
    mybin = mypackage.main:cli
    """
    )

    任选其一。

  3. 包含 data 文件

    setup(
    include_package_data=True    # 从MANIFEST.in中读取配置
    )

    或者

    setup(
    package_data={"": ["*.json"]}  # 包含所有json文件
    )
  4. 指定源代码结构,如果你使用的是 src/ 存放包的源码这种项目结构,可以:

    setup(
    package_dir={"": "src"}
    )

打包上传和安装

打包

好了,这个万恶的 setup.py 我已经写好了,咱要发布 PyPI 了。第一步,打包成可分发的文件:

$ python setup.py sdist bdist_wheel --universal

这条命令会同时生成源代码包(Source Distribution),和二进制包(Binary Distribution)。当然,大部分的 Python 发布包中并不真的包含二进制, 只是沿用了软件工程中的一般叫法。其中 bdist_wheel 生成的二进制包是 wheel 格式(需要安装 wheel 才能打包), --universal 的意思是这个二进制包对所有 支持的 Python 版本和 ABI 都适用,「 一处打包,到处使用」,生成的文件名类似: my_package-0.1.0-py3-none-any.whl 。如果你包中有 C 扩展, 也就是打包出来的 wheel 会真的有二进制文件时就不能加这个 flag 了,这时生成的文件名类似: my_package-0.1.0-cp38-cp38-win_amd64.whl 。 这个文件名不是乱来的,是要遵循一定规则,下载器能直接从这个文件名获得这个包的基本信息:

上传

可能有老的教程,让你直接用 python setup.py sdist bdist_wheel register upload 打包上传一步到位,这个方式已经过时了不推荐使用。正确的方法应该用 twine 工具:

$ twine upload dist/*

如果你要把上传放到 CI 里自动执行,最好生成一个 token 来使用,访问 https://pypi.org/manage/account/token/ 按提示生成一个 token,使用的时候只要用命令指定下用户名和密码:

twine upload --username __token__ --password ${{ secrets.PYPI_TOKEN }} dist/*

安装

把包上传到 PyPI 以后, pip install my-package 的时候是怎么安装的呢?

  1. 访问 https://pypi.org/simple/my-package ,解析所有链接
  2. 若是 whl 文件,判断是否与当前 Python 版本、ABI、平台适配,加入到候选列表
  3. <a> 标签中读取 data-requires-python 属性,判断是否与当前 Python 版本兼容,加入候选列表
  4. 若是源代码包,直接加入候选列表

最终在候选列表中优先选择 whl 文件为待安装的包,将包下载到本地,候选包的选择可以由 pip install--only-binary--no-binary 选项控制。

现在准备安装了,如果待安装的是 whl,那就非常简单,直接解压(whl 文件是一种 zip 格式),放到目标目录即可,解压后产生的文件除了代码或二进制以外,还会包含一个 my_package-0.1.0.dist-info/ 目录,包含这个包的元数据信息,比如有哪些文件、文件 hash 值、entry_points 等等。

如果待安装的文件是源代码包,那么需要把这个压缩包解压到一个临时目录,根据包指定的方式编译构建,生成 whl 文件,再用 whl 安装同样的方法放到目标目录中。而这个指定的编译方式,在 PEP 517 提案之前,是调用 python setup.py install 命令。在 PEP 517 发布之后,则由 PEP 517 的 build backend 控制。

setuptools 不再是唯一的选择

PEP 517 的内容简单来说,就是在项目根目录下的 pyproject.toml 定义了两个特殊属性:

[build-system]
requires = ["setuptools >= 40.8.0", "wheel"]
build-backend = "setuptools.build_meta:__legacy__"

上面这个就是 setuptools 的 PEP 517 的配置,这样可以让老的项目,能直接用 PEP 517 的方式构建。如果你的项目中并没有 pyproject.toml 文件, pip 能自动填充为此缺省配置。其中 requires 意为这个 backend 依赖的包列表, build-backend 则为 backend 的具体位置。这个 backend 需要实现几个约定的接口:

  1. get_requires_for_build_wheel ,构建 wheel 需要的依赖列表,这个一般没有特殊要求都是空
  2. get_requires_for_build_sdist ,构建 sdist 需要的依赖列表,同上
  3. prepare_metadata_for_build_wheel ,生成一个 wheel 要用的 dist-info/ 文件夹
  4. build_wheel ,生成 wheel 文件
  5. build_sdist ,生成 sdist 文件

有了这些接口, pip 以及其他可能的 frontend 就能从源代码构建一个 wheel 出来。因此, pyproject.toml 必须被包含在源代码包中。

有了 PEP 517 的协议规范以后,backend 和 frontend 就能自由组合,不再是非 setuptools 不可了,实现了 PEP 517 的 backend 有:

所以我可以不用写 setup.py 了

setup.py 作为一个元数据的定义格式是有问题的:

  1. 必须由 Python 运行,无法静态解析
  2. 由于第 1 点,有注入恶意代码的操作可行性

所以需要指定一个元数据的配置格式,这个格式规范最近也定下来了,它就是 PEP 621,也是使用 pyproject.toml 来定义的。而且, PDM 已经支持这个配置格式了,仅此一家。

阅读链接

Frost's Blog
我还没有学会写个人说明!
上一篇

在2021年,可能会是前景比较好的五门编程语言

你也可能喜欢

评论已经被关闭。

插入图片