Rendering#

Render recipes with variant configurations to produce buildable outputs.

You can import the rendering classes from rattler_build:

from rattler_build import VariantConfig, RenderConfig, RenderedVariant

`VariantConfig`#

Configuration for build variants.

Variants allow building the same recipe with different configurations, such as different Python versions, compilers, or other parameters.

This class provides a dict-like interface for managing variants.

Example

# Create from dict
config = VariantConfig({
    "python": ["3.8", "3.9", "3.10"],
    "numpy": ["1.21", "1.22"]
})
len(config.combinations())  # 3 * 2 = 6 combinations
# 6

# Dict-like access
print(config["python"])
# ['3.8', '3.9', '3.10']

# Get values
print(config.get_values("python"))
# ['3.8', '3.9', '3.10']

# Load from YAML file
config = VariantConfig.from_file("variant_config.yaml")
print(config.keys())

zip_keys `property` #

zip_keys

Get zip_keys - groups of keys that should be zipped together.

Zip keys ensure that certain variant keys are synchronized when creating combinations. For example, if python and numpy are zipped, then python=3.9 will always be paired with numpy=1.20, not with other numpy versions.

Returns:

Type	Description
`list[list[str]] \| None`	List of groups (each group is a list of keys), or None if no zip keys are defined

Example

config = VariantConfig(
    {"python": ["3.9", "3.10"], "numpy": ["1.20", "1.21"]},
    zip_keys=[["python", "numpy"]]
)
len(config.combinations())  # 2, not 4
# 2

init #

__init__(variants=None, zip_keys=None)

Create a new VariantConfig.

Parameters:

Name	Type	Description	Default
`variants`	`dict[str, list[Any]] \| None`	A dictionary mapping variant keys to value lists. If None, creates empty config.	`None`
`zip_keys`	`list[list[str]] \| None`	Optional list of groups (each group is a list of keys) that should be zipped together. Ensures that certain variant keys are synchronized.	`None`

Example

# Create from dict
config = VariantConfig({"python": ["3.9", "3.10"]})

# Create with zip_keys
config = VariantConfig(
    {"python": ["3.9", "3.10"], "numpy": ["1.21", "1.22"]},
    zip_keys=[["python", "numpy"]]
)

# Create empty
config = VariantConfig()

from_file `classmethod` #

from_file(path)

Load VariantConfig from a YAML file (variants.yaml format).

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to the variant configuration YAML file	required

Returns:

Type	Description
`VariantConfig`	A new VariantConfig instance

Example

config = VariantConfig.from_file("variants.yaml")

from_file_with_context `classmethod` #

from_file_with_context(path, jinja_config)

Load VariantConfig from a YAML file with a JinjaConfig context (variants.yaml format).

This allows evaluation of conditionals and templates in the variant file. The jinja_config provides platform information and other context needed for evaluation.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to the variant configuration YAML file	required
`jinja_config`	`JinjaConfig`	JinjaConfig providing context for evaluation	required

Returns:

Type	Description
`VariantConfig`	A new VariantConfig instance

Example

from rattler_build import JinjaConfig

jinja_config = JinjaConfig(target_platform="linux-64")
config = VariantConfig.from_file_with_context("variants.yaml", jinja_config)

from_files `classmethod` #

from_files(paths)

Load multiple VariantConfig files and merge them.

Files are merged in order, with later files taking precedence for overlapping keys. Zip keys from the last file that specifies them will be used.

Parameters:

Name	Type	Description	Default
`paths`	`list[str \| Path]`	List of paths to variant configuration YAML files	required

Returns:

Type	Description
`VariantConfig`	A new VariantConfig instance with all files merged

Example

config = VariantConfig.from_files([
    "base_variants.yaml",
    "override_variants.yaml",
])

from_files_with_context `classmethod` #

from_files_with_context(paths, jinja_config)

Load multiple VariantConfig files with a JinjaConfig context and merge them.

Files are merged in order, with later files taking precedence. Files named conda_build_config.yaml are loaded using the legacy loader which supports # [selector] syntax.

Parameters:

Name	Type	Description	Default
`paths`	`list[str \| Path]`	List of paths to variant configuration YAML files	required
`jinja_config`	`JinjaConfig`	JinjaConfig providing context for evaluation	required

Returns:

