Recipe

Recipe classes for parsing and working with conda recipes.

rattler-build uses a two-stage recipe system:

1. Stage0 - Parsed YAML recipes before Jinja template evaluation
2. Stage1 - Fully evaluated recipes ready for building

You can import the recipe classes from rattler_build:

from rattler_build import Stage0Recipe, SingleOutputRecipe, MultiOutputRecipe, Stage1Recipe

Stage0 - Parsed Recipes

Stage0Recipe

Bases: ABC

A parsed conda recipe (stage0).

This is an abstract base class. Use from_yaml(), from_file(), or from_dict() to create concrete instances (SingleOutputRecipe or MultiOutputRecipe).

Example

recipe = Stage0Recipe.from_yaml(yaml_string)
if isinstance(recipe, SingleOutputRecipe):
    print(recipe.package.name)

schema_version abstractmethod property

schema_version

Get the schema version.

context abstractmethod property

context

Get the context variables as a dictionary.

build abstractmethod property

build

Get the build configuration.

about abstractmethod property

about

Get the about metadata.

from_yaml classmethod

from_yaml(yaml, *, recipe_dir=None)

Parse a recipe from a YAML string.

Parameters:

Name	Type	Description	Default
yaml	str	The YAML recipe content.	required
recipe_dir	Path | str | None	Directory to write the recipe file into. When None (the default) a temporary directory is created.	None

Returns:

Type	Description
Stage0Recipe	SingleOutputRecipe or MultiOutputRecipe depending on the recipe type.

from_file classmethod

from_file(path)

Parse a recipe from a YAML file.

The file path is used as the recipe path directly — no copy is made.

Returns:

Type	Description
Stage0Recipe	SingleOutputRecipe or MultiOutputRecipe depending on the recipe type.

from_dict classmethod

from_dict(recipe_dict, *, recipe_dir=None)

Create a recipe from a Python dictionary.

This method validates the dictionary structure and provides detailed error messages if the structure is invalid or types don't match.

Parameters:

Name	Type	Description	Default
recipe_dict	dict[str, Any]	Dictionary containing recipe data (must match recipe schema).	required
recipe_dir	Path | str | None	Directory to write the recipe file into. When None (the default) a temporary directory is created.	None

Returns:

Type	Description
Stage0Recipe	SingleOutputRecipe or MultiOutputRecipe depending on the recipe type.

Raises:

Type	Description
PyRecipeParseError	If the dictionary structure is invalid or types don't match.

Example

recipe_dict = {
    "package": {
        "name": "my-package",
        "version": "1.0.0"
    },
    "build": {
        "number": 0
    }
}
recipe = Stage0Recipe.from_dict(recipe_dict)

as_single_output

as_single_output()

Get as a single output recipe.

Raises:

Type	Description
TypeError	If this is not a single-output recipe.

as_multi_output

as_multi_output()

Get as a multi output recipe.

Raises:

Type	Description
TypeError	If this is not a multi-output recipe.

to_dict

to_dict()

Convert to Python dictionary.

render

render(variant_config=None, render_config=None)

Render this recipe with variant configuration.

This method takes this Stage0 recipe and evaluates all Jinja templates with different variant combinations to produce ready-to-build Stage1 recipes.

The recipe's :attr:recipe_path is automatically injected into the render configuration so that Jinja functions like include() and file_name() can resolve relative paths.

Parameters:

Name	Type	Description	Default
variant_config	VariantConfig | None	Optional VariantConfig to use. If None, creates an empty config.	None
render_config	RenderConfig | None	Optional RenderConfig to use. If None, uses default config.	None

Returns:

Type	Description
list[RenderedVariant]	List of RenderedVariant objects (one for each variant combination)

Example

recipe = Stage0Recipe.from_yaml(yaml_string)
variants = recipe.render(variant_config)
for variant in variants:
    print(variant.recipe.package.name)

run_build

run_build(
    variant_config=None,
    tool_config=None,
    output_dir=None,
    channels=None,
    progress_callback=None,
    no_build_id=False,
    package_format=None,
    no_include_recipe=False,
    debug=False,
    exclude_newer=None,
)

Build this recipe.

This method renders the recipe with variants and then builds the rendered outputs. The :attr:recipe_path is used automatically for directory setup and recipe inclusion in the package.

Parameters:

Name	Type	Description	Default
variant_config	VariantConfig | None	Optional VariantConfig to use for building variants.	None
tool_config	ToolConfiguration | None	ToolConfiguration to use for the build. If None, uses defaults.	None
output_dir	str | Path | None	Directory to store the built packages. Defaults to <recipe_dir>/output.	None
channels	list[str] | None	List of channels to use for resolving dependencies. Defaults to ["conda-forge"].	None
progress_callback	ProgressCallback | None	Optional progress callback for build events.	None
no_build_id	bool	Don't include build ID in output directory.	False
package_format	str | None	Package format ("conda" or "tar.bz2").	None
no_include_recipe	bool	Don't include recipe in the output package.	False
debug	bool	Enable debug mode.	False
exclude_newer	datetime | None	Exclude packages newer than this timestamp.	None

Returns:

Type	Description
list[BuildResult]	list[BuildResult]: List of build results, one per variant built.

Example

