PEP 441 -- Improving Python ZIP Application Support (original) (raw)

PEP Index > PEP 441 -- Improving Python ZIP Application Support

Contents

• Improving Python ZIP Application Support
• A New Python ZIP Application Extension
• Minimal Tooling: The zipapp Module
  • Module Interface
    * create_archive(source, target=None, interpreter=None, main=None)
    * get_interpreter(archive)
  • Command Line Usage
  • FAQ
• Rejected Proposals
  • Convenience Values for Shebang Lines
  • Registering .pyz as a Media Type
  • Default Interpreter
  • Command Line Tool to Manage Shebang Lines
• Reference Implementation
• References
• Copyright

Python has had the ability to execute directories or ZIP-format archives as scripts since version 2.6 [1]. When invoked with a zip file or directory as its first argument the interpreter adds that directory to sys.path and executes the __main__ module. These archives provide a great way to publish software that needs to be distributed as a single file script but is complex enough to need to be written as a collection of modules.

This feature is not as popular as it should be mainly because it was not promoted as part of Python 2.6 [2], so that it is relatively unknown, but also because the Windows installer does not register a file extension (other than .py) for this format of file, to associate with the launcher.

This PEP proposes to fix these problems by re-publicising the feature, defining the .pyz and .pyzw extensions as "Python ZIP Applications" and "Windowed Python ZIP Applications", and providing some simple tooling to manage the format.

A New Python ZIP Application Extension

The terminology "Python Zip Application" will be the formal term used for a zip-format archive that contains Python code in a form that can be directly executed by Python (specifically, it must have a__main__.py file in the root directory of the archive). The extension .pyz will be formally associated with such files.

The Python 3.5 installer will associate .pyz and .pyzw "Python Zip Applications" with the platform launcher so they can be executed. A .pyz archive is a console application and a .pyzw archive is a windowed application, indicating whether the console should appear when running the app.

On Unix, it would be ideal if the .pyz extension and the name "Python Zip Application" were registered (in the mime types database?). However, such an association is out of scope for this PEP.

Python Zip applications can be prefixed with a #! line pointing to the correct Python interpreter and an optional explanation:

#!/usr/bin/env python3

Python application packed with zipapp module

(binary contents of archive)

On Unix, this allows the OS to run the file with the correct interpreter, via the standard "shebang" support. On Windows, the Python launcher implements shebang support.

However, it is always possible to execute a .pyz application by supplying the filename to the Python interpreter directly.

As background, ZIP archives are defined with a footer containing relative offsets from the end of the file. They remain valid when concatenated to the end of any other file. This feature is completely standard and is how self-extracting ZIP archives and the bdist_wininst installer format work.

Rejected Proposals

Convenience Values for Shebang Lines

Is it worth having "convenience" forms for any of the common interpreter values? For example, -p 3 meaning the same as -p"/usr/bin/env python3". It would save a lot of typing for the common cases, as well as giving cross-platform options for people who don't want or need to understand the intricacies of shebang handling on "other" platforms.

Downsides are that it's not obvious how to translate the abbreviations. For example, should "3" mean "/usr/bin/env python3", "/usr/bin/python3", "python3", or something else? Also, there is no obvious short form for the key case of "/usr/bin/env python" (any available version of Python), which could easily result in scripts being written with overly-restrictive shebang lines.

Overall, this seems like there are more problems than benefits, and as a result has been dropped from consideration.

Default Interpreter

The initial draft of this PEP proposed using /usr/bin/env pythonas the default interpreter. Unix users have problems with this behaviour, as the default for the python command on many distributions is Python 2, and it is felt that this PEP should prefer Python 3 by default. However, using a command of python3 can result in unexpected behaviour for Windows users, where the default behaviour of the launcher for the command python is commonly customised by users, but the behaviour of python3 may not be modified to match.

As a result, the principle "in the face of ambiguity, refuse to guess" has been invoked, and archives have no shebang line unless explicitly requested. On Windows, the archives will still be run (with the default Python) by the launcher, and on Unix, the archives can be run by explicitly invoking the desired Python interpreter.

Copyright

This document has been placed into the public domain.