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.

class ssg.jinja.JinjaEnvironment(bytecode_cache=None)[source]

Bases: Environment

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.initialize(substitutions_dict)[source]
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.preload_macros(env)[source]
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

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