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_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)

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,
    debug=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).

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`
`debug`	`bool`	Enable debug mode.	`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]}")

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_conda_build_config classmethod #

from_yaml classmethod #

from_yaml_with_context classmethod #

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_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` #