28.4. zipapp — Manage executable python zip archives

    源代码：

    本模块提供了一套管理工具，用于创建包含 Python 代码的压缩文件，这些文件可以 直接由 Python 解释器执行。 本模块提供 和 Python API。

    下述例子展示了用 根据含有 Python 代码的目录创建一个可执行的打包文件。 运行后该打包文件时，将会执行 模块中的 main 函数。

    28.4.2. 命令行界面

    若要从命令行调用，则采用以下形式：

    1. $ python -m zipapp source [options]

    如果 source 是个目录，将根据 source 的内容创建一个打包文件。如果 source 是个文件，则应为一个打包文件，将会复制到目标打包文件中（如果指定了 -info 选项，将会显示 shebang 行的内容）。

    可以接受以下参数：

    -o <output>``, --output``=<output>

    将程序的输出写入名为 output 的文件中。若未指定此参数，输出的文件名将与输入的 source 相同，并添加扩展名 .pyz。如果显式给出了文件名，将会原样使用（因此必要时应包含扩展名 .pyz）。

    如果 source 是个打包文件，必须指定一个输出文件名（这时 output 必须与 source 不同）。

    -p <interpreter>``, --python``=<interpreter>

    给打包文件加入 #! 行，以便指定 解释器 作为运行的命令行。另外，还让打包文件在 POSIX 平台上可执行。默认不会写入 #! 行，也不让文件可执行。

    -m <mainfn>``, --main``=<mainfn>

    在打包文件中写入一个 __main__.py 文件，用于执行 mainfn。mainfn 参数的形式应为 “pkg.mod:fn”，其中 “pkg.mod”是打包文件中的某个包/模块，“fn”是该模块中的一个可调用对象。__main__.py 文件将会执行该可调用对象。

    在复制打包文件时，不能设置 参数。

    --info

    显示嵌入在打包文件中的解释器程序，以便诊断问题。这时会忽略其他所有参数，SOURCE 必须是个打包文件，而不是目录。

    -h``, --help

    打印简短的用法信息并退出。

    该模块定义了两个快捷函数：

    zipapp.create_archive(source, target=None, interpreter=None, main=None)

    由 source 创建一个应用程序打包文件。source 可以是以下形式之一：

    • The name of a directory, or a pathlib.Path object referring to a directory, in which case a new application archive will be created from the content of that directory.

    • The name of an existing application archive file, or a object referring to such a file, in which case the file is copied to the target (modifying it to reflect the value given for the interpreter argument). The file name should include the .pyz extension, if required.

    target 参数定义了打包文件的写入位置：

    • If it is the name of a file, or a pathlb.Path object, the archive will be written to that file.

    • 若是个打开的文件对象，打包文件将写入该对象，该文件对象必须在字节串写入模式下打开。

    • 如果省略了 target （或为 None），则 source 必须为一个目录，target 将是与 source 同名的文件，并加上 .pyz 扩展名。

    参数 interpreter 指定了 Python 解释器程序名，用于执行打包文件。这将以 “释伴（shebang）”行的形式写入打包文件的头部。在 POSIX 平台上，操作系统会进行解释，而在 Windows 平台则会由 Python 启动器进行处理。省略 interpreter 参数则不会写入释伴行。如果指定了解释器，且目标为文件名，则会设置目标文件的可执行属性位。

    参数 main 指定某个可调用程序的名称，用作打包文件的主程序。仅当 source 为目录且不含 __main__.py 文件时，才能指定该参数。main 参数应采用 “pkg.module:callable”的形式，通过导入“pkg.module”并不带参数地执行给出的可调用对象，即可执行打包文件。如果 source 是目录且不含``__main__.py`` 文件，省略 main 将会出错，生成的打包文件将无法执行。

    若 source 或 target 指定的是文件对象，则调用者有责任在调用 create_archive 之后关闭文件。

    当复制已有的打包文件时，提供的文件对象只需 read 和 readline 方法，或 write 方法。当由目录创建打包文件时，若目标为文件对象，将会将其传给 类，且必须提供 类所需的方法。

    zipapp.get_interpreter(archive)

    返回打包文件开头的 行指定的解释器程序。如果没有 #! 行，则返回 None。参数 archive 可为文件名或在字节串模式下打开以供读取的文件类对象。#! 行假定是在打包文件的开头。

    28.4.4. 例子

    将目录打包成一个文件并运行它。

    1. $ python -m zipapp myapp
    2. $ python myapp.pyz
    3. <output from myapp>

    The same can be done using the create_archive() functon:

    要让应用程序能在 POSIX 平台上直接执行，需要指定所用的解释器。

    1. $ ./myapp.pyz
    2. <output from myapp>

    若要替换已有打包文件中的释伴行，请用 函数另建一个修改好的打包文件：

    1. >>> import zipapp
    2. >>> zipapp.create_archive('old_archive.pyz', 'new_archive.pyz', '/usr/bin/python3')

    若要原地更新打包文件，可用 BytesIO 对象在内存中进行替换，然后再覆盖源文件。注意，原地覆盖文件会有风险，出错时会丢失原文件。这里没有考虑出错情况，但生产代码则应进行处理。另外，这种方案仅当内存足以容纳打包文件时才有意义：

    注意，如果指定了解释器程序再发布应用程序打包文件，需要确保所用到的解释器是可移植的。Windows 的 Python 启动器支持大多数常见的 POSIX #! 行，但还需要考虑一些其他问题。

    • 如果采用“/usr/bin/env python”（或其他格式的 python 调用命令，比如“/usr/bin/python”)，需要考虑默认版本既可能是 Python 2 又可能是 Python 3，应让代码在两个版本下均能正常运行。

    • 如果用到的 Python 版本明确，如“/usr/bin/env python3”，则没有该版本的用户将无法运行应用程序。（如果代码不兼容 Python 2，可能正该如此）。

    • 因为无法指定“python X.Y以上版本”，所以应小心“/usr/bin/env python3.4”这种精确版本的指定方式，因为对于 Python 3.5 的用户就得修改释伴行，比如：

    通常应该用“/usr/bin/env python2”或“/usr/bin/env python3”的格式，具体根据代码适用于 Python 2 还是 3 而定。

    28.4.6. 用 zipapp 创建独立运行的应用程序

    利用 模块可以创建独立运行的 Python 程序，以便向最终用户发布，仅需在系统中装有合适版本的 Python 即可运行。操作的关键就是把应用程序代码和所有依赖项一起放入打包文件中。

    创建独立运行打包文件的步骤如下：

    1. 照常在某个目录中创建应用程序，于是会有一个 myapp 目录，里面有个``__main__.py`` 文件，以及所有支持性代码。

      1. $ python -m pip install -r requirements.txt --target myapp

      （这里假定在 requirements.txt 文件中列出了项目所需的依赖项，也可以在 pip 命令行中列出依赖项）。

    3. pip 在 myapp 中创建的 .dist-info 目录，是可以删除的。这些目录保存了 pip 用于管理包的元数据，由于接下来不会再用到 pip，所以不是必须存在，当然留下来也不会有什么坏处。

    4. 用以下命令打包：

      1. $ python -m zipapp -p "interpreter" myapp

    这会生成一个独立的可执行文件，可在任何装有合适解释器的机器上运行。详情参见 指定解释器程序。可以单个文件的形式分发给用户。

    在 Unix 系统中，myapp.pyz 文件将以原有文件名执行。如果喜欢 “普通”的命令名，可以重命名该文件，去掉扩展名 .pyz 。在 Windows 系统中，myapp.pyz[w] 是可执行文件，因为 Python 解释器在安装时注册了扩展名``.pyz`` 和 .pyzw 。

    在 Windows 系统中，可能没有注册扩展名 .pyz，另外有些场合无法“透明”地识别已注册的扩展（最简单的例子是，subprocess.run(['myapp']) 就找不到——需要明确指定扩展名）。

    因此，在 Windows 系统中，通常最好 由zipapp 创建一个可执行文件。虽然需要用到 C 编译器，但还是相对容易做到的。基本做法有赖于以下事实，即 zip 文件内可预置任意数据，Windows 的 exe 文件也可以附带任意数据。因此，创建一个合适的启动程序并将 .pyz 文件附在后面，最后就能得到一个单文件的可执行文件，可运行 Python 应用程序。

    合适的启动程序可以简单如下：

    若已定义了预处理器符号 WINDOWS，上述代码将会生成一个 GUI 可执行文件。若未定义则生成一个可执行的控制台文件。

    直接使用标准的 MSVC 命令行工具，或利用 distutils 知道如何编译 Python 源代码，即可编译可执行文件：

    1. >>> from distutils.ccompiler import new_compiler
    3. >>> import sys
    4. >>> import os
    5. >>> from pathlib import Path
    7. >>>     src = Path(src)
    8. >>>     cc = new_compiler()
    9. >>>     exe = src.stem
    10. >>>     cc.add_include_dir(distutils.sysconfig.get_python_inc())
    11. >>>     cc.add_library_dir(os.path.join(sys.base_exec_prefix, 'libs'))
    12. >>>     # First the CLI executable
    13. >>>     objs = cc.compile([str(src)])
    14. >>>     cc.link_executable(objs, exe)
    15. >>>     # Now the GUI executable
    16. >>>     cc.define_macro('WINDOWS')
    17. >>>     objs = cc.compile([str(src)])
    18. >>>     cc.link_executable(objs, exe + 'w')
    20. >>> if __name__ == "__main__":
    21. >>>     compile("zastub.c")

    生成的启动程序用到了 “受限 ABI”，所以可在任意版本的 Python 3.x 中运行。只要用户的 PATH 中包含了 Python（python3.dll）路径即可。

    若要得到完全独立运行的发行版程序，可将附有应用程序的启动程序，与“内嵌版” Python 打包在一起即可。这样在架构匹配（32位或64位）的任一 PC 上都能运行。

    28.4.6.2. 注意事项

    要将应用程序打包为单个文件，存在一些限制。大多数情况下，无需对应用程序进行重大修改即可解决。

    1. 如果应用程序依赖某个带有 C 扩展的包，则此程序包无法由打包文件运行（这是操作系统的限制，因为可执行代码必须存在于文件系统中，操作系统才能加载）。这时可去除打包文件中的依赖关系，然后要求用户事先安装好该程序包，或者与打包文件一起发布并在 __main__.py 中增加代码，将未打包模块的目录加入 sys.path 中。采用增加代码方式时，一定要为目标架构提供合适的二进制文件（可能还需在运行时根据用户的机器选择正确的版本加入 sys.path）。

    2. 若要如上所述发布一个 Windows 可执行文件，就得确保用户在 PATH 中包含``python3.dll`` 的路径（安装程序默认不会如此），或者应把应用程序与内嵌版 Python 一起打包。

    3. 上述给出的启动程序采用了 Python 嵌入 API。 这意味着应用程序将会是 sys.executable ，而不是传统的 Python 解释器。代码及依赖项需做好准备。例如，如果应用程序用到了 multiprocessing 模块，就需要调用 来让模块知道标准 Python 解释器的位置。

    自 2.6 版开始，Python 即能够执行包含 文件的打包文件了。为了能被 Python 执行，应用程序的打包文件必须为包含 __main__.py 文件的标准 zip 文件，__main__.py 文件将作为应用程序的入口运行。类似于常规的 Python 脚本，父级（这里指打包文件）将放入 sys.path ，因此可从打包文件中导入更多的模块。

    zip 文件格式允许在文件中预置任意数据。利用这种能力，zip 应用程序格式在文件中预置了一个标准的 POSIX “释伴”行（#!/path/to/interpreter）。

    因此，Python zip 应用程序的格式会如下所示：

    1. 可选的释伴行，包含字符 ，后面是解释器名，然后是换行符 （b'\n'）。 解释器名可为操作系统 “释伴”处理所能接受的任意值，或为 Windows 系统中的 Python 启动程序。解释器名在 Windows 中应用 UTF-8 编码，在 POSIX 中则用 。

    如果应用程序的打包文件带有释伴行，则在 POSIX 系统中可能需要启用可执行属性，以允许直接执行。

    不一定非要用本模块中的工具创建应用程序打包文件，本模块只是提供了便捷方案，上述格式的打包文件可用任何方式创建，均可被 Python 接受。