Type	Description
`VariantConfig`	A new VariantConfig instance with all files merged

Example

from rattler_build import JinjaConfig

jinja_config = JinjaConfig(target_platform="linux-64")
config = VariantConfig.from_files_with_context(
    ["base_variants.yaml", "conda_build_config.yaml"],
    jinja_config,
)

from_conda_build_config `classmethod` #

from_conda_build_config(path, jinja_config)

Load VariantConfig from a conda_build_config.yaml file.

This supports the legacy conda-build format with # [selector] syntax. Selectors are evaluated using the provided JinjaConfig.

Parameters:

Name	Type	Description	Default
`path`	`str \| Path`	Path to the conda_build_config.yaml file	required
`jinja_config`	`JinjaConfig`	JinjaConfig providing context for selector evaluation	required

Returns:

Type	Description
`VariantConfig`	A new VariantConfig instance

Example

from rattler_build import JinjaConfig

jinja_config = JinjaConfig(target_platform="linux-64")
config = VariantConfig.from_conda_build_config("conda_build_config.yaml", jinja_config)

from_yaml `classmethod` #

from_yaml(yaml)

Load VariantConfig from a YAML string (variants.yaml format).

Parameters:

Name	Type	Description	Default
`yaml`	`str`	YAML string containing variant configuration	required

Returns:

Type	Description
`VariantConfig`	A new VariantConfig instance

Example

yaml_str = '''
python:
  - "3.8"
  - "3.9"
'''
config = VariantConfig.from_yaml(yaml_str)

from_yaml_with_context `classmethod` #

from_yaml_with_context(yaml, jinja_config)

Load VariantConfig from a YAML string with a JinjaConfig context (variants.yaml format).

This allows evaluation of conditionals and templates in the variant YAML. The jinja_config provides platform information and other context needed for evaluation.

Parameters:

Name	Type	Description	Default
`yaml`	`str`	YAML string containing variant configuration	required
`jinja_config`	`JinjaConfig`	JinjaConfig providing context for evaluation	required

Returns:

Type	Description
`VariantConfig`	A new VariantConfig instance

Example

from rattler_build import JinjaConfig

yaml_str = '''
c_compiler:
  - if: unix
    then: gcc
  - if: win
    then: msvc
'''
jinja_config = JinjaConfig(target_platform="linux-64")
config = VariantConfig.from_yaml_with_context(yaml_str, jinja_config)

merge #

merge(other)

Merge another VariantConfig into this one, returning a new VariantConfig.

Values from other take precedence for overlapping keys. Zip keys from other replace those in self if present.

Parameters:

Name	Type	Description	Default
`other`	`VariantConfig`	The VariantConfig to merge into this one	required

Returns:

Type	Description
`VariantConfig`	A new VariantConfig with merged values

Example

base = VariantConfig({"python": ["3.9", "3.10"]})
override = VariantConfig({"python": ["3.11"], "numpy": ["1.24"]})
merged = base.merge(override)
merged["python"]
# ['3.11']
merged["numpy"]
# ['1.24']

keys #

keys()

Get all variant keys.

Returns:

Type	Description
`list[str]`	List of variant key names

Example

config = VariantConfig({"python": ["3.8", "3.9"], "numpy": ["1.21"]})
config.keys()
# ['numpy', 'python']

get_values #

get_values(key)

Get values for a specific variant key.

Parameters:

Name	Type	Description	Default
`key`	`str`	The variant key name	required

Returns:

Type	Description
`list[Any] \| None`	List of values for the key, or None if key doesn't exist

Example

config = VariantConfig({"python": ["3.8", "3.9", "3.10"]})
config.get_values("python")
# ['3.8', '3.9', '3.10']

to_dict #

to_dict()

Get all variants as a dictionary.

Returns:

Type	Description
`dict[str, list[Any]]`	Dictionary mapping variant keys to their value lists

Example

config = VariantConfig({"python": ["3.8", "3.9"]})
config.to_dict()
# {'python': ['3.8', '3.9']}

combinations #

combinations()

Generate all combinations of variant values.

Returns:

Type	Description
`list[dict[str, Any]]`	List of dictionaries, each representing one variant combination

Example

config = VariantConfig({"python": ["3.8", "3.9"], "numpy": ["1.21", "1.22"]})
combos = config.combinations()
len(combos)
# 4
combos[0]
# {'python': '3.8', 'numpy': '1.21'}

