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