基本範例¶

The following example shows how the命令執行列介面can be used to create an executable archive from a directory containingPython code. When run, the archive will execute themain function fromthe modulemyapp in the archive.

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

命令執行列介面¶

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

$python-mzipappsource[options]

Ifsource is a directory, this will create an archive from the contents ofsource. Ifsource is a file, it should be an archive, and it will becopied to the target archive (or the contents of its shebang line will bedisplayed if the --info option is specified).

The following options are understood:

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

Write the output to a file namedoutput. If this option is not specified,the output filename will be the same as the inputsource, with theextension.pyz added. If an explicit filename is given, it is used asis (so a.pyz extension should be included if required).

An output filename must be specified if thesource is an archive (and inthat case,output must not be the same assource).

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

Add a#! line to the archive specifyinginterpreter as the commandto run. Also, on POSIX, make the archive executable. The default is towrite no#! line, and not make the file executable.

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

Write a__main__.py file to the archive that executesmainfn. Themainfn argument should have the form "pkg.mod:fn", where "pkg.mod" is apackage/module in the archive, and "fn" is a callable in the given module.The__main__.py file will execute that callable.

--main cannot be specified when copying an archive.

-c,--compress¶

Compress files with the deflate method, reducing the size of the outputfile. By default, files are stored uncompressed in the archive.

--compress has no effect when copying an archive.

在 3.7 版被加入.

--info¶

Display the interpreter embedded in the archive, for diagnostic purposes. Inthis case, any other options are ignored and SOURCE must be an archive, not adirectory.

-h,--help¶

Print a short usage message and exit.

Python API¶

The module defines two convenience functions:

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

Create an application archive fromsource. The source can be anyof the following:

• The name of a directory, or apath-like object referringto a directory, in which case a new application archive will becreated from the content of that directory.

• The name of an existing application archive file, or apath-like objectreferring to such a file, in which case the file is copied tothe target (modifying it to reflect the value given for theinterpreterargument). The file name should include the.pyz extension, if required.

• A file object open for reading in bytes mode. The content of thefile should be an application archive, and the file object isassumed to be positioned at the start of the archive.

Thetarget argument determines where the resulting archive will bewritten:

• If it is the name of a file, or apath-like object,the archive will be written to that file.

• If it is an open file object, the archive will be written to thatfile object, which must be open for writing in bytes mode.

• If the target is omitted (orNone), the source must be a directoryand the target will be a file with the same name as the source, witha.pyz extension added.

Theinterpreter argument specifies the name of the Pythoninterpreter with which the archive will be executed. It is written asa "shebang" line at the start of the archive. On POSIX, this will beinterpreted by the OS, and on Windows it will be handled by the Pythonlauncher. Omitting theinterpreter results in no shebang line beingwritten. If an interpreter is specified, and the target is afilename, the executable bit of the target file will be set.

Themain argument specifies the name of a callable which will beused as the main program for the archive. It can only be specified ifthe source is a directory, and the source does not already contain a__main__.py file. Themain argument should take the form"pkg.module:callable" and the archive will be run by importing"pkg.module" and executing the given callable with no arguments. Itis an error to omitmain if the source is a directory and does notcontain a__main__.py file, as otherwise the resulting archivewould not be executable.

The optionalfilter argument specifies a callback function thatis passed a Path object representing the path to the file being added(relative to the source directory). It should returnTrue if thefile is to be added.

The optionalcompressed argument determines whether files arecompressed. If set toTrue, files in the archive are compressedwith the deflate method; otherwise, files are stored uncompressed.This argument has no effect when copying an existing archive.

If a file object is specified forsource ortarget, it is thecaller's responsibility to close it after calling create_archive.

When copying an existing archive, file objects supplied only needread andreadline, orwrite methods. When creating anarchive from a directory, if the target is a file object it will bepassed to thezipfile.ZipFile class, and must supply the methodsneeded by that class.

