Package your python code into one zip file, even a virtual environment.
Project description
zipapps
Package your python code (with requirements) into a standalone zip file (like a jar
).
zipapps
is a pure-python library
, without any 3rd-party dependencies. Inspired by shiv but unlike shiv
, this lib will not always create new cache folders while running, and easy to combine multiple venv.pyz
files then let them work well together.
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. Then what you only need is a Python Interpreter as the runtime environment.
PS: The pyz ext could be any other suffixes even without ext names, so you can rename app.pyz
to app.zip
as you wish. Depends on PEP441, then the apps may be cross-platform
as long as written with pure python code without any C++ building processes.
Where to Use it?
- Hadoop-Streaming's mapper & reducer scripts.
- Simple deployment towards different servers with
jenkins
, or other CI/CD tools.- Easy to uploads a clean
standalone
zip file.
- Easy to uploads a clean
- Distribute
zipapp
with embedded python. - Use as a requirements zip path, or some venv usages.
import sys;sys.path.insert(0, 'app.pyz')
(without .so/.pyd)python3 app.pyz script.py
- Other usages need to be found, and enjoy yourself.
Install
pip install zipapps -U
Quick Start
zip as the app
- zipapps with requirements
-
python3 -m zipapps -u AUTO -a entry.py -m entry:main -o app.pyz aiohttp,psutils
-
- run app.pyz
-
python3 app.pyz
- cache will be unzipped to
./zipapps_cache/app
-
zip as the venv
- zipapps with requirements
-
python3 -m zipapps -u AUTO -o venv.pyz -r requirements.txt
-
- run entry.py with venv.pyz
-
python3 venv.pyz entry.py
- cache will be unzipped to
./zipapps_cache/venv
-
CMD Args
Packaging args
most common args:
-c
-a xxx.py
-u=AUTO
,-r requirements.txt
-o my_app.pyz
-m app.__main__:main
-p /usr/bin/python3
-h, --help
- show the simple doc
--includes, --add, -a
- The given paths will be copied to
cache_path
while packaging, which can be used while running. The path strings will be splited by ",".- such as
my_package_dir,my_module.py,my_config.json
- often used for libs not from
pypi
or some special config files
- such as
- the
output
arg ofzipapps.create_app
- The given paths will be copied to
--output, -o
- The path of the output file, defaults to
app.pyz
. - the
output
arg ofzipapps.create_app
- The path of the output file, defaults to
--python, -p
- The path of the Python interpreter which will be set as the
shebang line
, defaults toNone
.- with shebang
/usr/bin/python3
you can run app with./app.pyz
directly, no need forpython3 app.pyz
- with shebang
- the
interpreter
arg ofzipapps.create_app
- The path of the Python interpreter which will be set as the
--main, -m
- The entry point function of the application, the
valid format
is:package.module:function
package.module
module:function
package
- the
main
arg ofzipapps.create_app
- WARNING: If the
--main
arg is set,python3 app.pyz
will not be able to used as venv likepython3 app.pyz xxx.py
- The entry point function of the application, the
--compress, -c
Boolean
value, compress files with the deflate method or not.- the
compressed
arg ofzipapps.create_app
--unzip, -u
- The names which need to be unzipped while running, splited by ","
without ext
, such asbottle,aiohttp
, or the complete path likebin/bottle.py,temp.py
. For.so/.pyd
files(which can not be loaded by zipimport), or packages with operations of static files.- if unzip is set to "*", then will unzip all files and folders.
- if unzip is set to AUTO, then will add the
.pyd
and.so
files automatically.
- the
unzip
arg ofzipapps.create_app
- The names which need to be unzipped while running, splited by ","
--unzip-path, -up
- If
unzip
arg is not null, cache files will be unzipped to the given path while running. Defaults tozipapps_cache
, support some internal variables as runtime args:TEMP/HOME/SELF
as prefix, for exampleHOME/zipapps_cache
TEMP
meanstempfile.gettempdir()
HOME
meansPath.home()
SELF
means.pyz
file path.
- And you can also overwrite it with environment variables:
ZIPAPPS_CACHE
orUNZIP_PATH
- the
unzip_path
arg ofzipapps.create_app
- If
-cc, --pyc, --compile, --compiled
- Compile .py to .pyc for fast import, but zipapp does not work unless you unzip it(so NOT very useful).
- the
compiled
arg ofzipapps.create_app
--cache-path, --source-dir, -cp
- The cache path of zipapps to store site-packages and
includes
files. If not set, will create and clean-up in TEMP dir automately. - the
cache_path
arg ofzipapps.create_app
--shell, -s
- Only while
main
is not set, used for shell=True insubprocess.run
.- very rarely used, because extra sub-process is not welcome
- the
shell
arg ofzipapps.create_app
- Only while
--main-shell, -ss
- Only for
main
is not null, callmain
withsubprocess.Popen
:python -c "import a.b;a.b.c()"
. This is used forpsutil
ImportError of DLL load.- very rarely used too
- the
main_shell
arg ofzipapps.create_app
- Only for
--strict-python-path, -spp
Boolean
value. Ignore global PYTHONPATH, only usezipapps_cache
andapp.pyz
.- the
ignore_system_python_path
arg ofzipapps.create_app
-b, --build-id
- 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 useglob
function to get paths. For example, you can set requirements.txt as your build_id bypython3 -m zipapps -b requirements.txt -r requirements.txt
when you use pyz as venv.- very rarely used too too
- the
build_id
arg ofzipapps.create_app
- 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
- all the other (or
unknown
) args will be used by "pip install"- such as
-r requirements.txt
- such as
bottle aiohttp
- the
pip_args
arg ofzipapps.create_app
- such as
Running args
available args while the
.pyz
is running
--zipapps
- including some other pyz into PYTHONPATH
- often be used as
multiple venv combination
- for example
- building
python3 -m zipapps -o six.pyz six
python3 -m zipapps -o psutil.pyz -u AUTO psutil
python3 -m zipapps -o bottle.pyz bottle
- run
python3 six.pyz --zipapps=psutil.pyz,bottle.pyz -c "import psutil, bottle"
- building
Changelogs
- 2021.01.11
- add
--zipapps
arg while building pyz files- to activate some venv pyz with given paths while running it
- also support
TEMP/HOME/SELF
prefix, these internal variables are still runtime args.
- add
- 2020.12.27
- Combile multiple
pyz
files, do like this:- python3 -m zipapps -o six.pyz six
- python3 -m zipapps -o psutil.pyz -u AUTO psutil
- python3 six.pyz --zipapps=psutil.pyz -c "import six,psutil;print(six.file, psutil.file)"
- Combile multiple
- 2020.12.23
--unzip
support auto-check by-u AUTO
, alias for--unzip=AUTO_UNZIP
- fix
run_module
bug while running./app.pyz -m module
- 2020.12.21
- now will not run a new subprocess in most cases.
- using
runpy.run_path
andrunpy.run_module
- and using
subprocess.run
instead ofsubprocess.call
- using
- now will not run a new subprocess in most cases.
- 2020.12.13
--unzip
support complete path--unzip
support auto-check by--unzip=AUTO_UNZIP
- 2020.11.23
- add
activate_zipapps
to activate zipappsPYTHONPATH
easily
- add
- 2020.11.21
- reset unzip_path as the parent folder to unzip files
- so the cache path will be like
./zipapps_cache/app/
forapp.pyz
, - this is different from old versions.
- so the cache path will be like
- add environment variable
ZIPAPPS_CACHE
for argunzip_path
- add environment variable
ZIPAPPS_UNZIP
for argunzip
- reset unzip_path as the parent folder to unzip files
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distributions
Built Distribution
Hashes for zipapps-2021.1.11-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 9684b37868d6d8224c9e27f58750d6f89b4e0dae39c6e643b95875e4025c1e97 |
|
MD5 | 658ad95d597e3325ebe70ddf28eb12d9 |
|
BLAKE2b-256 | fbf3510213dde0cd9eeefd1bb7758d3115888f723e135d14ac32f549de55f25e |