Entry points
Dockerfile
Renders a recipe module into Dockerfile text.
Usage
Dockerfile(module)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.
Parameter Attributes
module: ModuleType
Example
>>> import my_recipe
>>> text = Dockerfile(my_recipe).render(gpu=True)Methods
| Name | Description |
|---|---|
| render() | Render the recipe into Dockerfile text. |
render()
Render the recipe into Dockerfile text.
Usage
render(path=None, **config_values)Rendering runs the recipe module a second time. The first run — the import that produced module — is the discovery pass, where every DSL call is a no-op and only context.register fires, declaring the config schema. This call validates config_values against that schema with pydantic, then re-executes the module body so each Stage and method call accumulates into the active build.
Parameters
path: str | Path | None = None-
Where to write the rendered text. When given, the file is written; the text is returned either way.
**config_values: Any-
One value per field the recipe registered with
context.register. Every registered field is required, and values are validated before the render pass runs.
Returns
str- The rendered Dockerfile text.
Example
>>> Dockerfile(my_recipe).render(tag="v1.0.0", path="Dockerfile")BuildContext
Recipe-facing handle for config fields, exported as context.
Usage
BuildContext()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"Methods
| Name | Description |
|---|---|
| register() | Declare a required config field. |
register()
Declare a required config field.
Usage
register(name, type_)Call this in the recipe body, once per field the recipe accepts. It takes effect only during the discovery pass; on the render pass it is a no-op, so the schema is fixed by what the import declared. pydantic validates the field’s value against type_ before rendering.
Parameters
name: str-
Field name, passed to Dockerfile.render and exposed as
context.<name>. type_: type- The field’s type, used to validate the supplied value.
rendering()
Report whether a render pass is in progress.
Usage
rendering()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
bool-
Trueduring the render pass,Falseduring discovery.