pydrake.common.yaml

pydrake.common.yaml.yaml_dump(data, *, filename=None)

Dumps a yaml object to a string or filename (if specified).

This is the counterpart to yaml_load(…, private=True), and will permit re-expressing the same tagged data.

pydrake.common.yaml.yaml_dump_typed(data, *, filename=None, schema=None, child_name=None, defaults=None)

Dumps an object to a YAML string or filename (if specified), using the schema in order to support non-primitive types.

This mimics the C++ function drake::common::yaml::SaveYamlFile. This is the complementary operation to yaml_load_typed.

Parameters

  • data – The object to be dumped.

  • filename – If provided, the YAML filename to be written to. When None, this function will return a YAML string instead of writing to a file.

  • schema – If provided, the type to dump as. When None, the default is type(data). This either must be a dataclass, a C++ class bound using pybind11 and DefAttributesUsingSerialize, or a Mapping[str, ...] where the mapping’s value type is one of those two categories.

  • child_name – If provided, dumps using given name as the document root, with the data nested underneath.

  • defaults – If provided, then only data that differs from the given defaults will be dumped.

pydrake.common.yaml.yaml_load(*, data=None, filename=None, private=False)

Loads either a data str xor a filename (exactly one must be specified) and returns the value as a yaml object.

This is sugar for calling either yaml_load_data or yaml_load_file; refer to those functions for additional details.

This function returns the raw, untyped data (dict, list, str, float, etc.) without any schema checking nor default values. To load with respect to a schema with defaults, see yaml_load_typed().

pydrake.common.yaml.yaml_load_data(data, *, private=False)

Loads and returns the given data str as a yaml object, while also accounting for variant-like type tags. Any tags are reported as an extra “_tag” field in the returned dictionary.

(Alternatively, data may be a file-like stream instead of a str.)

By default, removes any root-level keys that begin with an underscore, so that yaml anchors and templates are invisibly easy to use. Callers that wish to receive the private data may pass private=True.

This function returns the raw, untyped data (dict, list, str, float, etc.) without any schema checking nor default values. To load with respect to a schema with defaults, see yaml_load_typed().

pydrake.common.yaml.yaml_load_file(filename, *, private=False)

Loads and returns the given filename as a yaml object, while also accounting for variant-like type tags.

See yaml_load_data for full details; this function differs only by reading the yaml data from a file instead of memory.

pydrake.common.yaml.yaml_load_typed(*, schema=None, data=None, filename=None, child_name=None, defaults=None, allow_yaml_with_no_schema=False, allow_schema_with_no_yaml=True, retain_map_defaults=True)

Loads either a data str or a filename against the given schema type and returns an instance of that type.

This mimics the C++ function drake::common::yaml::LoadYamlFile. This is the complementary operation to yaml_dump_typed.

Parameters

  • schema – The type to load as. This either must be a dataclass, a C++ class bound using pybind11 and DefAttributesUsingSerialize, or a Mapping[str, ...] where the mapping’s value type is one of those two categories. If a non-None defaults is provided, then schema can be None and will use type(defaults) in that case.

  • data – The string of YAML data to be loaded. Exactly one of either data or filename must be provided.

  • filename – The filename of YAML data to be loaded. Exactly one of either data or filename must be provided.

  • child_name – If provided, loads data from given-named child of the document’s root instead of the root itself.

  • defaults – If provided, then the object being read into will be initialized using this value instead of the schema’s default constructor.

  • allow_yaml_with_no_schema – Allows yaml Maps to have extra key-value pairs that are specified by the schema being parsed into. In other words, the schema argument provides only an incomplete schema for the YAML data. This allows for parsing only a subset of the YAML data.

  • allow_schema_with_no_yaml – Allows the schema to provide more key-value pairs than are present in the YAML data. In other words, objects can have default values that are left intact unless the YAML data provides a value.

  • retain_map_defaults – If set to true, when parsing a Mapping the loader will merge the YAML data into the destination, instead of replacing the dict contents entirely. In other words, a Mapping field in a schema can have default values that are left intact unless the YAML data provides a value for that specific key.