RunBuilder

Accumulates shell commands into a single RUN instruction.

Usage

Source

RunBuilder()

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.