tddschn / zipapp-utils

zipapp utilities

zipapp-utils

zipapp utilities

• zipapp-utils
  • Features
  • Demo
  • Install, Upgrade and Uninstall
    • pipx (recommended)
    • pip
  • Usage
    • zipapp-utils
    • zipapp-utils py2pyz
    • zipapp-utils create-archive
    • zipapp-utils create-shell-script
    • Examples
      • Generate a shell script that bundles and runs a python script
  • Why did you make this?
  • Changelog

Features

• Creating application archive (.pyz files) like python -m zipapp does, but with convenient features.
• Create shell scripts that bundle a python scripts with all of its dependencies, and can be executable on any system that has python3 >= 3.5 installed.

Demo

See Generate a shell script that bundles and runs a python script

Install, Upgrade and Uninstall

pipx (recommended)

pipx install zipapp-utils

About pipx

pip

pip install zipapp-utils

Usage

zipapp-utils

zipapp-utils is the base command.

zau is an installed alias for zipapp-utils, you can use them interchangeably.

$ zipapp-utils --help # or zau --help

usage: zipapp-utils [-h] [-V] {py2pyz,p,create-archive,ca,zipapp,create-shell-script,sh} ...

zipapp utilities

positional arguments:
  {py2pyz,p,create-archive,ca,zipapp,create-shell-script,sh}
    py2pyz (p)          Create archive from a python script
    create-archive (ca, zipapp)
                        Create a zipapp archive
    create-shell-script (sh)
                        Create an ASCII shellscript that runs a zipapp archive

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit

zipapp-utils py2pyz

Create archive from a python script

$ zau p --help

usage: zipapp-utils py2pyz [-h] [-d DEP] [-r [REQUIREMENT]] [--output OUTPUT] [--python PYTHON] [--main MAIN] [--compress] SCRIPT

Create archive from a python script

positional arguments:
  SCRIPT                Python script file

options:
  -h, --help            show this help message and exit
  -d DEP, --dep DEP     Add dependency
  -r [REQUIREMENT], --requirement [REQUIREMENT]
                        Install dependencies from the given requirements file. Defaults to "requirements.txt"
  --output OUTPUT, -o OUTPUT
                        The name of the output archive. Required if SOURCE is an archive.
  --python PYTHON, -p PYTHON
                        The name of the Python interpreter to use (default: no shebang line).
  --main MAIN, -m MAIN  The main function of the application (default: use an existing __main__.py).
  --compress, -c        Compress files with the deflate method. Files are stored uncompressed by default.

zipapp-utils create-archive

Create a zipapp archive (.pyz file)

$ zau ca --help

usage: zipapp-utils create-archive [-h] [--output OUTPUT] [--python PYTHON] [--main MAIN] [--compress] [--info] source

Create a zipapp archive

positional arguments:
  source                Source directory (or existing archive).

options:
  -h, --help            show this help message and exit
  --output OUTPUT, -o OUTPUT
                        The name of the output archive. Required if SOURCE is an archive.
  --python PYTHON, -p PYTHON
                        The name of the Python interpreter to use (default: no shebang line).
  --main MAIN, -m MAIN  The main function of the application (default: use an existing __main__.py).
  --compress, -c        Compress files with the deflate method. Files are stored uncompressed by default.
  --info                Display the interpreter from the archive.

zipapp-utils create-shell-script

Create an ASCII shellscript that runs a zipapp archive

$ zau sh --help

usage: zipapp-utils create-shell-script [-h] [-o OUTPUT] PYTHON_APPLICATION_ARCHIVE

Create an ASCII shellscript that runs a zipapp archive

positional arguments:
  PYTHON_APPLICATION_ARCHIVE
                        Path to the pyz file

options:
  -h, --help            show this help message and exit
  -o OUTPUT, --output OUTPUT
                        Path to the output file, or stdout if not set

Examples

Generate a shell script that bundles and runs a python script

As described in the Why did you make this? section.

See Demo for a recording of the process.

# make an executable, compressed .pyz file from the script post_status.py, with dependencies pysnc and requests-oauthlib, outputs to test.pyz
zau p post_status.py -d pysnc -d requests-oauthlib -o test.pyz -c

# run test.pyz to verify it works
./test.pyz

# create a shell script that runs test.pyz
zau sh test.pyz -o test.sh

# run test.sh to verify it works
./test.sh

# if it works, just copy the content of test.sh and paste it into a jenkins textbox that runs the script.
# make sure python3 >= 3.5 is installed on the jenkins executor node.

Why did you make this?

This project was created because I needed to run a python script with some dependencies in on a managed Jenkins environment,

and I wasn't able to install any software (including pypi packages) on the node.

I tried to bundle the pypi dependency in my script.

The closest I've tried was to use pyinstaller, which allows you to compile a single executable from a python script. It compiled and ran on my Linux box, but not on the Jenkins node because of incompatible glibc version used by python in the binary.

Then I remembered the zipapp module, which allowed me to use this script on Jenkins:

#!/usr/bin/env bash

ENCODED_PYZ_FILE='{{ encoded_pyz_file }}'

echo -n "${ENCODED_PYZ_FILE}" | base64 -d > /tmp/pyz.pyz
python3 /tmp/pyz.pyz

And voila, it worked!

So I decided to create this project to ease the process of creating such shell scripts for use on Jenkins.

Changelog