get #

get(key, default=None)

Get values for a variant key with a default.

Parameters:

Name	Type	Description	Default
`key`	`str`	The variant key name	required
`default`	`list[Any] \| None`	Default value if key doesn't exist	`None`

Returns:

Type	Description
`list[Any] \| None`	List of values for the key, or default if key doesn't exist

Example

config = VariantConfig({"python": ["3.9"]})
config.get("python")
# ['3.9']
config.get("ruby", ["2.7"])
# ['2.7']

items #

items()

Get all variant key-value pairs.

Returns:

Type	Description
`ItemsView[str, list[str]]`	Iterator of (key, values) tuples

Example

config = VariantConfig({"python": ["3.9", "3.10"]})
dict(config.items())
# {'python': ['3.9', '3.10']}

values #

values()

Get all variant value lists.

Returns:

Type	Description
`ValuesView[list[str]]`	Iterator of value lists

Example

config = VariantConfig({"python": ["3.9", "3.10"]})
list(config.values())
# [['3.9', '3.10']]

`RenderConfig`#

Configuration for rendering recipes with variants.

This class configures how recipes are rendered, including platform settings, experimental features, and additional Jinja context variables.

The recipe_path is not set here — it is automatically injected from the :class:~rattler_build.stage0.Stage0Recipe during :meth:render.

Parameters:

Name	Type	Description	Default
`platform`	`PlatformConfig \| None`	Platform configuration (target, build, host platforms, experimental flag)	`None`
`extra_context`	`dict[str, ContextValue] \| None`	Dictionary of extra context variables for Jinja rendering	`None`

Example

from rattler_build.tool_config import PlatformConfig

platform = PlatformConfig(target_platform="linux-64")
config = RenderConfig(
    platform=platform,
    extra_context={"custom_var": "value", "build_num": 42}
)

target_platform `property` #

target_platform

Get the target platform.

build_platform `property` #

build_platform

Get the build platform.

host_platform `property` #

host_platform

Get the host platform.

experimental `property` #

experimental

Get whether experimental features are enabled.

init #

__init__(platform=None, extra_context=None)

Create a new render configuration.

get_context #

get_context(key)

Get an extra context variable.

Parameters:

Name	Type	Description	Default
`key`	`str`	Variable name	required

Returns:

Type	Description
`ContextValue \| None`	The variable value, or None if not found

get_all_context #

get_all_context()

Get all extra context variables as a dictionary.

`RenderedVariant`#

Result of rendering a recipe with a specific variant combination.

Each RenderedVariant represents one specific variant of a recipe after all Jinja templates have been evaluated and variant values applied.

The :attr:recipe_path is carried over from the :class:~rattler_build.stage0.Stage0Recipe that produced this variant and is used automatically by :meth:run_build.

Attributes:

Name	Type	Description
`variant`	`dict[str, str]`	The variant combination used (variable name -> value)
`recipe`	`Stage1Recipe`	The rendered Stage1 recipe
`hash_info`	`HashInfo \| None`	Build string hash information
`pin_subpackages`	`dict[str, PinSubpackageInfo]`	Pin subpackage dependencies
`recipe_path`	`Path`	Path to the recipe file on disk

Example

for variant in rendered_variants:
    print(f"Package: {variant.recipe.package.name}")
    print(f"Variant: {variant.variant}")
    print(f"Build string: {variant.recipe.build.string}")

variant `property` #

variant

Get the variant combination used for this render.

Returns:

Type	Description
`dict[str, str]`	Dictionary mapping variable names to their values

recipe `property` #

recipe

Get the rendered Stage1 recipe.

Returns:

Type	Description
`Stage1Recipe`	The fully evaluated Stage1 recipe ready for building

hash_info `property` #

hash_info

Get hash info if available.

Returns:

Type	Description
`HashInfo \| None`	HashInfo object with 'hash' and 'prefix' attributes, or None

Example

rendered = recipe.render(variant_config)[0]
hash_info = rendered.hash_info
if hash_info:
    print(f"Hash: {hash_info.hash}")
    print(f"Prefix: {hash_info.prefix}")

pin_subpackages `property` #

pin_subpackages

Get pin_subpackage information.

Returns:

