## Entry points


## Dockerfile


Renders a recipe module into Dockerfile text.


Usage

``` python
Dockerfile(module)
```


A recipe is an ordinary Python module whose top-level code declares stages and instructions. Wrap it in a [Dockerfile](entry-points.md#docker_dsl.Dockerfile) and call [render](entry-points.md#docker_dsl.Dockerfile.render) to produce the text, once per configuration.


#### Parameter Attributes


`module: ModuleType`  


#### Example

``` python
>>> import my_recipe
>>> text = Dockerfile(my_recipe).render(gpu=True)
```


#### Methods

| Name | Description |
|----|----|
| [render()](#docker_dsl.Dockerfile.render) | Render the recipe into Dockerfile text. |


##### render()


Render the recipe into Dockerfile text.


Usage

``` python
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](stage-authoring.md#docker_dsl.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

``` python
>>> Dockerfile(my_recipe).render(tag="v1.0.0", path="Dockerfile")
```


## BuildContext


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


Usage

``` python
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](entry-points.md#docker_dsl.BuildContext.register).


#### Example

``` python
>>> 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()](#docker_dsl.BuildContext.register) | Declare a required config field. |


##### register()


Declare a required config field.


Usage

``` python
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](entry-points.md#docker_dsl.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

``` python
rendering()
```


Returns `True` while [Dockerfile.render](entry-points.md#docker_dsl.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`  
`True` during the render pass, `False` during discovery.