[Distutils] PEP: Improving Python ZIP Application Support

[Daniel Holth]

Python ZIP Application Support -
https://docs.google.com/document/d/1MKXgPzhWD5wIUpoSQX7dxmqgTZVO6l9iZZis8dnri78/edit?usp=sharing


PEP: 4XX

Title: Improving Python ZIP Application Support

Author: Daniel Holth <dholth at gmail.com>

Status: Draft

Type: Standards Track

Python-Version: 3.4

Created: 30 March 2013

Post-History: 30 March 2013


Improving Python ZIP Application Support


Python has had the ability to execute directories or ZIP-format
archives as scripts since version 2.6. 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 for two reasons: a)
users haven’t heard of it because it wasn’t mentioned in earlier
versions of Python 2.6 “What’s New” document, and b) Windows users
don’t have a file extension (other than .py) 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 Python 3.4 installer will associate .pyz and .pyzw “Python ZIP
Applications” with itself so they can be executed by the Windows
launcher. A .pyz archive is a console application and a .pyzw archive
is a windowed application. This indicates whether the console should
appear when running the app.


Why not use .zip or .py? Users expect a .zip file would be opened with
an archive tool, and users expect .py to be opened with a text editor.
Both would be confusing for this use case.


For UNIX users, .pyz applications should be prefixed with a #! line
pointing to the correct Python interpreter and an optional
explanation.


#!/usr/bin/env python

# This is a Python application stored in a ZIP archive.

(binary contents of archive)


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.

Minimal Tooling: The pyzaa Module

This PEP also proposes including a simple application for working with
Python ZIP Archives: The Python Zip Application Archiver “pyzaa”
(rhymes with “huzzah” or “pizza”). “pyzaa” can archive or extract
these files, compile bytecode, and can write the __main__ module if it
is not present.

Usage

python -m pyzaa (pack | unpack | compile)


python -m pyzaa pack [-o path/name] [-m module.submodule:callable]
[-c] [-w] [-p interpreter] directory:

    ZIP the contents of directory as directory.pyz or [-w]
directory.pyzw. Adds the executable flag to the archive.

    -c compile .pyc files and add them to the archive

    -p interpreter include #!interpreter as the first line of the archive

    -o path/name archive is written to path/name.pyz[w] instead of
dirname. The extension is added if not specified.

    -m module.submodule:callable __main__.py is written as “import
module.submodule; module.submodule.callable()”


    pyzaa pack will warn if the directory contains C extensions or if
it doesn’t contain __main__.py.


python -m pyzaa unpack arcname.pyz[w]

    The archive is unpacked into a directory [arcname]


python -m pyzaa compile arcname.pyz[w]

    The Python files in arcname.pyz[w] are compiled and appended to
the ZIP file.

References

[1] http://bugs.python.org/issue1739468 “Allow interpreter to execute
a zip file”

Copyright

This document has been placed into the public domain.