The run builder

RunBuilder

Accumulates shell commands into a single RUN instruction.

Usage

Source

RunBuilder(
    apt_updated=False,
    apt_dirty=True,
    stage,
    commands=list(),
)

Obtained from Stage.run used as a with block. Any attribute you access becomes a shell binary: r.git("clone", url) emits git clone <url>, with keyword arguments turned into flags by CmdInvoker. The shipped builder.pyi type stub gives editors completions for the common binaries. Use __call__ for a raw command line, and the apt helpers from AptMixin for package installs.

On block exit, the accumulated commands join with && into one RUN; nothing is emitted if the block raises or stays empty.

Parameter Attributes

apt_updated: bool = False
apt_dirty: bool = True
stage: Stage
commands: list[ShellCommand] = list()

Example

>>> with s.run() as r:
...     r.git("clone", "https://example.com/repo.git", ".")
...     r.make("-j$(nproc)")

Methods

Name Description
__call__() Append a raw command line, for anything the dispatch can’t express.
echo() Build an echo whose output you redirect to a file.
cd() Change directory, as a statement or a scoped with block.
curl_bash() Pipe a remote install script into bash over a pinned-TLS curl.
install() Download a tarball and extract it into a directory.
fetch_file() Download a single file, creating its parent directory first.
__call__()

Append a raw command line, for anything the dispatch can’t express.

Usage

Source

__call__(raw, *, env=None)
Parameters
raw: str

The verbatim shell command.

env: dict[str, str] | None = None
Environment variables prefixed onto the command.
echo()

Build an echo whose output you redirect to a file.

Usage

Source

echo(text)

Apply >> to append or > to truncate, with the destination path on the right (see RedirectableCmd).

Parameters
text: str
The text to echo. It is quoted for you.
Returns
RedirectableCmd
A RedirectableCmd awaiting a >> or > redirect.
Example
>>> r.echo("deb ... main") >> "/etc/apt/sources.list.d/extra.list"
cd()

Change directory, as a statement or a scoped with block.

Usage

Source

cd(path)

As a bare call, later commands run from path. As a with block, the directory is restored with cd - on exit (see CdScope).

Parameters
path: str
Directory to change into.
Returns
CdScope
A CdScope, usable as a statement or a with block.
Example
>>> with r.cd("/src"):
...     r.make("install")
curl_bash()

Pipe a remote install script into bash over a pinned-TLS curl.

Usage

Source

curl_bash(url, *, args=())
Parameters
url: str

Script URL, fetched with --proto '=https' --tlsv1.2.

args: tuple[str, …] = ()
Arguments passed to the script after -s --.
install()

Download a tarball and extract it into a directory.

Usage

Source

install(url, *, target="/usr/local/bin", strip=1)
Parameters
url: str

Tarball URL.

target: str = "/usr/local/bin"

Directory to extract into.

strip: int = 1
Leading path components to strip (tar --strip-components).
fetch_file()

Download a single file, creating its parent directory first.

Usage

Source

fetch_file(url, dest)
Parameters
url: str

File URL.

dest: str
Destination path; its parent directory is created.

AptMixin

AptMixin(*, apt_updated: ‘bool’ = False, apt_dirty: ‘bool’ = True)

Usage

Source

AptMixin(*, apt_updated=False, apt_dirty=True)

Parameter Attributes

apt_updated: bool = False
apt_dirty: bool = True

Methods

Name Description
apt_install() Install apt packages, inserting apt-get update only when stale.
add_apt_ppa() Add a PPA and mark the package lists stale.
add_apt_repo() Add a third-party apt repository with its signing key.
apt_install()

Install apt packages, inserting apt-get update only when stale.

Usage

Source

apt_install(*packages, fast=False)

An update runs before the first install and again after anything that dirties the package lists (add_apt_ppa, add_apt_repo), so you never write apt-get update by hand and never run it redundantly.

Parameters
*packages: str

Package names to install.

fast: bool = False
Install with apt-fast instead of apt-get (requires apt-fast to be installed first).
add_apt_ppa()

Add a PPA and mark the package lists stale.

Usage

Source

add_apt_ppa(ppa)

The next apt_install re-runs apt-get update so the PPA’s packages are visible.

Parameters
ppa: str
PPA spec, e.g. ppa:apt-fast/stable.
add_apt_repo()

Add a third-party apt repository with its signing key.

Usage

Source

add_apt_repo(key_url, repo_url, *, name)

Fetches the GPG key, dearmors it into /usr/share/keyrings, writes a signed-by source list, and marks the package lists stale so the next apt_install re-runs apt-get update.

Parameters
key_url: str

URL of the repository’s GPG key.

repo_url: str

The deb line’s repository and components, e.g. https://example.com/apt stable main.

name: str
Basename for the keyring and source-list files.

RedirectableCmd

A pending echo awaiting a redirect target.

Usage

Source

RedirectableCmd(builder, text)

Returned by RunBuilder.echo. Apply >> to append to a file or > to truncate it, with the path on the right. The echoed text is quoted for you.

Parameter Attributes

builder: RunBuilder
text: str

Example

>>> r.echo("pillow>=11") >> "/root/overrides.txt"   # append
>>> r.echo("numpy<3") > "/etc/pip/constraint.txt"    # truncate

CdScope

A cd that optionally restores the previous directory.

Usage

Source

CdScope(builder, path)

Returned by RunBuilder.cd. As a bare statement it just changes directory. As a with block it appends cd - on exit, so later commands resume where they were.

Parameter Attributes

builder: RunBuilder
path: str

Example

>>> with r.cd("/src/build"):
...     r.make("install")
... # cd /src/build && make install && cd -

CmdInvoker

A bound shell binary, produced by RunBuilder’s attribute dispatch.

Usage

Source

CmdInvoker(builder, binary)

Accessing r.<name> yields one of these for <name>; calling it appends the command. Positional arguments pass through verbatim. Keyword arguments become flags: depth="1" adds --depth 1, verbose=True adds --verbose, and a False value is dropped. Underscores in names become hyphens.

Parameter Attributes

builder: RunBuilder
binary: str

Example

>>> r.git("clone", url, depth="1", recurse_submodules=True)
... # git clone <url> --depth 1 --recurse-submodules