ssg.rule_yaml module

The rule_yaml module provides various utility functions for handling YAML files containing Jinja macros, without having to parse the macros.

ssg.rule_yaml.add_key_value(contents, key, start_line, new_value)[source]

Adds a new key-value pair to the contents at a specified line.

Does not modify the value of contents.

Parameters:

  • contents (list of str) – The original list of strings representing the contents.

  • key (str) – The key to be added.

  • start_line (int) – The line number after which the new key-value pair should be added.

  • new_value (str) – The value associated with the key.

Returns:

A new list of strings with the key-value pair added and a blank line afterwards.

Return type:

list of str

ssg.rule_yaml.find_section_lines(file_contents, sec)[source]

Parses the given file_contents as YAML to find the section with the given identifier.

Note that this does not call into the yaml library and thus correctly handles Jinja macros at the expense of not being a strictly valid yaml parsing.

Parameters:

  • file_contents (list of str) – The contents of the file, split into lines.

  • sec (str) – The identifier of the section to find.

Returns:

A list of namedtuples (start, end) representing the lines where the

section exists.

Return type:

list of namedtuple

ssg.rule_yaml.get_section_lines(file_path, file_contents, key_name)[source]

From the given file_path and file_contents, find the lines describing the section key_name and returns the line range of the section.

Parameters:

  • file_path (str) – The path to the file being analyzed.

  • file_contents (str) – The contents of the file as a string.

  • key_name (str) – The name of the section to find within the file contents.

Returns:

A tuple representing the start and end line numbers of the section if found. None: If the section is not found.

Return type:

tuple

Raises:

ValueError – If multiple instances of the section are found in the file.

ssg.rule_yaml.get_yaml_contents(rule_obj)[source]

From a rule_obj description, return a namedtuple of (path, contents).

Parameters:

rule_obj (dict) – A dictionary containing information about the rule. It must have the keys ‘dir’ and ‘id’.

Returns:

A namedtuple with ‘path’ as the path to the rule YAML file and ‘contents’ as

the list of lines in the file.

Return type:

namedtuple

Raises:

ValueError – If the YAML file does not exist for the given rule_id.

ssg.rule_yaml.has_duplicated_subkeys(file_path, file_contents, sections)[source]

Checks whether a section has duplicated keys in a YAML file.

Note that these duplicated keys are silently ignored by the YAML parser used.

Parameters:

  • file_path (str) – The path to the YAML file.

  • file_contents (list of str) – The contents of the YAML file as a list of lines.

  • sections (str or list of str) – The section or list of sections to check for duplicated keys.

Returns:

True if any section has duplicated keys, False otherwise.

Return type:

bool

ssg.rule_yaml.parse_from_yaml(file_contents, lines)[source]

Parse the given line range as a YAML, returning the parsed object.

Parameters:

  • file_contents (list of str) – The contents of the file as a list of strings.

  • lines (slice) – A slice object indicating the start and end lines to parse.

Returns:

The parsed YAML object.

Return type:

object

ssg.rule_yaml.remove_lines(contents, lines)[source]

Remove the specified lines from the contents.

This function takes the contents of a file and a range of lines to be removed, and returns the new contents with those lines removed. The original contents are not modified.

Parameters:

  • contents (list of str) – The contents of the file as a list of lines.

  • lines (slice) – A slice object representing the range of lines to be removed.

Returns:

The new contents with the specified lines removed.

Return type:

list of str

ssg.rule_yaml.sort_section_keys(file_path, file_contents, sections, sort_func=None)[source]

Sort subkeys in a YAML file’s section.

Parameters:

  • file_path (str) – The path to the YAML file.

  • file_contents (list of str) – The contents of the YAML file as a list of lines.

  • sections (str or list of str) – The section or sections whose subkeys need to be sorted.

  • sort_func (callable, optional) – A function to determine the sort order of the subkeys. If None, the subkeys are sorted in ascending order.

Returns:

The modified contents of the YAML file with sorted subkeys in the specified

sections.

Return type:

list of str

Raises:

  • ValueError – If a duplicated key is found within the same section.

  • AssertionError – If the section contains more than one parent key or if a subkey line cannot be found.

ssg.rule_yaml.update_key_value(contents, key, old_value, new_value)[source]

Find a key in the contents of a file and replace its value with a new value, returning the resulting file contents.

This function validates that the old value is constant and hasn’t changed since parsing its value. Does not modify the original contents.

Parameters:

  • contents (list of str) – The contents of the file as a list of strings.

  • key (str) – The key whose value needs to be updated.

  • old_value (str) – The current value associated with the key.

  • new_value (str) – The new value to replace the old value.

Returns:

The updated contents of the file.

Return type:

list of str

Raises:

ValueError – If the key cannot be found in the given contents or if the old value does not match the current value associated with the key.