A tool for creating Python-executable archives.
pyzzer is a simple tool for creating Python-runnable zip archives from Python package and module sources. It uses Python’s standard library zipfile module to construct runnable .zip files. There are several elements to making archives runnable:
On Windows, the recommended way of running archives is to have the Python Launcher for Windows installed and to use that to run archives. The launcher processes POSIX-style shebang lines and is included in Python 3.3 and later, but the standalone launcher receives updates more frequently. While the Python 3.3 launcher only recognises .py, .pyc, .pyo and .pyw extensions, the standalone launcher also recognises .pyz and .pyzw extensions, which are used for runnable archives.
It is possible to have pyzzer provide the ability to prepend archives with a suitable native Windows executable which is capable of launching archives appended to it. Such launchers are available for 32- and 64-bit console and Windows applications (they are developed in a separate project). Since including these executables in pyzzer makes it larger, this support is provided in a separate download (see Getting pyzzer).
The usage message gives the available options:
Usage: pyzzer [options] DIR_OR_FILE_OR_ARCHIVE [DIR_OR_FILE ...] Convert Python source directories and files to runnable zip files. The first argument can be an existing archive, which can be added to with additional sources. Options: -h, --help show this help message and exit -s SHEBANG Specify a shebang line to prepend to the archive, or the path to an interpreter which can be used to determine the shebang line to use. Defaults to "#! /usr/bin/env python" on POSIX and to the value of sys.executable on Windows. -m MODULE:ATTR Specify a callable which is the main entry point. -x REGEX Specify regexes to exclude from the zip (can specify more than once). -o FILENAME Specify the path of the file to write to. If not specified and a source archive is given, it will be used; otherwise the extension defaults to .pyz and the name defaults to the first directory or file specified. -v Provide information about progress. -i Inspect an existing archive. -l LAUNCHER Specify a Windows launcher to use (t32/w32/t64/w64).* -r Recurse package directories.
* Only available with the pyzzerw.pyz variant (see Getting pyzzer).
The following sections discuss the options in more detail.
The positional arguments are an optional existing archive to add to, followed by a list of directories and files. These are processed as follows:
Before adding to an archive, files in directories will be checked against any exclusion patterns specified using -x and excluded if they match. In addition, files .hgignore, .gitignore and .bzrignore are never added, and directories .hg, .git, .bzr and .svn are never recursed into even when -r is specified. Any files not specifically excluded will be included in the archive on the assumption that they are package data. Any files specified in the command line are assumed to be wanted and are not checked against any exclusion patterns.
You can use the -s argument to specify the shebang line to use. If the argument value does not begin with a #!, it will be prepended to the specified value – so you can just specify the path to an interpreter, as that’s all that’s needed.
You can specify an existing function somewhere in the archived source files as the main function called by Python when it runs an archive, by using the -m argument with a module:callable argument such as foo:main or foo.bar:baz.main. When you do this, pyzzer wraps a call to this function in a Python source file which is saved as a top-level __main__.py in the archive. If you do this, you must not specify a __main__.py file in your sources. If you don’t specify -m, there must be a top-level __main__.py file specified in the sources you add to the archive.
You can specify one or more regular expressions which indicate that files with names matching them should be excluded from the archiving. The matches are done using search, which means that you need to specify ^ and $ explicitly to anchor matches. If any pattern matches a file name, that file is skipped. Note that patterns are passed as is to the regular expression compiler, so take care to quote and/or escape any special characters in the pattern.
You can specify a name for the output archive using the -o argument. If not specified and an archive was passed as the first argument, the same archive will be overwritten. If the first argument is not an archive, its file name is used as the output archive name, and .pyz is used as the extension.
If the -v option is specified, pyzzer will print to the console the relative names of files as it writes them to the archive.
If the -i argument is specified, the first positional argument should be an existing archive and subsequent positional arguments are ignored. The existing archive’s shebang line and contents are printed. If a native executable launcher is detected, that is indicated in the output.
To recursively add sub-packages in a package, specify the -r argument. When recursing, all directories below a package are assumed to be sub-packages or data.
Though it is preferred that Windows support is through the Python Launcher for Windows, the pyzzerw.pyz archive allows stock native executables to be prepended to the archive. To use them, specify -l with one of t32, w32, t64 or w64 where the numeric suffix indicates whether a 32-bit or a 64-bit launcher is used, and the initial letter is interpreted as t for text (i.e. console) applications, and w for Windows application. You should also specify -o with a filename with a .exe extension.
In theory, you should be able to launch 32-bit or 64-bit Python interpreters from a 32-bit launcher. However, 64-bit launchers have been provided in case of problems.
Note that for best effect, any shebang you specify should match the launcher used (e.g. w32 or w64 would be used with a shebang specifying the path to a pythonw.exe). Otherwise, you may see spurious console windows (windowed application run with a python.exe) or no output at all (console application run with a pythonw.exe).
These launchers know how to process an archive appended to them. When the main program in the archive is run, sys.argv will specify the name of the executable archive (something.exe).
The launchers have embedded manifests, which should mean that you won’t get UAC prompts.
You should just be able to run runnable archives like any normal Python script, by specifying the archive name as the command and any arguments to be passed to the script as arguments to the command.
There are two variants available. The pyzzer.pyz download doesn’t include support for native Windows launchers, whereas the pyzzerw.pyz download does. Note that both of these are console applications on Windows.
Naturally, pyzzer was used to build executable archives containing itself. The command line for building pyzzer.pyz is:
python -m pyzzer -o pyzzer.pyz -x "exe|__main__|lau" -m pyzzer:main pyzzer
and that for pyzzerw.pyz is:
python -m pyzzer -o pyzzerw.pyz -x "exe|__main__" -m pyzzer:main pyzzer
These commands were run from the pyzzer project directory (above the pyzzer package directory). The pyzzer.launchers module, which contains the extended Windows launcher functionality and enables the -l option, is excluded from the first build.
To run the test suite for pyzzer, you need to clone the repository, and then build pyzzer.pyz and pyzzerw.pyz using the commands shown above. After this, you can run the test_pyzzer.py script. The tests are run using subprocess to invoke the built files with various command line options.
Many thanks to Paul Moore for helpful suggestions about how to improve pyzzer.
Patches are welcome to help remove or mitigate these limitations.