Super Zippy is no longer maintained.

Python 3.5 ships with a tool that is about as easy to use as SuperZippy. Check out zipapp!

---

Super Zippy

Super Zippy takes a Python package and its pure Python dependencies and transforms them all into a single executable file.

Linux and Mac OS X are the only operating systems that are officially supported right now. It seems like Superzippy should work for any operating system though, so feel free to try it on your own (and let me know if you want to help testing!).

Examples

Say I'm trying to write a Python script that uses Clint to provide nice console output. I can create a project with a directory tree as below (this example is in the repo under examples/readme/).

+ setup.py
+ tinyscript/
|   + __init__.py
|   + main.py

The setup.py file establishes the Clint dependency and is very short. This file must exist because Super Zippy will use pip to install your package, and pip needs this file.

# setup.py
from setuptools import setup, find_packages
setup(
    name = "tinyscript",
    packages = find_packages(),
    install_requires = ["Clint"]
)

The __init__.py file is empty (see here for info).

Finally, the main.py file has our actual script.

# main.py
from clint.textui import puts, colored
import sys

def foo():
    puts(colored.red("I am a mighty foo function!"))
    sys.exit(0)

def bar():
    puts(colored.blue("Nice to meet you, I am bar."))
    sys.exit(1)

if __name__ == "__main__":
    puts("Running as a script!")
    sys.exit(2)

We can now use Super Zippy.

$ ls
setup.py tinyscript/
$ superzippy . tinyscript.main:foo
$ ls
setup.py tinyscript/ tinyscript.sz
$ ./tinyscript.sz
I am a mighty foo function!
$ echo $?
0

Note that "I am a mighty foo function!" above is displayed in red if you actually run it.

If we'd like to have the bar() function be our entry point (rather than the foo() function above), we could run

$ superzippy . tinyscript.main:bar
$ ./tinyscript.sz
Nice to meet you, I am bar.
$ echo $?
1

There's a number of options you can give Super Zippy and you can get an up-to-date listing of them by running superzippy -h.

Installing

You can install Super Zippy from pip easily (see here for installing pip). This will grab the latest stable release.

$ pip install superzippy

Alternatively, you can install the most recent version off of GitHub.

$ git clone https://github.com/itsjohncs/superzippy.git
$ cd superzippy/
$ python setup.py install

If you are planning to do development on Super Zippy, you may want to install Super Zippy in editable mode. You can do this by running python setup.py develop instead of python setup.py install.

You can of course also use Super Zippy on itself to make a Super Zip of Super Zippy. Though doing this automatically may be done in the future, it seems mostly unecessary at the moment to add this into our release process.

How it Works

Super Zippy's algorithm is fairly straightforward.

1. Create a virtual environment using virtualenv.
2. Install all the desired packages into the virtual environment using pip.
3. Grab the site-packages directory out from the virtual environment (which is the directory that contains all installed packages) and put it in an empty temporary directory.
4. Add a __main__.py file to the temporary directory that executes the desired function.
5. Zip the temporary directory up.
6. Make the zip file executable by flipping the executable bit and adding #!/usr/bin/env python to the beginning of the zip file.

Adding a shebang to the beginning of the zip file doesn't affect our ability to decompress it because a zip file's "header" is located at the back of the file (see this wikipedia article).

Who Made This?

My name is John Sullivan and I created this over a couple weekends with the assistance of Chris Manghane. After the initial release, Steven Myint graciously submitted several useful patches as well.

If you are interested in helping with the development, feel free to fork and dive in! If you'd just like to send me a message you can find my contact information on my portfolio at johnsullivan.name.

License

Apache License v2.0 (see LICENSE for full text).

If you need a more permissive license please open up an issue in the tracker that describes your desired use case.