Skip to content
Back to top
View this page

# annotatedyaml package

YAML utility functions.

class annotatedyaml.Input(name: str)

  Bases: `object`

  Input that should be substituted.

  classmethod from_node(loader: Loader, node: Node) → Input

    Create a new placeholder from a node.

  name: str

class annotatedyaml.NodeDictClass

  Bases: `dict`

  Wrapper class to be able to add attributes on a dict.

class annotatedyaml.NodeListClass(iterable=(), /)

  Bases: `list`

  Wrapper class to be able to add attributes on a list.

class annotatedyaml.NodeStrClass

  Bases: `str`

  Wrapper class to be able to add attributes on a string.

class annotatedyaml.Secrets(config_dir: Path)

  Bases: `object`

  Store secrets while loading YAML.

  get(requester_path: str, secret: str) → str

    Return the value of a secret.

exception annotatedyaml.UndefinedSubstitution(input_name: str)

  Bases: `Exception`

  Error raised when we find a substitution that is not defined.

exception annotatedyaml.YAMLException

  Bases: `Exception`

  Base class for all YAML exceptions.

exception annotatedyaml.YamlTypeError

  Bases: `YAMLException`

  Raised by load_yaml_dict if top level data is not a dict.

annotatedyaml.dump(_dict: dict | list) → str

  Dump YAML to a string and remove null.

annotatedyaml.extract_inputs(obj: Any) → set[str]

  Extract input from a structure.

annotatedyaml.load_yaml(fname: str | PathLike[str], secrets: Secrets | None = None) → list | dict | str | None

  Load a YAML file.

  If opening the file raises an OSError it will be wrapped in a YAMLException, except for FileNotFoundError which will be re-raised.

annotatedyaml.load_yaml_dict(fname: str | PathLike[str], secrets: Secrets | None = None) → dict

  Load a YAML file and ensure the top level is a dict.

  Raise if the top level is not a dict. Return an empty dict if the file is empty.

annotatedyaml.parse_yaml(content: str | TextIO | StringIO, secrets: Secrets | None = None) → list | dict | str

  Parse YAML with the fastest available loader.

annotatedyaml.save_yaml(path: str, data: dict) → None

  Save YAML to a file.

annotatedyaml.secret_yaml(loader: LoaderType, node: Node) → list | dict | str

  Load secrets and embed it into the configuration YAML.

annotatedyaml.substitute(obj: Any, substitutions: dict[str, Any]) → Any

  Substitute values.

## Submodules

## annotatedyaml.const module

Constants.

## annotatedyaml.constructors module

Constructors for the custom loader.

## annotatedyaml.dumper module

Custom dumper and representers.

annotatedyaml.dumper.add_representer(klass: Any, representer: Any) → None

  Add to representer to the dumper.

annotatedyaml.dumper.dump(_dict: dict | list) → str

  Dump YAML to a string and remove null.

annotatedyaml.dumper.represent_odict(dumper, tag, mapping, flow_style=None) → MappingNode

  Like BaseRepresenter.represent_mapping but does not issue the sort().

annotatedyaml.dumper.save_yaml(path: str, data: dict) → None

  Save YAML to a file.

## annotatedyaml.exceptions module

exception annotatedyaml.exceptions.YAMLException

  Bases: `Exception`

  Base class for all YAML exceptions.

exception annotatedyaml.exceptions.YamlTypeError

  Bases: `YAMLException`

  Raised by load_yaml_dict if top level data is not a dict.

## annotatedyaml.input module

Deal with YAML input.

exception annotatedyaml.input.UndefinedSubstitution(input_name: str)

  Bases: `Exception`

  Error raised when we find a substitution that is not defined.

annotatedyaml.input.extract_inputs(obj: Any) → set[str]

  Extract input from a structure.

annotatedyaml.input.substitute(obj: Any, substitutions: dict[str, Any]) → Any

  Substitute values.

## annotatedyaml.loader module

Custom loader.

