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.

Args:

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

Returns:

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

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.

Args:

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:

dict: The processed YAML content as a dictionary.

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(yaml_file, substitutions_dict=None)[source]

Opens a YAML file and expands macros within it using the provided substitutions dictionary.

This function loads definitions of macros and uses them to expand the template within the YAML file. It is similar to open_and_expand, but load definitions of macros

Args:: yaml_file (str): The path to the YAML file to be opened and expanded. substitutions_dict (dict, optional): A dictionary containing macro definitions and their

corresponding values. If not provided, an empty dictionary is used.
Returns:: dict: The expanded content of the YAML file with macros substituted.

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_macro_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.

Args:: 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:: dict: The expanded content of the YAML file.

ssg.yaml.open_raw(yaml_file)[source]

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

Args:: yaml_file (str): The path to the YAML file to be opened and parsed.
Returns:: dict: The parsed contents of the YAML file.
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.

Args:

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:

Optional[str]: The YAML string if stream is None, otherwise None.

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.

Args:

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:

OrderedDict: The loaded YAML data with preserved order of dictionaries.

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.

Args:

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:

str or list of str: 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.