zipapps

Changelogs

zipapps is a pure-python library, to package your python code into a single zip file with its dependencies.

Depends on PEP441 + zipapp + zipimport.

What is the .pyz?

.pyz to Python is like .jar to Java.

They are both zip archive files which aggregate many packages and associated metadata and resources (text, images, etc.) into one file for distribution.

All you need is the Python Interpreter as the runtime environment.

So, what could zipapps be?

1. packaging tool

   compress your package folder into a zip file.

2. single-file virtual environment

   a portable site-packages.

3. dependences installer

   lazy install requirements while first running.

4. set of import-path

   add many venv.pyz files to PYTHONPATH automatically.

5. requirements.txt freezing toolkit

   use venv to freeze your pip packages.

PS: The pyz extension can be modified to any character you want, such as .py and .zip.

Install & Quick Start

pip install zipapps -U

1. Source code without dependences

1. add your source code into the zip file, and set the entrypoint with -m

   1. python3 -m zipapps -c -a entry.py -m entry:main -o app.pyz

      1. entry.py could be a package package_name
      2. -m format is package.module:function
2. run app.pyz

   1. python3 app.pyz

2. Source code with dependences

1. zipapps with requirements

   1. python3 -m zipapps -c -a entry.py -m entry:main -o app.pyz bottle

      1. bottle is a pure-python lib which may not be unzipped
         1. -u AUTO or -u=* should be set for some .so/.pyd libs
            1. such as psutil
            2. notice that the -u=* != -u *

   2. you don't need to install requirements at running

      1. ensure the compatibility of the system environment and python version
      2. or add -d of lazy install mode to skip the compatibility problem
         1. but comes a long-time pip install process at the first running.

2. run app.pyz

   1. python3 app.pyz

   2. libs with .pyd/.so caches will be unzipped to the ./zipapps_cache/app by -u AUTO

3. Virtual environments

1. zipapps with requirements

   1. python3 -m zipapps -c -u AUTO -o venv.pyz -r requirements.txt

2. run entry.py with venv.pyz

   1. python3 venv.pyz entry.py

   2. the cache will be unzipped to ./zipapps_cache/venv for -u is not null

4. Activate the .pyz environment

1. use importlib (Recommended)
   1. sys.path.insert(0, "some_lib_venv.pyz");importlib.import_module("ensure_zipapps")
   2. automatically unzip cache, and add the path to sys.path
      1. it can be run multiple times
2. if they are all pure-python code and no need to decompress
   1. impory sys; sys.path.insert(0, "bottle.pyz")
3. use zipimport

# 1. use zipapps lib
from zipapps.activate_zipapps import activate
activate("app.pyz")

# or use source code directly
from zipimport import zipimporter

importer = zipimporter("app.pyz")
try:
    spec = importer.find_spec("ensure_zipapps")
    if spec and spec.loader:
        module = spec.loader.load_module("ensure_zipapps")
    else:
        raise ImportError("Module not found")
except AttributeError:
    module = importer.load_module("ensure_zipapps")
del module
sys.modules.pop("ensure_zipapps", None)

Command line usage

Build Args

most common args:

• -c
  • to compress files, only for python3.7+.
• -a xxx.py
  • to add some files/folders into the zipped file.
• -u=AUTO
  • Recommended
  • auto unzip the .pyd / .so files
    • or -u=* to unzip all the files
• -r requirements.txt
  • install requirements with pip install
• -o my_app.pyz
  • output the zipped file as given path
• -m app.__main__:main
  • entry point
• -p /usr/bin/python3
  • set the shebang line
• -d
  • Recommended
  • requirements will be installed with pip while first running in the lazy install mode
  • zip file size will be very small, and the default unzip path is SELF/zipapps_cache/
• --clear-zipapps-cache, -czc
  • Clear the zipapps cache folder after running, but maybe failed for .pyd/.so files.

Details:

python3 -m zipapps -h

1. -h, --help
   1. show the simple doc
2. --includes, --add, -a
   1. The given paths will be copied to cache_path while packaging, which can be used while running. The path strings will be splited by ",".
      1. such as my_package_dir,my_module.py,my_config.json
      2. often used for libs not from pypi or some special config files
   2. the output arg of zipapps.create_app