class annotatedyaml.loader.FastSafeLoader(stream: Any, secrets: Secrets | None = None)

  Bases: `CSafeLoader`, `_LoaderMixin`

  The fastest available safe loader, either C or Python.

  yaml_constructors = {'!env_var': <function _env_var_yaml>, '!include': <function _raise_if_no_value.<locals>.wrapper>, '!include_dir_list': <function _raise_if_no_value.<locals>.wrapper>, '!include_dir_merge_list': <function _raise_if_no_value.<locals>.wrapper>, '!include_dir_merge_named': <function _raise_if_no_value.<locals>.wrapper>, '!include_dir_named': <function _raise_if_no_value.<locals>.wrapper>, '!input': <bound method Input.from_node of <class 'annotatedyaml.objects.Input'>>, '!secret': <function secret_yaml>, 'tag:yaml.org,2002:binary': <function SafeConstructor.construct_yaml_binary>, 'tag:yaml.org,2002:bool': <function SafeConstructor.construct_yaml_bool>, 'tag:yaml.org,2002:float': <function SafeConstructor.construct_yaml_float>, 'tag:yaml.org,2002:int': <function SafeConstructor.construct_yaml_int>, 'tag:yaml.org,2002:map': <function _handle_mapping_tag>, 'tag:yaml.org,2002:null': <function SafeConstructor.construct_yaml_null>, 'tag:yaml.org,2002:omap': <function SafeConstructor.construct_yaml_omap>, 'tag:yaml.org,2002:pairs': <function SafeConstructor.construct_yaml_pairs>, 'tag:yaml.org,2002:seq': <function _construct_seq>, 'tag:yaml.org,2002:set': <function SafeConstructor.construct_yaml_set>, 'tag:yaml.org,2002:str': <function _handle_scalar_tag>, 'tag:yaml.org,2002:timestamp': <function SafeConstructor.construct_yaml_timestamp>, None: <function SafeConstructor.construct_undefined>}

class annotatedyaml.loader.PythonSafeLoader(stream: Any, secrets: Secrets | None = None)

  Bases: `SafeLoader`, `_LoaderMixin`

  Python safe loader.

  yaml_constructors = {'!env_var': <function _env_var_yaml>, '!include': <function _raise_if_no_value.<locals>.wrapper>, '!include_dir_list': <function _raise_if_no_value.<locals>.wrapper>, '!include_dir_merge_list': <function _raise_if_no_value.<locals>.wrapper>, '!include_dir_merge_named': <function _raise_if_no_value.<locals>.wrapper>, '!include_dir_named': <function _raise_if_no_value.<locals>.wrapper>, '!input': <bound method Input.from_node of <class 'annotatedyaml.objects.Input'>>, '!secret': <function secret_yaml>, 'tag:yaml.org,2002:binary': <function SafeConstructor.construct_yaml_binary>, 'tag:yaml.org,2002:bool': <function SafeConstructor.construct_yaml_bool>, 'tag:yaml.org,2002:float': <function SafeConstructor.construct_yaml_float>, 'tag:yaml.org,2002:int': <function SafeConstructor.construct_yaml_int>, 'tag:yaml.org,2002:map': <function _handle_mapping_tag>, 'tag:yaml.org,2002:null': <function SafeConstructor.construct_yaml_null>, 'tag:yaml.org,2002:omap': <function SafeConstructor.construct_yaml_omap>, 'tag:yaml.org,2002:pairs': <function SafeConstructor.construct_yaml_pairs>, 'tag:yaml.org,2002:seq': <function _construct_seq>, 'tag:yaml.org,2002:set': <function SafeConstructor.construct_yaml_set>, 'tag:yaml.org,2002:str': <function _handle_scalar_tag>, 'tag:yaml.org,2002:timestamp': <function SafeConstructor.construct_yaml_timestamp>, None: <function SafeConstructor.construct_undefined>}

class annotatedyaml.loader.Secrets(config_dir: Path)

  Bases: `object`

  Store secrets while loading YAML.

  get(requester_path: str, secret: str) → str

    Return the value of a secret.

annotatedyaml.loader.add_constructor(tag: Any, constructor: Any) → None

  Add to constructor to all loaders.

annotatedyaml.loader.load_yaml(fname: str | PathLike[str], secrets: Secrets | None = None) → list | dict | str | None

  Load a YAML file.

  If opening the file raises an OSError it will be wrapped in a YAMLException, except for FileNotFoundError which will be re-raised.

annotatedyaml.loader.load_yaml_dict(fname: str | PathLike[str], secrets: Secrets | None = None) → dict

  Load a YAML file and ensure the top level is a dict.

  Raise if the top level is not a dict. Return an empty dict if the file is empty.

annotatedyaml.loader.parse_yaml(content: str | TextIO | StringIO, secrets: Secrets | None = None) → list | dict | str

  Parse YAML with the fastest available loader.

annotatedyaml.loader.secret_yaml(loader: LoaderType, node: Node) → list | dict | str

  Load secrets and embed it into the configuration YAML.

## annotatedyaml.objects module

Custom yaml object types.

class annotatedyaml.objects.Input(name: str)

  Bases: `object`

  Input that should be substituted.

  classmethod from_node(loader: Loader, node: Node) → Input

    Create a new placeholder from a node.

  name: str

class annotatedyaml.objects.NodeDictClass

  Bases: `dict`

  Wrapper class to be able to add attributes on a dict.

class annotatedyaml.objects.NodeListClass(iterable=(), /)

  Bases: `list`

  Wrapper class to be able to add attributes on a list.

class annotatedyaml.objects.NodeStrClass

  Bases: `str`

  Wrapper class to be able to add attributes on a string.

## annotatedyaml.reference module

## annotatedyaml.reference_object module