Python 的 zipapp：构建可执行的 Zip 应用程序

什么是 Python Zip 应用程序？

PEP 441 – 改进 Python ZIP 应用程序支持使Python Zip 应用程序的思想、术语和规范正式化。这种类型的应用程序由一个使用ZIP 文件格式的文件组成，并包含 Python 可以作为程序执行的代码。这些应用程序依赖于 Python 从 ZIP 文件中运行代码的能力，这些 ZIP 文件__main__.py的根有一个模块，作为入口点脚本工作。

自2.6 和 3.0版本以来，Python 已经能够从 ZIP 文件运行脚本。实现这一目标的步骤非常简单。您只需要一个 ZIP 文件__main__.py，其根目录下有一个模块。然后，您可以将该文件传递给 Python，Python 将其添加到程序中sys.path并__main__.py作为程序执行。将应用程序的存档放入sys.path允许您通过 Python 的导入系统访问其代码。

作为所有工作原理的快速示例，假设您在类 Unix操作系统上，例如 Linux 或 macOS，并运行以下命令：

$ echo 'print("Hello, World!")' > __main__.py

$ zip hello.zip __main__.py
  adding: __main__.py (stored 0%)

$ python ./hello.zip
Hello, World!

您可以使用该echo命令创建一个__main__.py包含代码的文件print("Hello, World!")。然后使用该zip命令归档__main__.py到hello.zip. 完成后，您可以hello.zip通过将文件名作为参数传递给python命令来作为程序运行。

为了总结 Python Zip 应用程序的内部结构，您需要一种方法来告诉操作系统如何执行它们。ZIP 文件格式允许您在 ZIP 存档的开头添加任意数据。Python Zip 应用程序利用该功能在应用程序的存档中包含标准的Unix shebang行：

#!/usr/bin/env python3

在 Unix 系统上，这一行告诉操作系统使用哪个程序来执行手头的文件，以便您可以直接运行该文件而无需python命令。在 Windows 系统上，Python 启动器正确理解 shebang 行并为您运行 Zip 应用程序。

即使使用 shebang 行，您始终可以通过将应用程序的文件名作为参数传递给python命令来执行 Python Zip 应用程序。

总之，要构建 Python Zip 应用程序，您需要：

• 使用标准 ZIP 文件格式并在其根目录包含一个__main__.py模块的存档
• 一个可选的shebang 行，指定合适的Python 解释器来运行应用程序

除了__main__.py模块之外，应用程序的 ZIP 文件还可以包含 Python模块和包以及任何其他任意文件。但是，只有.py、.pyc和.pyo文件可通过导入系统直接使用。换句话说，您可以在应用程序文件中打包.pyd、.so和.dll文件，但除非将它们解压缩到文件系统中，否则将无法使用它们。

PEP 441 提出.pyz并.pyzw作为Python Zip 应用程序的文件扩展名。的.pyz分机识别控制台或命令行应用程序，而.pyzw扩展名是指窗或GUI应用程序。

在 Unix 系统上，.pyz如果您更喜欢 CLI 应用程序的简单命令名称，则可以删除扩展名。在 Windows 上，.pyz和.pyzw文件是可执行文件，因为 Python 解释器将它们注册为可执行文件。

为什么要使用 Python Zip 应用程序？

假设您有一个程序，您的团队在其内部工作流程中经常使用该程序。该程序已经从单个文件脚本发展成为具有多个包、模块和文件的成熟应用程序。

此时，一些团队成员难以安装和设置每个新版本。他们不断要求您提供一种更快、更简单的方法来设置和运行程序。在这种情况下，您应该考虑创建一个 Python Zip 应用程序，将您的程序捆绑到一个文件中，并将其作为一个随时可用的应用程序分发给您的同事。

Python Zip 应用程序是发布必须作为单个可执行文件分发的软件的绝佳选择。这也是使用非正式渠道分发软件的便捷方式，例如通过计算机网络发送软件或将其托管在 FTP 服务器上。

Python Zip 应用程序是一种方便快捷的方法，可以将 Python 应用程序打包和分发为即用型格式，可以让您的最终用户的生活更加愉快。

设置 Python Zip 应用程序

到目前为止，您已经了解了什么是 Python Zip 应用程序、如何构建它们、为什么使用它们以及在创建它们时需要遵循哪些步骤。您已准备好开始构建自己的。不过，首先，您需要有一个可用于 Python Zip 应用程序的功能性应用程序或脚本。

