ssg.jinja module

Common functions for processing Jinja2 in SSG

class ssg.jinja.AbsolutePathFileSystemLoader(encoding='utf-8')[source]

Bases: BaseLoader

AbsolutePathFileSystemLoader is a custom Jinja2 template loader that loads templates from the file system using absolute paths.

encoding

The encoding used to read the template files. Defaults to ‘utf-8’.

Type:

str

get_source(environment, template)[source]

Retrieves the source code of a Jinja2 template from the file system.

Parameters:

  • environment (jinja2.Environment) – The Jinja2 environment.

  • template (str) – The absolute path to the template file.

Returns:

A tuple containing the template contents as a string, the template path, and a

function to check if the template file has been updated.

Return type:

tuple

Raises:

  • jinja2.TemplateNotFound – If the template file does not exist or the path is not absolute.

  • RuntimeError – If there is an error reading the template file.

exception ssg.jinja.MacroError[source]

Bases: RuntimeError

ssg.jinja.add_python_functions(substitutions_dict)[source]

Adds predefined Python functions to the provided substitutions dictionary.

The following functions are added: - ‘product_to_name’: Maps a product identifier to its name. - ‘name_to_platform’: Maps a name to its platform. - ‘product_to_platform’: Maps a product identifier to its platform. - ‘url_encode’: Encodes a URL. - ‘raise’: Raises an exception. - ‘expand_yaml_path’: Expands a YAML path.

Parameters:

substitutions_dict (dict) – The dictionary to which the functions will be added.

ssg.jinja.expand_yaml_path(path, parameter)[source]

Expands a dot-separated YAML path into a formatted YAML string.

Parameters:

  • path (str) – The dot-separated path to be expanded.

  • parameter (str) – An additional parameter to be appended at the end of the path.

Returns:

A formatted YAML string representing the expanded path.

Return type:

str

ssg.jinja.load_macros(substitutions_dict=None)[source]

Augments the provided substitutions_dict with project Jinja macros found in the in JINJA_MACROS_DIRECTORY from constants.py.

Parameters:

substitutions_dict (dict, optional) – A dictionary to be augmented with Jinja macros. Defaults to None.

Returns:

The updated substitutions_dict containing the Jinja macros.

Return type:

dict

ssg.jinja.load_macros_from_content_dir(content_dir, substitutions_dict=None)[source]

Augments the provided substitutions_dict with project Jinja macros found in a specified content directory.

Parameters:

  • content_dir (str) – The base directory containing the ‘shared/macros’ subdirectory.

  • substitutions_dict (dict, optional) – A dictionary to be augmented with Jinja macros. Defaults to None.

Returns:

The updated substitutions_dict containing the Jinja macros.

Return type:

dict

ssg.jinja.process_file(filepath, substitutions_dict)[source]

Process the Jinja file at the given path with the specified substitutions.

Parameters:

  • filepath (str) – The path to the Jinja file to be processed.

  • substitutions_dict (dict) – A dictionary containing the substitutions to be applied to the template.

Returns:

The rendered template as a string.

Return type:

str

Note

This function does not load the project macros. Use process_file_with_macros(…) for that.

ssg.jinja.process_file_with_macros(filepath, substitutions_dict)[source]

Process a file with Jinja macros.

This function processes the file located at the given filepath using Jinja macros and the specified substitutions_dict. The substitutions_dict is first processed to load any macros, and then it is used to substitute values in the file. The function ensures that the key ‘indent’ is not present in the substitutions_dict.

Parameters:

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

  • substitutions_dict (dict) – A dictionary containing the substitutions to be applied to the file.

Returns:

The processed file content as a string.

Return type:

str

Raises:

AssertionError – If the key ‘indent’ is present in substitutions_dict.

See also

process_file: A function that processes a file with the given substitutions.

ssg.jinja.raise_exception(message)[source]
ssg.jinja.render_template(data, template_path, output_path, loader)[source]

Renders a template with the given data and writes the output to a file.

Parameters:

  • data (dict) – The data to be used in the template rendering.

  • template_path (str) – The path to the template file.

  • output_path (str) – The path where the rendered output will be written.

  • loader (jinja2.BaseLoader) – The Jinja2 loader to use for loading templates.

Returns:

None

ssg.jinja.update_substitutions_dict(filename, substitutions_dict)[source]

Update the substitutions dictionary with macro definitions from a Jinja2 file.

This function treats the given filename as a Jinja2 file containing macro definitions. It exports definitions that do not start with an underscore (_) into the substitutions_dict, which is a dictionary mapping names to macro objects. During the macro compilation process, symbols that already exist in substitutions_dict may be used by the new definitions.

Parameters:

  • filename (str) – The path to the Jinja2 file containing macro definitions.

  • substitutions_dict (dict) – The dictionary to update with new macro definitions.

Returns:

None

ssg.jinja.url_encode(source)[source]

Encodes a given string into a URL-safe format.

Parameters:

source (str) – The string to be URL-encoded.

Returns:

The URL-encoded string.

Return type:

str