----------------------------------------------------------------------
This is the API documentation for the docker_dsl library.
----------------------------------------------------------------------


## Entry points

Declare config and render a recipe into a Dockerfile.


Dockerfile(module: 'ModuleType') -> None

Renders a recipe module into Dockerfile text.

A recipe is an ordinary Python module whose top-level code declares stages
and instructions. Wrap it in a `Dockerfile` and call `render` to produce the
text, once per configuration.

Example:
    >>> import my_recipe
    >>> text = Dockerfile(my_recipe).render(gpu=True)

BuildContext()

Recipe-facing handle for config fields, exported as `context`.

Read a registered field as an attribute: `context.gpu` returns the
validated value during a render pass, and `None` during discovery. Declare
fields with `register`.

Example:
    >>> from docker_dsl import context as ctx
    >>> ctx.register("gpu", bool)
    >>> base = "nvidia/cuda:12.4.0-base" if ctx.gpu else "ubuntu:24.04"

rendering() -> 'bool'

Report whether a render pass is in progress.

Returns `True` while `Dockerfile.render` is re-executing a recipe, and
`False` during the discovery import. Use it to guard code that should run
only when the build is live.

Returns:
    `True` during the render pass, `False` during discovery.


## Stage authoring

Declare stages and emit instructions.


Stage(base: 'str', name: 'str' = 'base', graph: 'StageGraph | None' = <factory>, instructions: 'list[Instruction]' = <factory>, mounts_stack: 'list[Mount]' = <factory>, env_stack: 'list[dict[str, str]]' = <factory>, counter: 'int' = 0) -> None

A build stage — one `FROM` and the instructions that follow it.

Open a stage as a context manager; every method call inside the block
appends an instruction to it. Derive child stages with `stage` and copy
artifacts between them with `copy`.

Args:
    base: The base image, or a parent stage's name for a derived stage.
    name: The stage name used in `FROM ... AS <name>`. Child stages created
        with `stage` infer this from the `as` target.

Example:
    >>> with Stage("ubuntu:24.04") as s:
    ...     s.workdir("/app")
    ...     s.cmd("./server")

MountScope(stage: 'Stage', mount: 'Mount') -> None

A `with` block that applies a mount to the `RUN` commands inside it.

Returned by `Stage.cache`, `Stage.secret`, and `Stage.bind`. Nest several
in one `with` to apply them together. You rarely construct this directly.

EnvScope(stage: 'Stage', env: 'dict[str, str]') -> None

A `with` block that confines env variables to the `RUN` commands inside.

Returned by `Stage.env`. Inside the block, the variables are exported ahead
of each `RUN` rather than emitted as a stage-wide `ENV`, so they do not leak
into the image. You rarely construct this directly.


## The run builder

Accumulate shell commands into one RUN instruction.


RunBuilder(stage: 'Stage', commands: 'list[ShellCommand]' = <factory>, *, apt_updated: 'bool' = False, apt_dirty: 'bool' = True) -> None

Accumulates shell commands into a single `RUN` instruction.

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.

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

AptMixin(*, apt_updated: 'bool' = False, apt_dirty: 'bool' = True) -> None

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

RedirectableCmd(builder: 'RunBuilder', text: 'str') -> None

A pending `echo` awaiting a redirect target.

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.

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

CdScope(builder: 'RunBuilder', path: 'str') -> None

A `cd` that optionally restores the previous directory.

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.

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

CmdInvoker(builder: 'RunBuilder', binary: 'str') -> None

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

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.

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


## Introspection

Query the active build during a render pass.


current_stage() -> 'Stage | None'

Return the stage of the innermost open `with Stage(...)` block.

Use it inside a reusable helper that operates on whichever stage is active,
so callers need not pass the stage explicitly. Returns `None` outside any
stage block, including during the discovery pass.

Returns:
    The active stage, or `None` when no stage block is open.