[Python-Dev] Documentation for ability to execute zipfiles & directories

[Nick Coghlan]

A few months ago, 2.6 & 3.0 gained the ability to execute zipfiles and 
directories containing a __main__.py file (see [1] for details).

The idea is that a whole application can be bundled into a zipfile 
containing a __main__.py module in its root directory, and then passed 
directly to the interpreter for execution, with the zipfile being 
inserted as the first entry on sys.path to allow easy access to the rest 
of the application code. It is inspired by Java's JAR option, but not 
needing an explicit interpreter option makes it more shebang friendly on 
*nix systems (it can also be mapped more easily to the existing Python 
file type handling on Windows).

The ability to also execute directories containing a __main__.py was 
something of a side effect of the implementation technique, but was also 
considered valuable as it makes it much easier to develop such bundled 
applications (using a directory most of the time, and then bundling into 
a single zipfile prior to release).

The part I'm struggling with now is where to document the way this 
feature works. Currently, the only real documentation we have of the 
command line invocation is in section 2.1 of the tutorial, and the idea 
of packaging whole applications as zipfiles seems far too esoteric to be 
covering it there. It doesn't really seem to fit in section 6 (covering 
modules and packages) either.

Do we need a new appendix to the tutorial which goes into detail about 
the CPython interpreter's command line options, environment variables 
and details on what can be executed?

Cheers,
Nick.

[1] http://bugs.python.org/issue1739468

-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------
             http://www.boredomandlaziness.org