## Stage authoring ## Stage A build stage -- one `FROM` and the instructions that follow it. Usage ``` python Stage( base, name="base", graph=current_graph.get(), instructions=list(), mounts_stack=list(), env_stack=list(), counter=0 ) ``` Open a stage as a context manager; every method call inside the block appends an instruction to it. Derive child stages with [stage](stage-authoring.md#docker_dsl.Stage.stage) and copy artifacts between them with [copy](stage-authoring.md#docker_dsl.Stage.copy). #### Parameters `base: str` The base image, or a parent stage's name for a derived stage. `name: str = ``"base"` The stage name used in `FROM ... AS `. Child stages created with [stage](stage-authoring.md#docker_dsl.Stage.stage) infer this from the `as` target. #### Example ``` python >>> with Stage("ubuntu:24.04") as s: ... s.workdir("/app") ... s.cmd("./server") ``` #### Methods | Name | Description | |----|----| | [arg()](#docker_dsl.Stage.arg) | Emit an `ARG` build argument. | | [env()](#docker_dsl.Stage.env) | Emit an `ENV` instruction, and optionally scope it. | | [add_to_path()](#docker_dsl.Stage.add_to_path) | Prepend entries to `PATH` with an `ENV` instruction. | | [workdir()](#docker_dsl.Stage.workdir) | Emit a `WORKDIR` instruction. | | [copy()](#docker_dsl.Stage.copy) | Emit a `COPY` instruction. | | [entrypoint()](#docker_dsl.Stage.entrypoint) | Emit an `ENTRYPOINT` in exec form. | | [cmd()](#docker_dsl.Stage.cmd) | Emit a `CMD` in exec form. | | [run()](#docker_dsl.Stage.run) | Emit a `RUN` instruction, directly or via a builder. | | [cache()](#docker_dsl.Stage.cache) | Scope a BuildKit cache mount over a `with` block. | | [secret()](#docker_dsl.Stage.secret) | Scope a BuildKit secret mount over a `with` block. | | [bind()](#docker_dsl.Stage.bind) | Scope a BuildKit bind mount over a `with` block. | | [stage()](#docker_dsl.Stage.stage) | Derive a child stage from this one (`FROM AS ...`). | ##### arg() Emit an `ARG` build argument. Usage ``` python arg(name, value, *, env=False) ``` ##### Parameters `name: str` Argument name. `value: str` Default value. `env: bool = ``False` When `True`, also emit an `ENV` that forwards the argument into the image environment. ##### env() Emit an `ENV` instruction, and optionally scope it. Usage ``` python env(mapping) ``` Keys whose value is `None` are dropped, so a conditional value need not be guarded at the call site. Used as a plain call, the variables persist for the rest of the stage. Used as a `with` block, they apply only to the `RUN` commands inside it (see [EnvScope](stage-authoring.md#docker_dsl.EnvScope)). ##### Parameters `mapping: dict[str, str] | dict[str, str | None]` Environment variables to set. `None` values are skipped. ##### Returns EnvScope An [EnvScope](stage-authoring.md#docker_dsl.EnvScope) for optional `with`-block scoping. ##### add_to_path() Prepend entries to `PATH` with an `ENV` instruction. Usage ``` python add_to_path(*entries) ``` ##### Parameters `*entries: str` Directories to prepend, ahead of the existing `$PATH`. ##### workdir() Emit a `WORKDIR` instruction. Usage ``` python workdir(path) ``` ##### Parameters `path: str` The working directory for later instructions. ##### copy() Emit a `COPY` instruction. Usage ``` python copy(src, dst=None, *, image=None, stage=None, from_=None, link=None) ``` Pass [stage](stage-authoring.md#docker_dsl.Stage.stage) to copy an artifact from another stage (`COPY --from`), `image` to copy from a named image, or neither to copy from the build context. `--link` is added automatically for cross-stage and cross-image copies; override with `link`. ##### Parameters `src: str` Source path. `dst: str | None = None` Destination path. Defaults to `src`. `image: str | None = None` Image to copy from. `stage: `Stage` | None = None` Stage to copy from; its name becomes the `--from` value. `from_: str | None = None` Raw `--from` value, when neither `image` nor [stage](stage-authoring.md#docker_dsl.Stage.stage) fits. `link: bool | None = None` Force `--link` on or off. ##### entrypoint() Emit an `ENTRYPOINT` in exec form. Usage ``` python entrypoint(*cmd) ``` ##### Parameters `*cmd: str` The executable and its fixed arguments. ##### cmd() Emit a `CMD` in exec form. Usage ``` python cmd(*args) ``` ##### Parameters `*args: str` The default command and arguments. ##### run() Emit a `RUN` instruction, directly or via a builder. Usage ``` python run(self) -> RunBuilder run(self, args: str = (), env: dict[str, str] | None = None) -> None ``` Called with arguments, it emits one `RUN` for that single command. Called with no arguments, it returns a [RunBuilder](the-run-builder.md#docker_dsl.RunBuilder) to use as a `with` block; the commands accumulated inside it become one `&&`-joined `RUN`, picking up any mounts and env scopes open around the block. ##### Parameters `*args: str` A single command's words. Omit to get a [RunBuilder](the-run-builder.md#docker_dsl.RunBuilder). `env: dict[str, str] | None = None` Inline environment variables for the command. ##### Returns RunBuilder` | None` A [RunBuilder](the-run-builder.md#docker_dsl.RunBuilder) when called with no arguments; otherwise `None`. ##### Example ``` python >>> with s.run() as r: ... r.apt_install("git", "curl") ``` ##### cache() Scope a BuildKit cache mount over a `with` block. Usage ``` python cache(target, *, lock=False) ``` Every `RUN` inside the block mounts a persistent cache at `target`, so package and build caches survive between builds. ##### Parameters `target: str` Mount path inside the container. `lock: bool = ``False` Use `sharing=locked` instead of the default `shared`, to serialize concurrent builds that write the same cache. ##### Returns MountScope A [MountScope](stage-authoring.md#docker_dsl.MountScope) to use as a `with` block. ##### secret() Scope a BuildKit secret mount over a `with` block. Usage ``` python secret(secret_id, *, target) ``` The secret is mounted only for `RUN` commands inside the block and never lands in an image layer. ##### Parameters `secret_id: str` Secret id, supplied at build time with `docker build --secret`. `target: str` Mount path inside the container. ##### Returns MountScope A [MountScope](stage-authoring.md#docker_dsl.MountScope) to use as a `with` block. ##### bind() Scope a BuildKit bind mount over a `with` block. Usage ``` python bind(*, source, target) ``` Mounts a build-context path read-only for `RUN` commands inside the block, avoiding a `COPY` when files are only needed during the command. ##### Parameters `source: str` Path in the build context. `target: str` Mount path inside the container. ##### Returns MountScope A [MountScope](stage-authoring.md#docker_dsl.MountScope) to use as a `with` block. ##### stage() Derive a child stage from this one (`FROM AS ...`). Usage ``` python stage(*, name=None) ``` The child's name is taken from the `as` target of the `with` statement -- `with base.stage() as builder:` names it `builder` -- so it need not be passed. Override with `name`. ##### Parameters `name: str | None = None` Explicit stage name, overriding the inferred one. ##### Returns Stage A new [Stage](stage-authoring.md#docker_dsl.Stage) based on this stage. ##### Example ``` python >>> with base.stage() as builder: ... builder.run("make") ``` ## MountScope A `with` block that applies a mount to the `RUN` commands inside it. Usage ``` python MountScope(stage, mount) ``` Returned by [Stage.cache](stage-authoring.md#docker_dsl.Stage.cache), [Stage.secret](stage-authoring.md#docker_dsl.Stage.secret), and [Stage.bind](stage-authoring.md#docker_dsl.Stage.bind). Nest several in one `with` to apply them together. You rarely construct this directly. #### Parameter Attributes `stage: `Stage `mount: Mount` ## EnvScope A `with` block that confines env variables to the `RUN` commands inside. Usage ``` python EnvScope(stage, env) ``` Returned by [Stage.env](stage-authoring.md#docker_dsl.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. #### Parameter Attributes `stage: `Stage `env: dict[str, str]`