{ "info": { "author": "Vinay Sajip", "author_email": "vinay_sajip@yahoo.co.uk", "bugtrack_url": null, "classifiers": [], "description": "What is it?\r\n===========\r\n\r\n``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:\r\n\r\n* They need a `shebang line `_ 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``.\r\n\r\n* 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.\r\n\r\n* 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, specifying only a single source file (which then is written to the archive as ``__main__.py``) 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``.\r\n\r\nWindows support\r\n===============\r\n\r\nOn Windows, the recommended way of running archives is to have the\r\n`Python Launcher for Windows `_ installed and to\r\nuse that to run archives. The launcher processes POSIX-style shebang lines and is included in\r\nPython 3.3 and later, but the standalone launcher receives updates more frequently. While the\r\nPython 3.3 launcher only recognises ``.py``, ``.pyc``, ``.pyo`` and ``.pyw`` extensions, the\r\nstandalone launcher also recognises ``.pyz`` and ``.pyzw`` extensions, which are used for\r\nrunnable archives.\r\n\r\nIt *is* possible to have ``pyzzer`` provide the ability to prepend archives with a suitable\r\nnative Windows executable which is capable of launching archives appended to it. Such launchers\r\nare available for 32- and 64-bit console and Windows applications (they are developed in a\r\n`separate project `_). Since including these\r\nexecutables in ``pyzzer`` makes it larger, this support is provided in a separate download (see `Getting pyzzer`_).\r\n\r\nUsage\r\n=====\r\n\r\nThe usage message gives the available options::\r\n\r\n Usage: pyzzer [options] DIR_OR_FILE_OR_ARCHIVE [DIR_OR_FILE ...]\r\n\r\n Convert Python source directories and files to runnable zip files. The\r\n first argument can be an existing archive, which can be added to with\r\n additional sources.\r\n\r\n Options:\r\n -h, --help show this help message and exit\r\n -s SHEBANG Specify a shebang line to prepend to the archive, or the\r\n path to an interpreter which can be used to determine the\r\n shebang line to use. Defaults to \"#! /usr/bin/env python\"\r\n on POSIX and to the value of sys.executable on Windows.\r\n -m MODULE:ATTR Specify a callable which is the main entry point.\r\n -x REGEX Specify regexes to exclude from the zip (can specify more\r\n than once).\r\n -o FILENAME Specify the path of the file to write to. If not specified\r\n and a source archive is given, it will be used; otherwise\r\n the extension defaults to .pyz and the name defaults to\r\n the first directory or file specified.\r\n -v Provide information about progress.\r\n -i Inspect an existing archive.\r\n -l LAUNCHER Specify a Windows launcher to use (t32/w32/t64/w64).*\r\n -r Recurse package directories.\r\n\r\n\\* Only available with the ``pyzzerw.pyz`` variant (see `Getting pyzzer`_).\r\n\r\nThe following sections discuss the options in more detail.\r\n\r\nPositional arguments\r\n--------------------\r\n\r\nThe positional arguments are an optional existing archive to add to, followed by a list of directories and files. These are processed as follows:\r\n\r\n* 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.\r\n\r\n* If an argument is a file, it is archived as a top-level file.\r\n\r\n* 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.\r\n\r\n* If any files are added which already exist in the archive, an error will be raised.\r\n\r\nBefore 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.\r\n\r\nSetting the shebang line\r\n------------------------\r\n\r\nYou 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.\r\n\r\nSpecifying a main program\r\n-------------------------\r\n\r\nYou 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.\r\n\r\nExcluding files from an archive\r\n-------------------------------\r\n\r\nYou 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.\r\n\r\nSpecifying the output archive name\r\n----------------------------------\r\n\r\nYou 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.\r\n\r\nGetting feedback on progress\r\n----------------------------\r\n\r\nIf the ``-v`` option is specified, ``pyzzer`` will print to the console the relative names of files as it writes them to the archive.\r\n\r\nExamining an existing archive\r\n-----------------------------\r\n\r\nIf 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.\r\n\r\nRecursing over sub-packages\r\n----------------------------\r\n\r\nTo 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.\r\n\r\nSpecifying a Windows launcher\r\n-----------------------------\r\n\r\nThough 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.\r\n\r\nIn 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.\r\n\r\nNote 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``).\r\n\r\nThese launchers know how to process an archive appended to them. When the main program in the archive is run,\r\n``sys.argv[0]`` will specify the name of the executable archive (``something.exe``).\r\n\r\nThe launchers have embedded manifests, which should mean that you won't get UAC prompts.\r\n\r\nRunning programs in runnable archives\r\n-------------------------------------\r\n\r\nYou 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.\r\n\r\nGetting pyzzer\r\n==============\r\n\r\nThere 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.\r\n\r\nHow pyzzer was built\r\n====================\r\n\r\nNaturally, ``pyzzer`` was used to build executable archives containing itself. The command line for building ``pyzzer.pyz`` is::\r\n\r\n python -m pyzzer -o pyzzer.pyz -x \"exe|__main__|lau\" -m pyzzer:main pyzzer\r\n\r\nand that for ``pyzzerw.pyz`` is::\r\n\r\n python -m pyzzer -o pyzzerw.pyz -x \"exe|__main__\" -m pyzzer:main pyzzer\r\n\r\nThese 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.\r\n\r\nTesting pyzzer\r\n==============\r\n\r\nTo 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.\r\n\r\nAcknowledgements\r\n================\r\n\r\nMany thanks to Paul Moore for helpful suggestions about how to improve ``pyzzer``.\r\n\r\nLimitations\r\n===========\r\n\r\n* There is no byte-compilation support at present.\r\n* No checks are made to verify that a specified ``-m`` value actually exists in the sources.\r\n* 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).\r\n* Replacing files in existing archives is not supported.\r\n\r\nPatches are welcome to help remove or mitigate these limitations.\r\n\r\nOther resources\r\n===============\r\n\r\n* `PEP 441 `_ is the PEP advocating added support for ``.pyz`` and ``.pyzw`` archives.\r\n* Daniel Holth's `pyzaa package `_ provides similar functionality to ``pyzzer``.\r\n* 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 `_.\r\n\r\nChange log\r\n==========\r\n\r\n0.1.1\r\n-----\r\n\r\nReleased: 2013-08-23.\r\n\r\n- Fixed ``TypeError`` in Python 3.x.\r\n\r\n- Made the default shebang use ``sys.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).\r\n\r\n- If the output extension is ``.exe`` and no launcher has been specified, ``t32`` will be assumed except on 64-bit Windows (where ``t64`` will be assumed).\r\n\r\n- 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``.\r\n\r\n- Added tests.\r\n\r\n- Tweaked help messages.\r\n\r\n- Removed unused code.\r\n\r\n- Moved change log to the README and updated documentation.\r\n\r\n0.1.0\r\n-----\r\n\r\nReleased: 2013-08-19\r\n\r\n- Initial release.", "description_content_type": null, "docs_url": null, "download_url": "http://pypi.python.org/packages/source/p/pyzzer/pyzzer-0.1.1.tar.gz", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "", "keywords": "executable,archive,zip", "license": "MIT", "maintainer": "", "maintainer_email": "", "name": "pyzzer", "package_url": "https://pypi.org/project/pyzzer/", "platform": "Any", "project_url": "https://pypi.org/project/pyzzer/", "project_urls": { "Download": "http://pypi.python.org/packages/source/p/pyzzer/pyzzer-0.1.1.tar.gz" }, "release_url": "https://pypi.org/project/pyzzer/0.1.1/", "requires_dist": null, "requires_python": null, "summary": "A tool for creating Python-executable archives.", "version": "0.1.1" }, "last_serial": 847363, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "c73b28480aa66e5a8c9960df17a24ae2", "sha256": "32fabb73c4e9b4c9a7a8e32f997216385b08506000e56cc11f099e7798a97c3e" }, "downloads": -1, "filename": "pyzzer-0.1.0.tar.gz", "has_sig": false, "md5_digest": "c73b28480aa66e5a8c9960df17a24ae2", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 178347, "upload_time": "2013-08-19T16:49:19", "url": "https://files.pythonhosted.org/packages/51/7f/e41fd0ede2233d67e5067f0c88c410ad7bc35c9b389c37a5cca5385833b2/pyzzer-0.1.0.tar.gz" } ], "0.1.1": [ { "comment_text": "", "digests": { "md5": "dcbf3cab443b26c9bad4765fa7773ef6", "sha256": "19a020c4c3b273e5132cb03e6a0a55272bed7a1217f99964a0bf25abc4fe2ef5" }, "downloads": -1, "filename": "pyzzer-0.1.1.tar.gz", "has_sig": false, "md5_digest": "dcbf3cab443b26c9bad4765fa7773ef6", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 179540, "upload_time": "2013-08-23T19:37:08", "url": "https://files.pythonhosted.org/packages/92/45/3672733a72ee12ba440ea2746aae9f8375585caa7674bc8a2ed60ed37e56/pyzzer-0.1.1.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "dcbf3cab443b26c9bad4765fa7773ef6", "sha256": "19a020c4c3b273e5132cb03e6a0a55272bed7a1217f99964a0bf25abc4fe2ef5" }, "downloads": -1, "filename": "pyzzer-0.1.1.tar.gz", "has_sig": false, "md5_digest": "dcbf3cab443b26c9bad4765fa7773ef6", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 179540, "upload_time": "2013-08-23T19:37:08", "url": "https://files.pythonhosted.org/packages/92/45/3672733a72ee12ba440ea2746aae9f8375585caa7674bc8a2ed60ed37e56/pyzzer-0.1.1.tar.gz" } ] }