recipe = Stage0Recipe.from_yaml(yaml_string)
# Build with default output dir (<recipe_dir>/output)
results = recipe.run_build()
for result in results:
    print(f"Built {result.name} {result.version}")
    print(f"Package at: {result.packages[0]}")

# Or with custom tool configuration
from rattler_build import ToolConfiguration
config = ToolConfiguration(keep_build=True, test_strategy="native")
results = recipe.run_build(tool_config=config, output_dir="./output")

SingleOutputRecipe

Bases: Stage0Recipe

A single-output recipe at stage0 (parsed, not yet evaluated).

schema_version property

schema_version

Get the schema version.

context property

context

Get the context variables as a dictionary.

package property

package

Get the package metadata.

build property

build

Get the build configuration.

requirements property

requirements

Get the requirements.

about property

about

Get the about metadata.

MultiOutputRecipe

Bases: Stage0Recipe

A multi-output recipe at stage0 (parsed, not yet evaluated).

schema_version property

schema_version

Get the schema version.

context property

context

Get the context variables as a dictionary.

recipe property

recipe

Get the top-level recipe metadata.

build property

build

Get the top-level build configuration.

about property

about

Get the top-level about metadata.

outputs property

outputs

Get all outputs (package and staging).

Stage1 - Evaluated Recipes

Stage1Recipe

A fully evaluated conda recipe (stage1), ready for building.

This represents the recipe after all Jinja templates have been evaluated and all conditionals resolved.

Example

# After parsing and rendering a Stage0Recipe
stage0_recipe = Stage0Recipe.from_yaml(yaml_string)
rendered = stage0_recipe.render(variant_config)
stage1_recipe = rendered[0].recipe
print(stage1_recipe.package.name)
print(stage1_recipe.package.version)

package property

package

Get the package metadata.

build property

build

Get the build configuration.

requirements property

requirements

Get the requirements.

about property

about

Get the about metadata.

context property

context

Get the evaluation context.

used_variant property

used_variant

Get the variant values used in this build.

sources property

sources

Get all sources for this recipe.

staging_caches property

staging_caches

Get all staging caches.

inherits_from property

inherits_from

Get inheritance information if this output inherits from a cache.

to_dict

to_dict()

Convert to Python dictionary.

Supporting Types

Stage0 Types

Package metadata at stage0.

name property

name

Get the package name (may be a template string like '${{ name }}').

version property

version

Get the package version (may be a template string like '${{ version }}').

to_dict

to_dict()

Convert to Python dictionary.

A package output in a multi-output recipe.

package property

package

Get the package metadata for this output.

to_dict

to_dict()

Convert to Python dictionary.

A staging output in a multi-output recipe.

to_dict

to_dict()

Convert to Python dictionary.

Recipe metadata for multi-output recipes.

to_dict

to_dict()

Convert to Python dictionary.

Build configuration at stage0.

number property

number

Get the build number (may be a template).

string property

string

Get the build string (may be a template or None for auto-generated).

script property

script

Get the build script configuration.

noarch property

noarch

Get the noarch type (may be a template or None).

to_dict

to_dict()

Convert to Python dictionary.

Requirements at stage0.

build property

build

Get build-time requirements (list of matchspecs or templates).

host property

host

Get host-time requirements (list of matchspecs or templates).

run property

run

Get run-time requirements (list of matchspecs or templates).

run_constraints property

run_constraints

Get run-time constraints (list of matchspecs or templates).

to_dict

to_dict()

Convert to Python dictionary.

About metadata at stage0.

homepage property

homepage

Get the homepage URL (may be a template or None).

license property

license

Get the license (may be a template or None).

license_family property

license_family

Get the license family (deprecated, may be a template or None).

summary property

summary

Get the summary (may be a template or None).

description property

description

Get the description (may be a template or None).

documentation property

documentation

Get the documentation URL (may be a template or None).

repository property

repository

Get the repository URL (may be a template or None).

to_dict

to_dict()

Convert to Python dictionary.

Stage1 Types

Package metadata at stage1 (fully evaluated).

name property

name

Get the package name.

version property

version

Get the package version.

to_dict

to_dict()

Convert to Python dictionary.

Build configuration at stage1 (fully evaluated).

number property

number

Get the build number.

string property

string

Get the build string.

script property

script

Get the build script.

noarch property

noarch

Get the noarch configuration if any.

to_dict

to_dict()

Convert to Python dictionary.

Requirements at stage1 (fully evaluated).

build property

build

Get build requirements.

host property

host

Get host requirements.

run property

run

Get run requirements.

to_dict

to_dict()

Convert to Python dictionary.

About metadata at stage1 (fully evaluated).

homepage property

homepage

Get the homepage URL.

repository property

repository

Get the repository URL.

documentation property

documentation

Get the documentation URL.

license property

license

Get the license string.

summary property

summary

Get the summary.

description property

description

Get the description.

to_dict

to_dict()

Convert to Python dictionary.

Source information at stage1 (fully evaluated).

to_dict

to_dict()

Convert to Python dictionary.

Staging cache information at stage1 (fully evaluated).

name property

name

Get the cache name.

build property

build

Get the build configuration for this cache.

requirements property

requirements

Get the requirements for this cache.

to_dict

to_dict()

Convert to Python dictionary.