ssg.yaml module

Common functions for processing YAML in SSG

exception ssg.yaml.DocumentationNotComplete[source]

Bases: Exception

ssg.yaml.convert_string_to_bool(string)[source]

Converts a string representation of a boolean to its corresponding boolean value.

Parameters:

string (str) – The string to convert. Expected values are “true” or “false” (case insensitive).

Returns:

True if the string is “true” (case insensitive), False if the string is “false”

(case insensitive).

Return type:

bool

Raises:

ValueError – If the string is not “true” or “false” (case insensitive).

ssg.yaml.open_and_expand(yaml_file, substitutions_dict=None)[source]

Process the given YAML file as a template, using the provided substitutions dictionary to perform variable expansion. After expanding the template, process the result as YAML content.

Parameters:

  • yaml_file (str) – The path to the YAML file to be processed.

  • substitutions_dict (dict, optional) – A dictionary containing key-value pairs for template substitution. Defaults to an empty dictionary if not provided.

Returns:

The processed YAML content as a dictionary.

Return type:

dict

Raises:

yaml.scanner.ScannerError – If there is an error in scanning the YAML content, typically due to incorrect indentation after template expansion.

See also

_open_yaml: Function to open and parse the YAML content.

ssg.yaml.open_and_macro_expand_from_dir(yaml_file, content_dir, substitutions_dict=None)[source]

Opens a YAML file and expands macros from a specified directory. It is similar to open_and_expand but loads macro definitions from a specified directory instead of the default directory defined in constants. This is useful in cases where the SSG library is consumed by an external project.

Parameters:

  • yaml_file (str) – The path to the YAML file to be opened and expanded.

  • content_dir (str) – The content dir directory to be used for expansion.

  • substitutions_dict (dict, optional) – A dictionary of substitutions to be used for macro expansion. If None, a new dictionary will be created from the content_dir.

Returns:

The expanded content of the YAML file.

Return type:

dict

ssg.yaml.open_raw(yaml_file)[source]

Open the given YAML file and parse its contents without performing any template processing.

Parameters:

yaml_file (str) – The path to the YAML file to be opened and parsed.

Returns:

The parsed contents of the YAML file.

Return type:

dict

See also

_open_yaml: The function used to parse the YAML contents.

ssg.yaml.ordered_dump(data, stream=None, Dumper=<class 'yaml.cyaml.CDumper'>, **kwds)[source]

Serializes a Python object into a YAML stream, preserving the order of dictionaries.

This function is a drop-in replacement for yaml.dump(), but it ensures that the order of dictionaries is preserved. It also includes custom representers for dictionaries and strings, and applies specific formatting fixes for YAML output.

Parameters:

  • data (Any) – The Python object to serialize.

  • stream (Optional[IO]) – The stream to write the YAML output to. If None, the YAML string is returned.

  • Dumper (yaml.Dumper) – The YAML dumper class to use. Defaults to yaml_Dumper.

  • **kwds – Additional keyword arguments to pass to yaml.dump().

Returns:

The YAML string if stream is None, otherwise None.

Return type:

Optional[str]

ssg.yaml.ordered_load(stream, Loader=<class 'yaml.cyaml.CLoader'>, object_pairs_hook=<class 'collections.OrderedDict'>)[source]

Load a YAML stream while preserving the order of dictionaries.

This function is a drop-in replacement for yaml.load(), but it ensures that the order of dictionaries is preserved by using OrderedDict.

Parameters:

  • stream (str) – The YAML stream to load.

  • Loader (yaml.Loader, optional) – The YAML loader class to use. Defaults to yaml_Loader.

  • object_pairs_hook (callable, optional) – A callable that will be used to construct ordered mappings. Defaults to OrderedDict.

Returns:

The loaded YAML data with preserved order of dictionaries.

Return type:

OrderedDict

Raises:

yaml.scanner.ScannerError – If there is an error when trying to load the stream.

Notes

  • If there is a ScannerError, additional hints will be printed to help diagnose common issues such as unquoted colons or other special symbols in the stream.

  • The function will exit the program with status code 1 if a ScannerError occurs.

ssg.yaml.update_yaml_list_or_string(current_contents, new_contents, prepend=False)[source]

Update a YAML list or string by combining current and new contents.

This function takes the current contents and new contents, both of which can be either a string or a list of strings, and combines them into a single list or string. If the prepend flag is set to True, the new contents are added before the current contents. Otherwise, the new contents are appended to the current contents.

Parameters:

  • current_contents (str or list of str) – The existing contents to be updated.

  • new_contents (str or list of str) – The new contents to be added.

  • prepend (bool) – If True, new contents are added before current contents. Defaults to False.

Returns:

The updated contents. If the result is a single item, it is returned

as a string. If the result is empty, an empty string is returned.

Return type:

str or list of str