在本教程中，您将使用一个名为 的示例应用程序reader，它是一个最小的Web 订阅源阅读器，可以从Real Python feed读取最新的文章和资源。

接下来，您应该将 的存储库克隆reader到本地计算机中。在您选择的工作目录中打开命令行并运行以下命令：

$ git clone https://github.com/realpython/reader.git

此命令将reader存储库的完整内容下载到reader/当前目录中的文件夹中。

克隆存储库后，您需要安装应用程序的依赖项。首先，您应该创建一个 Python虚拟环境。继续并运行以下命令：

$ cd reader/
$ python3 -m venv ./venv
$ source venv/bin/activate

这些命令在reader/目录中创建并激活一个新的 Python 虚拟环境，该目录是reader项目的根目录。

C:\> python -m venv venv
C:\> venv\Scripts\activate.bat

现在您可以安装reader使用的依赖项pip：

(venv) $ python -m pip install feedparser html2text importlib_resources

运行上面的命令将在活动的 Python 虚拟环境中安装所有应用程序的依赖项。

下面是一个reader用于从Real Python获取最新文章、课程、播客集和其他学习资源列表的示例：

(venv) $ python -m reader
The latest tutorials from Real Python (https://realpython.com/)
  0 The Django Template Language: Tags and Filters
  1 Pass by Reference in Python: Best Practices
  2 Using the "and" Boolean Operator in Python
    ...

由于reader在提要中列出了 30 个最新的学习资源，因此此输出对您来说会有所不同。每个学习资源都有一个 ID 号。要从这些学习资源中获取一项的内容，您可以将相应的 ID 号作为命令行参数传递给reader：

(venv) $ python -m reader 2
Using the "and" Boolean Operator in Python

Python has three Boolean operators, or **logical operators** : `and`, `or`,
and `not`. You can use them to check if certain conditions are met before
deciding the execution path your programs will follow. In this tutorial,
you'll learn about the `and` operator and how to use it in your code.
    ...

此命令使用Markdown文本格式将文章Using the “and” Boolean Operator in Python 的部分内容打印到屏幕上。您可以通过更改 ID 号来阅读任何可用的内容。

要从reader存储库创建 Zip 应用程序，您将主要使用该reader/文件夹。该文件夹具有以下结构：

reader/
|
├── config.cfg
├── feed.py
├── __init__.py
├── __main__.py
└── viewer.py

从reader/目录中要注意的最重要的事实是它包含一个__main__.py文件。该文件使您能够python -m reader像以前一样使用命令执行包。

拥有__main__.py文件提供了创建 Python Zip 应用程序所需的入口点脚本。在此示例中，__main__.py文件位于reader包内。如果您使用此目录结构创建 Zip 应用程序，则您的应用程序将无法运行，因为__main__.py无法从.zip 文件导入对象reader。

要解决此问题，请将reader包复制到名为的外部目录realpython/并将__main__.py文件放在其根目录下。然后删除__pycache__/运行结果的文件夹，python -m reader您之前这样做过。您应该最终得到以下目录结构：

realpython/
│
├── reader/
│   ├── __init__.py
│   ├── config.cfg
│   ├── feed.py
│   └── viewer.py
│
└── __main__.py

有了这个新的目录结构，您就可以使用zipapp. 这就是您将在下一节中执行的操作。

zipapp从命令行使用

的命令行界面zipapp简化了将 Python 应用程序打包成 ZIP 文件的过程。在内部，zipapp通过运行您之前学习的步骤从源代码创建一个 Zip 应用程序。

要从命令行运行zipapp，您应该使用以下命令语法：

$ python -m zipapp <source> [OPTIONS]

如果source是目录，则此命令将从该目录的内容创建一个 Zip 应用程序。如果source是文件，则该文件应该是包含应用程序代码的 ZIP 文件。然后将输入 ZIP 文件的内容复制到目标应用程序存档。

以下是zipapp接受的命令行选项的摘要：

运行 Python Zip 应用程序

到目前为止，您已经学习了如何使用zipapp命令行和 Python 代码创建 Python Zip 应用程序。现在是时候运行您的realpython.pyz应用程序以确保其正常工作。

如果您使用的是类 Unix 系统，那么您可以通过执行以下命令来运行您的应用程序：

(venv) $ ./realpython.pyz
The latest tutorials from Real Python (https://realpython.com/)
  0 The Django Template Language: Tags and Filters
  1 Pass by Reference in Python: Best Practices
  2 Using the "and" Boolean Operator in Python
    ...

凉爽的！有用！现在您拥有一个可以快速与朋友和同事共享的应用程序文件。

您不再需要调用 Python 来从命令行运行应用程序。由于您的 Zip 应用程序存档在开头有一个 shebang 行，因此操作系统将自动使用您的活动 Python 解释器来运行目标存档的内容。

如果您使用的是 Windows，那么您的 Python 安装应该已经注册.pyz和.pyzw文件并且应该能够运行它们：

C:\> .\realpython.pyz
The latest tutorials from Real Python (https://realpython.com/)
  0 The Django Template Language: Tags and Filters
  1 Pass by Reference in Python: Best Practices
  2 Using the "and" Boolean Operator in Python
    ...

reader您在本教程中使用的应用程序有一个命令行界面，因此从命令行或终端窗口运行它是有意义的。但是，如果您有一个 GUI 应用程序，那么您将能够从您最喜欢的文件管理器中运行它，就像您通常运行可执行应用程序一样。

同样，您可以通过使用应用程序的文件名作为参数调用适当的 Python 解释器来执行任何 Zip 应用程序：

$ python3 realpython.pyz
The latest tutorials from Real Python (https://realpython.com/)
  0 The Django Template Language: Tags and Filters
  1 Pass by Reference in Python: Best Practices
  2 Using the "and" Boolean Operator in Python
    ...

在本例中，您使用系统 Python 3.x 安装来运行realpython.pyz. 如果您的系统上有许多 Python 版本，那么您可能需要更具体并使用类似python3.9 realpython.pyz.

请注意，无论您使用什么解释器，都需要安装应用程序的依赖项。否则，您的应用程序将失败。不满意的依赖是 Python Zip 应用程序的常见问题。要解决这种烦人的情况，您可以创建一个独立的应用程序，这是下一节的主题。

创建一个独立的 Python Zip 应用程序 zipapp

您还可以使用zipapp创建自包含或独立的 Python Zip 应用程序。这种类型的应用程序将其所有依赖项捆绑到应用程序的 ZIP 文件中。这样，您的最终用户只需要一个合适的 Python 解释器来运行应用程序。他们不需要担心依赖关系。

要创建独立的 Python Zip 应用程序，首先需要使用pip. 继续并realpython/使用名称创建目录的副本realpython_sa/。然后运行以下命令来安装应用程序的依赖项：

(venv) $ python -m pip install feedparser html2text importlib_resources \
--target realpython_sa/

此命令安装与选项一起reader使用的所有依赖项。的文档说此选项允许您将软件包安装到目标目录中。在此示例中，该目录必须是您的应用程序的源目录.pip install--targetpiprealpython_sa/

(venv) $ python -m pip install \
-r requirements.txt \
--target app_directory/

安装readerinto的依赖项后realpython_sa/，您可以选择删除创建的*.dist-info目录pip。这些目录包含几个带有元数据的文件，pip用于管理相应的包。由于您不再需要该信息，因此可以将其删除。

该过程的最后一步是zipapp像往常一样使用以下命令构建 Zip 应用程序：

(venv) $ python -m zipapp realpython_sa/ \
-p "/usr/bin/env python3" \
-o realpython_sa.pyz \
-c

此命令生成一个独立的 Python Zip 应用程序realpython_sa.pyz。要运行此应用程序，您的最终用户只需要在他们的机器上安装一个合适的 Python 3 解释器。与常规 Zip 应用程序相比，此类应用程序的优势在于您的最终用户无需安装任何依赖项即可运行该应用程序。来试试看吧！

在上面的示例中，您使用 的-c选项zipapp来压缩realpython_sa/. 对于具有许多依赖项且占用大量磁盘空间的应用程序，此选项非常方便。

手动创建 Python Zip 应用程序

正如您已经了解到的那样，zipapp自 Python 3.5 以来，标准库中已经提供了。如果您使用的 Python 版本低于该版本，那么您仍然可以手动构建 Python Zip 应用程序，而无需zipapp.

在以下两节中，您将学习如何使用zipfilePython 标准库创建 Zip 应用程序。您还将学习如何使用一些命令行工具来完成相同的任务。

# build_app.py

import pathlib
import stat
import zipfile

app_source = pathlib.Path("realpython/")
app_filename = pathlib.Path("realpython.pyz")

with open(app_filename, "wb") as app_file:
    # 1. Prepend a shebang line
    shebang_line = b"#!/usr/bin/env python3\n"
    app_file.write(shebang_line)

    # 2. Zip the app's source
    with zipfile.ZipFile(app_file, "w") as zip_app:
        for file in app_source.rglob("*"):
            member_file = file.relative_to(app_source)
            zip_app.write(file, member_file)

# 3. Make the app executable (POSIX systems only)
current_mode = app_filename.stat().st_mode
exec_mode = stat.S_IEXEC
app_filename.chmod(current_mode | exec_mode)

使用第三方工具创建 Python 应用程序

在 Python 生态系统中，您会发现一些与zipapp. 它们提供了更多功能，可以用于探索。在本节中，您将了解其中两个第三方库：pex和shiv.

该pex项目提供了一个创建 PEX 文件的工具。PEX 代表Python 可执行文件，是一种存储独立的可执行 Python 虚拟环境的文件格式。该pex工具将这些环境打包成带有 shebang 行和__main__.py模块的ZIP 文件，允许您直接执行生成的 PEX 文件。该pex工具是对 PEP 441 中概述的想法的扩展。

要使用 来创建可执行应用程序pex，您首先需要安装它：

(venv) $ python -m pip install pex
(venv) $ pex --help
pex [-o OUTPUT.PEX] [options] [-- arg1 arg2 ...]

pex builds a PEX (Python Executable) file based on the given specifications:
sources, requirements, their dependencies and other options.
Command-line options can be provided in one or more files by prefixing the
filenames with an @ symbol. These files must contain one argument per line.
    ...

该pex工具提供了一组丰富的选项，可让您微调 PEX 文件。以下命令显示了如何为reader项目创建 PEX 文件：

(venv) $ pex realpython-reader -c realpython -o realpython.pex

此命令realpython.pex在您的当前目录中创建。这个文件是一个 Python 可执行文件，用于reader. 请注意，它pex处理PyPI的安装reader及其所有依赖项。该reader项目在 PyPI 上可用，名称为realpython-reader，这就是为什么您使用该名称作为pex.

该-c选项允许您定义应用程序将使用哪个控制台脚本。在这种情况下，控制台脚本realpython中定义setup.py的文件reader。该-o选项指定输出文件。像往常一样，您可以./realpython.pex从命令行执行以运行应用程序。

由于内容.pex文件被执行之前解压缩，PEX应用程序解决的限制zipapp应用程序，并允许您从执行代码.pyd，.so和.dll文件。

最后要注意的细节是pex在生成的 PEX 文件中创建和打包 Python 虚拟环境。这种行为使您的 Zip 应用程序比使用zipapp.

您将在本节中学习的第二个工具是shiv. 它是在PEP 441描述构建自成体系的Python邮编应用程序的命令行实用程序的优点shiv相比，zipapp是shiv会自动包括所有在最后归档应用程序的依赖关系，使他们在Python的可用模块搜索路径。

要使用shiv，您需要从 PyPI 安装它：

(venv) $ python -m pip install shiv
(venv) $ shiv --help
Usage: shiv [OPTIONS] [PIP_ARGS]...

  Shiv is a command line utility for building fully self-contained Python
  zipapps as outlined in PEP 441, but with all their dependencies included!
    ...

该--help选项显示完整的使用消息，您可以查看该消息以快速了解shiv工作原理。

要使用 构建 Python Zip 应用程序shiv，您需要一个带有setup.py或pyproject.toml文件的可安装 Python 应用程序。幸运的是，reader来自 GitHub的原始项目满足了这个要求。返回包含克隆reader/文件夹的目录并运行以下命令：

(venv) $ shiv -c realpython \
-o realpython.pyz reader/ \
-p "/usr/bin/env python3"

与该pex工具一样，shiv可以-c选择为应用程序定义控制台脚本。在-o和-p选项允许你提供一个输出文件名和适当的Python解释器，分别。

不像zipapp，shiv使您可以使用.pyd，.so以及.dll文件在应用程序的归档存储。为此，shiv在存档中包含一个特殊的引导功能。此函数将应用程序的依赖项解压到.shiv/您的主文件夹中的一个目录中，并将它们添加到 Python 的sys.path.

此功能允许您创建独立的应用程序，其中包含部分用 C 和 C++ 编写的库以提高速度和效率，例如NumPy。