Very lightweight, memory-efficient, dependency-free template engine (compiles to Python source).
Project description
utemplate
utemplate
is a lightweight and memory-efficient template engine for
Python, primarily intended for use with Pycopy, a lightweight Python
implementation (https://github.com/pfalcon/pycopy).
utemplate
syntax is roughly based on Django/Jinja2 syntax (e.g.
{% if %}
, {{var}}
), but only the most needed features are offered
(for example, "filters" are syntactic sugar for function calls, and
so far are not planned to be implemented).
utemplate
compiles templates to Python source code, specifically to
a generator function which, being iterated over, produces consecutive
parts (substrings) of a rendered template. This allows for minimal
memory usage during template substitution (with Pycopy, it starts
from mere hundreds of bytes). Generated Python code can be imported as
a module directly, or a simple loader class is provided for convenience.
There is also a loader class which will compile templates on the fly,
if not already compiled (currently not automatically recompiled if
changed, this is on TODO).
To test/manage templates, utemplate_util.py
tool is provided. For
example, to quickly try a template (assuming you are already in
examples/
dir):
pycopy ../utemplate_util.py run squares.tpl
or
python3 ../utemplate_util.py run squares.tpl
Templates can take parameters (that's how dynamic content is generated).
Template parameters are passed as arguments to a generator function
produced from a template. They also can be passed on the utemplate_util.py
command line (arguments will be treated as strings in this case, but
can be of any types if called from your code):
pycopy ../utemplate_util.py run test1.tpl foo bar
Quick Syntax Reference
Evaluating Python expression, converting it to a string and outputting to rendered content:
{{<expr>}}
Where expr
is an arbitrary Python expression - from a bare variable name,
to function calls, yield from
, await
expressions.
Supported statements:
{% if %}
,{% elif %}
,{% else %}
,{% endif %}
- the usual "if" statement{% for %}
,{% endfor %}
- the usual "for" statement{% while %}
,{% endwhile %}
- the usual "while" statement{% args var1, var2, ... %}
- specify arguments to a template{% set var = expr %}
- assignment statement{% include "name.tpl" %}
- statically include another template{% include {{name}} %}
- dynamically include template whose name is stored in variablename
.
Naming Conventions
The current conventions (may be adjusted in the future):
- The recommended extension for templates is
.tpl
, e.g.example.tpl
. - When template is compiled, dot (
.
) in its name is replaced with underscore (_
) and.py
appended, e.g.example_tpl.py
. It thus can be imported withimport example_tpl
. - The name passed to
{% include %}
statement should be full name of a template with extension, e.g.{% include "example.tpl" %}
. - For dynamic form of the
include
, a variable should similarly contain a full name of the template, e.g.{% set name = "example.tpl" %}
/{% include {{name}} %}
.
Examples
examples/squares.tpl
as mentioned in the usage examples above has the
following content:
{% args n=5 %}
{% for i in range(n) %}
| {{i}} | {{"%2d" % i ** 2}} |
{% endfor %}
More examples are available in the examples/ directory.
If you want to see a complete example web application which uses utemplate
,
refer to https://github.com/pfalcon/notes-pico .
License
utemplate
is written and maintained by Paul Sokolovsky. It's available
under the MIT license.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.