Type	Description
`dict[str, PinSubpackageInfo]`	Dictionary mapping package names to PinSubpackageInfo objects

Example

rendered = recipe.render(variant_config)[0]
for name, info in rendered.pin_subpackages.items():
    print(f"{name}: version={info.version}, exact={info.exact}")

run_build #

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

Build this rendered variant.

This method builds a single rendered variant directly without needing to go back through the Stage0 recipe. The recipe path is taken from this variant automatically (set during :meth:Stage0Recipe.render).

For multi-output recipes, sibling variants are automatically known from the :meth:~Stage0Recipe.render call and used to resolve pin_subpackage dependencies between outputs.

Parameters:

Name	Type	Description	Default
`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 package. 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`
`exclude_newer`	`datetime \| None`	Exclude packages newer than this timestamp.	`None`

Returns:

Name	Type	Description
`BuildResult`	`BuildResult`	Information about the built package including paths, metadata, and timing.

Example

from rattler_build import Stage0Recipe, VariantConfig

recipe = Stage0Recipe.from_yaml(yaml_string)
rendered = recipe.render(VariantConfig())
# Build just the first variant (output goes to <recipe_dir>/output)
result = rendered[0].run_build()
print(f"Built package: {result.packages[0]}")

# Multi-output recipes with pin_subpackage work automatically
for variant in rendered:
    variant.run_build()

Supporting Types#

`HashInfo`#

Hash information for a rendered variant.

This class wraps the Rust HashInfo type and provides convenient access to hash information computed during recipe rendering.

Attributes:

Name	Type	Description
`hash`	`str`	The hash string (first 7 letters of the sha1sum)
`prefix`	`str`	The hash prefix (e.g., 'py38' or 'np111')

Example

hash_info = variant.hash_info
if hash_info:
    print(f"Hash: {hash_info.hash}")
    print(f"Prefix: {hash_info.prefix}")

hash `property` #

hash

Get the hash string (first 7 letters of sha1sum).

prefix `property` #

prefix

Get the hash prefix (e.g., 'py38' or 'np111').

`PinSubpackageInfo`#

Information about a pin_subpackage dependency.

This class wraps the Rust PinSubpackageInfo type and provides information about packages pinned via the pin_subpackage() Jinja function.

Attributes:

Name	Type	Description
`name`	`str`	The name of the pinned subpackage
`version`	`str`	The version of the pinned subpackage
`build_string`	`str \| None`	The build string of the pinned subpackage (if known)
`exact`	`bool`	Whether this is an exact pin

Example

pins = variant.pin_subpackages
for name, info in pins.items():
    print(f"{name}: {info.version} (exact={info.exact})")

name `property` #

name

Get the package name.

version `property` #

version

Get the package version.

build_string `property` #

build_string

Get the build string if available.

exact `property` #

exact

Check if this is an exact pin.

Rendering#

VariantConfig#

zip_keys property #

__init__ #

from_file classmethod #

from_file_with_context classmethod #

from_files classmethod #

from_files_with_context classmethod #

from_conda_build_config classmethod #

from_yaml classmethod #

from_yaml_with_context classmethod #

merge #

keys #

get_values #

to_dict #

combinations #

get #

items #

values #

RenderConfig#

target_platform property #

build_platform property #

host_platform property #

experimental property #

__init__ #

get_context #

get_all_context #

RenderedVariant#

variant property #

recipe property #

hash_info property #

pin_subpackages property #

run_build #

Supporting Types#

HashInfo#

hash property #

prefix property #

PinSubpackageInfo#

name property #

version property #

build_string property #

exact property #

`VariantConfig`#

zip_keys `property` #

init #

from_file `classmethod` #

from_file_with_context `classmethod` #

from_files `classmethod` #

from_files_with_context `classmethod` #

from_conda_build_config `classmethod` #

from_yaml `classmethod` #

from_yaml_with_context `classmethod` #

`RenderConfig`#

target_platform `property` #

build_platform `property` #

host_platform `property` #

experimental `property` #

init #

`RenderedVariant`#

variant `property` #

recipe `property` #

hash_info `property` #

pin_subpackages `property` #

`HashInfo`#

hash `property` #

prefix `property` #

`PinSubpackageInfo`#

name `property` #

version `property` #

build_string `property` #

exact `property` #