Templating Module

The templating module provides functions for generating MARRMOT model configuration files using Jinja2 templates.

This module provides functions to generate textual configuration files using Jinja2 templating engine for MARRMOT model instantiations.

marrmotflow.templating.raise_helper(msg)[source]

Jinja2 helper function to raise exceptions.

marrmotflow.templating.render_models(model_files: Sequence[str], template_jinja_path: str | PathLike = 'marrmot_models.m.jinja') → Dict[str, str][source]

Render model files from a sequence of model names.

Parameters:

  • model_files (Sequence[str]) – A sequence of model names.

  • template_jinja_path (PathLike, optional) – Path to the Jinja2 template file. Default is TEMPLATE_MODEL.

Returns:

A dictionary mapping model names to their rendered content.

Return type:

Dict[str, str]

Functions

render_models

marrmotflow.templating.render_models(model_files: Sequence[str], template_jinja_path: str | PathLike = 'marrmot_models.m.jinja') → Dict[str, str][source]

Render model files from a sequence of model names.

Parameters:

  • model_files (Sequence[str]) – A sequence of model names.

  • template_jinja_path (PathLike, optional) – Path to the Jinja2 template file. Default is TEMPLATE_MODEL.

Returns:

A dictionary mapping model names to their rendered content.

Return type:

Dict[str, str]

Generate MARRMOT model configuration files from templates.

Parameters:

  • model_files (Sequence[str]) – Sequence of model file names to generate

  • template_jinja_path (PathLike, optional) – Path to Jinja2 template file

Returns:

Dictionary mapping file names to generated content

Return type:

Dict[str, str]

Example:

from marrmotflow.templating import render_models

# Generate model files using default template
model_files = ["model_7.m", "model_37.m"]
rendered = render_models(model_files)

# Access generated content
for filename, content in rendered.items():
    print(f"Generated {filename}")
    print(content[:100] + "...")

Custom Template:

# Use custom template
custom_template = "my_template.m.jinja"
rendered = render_models(
    model_files=["custom_model.m"],
    template_jinja_path=custom_template
)

raise_helper

marrmotflow.templating.raise_helper(msg)[source]

Jinja2 helper function to raise exceptions.

Jinja2 helper function for raising exceptions within templates.

Parameters:

msg (str) – Error message to raise

Raises:

Exception – Always raises an Exception with the provided message

This function is registered as a global in the Jinja2 environment and can be used within templates for error handling:

{% if not parameters %}
{{ raise("No parameters defined for model") }}
{% endif %}

Constants

marrmotflow.templating.TEMPLATE_MODEL = "marrmot_models.m.jinja"

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

Default template file name for MARRMOT models.

Template Environment

The module sets up a Jinja2 environment with the following configuration:

marrmotflow.templating.environment = <jinja2.environment.Environment object>

The core component of Jinja is the Environment. It contains important shared variables like configuration, filters, tests, globals and others. Instances of this class may be modified if they are not shared and if no template was loaded so far. Modifications on environments after the first template was loaded will lead to surprising effects and undefined behavior.

Here are the possible initialization parameters:

block_start_string

The string marking the beginning of a block. Defaults to '{%'.

block_end_string

The string marking the end of a block. Defaults to '%}'.

variable_start_string

The string marking the beginning of a print statement. Defaults to '{{'.

variable_end_string

The string marking the end of a print statement. Defaults to '}}'.

comment_start_string

The string marking the beginning of a comment. Defaults to '{#'.

comment_end_string

The string marking the end of a comment. Defaults to '#}'.

line_statement_prefix

If given and a string, this will be used as prefix for line based statements. See also line-statements.

line_comment_prefix

If given and a string, this will be used as prefix for line based comments. See also line-statements.

Added in version 2.2.

trim_blocks

If this is set to True the first newline after a block is removed (block, not variable tag!). Defaults to False.

lstrip_blocks

If this is set to True leading spaces and tabs are stripped from the start of a line to a block. Defaults to False.

newline_sequence

The sequence that starts a newline. Must be one of '\r', '\n' or '\r\n'. The default is '\n' which is a useful default for Linux and OS X systems as well as web applications.

keep_trailing_newline

Preserve the trailing newline when rendering templates. The default is False, which causes a single newline, if present, to be stripped from the end of the template.

Added in version 2.7.

extensions

List of Jinja extensions to use. This can either be import paths as strings or extension classes. For more information have a look at the extensions documentation.

optimized

should the optimizer be enabled? Default is True.

undefined

Undefined or a subclass of it that is used to represent undefined values in the template.

finalize

A callable that can be used to process the result of a variable expression before it is output. For example one can convert None implicitly into an empty string here.

autoescape

If set to True the XML/HTML autoescaping feature is enabled by default. For more details about autoescaping see Markup. As of Jinja 2.4 this can also be a callable that is passed the template name and has to return True or False depending on autoescape should be enabled by default.

