2013-04-07 21:51:33 -04:00
|
|
|
|
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
|
2013-04-07 21:57:47 -04:00
|
|
|
|
as scripts since version 2.6 [1]_. When invoked with a zip file or
|
2013-04-07 21:51:33 -04:00
|
|
|
|
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
|
2013-04-07 21:57:47 -04:00
|
|
|
|
heard of it as it wasn’t promoted as part of Python 2.6 [2]_, but also
|
2013-04-07 21:51:33 -04:00
|
|
|
|
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
|
|
|
|
|
|
==========
|
|
|
|
|
|
|
2013-04-07 21:57:47 -04:00
|
|
|
|
.. [1] “Allow interpreter to execute a zip file”:
|
|
|
|
|
|
http://bugs.python.org/issue1739468
|
|
|
|
|
|
|
|
|
|
|
|
.. [2] “Feature is not documented”:
|
|
|
|
|
|
http://bugs.python.org/issue17359
|
2013-04-07 21:51:33 -04:00
|
|
|
|
|
|
|
|
|
|
Copyright
|
|
|
|
|
|
=========
|
|
|
|
|
|
|
|
|
|
|
|
This document has been placed into the public domain.
|
|
|
|
|
|
|
