What is it?
===========

``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:

* They need a `shebang line <https://en.wikipedia.org/wiki/Shebang_(Unix)>`_ which indicates to POSIX shells the native executable that is used to run them. Archives created by ``pyzzer`` have a shebang line prepended to them, which is ``#! /usr/bin/env python`` by default but can be overridden with a command-line argument to ``pyzzer``.

* On POSIX systems, the executable bit should be set in the archive's file-system attributes. This is set by ``pyzzer`` for the current user.

* For Python to be able to run a .zip archive, the archive needs to contain a "main" module named   ``__main__.py``. For ``pyzzer``-created archives, you can either specify an existing ``__main__.py`` file or have ``pyzzer`` make one from a module:callable combination. An archive cannot be created with ``pyzzer`` unless it contains a top-level ``__main__.py``.

Windows support
===============

On Windows, the recommended way of running archives is to have the
`Python Launcher for Windows <https://bitbucket.org/pypa/pylauncher/downloads>`_ 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 <https://bitbucket.org/vinay.sajip/simple_launcher>`_). Since including these
executables in ``pyzzer`` makes it larger, this support is provided in a separate download (see `Getting pyzzer`_).

Usage
=====

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. Defaults
                      to "#!/usr/bin/env python".
      -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 (one of 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.

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 in the archive (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 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.

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.

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 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.

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 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.

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, 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 appliation. You should also specify ``-o`` with a filename with a ``.exe`` extension.

Note that for best effect, any shebang you specify should match the launcher used (e.g. ``w64`` would be used with a shebang specifying the path to a 64-bit ``pythonw.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``).

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.

Getting pyzzer
==============

There are two variants available. The `pyzzer.pyz <https://bitbucket.org/vinay.sajip/pyzzer/downloads/pyzzer.pyz>`_ download doesn't include support for native Windows launchers, whereas the `pyzzerw.pyz <https://bitbucket.org/vinay.sajip/pyzzer/downloads/pyzzerw.pyz>`_ download does. Note that both of these are console applications on Windows.

How pyzzer was built
====================

Naturally, ``pyzzer`` was used to build executable archives containing itself. The command line for building ``pyzzer.pyz`` is::

    python -m pyzzer -vo pyzzer.pyz -x "asc|exe|__main__|lau" -m pyzzer:main pyzzer

and that for ``pyzzerw.pyz`` is::

    python -m pyzzer -vo pyzzerw.pyz -x "asc|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.

Limitations
===========

* There is no byte-compilation support at present.
* No checks are made to verify that a specified ``-m`` value actually exists in the sources.
* Packages are recognised by the existence of an ``__init__.py__``, so there is no recognition of new-style namespace packages (which have no such file).
* Replacing files in existing archives is not supported.

Patches are welcome to help remove or mitigate these limitations.

Other resources
===============

* `PEP 441 <http://www.python.org/dev/peps/pep-0441/>`_ is the PEP advocating added support for ``.pyz`` and ``.pyzw`` archives.
* Daniel Holth's `pyzaa package <https://bitbucket.org/dholth/pyzaa>`_ provides similar functionality to ``pyzzer``.
* You don't *need* to install ``pyzzer`` using ``pip`` (it's a one-file executable, after all) - but if you absolutely must, here it is `on PyPI <https://pypi.python.org/pypi/pyzzer>`_.
