Positional arguments

The positional arguments are an optional existing archive to add to, followed by a list of directories and files. These are processed as follows:

• If the first argument is an archive, any shebang it contains will be preserved unless-s is used to override it. The contents of the archive are added to with the sources specified in the rest of the command line. Any file contents before the archive/shebang (such as a native executable launcher on Windows) are preserved unless-l is available and used.

• If an argument is a file, it is archived as a top-level file.

• If an argument is a directory,``pyzzer`` determines whether it is a package according to whether it contains an__init__.py. If it does, it is treated as a Python package and its contents are written to the archive as a directory. By default, sub-packages are not archived unless you specify-r, in which case all sub-packages are archived. If the directory is not a package, its contents will be archived as top-level files and no recursion into sub-directories will be performed.

• If any files are added which already exist in the archive, an error will be raised.

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.

Setting the shebang line

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.

Specifying a main program

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 asfoo:main orfoo.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.

Excluding files from an 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 usingsearch, 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.

Specifying the output archive name

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.

Getting feedback on progress

If the-v option is specified,pyzzer will print to the console the relative names of files as it writes them to the archive.

Examining an existing 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.

Recursing over sub-packages

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.

Specifying a Windows launcher

Though it is preferred that Windows support is through the Python Launcher for Windows, thepyzzerw.pyz archive allows stock native executables to be prepended to the archive. To use them, specify-l with one oft32,w32,t64 orw64 where the numeric suffix indicates whether a 32-bit or a 64-bit launcher is used, and the initial letter is interpreted ast for text (i.e. console) applications, andw 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 orw64 would be used with a shebang specifying the path to apythonw.exe). Otherwise, you may see spurious console windows (windowed application run with apython.exe) or no output at all (console application run with apythonw.exe).

These launchers know how to process an archive appended to them. When the main program in the archive is run,sys.argv[0] 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.

Running programs in runnable archives

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.

0.1.1

Released: 2013-08-23.

• FixedTypeError in Python 3.x.

• Made the default shebang usesys.executable on Windows when-l is specified, rather than/usr/bin/env python which is used on POSIX (and also Windows where the Python Launcher is used).

• If the output extension is.exe and no launcher has been specified,t32 will be assumed except on 64-bit Windows (wheret64 will be assumed).

• If only a single source file is specified, and no-m option is given, and the archive contains no other files, then the single file is written to the archive with name__main__.py.

• Added tests.

• Tweaked help messages.

• Removed unused code.

• Moved change log to the README and updated documentation.

0.1.0

Released: 2013-08-19

• Initial release.