在 3.7 版的變更:新增filter 與compressed 參數。

zipapp.get_interpreter(archive)¶

Return the interpreter specified in the#! line at the start of thearchive. If there is no#! line, returnNone.Thearchive argument can be a filename or a file-like object openfor reading in bytes mode. It is assumed to be at the start of the archive.

範例¶

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

$python-mzipappmyapp$pythonmyapp.pyz<output from myapp>

The same can be done using thecreate_archive() function:

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

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

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

To replace the shebang line on an existing archive, create a modified archiveusing thecreate_archive() function:

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

To update the file in place, do the replacement in memory using aBytesIOobject, and then overwrite the source afterwards. Note that there is a riskwhen overwriting a file in place that an error will result in the loss ofthe original file. This code does not protect against such errors, butproduction code should do so. Also, this method will only work if the archivefits in memory:

>>>importzipapp>>>importio>>>temp=io.BytesIO()>>>zipapp.create_archive('myapp.pyz',temp,'/usr/bin/python2')>>>withopen('myapp.pyz','wb')asf:>>>f.write(temp.getvalue())

Specifying the Interpreter¶

Note that if you specify an interpreter and then distribute your applicationarchive, you need to ensure that the interpreter used is portable. The Pythonlauncher for Windows supports most common forms of POSIX#! line, but thereare 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 haveeither Python 2 or Python 3 as their default, and write your code to workunder both versions.

• If you use an explicit version, for example "/usr/bin/env python3" yourapplication will not work for users who do not have that version. (Thismay 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 anexact version like "/usr/bin/env python3.4" as you will need to change yourshebang line for users of Python 3.5, for example.

Typically, you should use an "/usr/bin/env python2" or "/usr/bin/env python3",depending on whether your code is written for Python 2 or 3.

Creating Standalone Applications with zipapp¶

Using thezipapp module, it is possible to create self-contained Pythonprograms, which can be distributed to end users who only need to have asuitable version of Python installed on their system. The key to doing thisis to bundle all of the application's dependencies into the archive, alongwith the application code.

The steps to create a standalone archive are as follows:

1. Create your application in a directory as normal, so you have amyappdirectory containing a__main__.py file, and any supporting applicationcode.

2. Install all of your application's dependencies into themyapp directory,using pip:

   $python-mpipinstall-rrequirements.txt--targetmyapp

   (this assumes you have your project requirements in arequirements.txtfile - if not, you can just list the dependencies manually on the pip commandline).

3. Package the application using:

   $python-mzipapp-p"interpreter"myapp

This will produce a standalone executable, which can be run on any machine withthe appropriate interpreter available. SeeSpecifying the Interpreterfor details. It can be shipped to users as a single file.

On Unix, themyapp.pyz file is executable as it stands. You can rename thefile to remove the.pyz extension if you prefer a "plain" command name. OnWindows, themyapp.pyz[w] file is executable by virtue of the fact thatthe Python interpreter registers the.pyz and.pyzw file extensionswhen installed.

The Python Zip Application Archive Format¶

Python has been able to execute zip files which contain a__main__.py filesince version 2.6. In order to be executed by Python, an application archivesimply has to be a standard zip file containing a__main__.py file whichwill be run as the entry point for the application. As usual for any Pythonscript, the parent of the script (in this case the zip file) will be placed onsys.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. Thezip 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:

1. An optional shebang line, containing the charactersb'#!' followed by aninterpreter name, and then a newline (b'\n') character. The interpretername can be anything acceptable to the OS "shebang" processing, or the Pythonlauncher on Windows. The interpreter should be encoded in UTF-8 on Windows,and insys.getfilesystemencoding() on POSIX.

2. Standard zipfile data, as generated by thezipfile module. Thezipfile contentmust include a file called__main__.py (which must bein the "root" of the zipfile - i.e., it cannot be in a subdirectory). Thezipfile data can be compressed or uncompressed.

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

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