cape.sysutils: System utilities for using CAPE

This module provides various “system” utilities such as providing a universal Python method to open a PDF file for viewing.

cape.sysutils.get_pdf_viewer() → str

Get the preferred PDF viewer application based on system

Call:
>>> viewer = get_pdf_viewer()
Outputs:
viewer: str

Name of application to open PDF

Versions:

  • 2026-08-07 @ddalle: v1.0

cape.sysutils.get_png_viewer() → str

Get the preferred PNG viewer application based on system

Call:
>>> viewer = get_png_viewer()
Outputs:
viewer: str

Name of application to open PNG

Versions:

  • 2026-08-31 @ddalle: v1.0

cape.sysutils.open_img(fname: str, terminal: bool = True, dpi: int = 120, page: int = 0, width: int | str | None = None) → str

Attempt to open any image file, preferring in-terminal viewing

Call:
>>> open_img(fname, wait=False)
Inputs:
fname: str

Name of file to open

terminal: {True} | False

Option to try showing image in terminal

dpi: {120} | int

Resolution for converting PDFs to PNGs

page: {0} | int

Zero-based page index of PDF to view in terminal

width: {None} | int | str

Width, in terminal columns (or percent, e.g. "50%"), to use when displaying image in terminal; None uses the original image size

Output:
viewer: str

Name of viewer application (or "terminal" or "pdf")

cape.sysutils.open_pdf(fname: str, remote: str | None = None, wait: bool = False, pull: bool = False, local: bool | None = None) → Popen

Open a PDF file if found

Call:
>>> open_pdf(fname, wait=False)
Inputs:
fname: str

Name of file to open

remote: {None} | str

Absolute folder on remote host (or $PWD)

wait: True | {False}

Option to wait until PDF is closed

pull: True | {False}

Pull PDF from RemoteHost and open

local: {None} | True | False

Force “local” host instead of determining automatically

Output:
proc: subprocess.Popen

Subprocess handle

Versions:

  • 2026-08-07 @ddalle: v1.0

cape.sysutils.open_png(fname: str, terminal: bool = True, wait: bool = False) → str

Open a PNG file if found

Call:
>>> open_png(fname, wait=False)
Inputs:
fname: str

Name of file to open

terminal: {True} | False

Option to try showing image in terminal

wait: True | {False}

Option to wait until PNG is closed

Output:
viewer: str

Name of viewer used

cape.sysutils.pdftopng(fpdf: str, fpng: str | None = None, dpi: int = 120, page: int = 0) → str

Convert one page of a PDF to a PNG image

Uses the first available system command:

  1. pdftoppm (poppler)

  2. gs, gswin64c, gswin32c (Ghostscript)

  3. pdftocairo (poppler)

  4. magick or convert (ImageMagick)

Call:
>>> fpng = pdftopng(fpdf, fpng=None, dpi=200, page=0)
Inputs:
fpdf: str

Name of PDF file to read

fpng: {None} | str

Name of PNG file to write; uses fpdf with extension changed to .png if not given

dpi: {120} | int

Resolution of output image, in dots per inch

page: {0} | int

Index of PDF page to convert, first page is 0

Outputs:
fpng: str

Name of PNG file created

Versions:

  • 2026-08-31 @ddalle: v1.0

cape.sysutils.post_file(pat1: str, *pats, v: bool = False) → Tuple[int, list]

Collect file(s) in tar ball; send to RemoteHost if necessary

Call:
>>> ierr, filenames = post_file(pat1, *pats)
Outputs:
ierr: int

Return code

filenames: list[str]

List of posted file names

cape.sysutils.receive_file() → list

Receive the current cached tarball

Call:
>>> filenames = receive_file()
Outputs:
filenames: list[str]

List of unpacked files

cape.sysutils.terminal_image_supported() → bool

Check if the terminal can display images

Relies on the textual_image and rich packages and checks for sixel or kitty/TGP support.

Call:
>>> q = terminal_image_supported()
Outputs:
q: bool

Whether terminal can display images

Versions:

  • 2026-09-06 @ddalle: v1.0