Python 的 zipapp 模块提供了一种将 Python 代码打包成可执行 .pyz 档案的便捷方式。通过这种方式，开发者可以将整个 Python 应用程序打包成一个独立的、可执行的压缩文件，这不仅简化了代码的分发，还能提升部署的效率。自 Python 3.5 版本起，zipapp 模块提供了命令行接口和 Python API 两种使用方式，让开发者能够灵活地管理和分发代码。

zipapp 模块的功能

zipapp 模块的主要功能包括：

• 创建可执行的 zip 档案：可以将一个目录或现有的 zip 档案打包成一个新的可执行 zip 档案。
• 指定解释器：通过“shebang”行（#!/path/to/interpreter）指定用于执行档案的 Python 解释器，在跨平台分发时非常有用。
• 设置主程序入口：可以指定一个可调用对象（通常是 __main__.py 文件）作为档案的主程序入口，方便执行时自动运行。
• 文件压缩：可以选择使用 deflate 算法压缩档案中的文件，以减小档案大小。
• 获取解释器信息：可以从现有的 zip 档案中提取 “shebang” 行指定的解释器信息，方便调试和兼容性检查。

zipapp 的使用方法

1. 命令行接口

zipapp 模块提供了简单的命令行接口，可以直接通过 Python 命令行执行。其使用格式为：

$ python -m zipapp source [options]

其中，source 可以是一个目录或一个现有的 zip 档案文件。以下是一些常用选项：

• -o <output> 或 --output=<output>：指定输出文件名。
• -p <interpreter> 或 --python=<interpreter>：指定解释器路径。
• -m <mainfn> 或 --main=<mainfn>：指定主程序入口文件（通常是 __main__.py）。
• -c 或 --compress：启用文件压缩，减少 .pyz 文件大小。
• --info：显示档案中嵌入的解释器信息。
• -h 或 --help：显示帮助信息。

示例 1：创建 .pyz 档案

假设你有一个名为 myapp 的目录，里面包含了 Python 代码和一个 __main__.py 作为应用程序入口。你可以使用以下命令将它打包为一个可执行的 .pyz 档案：

$ python -m zipapp myapp -o myapp.pyz -p "/usr/bin/env python3"

这将创建一个名为 myapp.pyz 的可执行档案，并指定解释器为 /usr/bin/env python3。你可以在 Unix 系统上直接执行该档案：

示例 2：启用文件压缩

如果你想通过压缩减少 .pyz 文件的大小，可以使用 --compress 选项：

$ python -m zipapp myapp -o myapp_compressed.pyz -p "/usr/bin/env python3" --compress

2. Python API

除了命令行接口，zipapp 模块还提供了两个常用的 API 函数，分别是 create_archive() 和 get_interpreter()。

create_archive() 函数

create_archive() 函数用于创建一个 Python 应用程序存档。其函数签名为：

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

参数说明：

• source：源目录、源档案文件名或文件对象。
• target：目标文件名或文件对象，指定输出的 .pyz 档案。
• interpreter：指定用于执行存档的解释器路径。
• main：主程序入口（例如 __main__.py 文件的模块路径）。
• filter：一个回调函数，用于过滤要添加到存档中的文件。
• compressed：是否启用文件压缩（默认为 False）。

示例 1：创建 .pyz 存档

import zipapp

# 将 myapp 目录打包为 myapp.pyz
zipapp.create_archive('myapp', 'myapp.pyz', interpreter='/usr/bin/env python3', main='myapp.__main__', compressed=True)

示例 2：更新存档并修改解释器

import zipapp

# 更新旧的存档，将新的解释器添加到存档中
zipapp.create_archive('old_archive.pyz', 'new_archive.pyz', interpreter='/usr/bin/python3.8')

get_interpreter() 函数

get_interpreter() 函数可以从现有的 .pyz 存档中提取出所指定的解释器路径。

import zipapp

# 获取存档中的解释器路径
interpreter = zipapp.get_interpreter('myapp.pyz')
print(interpreter)

使用 zipapp 创建独立应用程序

zipapp 模块不仅适用于简单的脚本，也可以用于创建独立的 Python 应用程序。通过将 Python 代码和所有依赖项打包成一个 .pyz 存档，最终用户只需安装合适的 Python 版本即可运行应用程序。

创建独立应用程序的步骤：

1. 在一个目录中创建你的应用程序，例如 myapp 目录，其中包含 __main__.py 文件和所有支持的 Python 模块。
2. 安装应用程序的依赖项（如果有的话），并将它们放到 myapp 目录中。你可以通过 pip 安装到目标目录：

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

3. 使用 zipapp 创建一个可执行的 .pyz 存档：

   $ python -m zipapp myapp -o myapp.pyz -p "/usr/bin/env python3"
   

4. 将 .pyz 文件分发给用户。用户只需确保安装了合适的 Python 版本，即可通过执行 .pyz 文件来运行应用程序。

注意事项

• C 扩展支持： 如果你的应用程序依赖于 C 扩展（例如使用了 numpy 等库），则无法直接从 .pyz 存档中运行。这是因为 C 扩展需要存在于文件系统中，以便操作系统加载。如果你的应用程序包含 C 扩展，考虑将这些依赖项排除在 .pyz 文件之外，或者要求用户安装它们。
• 跨平台兼容性： 使用 shebang 行时，需要注意不同平台上的兼容性。Unix 系统通常使用 /usr/bin/env python3 作为 Python 解释器的路径，而 Windows 系统使用 Python 启动器来处理 .pyz 文件。因此，要确保指定的解释器路径在目标平台上可用。

总结

zipapp 模块为 Python 开发者提供了一种便捷的方式来创建和管理可执行的 .pyz 存档。通过这种方式，开发者可以更方便地分发应用程序，并简化部署过程。无论是创建小型的命令行工具，还是构建独立的 Python 应用程序，zipapp 都是一个非常实用的工具。

通过本教程，您已经了解了如何使用 zipapp 创建 .pyz 存档，如何指定解释器、设置主程序入口，以及如何压缩档案和管理依赖项。希望这些信息能帮助您更高效地打包和部署 Python 项目。