3. --output, -o
   1. The path of the output file, defaults to app.pyz.
   2. the output arg of zipapps.create_app
4. --python, -p
   1. The path of the Python interpreter which will be set as the shebang line, defaults to None.
      1. with shebang /usr/bin/python3 you can run app with ./app.pyz directly, no need for python3 app.pyz
   2. the interpreter arg of zipapps.create_app
5. --main, -m
   1. The entry point function of the application, the valid format is:
      1. package.module:function
      2. package.module
      3. module:function
      4. package
   2. the main arg of zipapps.create_app
   3. WARNING: If the --main arg is set, python3 app.pyz will not be able to used as venv like python3 app.pyz xxx.py
6. --compress, -c
   1. Boolean value, compress files with the deflate method or not.
   2. the compressed arg of zipapps.create_app
7. --unzip, -u
   1. The names which need to be unzipped while running, splited by "," without ext, such as bottle,aiohttp, or the complete path like bin/bottle.py,temp.py. For .so/.pyd files(which can not be loaded by zipimport), or packages with operations of static files.
      1. if unzip is set to "*", then will unzip all files and folders.
      2. if unzip is set to AUTO, then will add the .pyd and .so files automatically.
   2. Can be overwrite with environment variable ZIPAPPS_UNZIP
   3. the unzip arg of zipapps.create_app
8. --unzip-exclude, -ue
   1. The opposite of --unzip / -u which will not be unzipped, should be used with --unzip / -u.
   2. Can be overwrite with environment variable ZIPAPPS_UNZIP_EXCLUDE
9. --unzip-path, -up 3. If unzip arg is not null, cache files will be unzipped to the given path while running. Defaults to zipapps_cache, support some internal variables as runtime args:
   1. $TEMP/$HOME/$SELF/$PID/$CWD as prefix, for example $HOME/zipapps_cache
      1. TEMP means tempfile.gettempdir()
      2. HOME means Path.home()
      3. SELF means .pyz file path.
      4. $PID means os.getpid()
      5. $CWD means Path.cwd()
   2. And you can also overwrite it with environment variables:
      1. ZIPAPPS_CACHE or UNZIP_PATH
   3. the unzip_path arg of zipapps.create_app
10. -cc, --pyc, --compile, --compiled
    1. Compile .py to .pyc for fast import, but zipapp does not work unless you unzip it(so NOT very useful).
    2. the compiled arg of zipapps.create_app
11. --cache-path, --source-dir, -cp
    1. The cache path of zipapps to store site-packages and includes files. If not set, will create and clean-up in TEMP dir automately.
    2. the cache_path arg of zipapps.create_app
12. --shell, -s
    1. Only while main is not set, used for shell=True in subprocess.run.
       1. very rarely used, because extra sub-process is not welcome
    2. the shell arg of zipapps.create_app
13. --main-shell, -ss
    1. Only for main is not null, call main with subprocess.Popen: python -c "import a.b;a.b.c()". This is used for psutil ImportError of DLL load.
       1. very rarely used too
    2. the main_shell arg of zipapps.create_app
14. --strict-python-path, -spp
    1. Boolean value. Ignore global PYTHONPATH, only use zipapps_cache and app.pyz.
    2. the ignore_system_python_path arg of zipapps.create_app
15. -b, --build-id
    1. The string to skip duplicate builds, it can be the paths of files/folders which splited by ",", then the modify time will be used as build_id. If build_id contains *, will use glob function to get paths. For example, you can set requirements.txt as your build_id by python3 -m zipapps -b requirements.txt -r requirements.txt when you use pyz as venv.
       1. very rarely used too too
    2. the build_id arg of zipapps.create_app
16. --zipapps, --env-paths
    1. Default --zipapps arg if it is not given while running. Support $TEMP/$HOME/$SELF/$PID/$CWD prefix.
17. --delay, -d, --lazy-pip, --lazy-install, --lazy-pip-install
    1. Install packages with pip while first running, which means requirements will not be install into pyz file.
18. --ensure-pip
    1. Add the ensurepip package to your pyz file, works for embed-python(windows) or other python versions without pip installed but `lazy-install