venvstacks.pack_venv

Warning

The Python API is NOT YET STABLE. Function, class, and method names may change between releases without any deprecation period.

Utility library to convert Python virtual environments to portable archives.

Make env portable by making internal symlinks relative and external links hard.

If set, containing path must be a parent directory of the environment path and is used as the boundary for creating relative symlinks instead of hardlinks. If not set, the environment path itself is used as the boundary for creating relative symlinks.

Returns a 2-tuple containing lists of internal relative link conversions and external hard link conversions. Each list contains source/target Path pairs.

venvstacks.pack_venv.create_archive(source_dir: str | PathLike[str], archive_base_name: str | PathLike[str], *, install_target: str | None = None, clamp_mtime: datetime | None = None, work_dir: str | PathLike[str] | None = None, show_progress: bool = True) → Path

shutil.make_archive replacement, tailored for Python virtual environments.

  • injects a suitable postinstall.py script for the environment being archived

  • always creates zipfile archives on Windows and xztar archives elsewhere

  • excludes __pycache__ folders (to reduce archive size and improve reproducibility)

  • excludes package metadata RECORD files (to improve reproducibility)

  • excludes sitecustomize.py files (generated by the post-installation script)

  • replaces symlinks with copies on Windows and allows external symlinks elsewhere

  • discards tar entry owner and group information

  • clears tar entry high mode bits (setuid, setgid, sticky)

  • clears tar entry group/other write mode bits

  • clamps mtime of archived files to the given clamp mtime at the latest

  • shows progress reporting by default (archiving built ML/AI libs is slooooow)

Set work_dir if /tmp is too small for archiving tasks

venvstacks.pack_venv.export_venv(source_dir: str | PathLike[str], target_dir: str | PathLike[str], run_postinstall: Callable[[Path, Path], None] | None = None) → Path

Export the given build environment, skipping archive creation and unpacking.

  • injects a suitable postinstall.py script for the environment being exported

  • excludes __pycache__ folders (for consistency with archive publication)

  • excludes package metadata RECORD files (for consistency with archive publication)

  • excludes sitecustomize.py files (generated by the post-installation script)

  • replaces symlinks with copies on Windows or if the target doesn’t support symlinks

If supplied, run_postinstall is called with the path to the environment’s Python interpreter and its postinstall script, allowing execution of the post-install script by the calling application. The post-install script is NOT implicitly executed by the export process.

Returns the path to the exported environment.

venvstacks.pack_venv.get_archive_path(archive_base_name: str | PathLike[str]) → Path

Report the name of the archive that will be created for the given base name.