28.4. `zipapp` — 管理可执行文件 Python zip 存档 ¶

3.5 版新增。

This module provides tools to manage the creation of zip files containing Python code, which can be executed directly by the Python interpreter . The module provides both a 命令行接口和 Python API .

28.4.1. 基本范例 ¶

以下范例展示如何命令行接口 can be used to create an executable archive from a directory containing Python code. When run, the archive will execute the main function from the module myapp in the archive.

$ python -m zipapp myapp -m "myapp:main"
$ python myapp.pyz
<output from myapp>

28.4.2. 命令行接口 ¶

When called as a program from the command line, the following form is used:

$ python -m zipapp source [options]

若 source is a directory, this will create an archive from the contents of source 。若 source is a file, it should be an archive, and it will be copied to the target archive (or the contents of its shebang line will be displayed if the –info option is specified).

The following options are understood:

-o <output> , --output =<output> ¶

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

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

--info ¶

-h , --help ¶

28.4.3. Python API ¶

The module defines two convenience functions:

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

zipapp. get_interpreter ( archive ) ¶

28.4.4. 范例 ¶

Pack up a directory into an archive, and run it.

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

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

>>> import zipapp
>>> zipapp.create_archive('myapp.pyz', 'myapp')

To make the application directly executable on POSIX, specify an interpreter to use.

$ python -m zipapp myapp -p "/usr/bin/env python"
$ ./myapp.pyz
<output from myapp>

To replace the shebang line on an existing archive, create a modified archive using the create_archive() 函数：

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

To update the file in place, do the replacement in memory using a BytesIO object, and then overwrite the source afterwards. Note that there is a risk when overwriting a file in place that an error will result in the loss of the original file. This code does not protect against such errors, but production code should do so. Also, this method will only work if the archive fits in memory:

>>> import zipapp
>>> import io
>>> temp = io.BytesIO()
>>> zipapp.create_archive('myapp.pyz', temp, '/usr/bin/python2')
>>> with open('myapp.pyz', 'wb') as f:
>>>     f.write(temp.getvalue())

Note that if you specify an interpreter and then distribute your application archive, you need to ensure that the interpreter used is portable. The Python launcher for Windows supports most common forms of POSIX #! line, but there are other issues to consider:

If you use “/usr/bin/env python” (or other forms of the “python” command, such as “/usr/bin/python”), you need to consider that your users may have either Python 2 or Python 3 as their default, and write your code to work under both versions.
If you use an explicit version, for example “/usr/bin/env python3” your application will not work for users who do not have that version. (This may be what you want if you have not made your code Python 2 compatible).
There is no way to say “python X.Y or later”, so be careful of using an exact version like “/usr/bin/env python3.4” as you will need to change your shebang line for users of Python 3.5, for example.

28.4.5. The Python Zip Application Archive Format ¶

Python has been able to execute zip files which contain a __main__.py file since version 2.6. In order to be executed by Python, an application archive simply has to be a standard zip file containing a __main__.py file which will be run as the entry point for the application. As usual for any Python script, the parent of the script (in this case the zip file) will be placed on sys.path and thus further modules can be imported from the zip file.

The zip file format allows arbitrary data to be prepended to a zip file. The zip application format uses this ability to prepend a standard POSIX “shebang” line to the file ( #!/path/to/interpreter ).

Formally, the Python zip application format is therefore:

An optional shebang line, containing the characters b'#!' followed by an interpreter name, and then a newline ( b'\n' ) character. The interpreter name can be anything acceptable to the OS “shebang” processing, or the Python launcher on Windows. The interpreter should be encoded in UTF-8 on Windows, 和在 sys.getfilesystemencoding() on POSIX.
Standard zipfile data, as generated by the zipfile 模块。 zipfile content must include a file called __main__.py (which must be in the “root” of the zipfile - i.e., it cannot be in a subdirectory). The zipfile data can be compressed or uncompressed.

If an application archive has a shebang line, it may have the executable bit set on POSIX systems, to allow it to be executed directly.

There is no requirement that the tools in this module are used to create application archives - the module is a convenience, but archives in the above format created by any means are acceptable to Python.

28.4. zipapp — 管理可执行文件 Python zip 存档 ¶