add PEP-0441: Improving Python ZIP Application Support

pep-0441.txt

@@ -0,0 +1,126 @@
+PEP: 441
+Title: Improving Python ZIP Application Support
+Version: $Revision$
+Last-Modified: $Date$
+Author: Daniel Holth <dholth@gmail.com>
+Status: Draft
+Type: Standards Track
+Content-Type: text/x-rst
+Created: 30 March 2013
+Post-History: 30 March 2013, 1 April 2013
+
+Improving Python ZIP Application Support
+========================================
+
+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 no one’s
+heard of it as it wasn’t promoted as part of Python 2.6, but also
+because 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 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.
+
+Why not use .zip or .py? Users expect a .zip file would be opened with
+an archive tool, and users expect .py to contain text. 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 python3
+    # This is a Python application stored in a ZIP archive, created with
+    # pyzaa.
+    (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
+these archives: The Python Zip Application Archiver “pyzaa” (rhymes
+with “huzzah” or “pizza”). “pyzaa” can archive these files,
+compile bytecode, and can write the __main__ module if it is not present.
+
+Usage
+-----
+
+``python -m pyzaa (pack | 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 compile arcname.pyz[w]``
+
+    The Python files in arcname.pyz[w] are compiled and appended to the
+    ZIP file.
+
+A standard ZIP utility or Python’s zipfile module can unpack the
+archives.
+
+FAQ
+
+Q. Are you sure a standard ZIP utility can handle #! at the beginning?
+
+A. Absolutely. If it doesn't, it is a bug in your archive program.
+
+Q. Isn’t pyzaa just a very thin wrapper over zipfile and compileall?
+
+A. Yes.
+
+Q. How does this compete with existing sdist/bdist formats?
+
+A. There is some overlap, but .pyz files are especially interesting
+as a way to distribute an installer. They may also prove useful as a
+way to deliver applications when users shouldn’t be asked to perform
+virtualenv + “pip install”.
+
+References
+==========
+
+[1] http://bugs.python.org/issue1739468 “Allow interpreter to execute a zip file”
+[2] http://bugs.python.org/issue17359 “Feature is not documented”
+
+Copyright
+=========
+
+This document has been placed into the public domain.
+