adafruit_templateengine

Templating engine to substitute variables into a template string. Templates can also include conditional logic and loops. Often used for web pages.

  • Author(s): Michał Pokusa, Tim Cocks

Software and Dependencies:

class adafruit_templateengine.FileTemplate(template_path: str)

Class that loads a template from a file and allows to rendering it with different contexts.

Loads a file and creates a reusable template from its contents.

Parameters:

template_path (str) – Path to a file containing the template to be rendered

class adafruit_templateengine.Template(template_string: str)

Class that loads a template from str and allows to rendering it with different contexts.

Creates a reusable template from the given template string.

Parameters:

template_string (str) – String containing the template to be rendered

render(context: dict = None) → str

Render the template with the given context.

Parameters:

context (dict) – Dictionary containing the context for the template

Example:

template = ... # r"Hello {{ name }}!"

template.render({"name": "World"})
# 'Hello World!'
render_iter(context: dict = None, *, chunk_size: int = None) → Generator[str]

Renders the template using the provided context and returns a generator that yields the rendered output.

Parameters:

  • context (dict) – Dictionary containing the context for the template

  • chunk_size (int) – Size of the chunks to be yielded. If None, the generator yields the template in chunks sized specifically for the given template

Example:

template = ... # r"Hello {{ name }}!"

list(template.render_iter({"name": "World"}))
# ['Hello ', 'World', '!']

list(template.render_iter({"name": "CircuitPython"}, chunk_size=3))
# ['Hel', 'lo ', 'Cir', 'cui', 'tPy', 'tho', 'n!']
exception adafruit_templateengine.TemplateNotFoundError(path: str)

Raised when a template file is not found.

Specified template file that was not found.

exception adafruit_templateengine.TemplateSyntaxError(token: Token, reason: str)

Raised when a syntax error is encountered in a template.

Provided token is not a valid template syntax at the specified position.

class adafruit_templateengine.Token(template: str, start_position: int, end_position: int)

Stores a token with its position in a template.

adafruit_templateengine.render_string(template_string: str, context: dict = None, *, cache: bool = True)

Creates a Template from the given template_string and renders it using the provided context. Returns the rendered output as a string.

If cache is True, the template is saved and reused on next calls, even with different contexts.

Parameters:

  • context (dict) – Dictionary containing the context for the template

  • cache (bool) – When True, the template is saved and reused on next calls.

Example:

render_string(r"Hello {{ name }}!", {"name": "World"})
# 'Hello World!'
adafruit_templateengine.render_string_iter(template_string: str, context: dict = None, *, chunk_size: int = None, cache: bool = True)

Creates a Template from the given template_string and renders it using the provided context. Returns a generator that yields the rendered output.

If cache is True, the template is saved and reused on next calls, even with different contexts.

Parameters:

  • context (dict) – Dictionary containing the context for the template

  • chunk_size (int) – Size of the chunks to be yielded. If None, the generator yields the template in chunks sized specifically for the given template

  • cache (bool) – When True, the template is saved and reused on next calls.

Example:

list(render_string_iter(r"Hello {{ name }}!", {"name": "World"}))
# ['Hello ', 'World', '!']

list(render_string_iter(r"Hello {{ name }}!", {"name": "CircuitPython"}, chunk_size=3))
# ['Hel', 'lo ', 'Cir', 'cui', 'tPy', 'tho', 'n!']
adafruit_templateengine.render_template(template_path: str, context: dict = None, *, cache: bool = True)

Creates a FileTemplate from the given template_path and renders it using the provided context. Returns the rendered output as a string.

If cache is True, the template is saved and reused on next calls, even with different contexts.

Parameters:

  • context (dict) – Dictionary containing the context for the template

  • cache (bool) – When True, the template is saved and reused on next calls.

Example:

render_template(..., {"name": "World"}) # r"Hello {{ name }}!"
# 'Hello World!'
adafruit_templateengine.render_template_iter(template_path: str, context: dict = None, *, chunk_size: int = None, cache: bool = True)

Creates a FileTemplate from the given template_path and renders it using the provided context. Returns a generator that yields the rendered output.

If cache is True, the template is saved and reused on next calls, even with different contexts.

Parameters:

  • context (dict) – Dictionary containing the context for the template

  • chunk_size (int) – Size of the chunks to be yielded. If None, the generator yields the template in chunks sized specifically for the given template

  • cache (bool) – When True, the template is saved and reused on next calls.

Example:

list(render_template_iter(..., {"name": "World"})) # r"Hello {{ name }}!"
# ['Hello ', 'World', '!']

list(render_template_iter(..., {"name": "CircuitPython"}, chunk_size=3))
# ['Hel', 'lo ', 'Cir', 'cui', 'tPy', 'tho', 'n!']
adafruit_templateengine.safe_html(value: Any) → str

Encodes unsafe symbols in value to HTML entities and returns the string that can be safely used in HTML.

Examples:

safe_html('<a href="https://circuitpython.org/">CircuitPython</a>')
# &lt;a href&equals;&quot;https&colon;&sol;&sol;circuitpython&period;org&sol;&quot;&gt;...

safe_html(10 ** (-10))
# 1e&minus;10