Introduction

Tempiny is a tiny and really simple template engine.

The main feature is to be able to execute arbitrary python code inside the template, which makes it really powerful for code generation for example.

See the skbs project to have a sense of what it can achieve !

Install

Simply pip install it :

pip install tempiny

Template syntax

First an example to demonstrate all its features :

This text will be printed as it is

Lines starting with '##' (or a user-configured prefix) are python code.

## a=5 # this won't be printed
## # this is a comment in the python script. Won't be printed.

if/else/for/while/with/try/except etc blocks don't need indentation. Instead, a line containing only '## -' marks the block end.

## for i in range(a) :
##   b = a + 1 # you may indent
## c = a +2 # or not, still in the for block.
This text will be printed 5 times (a = {{a}}) Btw, between a double brace (2 '{'), you can put expression that will be converted to str, and printed instead.
To escape it, The prefered way is to declare variables containing the tokens (as done in skbs)
##   for j in range(3) :
You can also nest loops
##   -
## # ↑ end of inner loop
## -
## # end of outer loop

Expression can be as complex you want as long as they are valid python expression returning something that can be transformed to a string :
{{ ";".join( str(i) + f' - {a=},{b=},{c=}' for i in range(2)) }}

will be output as :

This text will be printed as it is

Lines starting with '##' (or a user-configured prefix) are python code.


if/else/for/while/with/try/except etc blocks don't need indentation. Instead, a line containing only '## -' marks the block end.

This text will be printed 5 times (a = 5) Btw, between a double brace (2 '{'), you can put expression that will be converted to str, and printed instead.
To escape it, The prefered way is to declare variables containing the tokens (as done in skbs)
You can also nest loops
You can also nest loops
You can also nest loops
This text will be printed 5 times (a = 5) Btw, between a double brace (2 '{'), you can put expression that will be converted to str, and printed instead.
To escape it, The prefered way is to declare variables containing the tokens (as done in skbs)
You can also nest loops
You can also nest loops
You can also nest loops
This text will be printed 5 times (a = 5) Btw, between a double brace (2 '{'), you can put expression that will be converted to str, and printed instead.
To escape it, The prefered way is to declare variables containing the tokens (as done in skbs)
You can also nest loops
You can also nest loops
You can also nest loops
This text will be printed 5 times (a = 5) Btw, between a double brace (2 '{'), you can put expression that will be converted to str, and printed instead.
To escape it, The prefered way is to declare variables containing the tokens (as done in skbs)
You can also nest loops
You can also nest loops
You can also nest loops
This text will be printed 5 times (a = 5) Btw, between a double brace (2 '{'), you can put expression that will be converted to str, and printed instead.
To escape it, The prefered way is to declare variables containing the tokens (as done in skbs)
You can also nest loops
You can also nest loops
You can also nest loops

Expression can be as complex you want as long as they are valid python expression returning something that can be transformed to a string : 0 - a=5,b=6,c=7;1 - a=5,b=6,c=7

Basically, there are 3 contexts :

Code context

Each line starting by the code prefix (specified in plugin.py, or '##' by default) is basically python code except for the block delimitation : in python, the indentation level delimits a block while with tempiny, for practical use, indentation doesn't matter, and a block is ended by a single dash ( "-" ).

Example :

## a = 5
## for i in range(a) :
##   b = 2 + i
##   # Do come stuff
## c=3 # this is still in the for
## -
## # end of the for

Any python code is allowed. This is the reason you should use templates only from trusted sources.

Text context

Any line that doesn't start with the code prefix is "text", and will be output as is each time the execution flow reaches it. Basically, you can imagine (by the way, this is actually how it is implemented...) each Text context is like a call to print

For example, the following :

This is a text
## for i in range(3):
To see
## -
how it works

Will output :

This is a test
To see
To see
To see
how it works

Expression context

Inside a Text context, you may want to print an expression (for example a variable value or the result of a python call etc.) You can do it by surrounding it with the expression delimiters (specified in plugin.py or '{{' and '}}' by default). It will be replaced by the expression value at the time of execution. Example:

## for i in range(3)
Item number {{i}}
## -

Will print :

Item number 0
Item number 1
Item number 2

Any python expression is allowed.

Once again, you should only execute trusted templates.

API

from tempiny import Tempiny # import tempiny

There are 3 built-in dialects:

Tempiny.C  = dict(stmt_line_start=r'//#', begin_expr='{{', end_expr='}}')
Tempiny.PY = dict(stmt_line_start=r'##', begin_expr='{{', end_expr='}}')
Tempiny.TEX = dict(stmt_line_start=r'%#', begin_expr='<<', end_expr='>>')

To configure a Tempiny instance :

T = Tempiny(
  stmt_line_start=PY['stmt_line_start'], # Code prefix. 
  begin_expr=PY['begin_expr'], # Expression delimiter (begin)
  end_expr=PY['end_expr'] # Expression delimiter (end)
)

Note that you can use any string for these tokens.

Tempiny.compile(self, f:Iterable[str], filename='<template>', default_globals={}, default_locals=None) -> Template: This method compiles a template. f should be an iterable of strings (an open file is ok). default_globals is a dict you can provide to have a default global scope when calling the template. You should probably leave default_locals to None except if you know what you are doing.

Example :

with open('test_template', 'r') as f:
  template = T.compile(f, 'test_template')

Template.__call__(self, out_stream, _globals={}, _locals=None) -> (dict, Exception) This method permits to call the template, outputting in out_stream (it should at least have a write(s:str) method. You can provide a global scope (it will be shallow-copied before entering the template) through _globals to pass values to the template. You can also provide a local scope through _locals, but it can lead to unexpected behaviour (not defined errors inside function or list-comprehension). Except if you know what to do, let it None, it will contain the same content as the globals. It returns the new locals (to retrieve names defined or modified from the template), and None if no exception occurred, or the exception if one raised.

Example:

with open('result', 'w') as f:
  template(f, {'author': 'Léo Flaventin Hauchecorne', 'date' : 2016})

License Notice

Tempiny is a tiny template engine Copyright © 2016-2020 Léo Flaventin Hauchecorne

This library is free software; you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation; either version 2.1 of the License, or (at your option) any later version.

This library is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.

You should have received a copy of the GNU Lesser General Public License along with this library; if not, write to the Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA