Shiv API

cli

shiv.cli.console_script_exists(site_packages_dirs: List[Path], console_script: str) → bool[source]

Return true if the console script with provided name exists in one of the site-packages directories.

Console script is expected to be in the ‘bin’ directory of site packages.

Parameters:

  • site_packages_dirs – Paths to site-packages directories on disk.

  • console_script – A console script name.

shiv.cli.copytree(src: Path, dst: Path) → None[source]

A utility function for syncing directories.

This function is based on shutil.copytree. In Python versions that are older than 3.8, shutil.copytree would raise FileExistsError if the “dst” directory already existed.

shiv.cli.find_entry_point(site_packages_dirs: List[Path], console_script: str) → str[source]

Find a console_script in a site-packages directory.

Console script metadata is stored in entry_points.txt per setuptools convention. This function searches all entry_points.txt files and returns the import string for a given console_script argument.

Parameters:

  • site_packages_dirs – Paths to site-packages directories on disk.

  • console_script – A console_script string.

constants —

This module contains various error messages.

builder

This module is a modified implementation of Python’s “zipapp” module.

We’ve copied a lot of zipapp’s code here in order to backport support for compression. https://docs.python.org/3.7/library/zipapp.html#cmdoption-zipapp-c

shiv.builder.create_archive(sources: List[Path], target: Path, interpreter: str, main: str, env: Environment, compressed: bool = True) → None[source]

Create an application archive from SOURCE.

This function is a heavily modified version of stdlib’s zipapp.create_archive

Path.rglob extended to follow symlinks, while we wait for Python 3.13.

shiv.builder.write_file_prefix(f: IO[Any], interpreter: str) → None[source]

Write a shebang line.

Parameters:

  • f – An open file handle.

  • interpreter – A path to a python interpreter.

shiv.builder.write_to_zipapp(archive: ZipFile, arcname: str, data: bytes, date_time: Tuple[int, int, int, int, int, int], compression: int, stat: stat_result | None = None) → None[source]

Write a file or a bytestring to a ZipFile as a separate entry and update contents_hash as a side effect.

pip

shiv.pip.clean_pip_env() → Generator[None, None, None][source]

A context manager for temporarily removing ‘PIP_REQUIRE_VIRTUALENV’ from the environment.

Since shiv installs via –target, we need to ignore venv requirements if they exist.

shiv.pip.install(args: List[str]) → None[source]

pip install as a function.

Accepts a list of pip arguments.

>>> install(['numpy', '--target', 'site-packages'])
Collecting numpy
Downloading numpy-1.13.3-cp35-cp35m-manylinux1_x86_64.whl (16.9MB)
    100% || 16.9MB 53kB/s
Installing collected packages: numpy
Successfully installed numpy-1.13.3

bootstrap

shiv.bootstrap.bootstrap()[source]

Actually bootstrap our shiv environment.

shiv.bootstrap.cache_path(archive, root_dir, build_id)[source]

Returns a ~/.shiv cache directory for unzipping site-packages during bootstrap.

Parameters:

  • archive (ZipFile) – The zipfile object we are bootstrapping from.

  • root_dir (str) – Optional, either a path or environment variable pointing to a SHIV_ROOT.

  • build_id (str) – The build id generated at zip creation.

shiv.bootstrap.current_zipfile()[source]

A function to vend the current zipfile, if any

shiv.bootstrap.ensure_no_modify(site_packages, hashes)[source]

Compare the sha256 hash of the unpacked source files to the files when they were added to the pyz.

shiv.bootstrap.extend_python_path(environ, additional_paths)[source]

Create or extend a PYTHONPATH variable with the frozen environment we are bootstrapping with.

shiv.bootstrap.extract_site_packages(archive, target_path, compile_pyc=False, compile_workers=0, force=False)[source]

Extract everything in site-packages to a specified path.

Parameters:

  • archive (ZipFile) – The zipfile object we are bootstrapping from.

  • target_path (Path) – The path to extract our zip to.

  • compile_pyc (bool) – A boolean to dictate whether we pre-compile pyc.

  • compile_workers (int) – An int representing the number of pyc compiler workers.

  • force (bool) – A boolean to dictate whether or not we force extraction.

shiv.bootstrap.import_string(import_name)[source]

Returns a callable for a given setuptools style import string

Parameters:

import_name (str) – A console_scripts style import string

shiv.bootstrap.run(module)[source]

Run a module in a scrubbed environment.

If a single pyz has multiple callers, we want to remove these vars as we no longer need them and they can cause subprocesses to fail with a ModuleNotFoundError.

Parameters:

module (Callable) – The entry point to invoke the pyz with.

bootstrap.environment

This module contains the Environment object, which combines settings decided at build time with overrides defined at runtime (via environment variables).

bootstrap.interpreter

The code in this module is adapted from https://github.com/pantsbuild/pex/blob/master/pex/pex.py

It is used to enter an interactive interpreter session from an executable created with shiv.