Python VHS

Python-VHS is a tiny python wrapper around VHS, a tool by charm that renders terminal commands into GIFs.

This package searches for VHS and its dependencies in system’s PATH, and invokes them. On Linux, if VHS is not found in the system, Python-VHS can download necessary binaries from GitHub.

Quickstart

Install VHS:

$ pip install vhs

Then resolve VHS binary and run it:

import vhs

vhs_runner = vhs.resolve()
vhs_runner.run("./example.tape", "./example.gif")

Or run VHS from command line:

$ python -m vhs --help

Reference

The entry point of the package is the resolve() function. It searches for an installed VHS, checks its version, downloads a new one if necessary, and returns a Vhs object through which you can invoke the found VHS binary:

vhs.resolve(*, min_version: str = '0.5.0', max_version: str | None = None, cache_path: str | PathLike[str] | None = None, quiet: bool = True, env: Dict[str, str] | None=None, cwd: str | PathLike[str] | None = None, install: bool = True, reporter: ProgressReporter = <vhs.ProgressReporter object>, timeout: int = 15, retry: Retry | None = None, auth: Auth | None = None, repo: str = 'charmbracelet/vhs') → Vhs

Find a system VHS installation or download VHS from GitHub.

If VHS is not installed, or it’s outdated, try to download it and install it into cache_path.

Automatic download only works on 64-bit Linux. MacOS users will be presented with an instruction to use brew, and other systems users will get a link to VHS installation guide.

Parameters:

  • cache_path – path where VHS binaries should be downloaded to.

  • min_version – minimal VHS version required.

  • max_version – maximal VHS version required. Version is not limited is None.

  • quiet – if true (default), any output from the VHS binary is hidden.

  • env – overrides environment variables for the VHS process.

  • cwd – overrides current working directory for the VHS process.

  • install – if false, disables installing VHS from GitHub.

  • reporter – a hook that will be called to inform user about installation progress. See ProgressReporter for API documentation, and DefaultProgressReporter for an example.

  • timeout – timeout in seconds for connecting to GitHub APIs.

  • retry – retry policy for reading from GitHub and downloading releases. The default retry polity uses exponential backoff to avoid rate limiting.

  • auth – authentication method for downloading releases from GitHub. If set to None, requests to GitHub’s API will be rate limited.

  • repo –

    where to download VHS from. Default is the official installation. You may use this option to switch to a fork with support for SVG output.

Returns:

resolved VHS installation.

Raises:

VhsError – VHS not available or installation failed.

vhs.default_cache_path() → Path

Return default path where VHS binaries should be downloaded to.

Currently it is equal to pathlib.Path(tempfile.gettempdir()) / "python_vhs_cache".

final class vhs.Vhs(*, _vhs_path: Path, _path: str, _quiet: bool = True, _env: Dict[str, str] | None = None, _cwd: str | PathLike[str] | None = None)

Interface for a VHS installation.

Do not create directly, use resolve() instead.

run(input_path: str | PathLike[str], output_path: str | PathLike[str] | None = None, *, quiet: bool | None = True, env: Dict[str, str] | None = None, cwd: str | PathLike[str] | None = None)

Renter the given VHS file.

Parameters:

  • input_path – path to a tape file.

  • output_path – path to the output file. By default, puts output to whichever path is set in the tape.

  • quiet – redefine quiet for this invocation. (see resolve()).

  • env – redefine env for this invocation. (see resolve()).

  • cwd – redefine cmd for this invocation. (see resolve()).

Raises:

VhsRunError – VHS process failed with non-zero return code.

run_inline(input_text: str, output_path: str | PathLike[str] | None = None, *, quiet: bool | None = True, env: Dict[str, str] | None = None, cwd: str | PathLike[str] | None = None)

Like run(), but accepts tape contents rather than a file.

Parameters:

  • input_text – contents of a tape.

  • output_path – path to the output file. By default, puts output to whichever path is set in the tape.

  • quiet – redefine quiet for this invocation (see resolve()).

  • env – redefine env for this invocation (see resolve()).

  • cwd – redefine cmd for this invocation (see resolve()).

Raises:

VhsRunError – VHS process failed with non-zero return code.

In case of an error, VHS raises a VhsError or its subclass:

class vhs.VhsError

Raised when VHS is unavailable, or when installation fails.

class vhs.VhsRunError(returncode, cmd, output=None, stderr=None)

Raised when VHS process fails.

By default, the resolve() function silently detects or installs VHS, without printing anything (it may emit warning log messages to the "vhs" logger).

You can display installation progress by passing a ProgressReporter. Specifically, there’s DefaultProgressReporter which will cover most basic cases:

class vhs.ProgressReporter

Interface for reporting installation progress.

start()

Called when installation starts.

progress(desc: str, dl_size: int, total_size: int, speed: float, /)

Called to update current progress.

Parameters:

  • desc – description of the currently performed operation.

  • dl_size – when the installer downloads files, this number indicates number of bytes downloaded so far. Otherwise, it is set to zero.

  • total_size – when the installer downloads files, this number indicates total number of bytes to download. Otherwise, it is set to zero.

  • speed – when the installer downloads files, this number indicates current downloading speed, in bytes per second. Otherwise, it is set to zero.

finish(exc_type, exc_val, exc_tb)

Called when installation finishes.

class vhs.DefaultProgressReporter(stream: TextIO | None = None)

Default reporter that prints progress to stderr.