Changed in version 2.4: autoescape can now be a function

loader

The template loader for this environment.

cache_size

The size of the cache. Per default this is 400 which means that if more than 400 templates are loaded the loader will clean out the least recently used template. If the cache size is set to 0 templates are recompiled all the time, if the cache size is -1 the cache will not be cleaned.

Changed in version 2.8: The cache size was increased to 400 from a low 50.

auto_reload

Some loaders load templates from locations where the template sources may change (ie: file system or database). If auto_reload is set to True (default) every time a template is requested the loader checks if the source changed and if yes, it will reload the template. For higher performance it’s possible to disable that.

bytecode_cache

If set to a bytecode cache object, this object will provide a cache for the internal Jinja bytecode so that templates don’t have to be parsed if they were not changed.

See bytecode-cache for more information.

enable_async

If set to true this enables async template execution which allows using async functions and generators.

Global Jinja2 environment configured for MARRMOT template processing.

Configuration:

  • Loader: PackageLoader(“marrmotflow”, “templates”)

  • trim_blocks: True

  • lstrip_blocks: True

  • line_comment_prefix: ‘##’

Global Variables:

  • raise: Helper function for raising exceptions in templates

Template Structure

Default Template Variables

The default template expects the following variables to be available:

Template Variables

Variable

Type

Description

model_name

str

Human-readable name of the model

model_number

int

MARRMOT model structure number

catchment_id

str

Unique identifier for the catchment

catchment_name

str

Human-readable catchment name

parameters

List[Dict]

List of model parameters with name, value, description

forcing_data

Dict[str, str]

Mapping of forcing variable names to data identifiers

timestamp

str

Generation timestamp

workflow_name

str

Name of the workflow generating the template

Template Syntax

The templates use Jinja2 syntax with the following customizations:

Line Comments:

## This is a comment that will be removed from output
% This is MATLAB code that will be preserved

Block Control:

{% for param in parameters %}
{{ param.name }} = {{ param.value }}; % {{ param.description }}
{% endfor %}

Conditional Logic:

{% if model_number == 7 %}
% HBV-96 specific configuration
{% elif model_number == 37 %}
% GR4J specific configuration
{% endif %}

Error Handling:

{% if not parameters %}
{{ raise("No parameters defined") }}
{% endif %}

Examples

Basic Template Rendering

from marrmotflow.templating import render_models

# Render multiple model files
model_files = ["hbv_model.m", "gr4j_model.m"]
results = render_models(model_files)

# Save to files
for filename, content in results.items():
    with open(f"generated_{filename}", 'w') as f:
        f.write(content)

Custom Template Usage

# Create custom template file: my_template.m.jinja
template_content = '''
% Custom MARRMOT Model: {{ model_name }}
% Generated: {{ timestamp }}

function output = {{ model_name|lower|replace('-', '_') }}_model()
    % Model parameters
    {% for param in parameters %}
    {{ param.name }} = {{ param.value }}; % {{ param.description }}
    {% endfor %}

    % Model implementation here
    output = struct();
end
'''

# Use custom template
results = render_models(
    ["custom_model.m"],
    template_jinja_path="my_template.m.jinja"
)

Template Context Creation

# Example of template context that would be passed to render_models
template_context = {
    "model_name": "HBV-96",
    "model_number": 7,
    "catchment_id": "basin_001",
    "catchment_name": "Example Basin",
    "parameters": [
        {
            "name": "TT",
            "value": 0.0,
            "description": "Temperature threshold for snow"
        },
        {
            "name": "C0",
            "value": 3.0,
            "description": "Degree-day factor"
        }
    ],
    "forcing_data": {
        "precipitation": "precip_data",
        "temperature": "temp_data"
    },
    "timestamp": "2024-07-16 12:00:00",
    "workflow_name": "ExampleWorkflow"
}

Error Handling

Template Errors

The templating system can raise several types of errors:

exception jinja2.TemplateNotFound

Raised when the specified template file cannot be found:

try:
    render_models(["model.m"], "nonexistent_template.jinja")
except jinja2.TemplateNotFound as e:
    print(f"Template not found: {e}")
exception jinja2.TemplateSyntaxError

Raised when the template contains syntax errors:

# Invalid template syntax will raise TemplateSyntaxError
# Example: unclosed block, invalid variable name, etc.
exception marrmotflow.templating.Exception

Raised by the raise_helper function within templates:

# Template with: {{ raise("Custom error message") }}
# Will raise: Exception: Custom error message

Best Practices

  1. Validate template syntax before deployment

  2. Use descriptive variable names in templates

  3. Include error checking with raise_helper

  4. Document template variables and their expected types

  5. Test templates with various input contexts

  6. Version control templates along with code

  7. Use meaningful file names for generated models

Type Definitions

marrmotflow.templating.PathLike

Type alias for file paths, supporting both string and os.PathLike objects. alias of str | PathLike

alias of str | PathLike