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:
pip3 install vhs
Then resolve VHS binary and run it:
import vhs
vhs_runner = vhs.resolve()
vhs_runner.run("./example.tape", "./example.gif")
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(*, cache_path: str | ~os.PathLike | None = None, min_version: str = '0.5.0', quiet: bool = True, env: ~typing.Dict[str, str] | None = None, cwd: str | ~os.PathLike | None = None, install: bool = True, reporter: ~vhs.ProgressReporter = <vhs.ProgressReporter object>, timeout: int = 15, retry: ~urllib3.util.retry.Retry | None = None) Vhs [source]
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.
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, andDefaultProgressReporter
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.
- Returns:
resolved VHS installation.
- Raises:
VhsError – VHS not available or installation failed.
- vhs.default_cache_path() Path [source]
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 | None = None)[source]
Interface for a VHS installation.
Do not create directly, use
resolve()
instead.- run(input_path: str | PathLike, output_path: str | PathLike | None = None, *, quiet: bool | None = True, env: Dict[str, str] | None = None, cwd: str | PathLike | None = None)[source]
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 | None = None, *, quiet: bool | None = True, env: Dict[str, str] | None = None, cwd: str | PathLike | None = None)[source]
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.VhsRunError(returncode, cmd, output=None, stderr=None)[source]
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[source]
Interface for reporting installation progress.
- progress(desc: str, dl_size: int, total_size: int, speed: float, /)[source]
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.