Skip to content

Templates

rn_forge.commons.text.templates

Strict Jinja2 rendering from filesystem or package templates.

RenderError(message, *message_args, error_code=-1, **error_data)

Bases: AppException

A template could not be loaded, compiled, or rendered.

check(value, message, *message_args, **kwargs) classmethod

Raise this exception if value is falsy.

Parameters:

Name Type Description Default
value Any

The value to test.

required
message str

Exception message (supports positional format args).

required
*message_args Any

Forwarded to message.format().

()
**kwargs Any

Forwarded as error_code / error_data to the constructor.

{}

Example::

AppException.check(path.exists(), "Missing file: {}", path, error_code=404)

TemplateEngine(*, directory=None, package=None, package_path='templates', strict=True, autoescape=False, **environment_kwargs)

Render templates from a directory or a package, with strict undefined handling.

Initialize :class:TemplateEngine.

Exactly one of directory or package must be given.

Parameters:

Name Type Description Default
directory str | None

A filesystem directory of templates (jinja2.FileSystemLoader).

None
package str | None

A Python package name whose package_path subdirectory holds templates (jinja2.PackageLoader) — the resource loads even when the package is installed as a zipped wheel.

None
package_path str

Subdirectory within package holding templates. Only meaningful with package.

'templates'
strict bool

Use jinja2.StrictUndefined (default) so referencing an undefined variable raises instead of rendering empty.

True
autoescape bool

HTML-escape every rendered value. Enable it when the output is HTML.

False
**environment_kwargs Any

Forwarded to the jinja2.Environment constructor (e.g. trim_blocks, lstrip_blocks). keep_trailing_newline=True is the default unless overridden here.

{}

Raises:

Type Description
ValueError

Both or neither of directory/package are given.

environment property

The underlying jinja2.Environment — the escape hatch.

cached(*, directory=None, package=None, package_path='templates', strict=True, autoescape=False, **environment_kwargs) classmethod

Return the engine already built in this process for equal arguments.

The engine is built on first use, so each template compiles once per process. It is shared: do not mutate its :attr:environment. Every argument must be hashable.

Parameters:

Name Type Description Default
directory str | None

As for the constructor.

None
package str | None

As for the constructor.

None
package_path str

As for the constructor.

'templates'
strict bool

As for the constructor.

True
autoescape bool

As for the constructor.

False
**environment_kwargs Any

As for the constructor.

{}

Returns:

Type Description
TemplateEngine

The shared engine for these arguments.

Raises:

Type Description
ValueError

Both or neither of directory/package are given.

render(name, context)

Render a named template from the configured directory or package.

Raises:

Type Description
RenderError

The template cannot be loaded, compiled, or evaluated.

render_string(template, context)

Render an inline template string.

Raises:

Type Description
RenderError

The template cannot be compiled or evaluated.

validate()

Compile every template visible to the loader; return error messages.

Returns [] (rather than raising TypeError) for an environment whose loader does not support listing templates.