utemplate 1.4.1
Very lightweight, memory-efficient, dependency-free template engine (compiles to Python source).
License: MIT

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 (`utemplate.compiled.Loader`)
is provided for convenience.

There is also a loader class which will compile templates on the fly,
if not already compiled - `utemplate.source.Loader`.

Finally, there's a loader which will automatically recompile a template
module if source template is changed - `utemplate.recompile.Loader`.
This loader class is the most convenient to use during development, but
on the other hand, it performs extra processing not required for a
finished/deployed application.

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, etc.

Supported statements:

* `{% args <var1>, <var2>, ... %}` - specify arguments to a template
  (optional, should be at the beginning of a template if you want to
  pass any arguments). All argument types as supported by Python can
  be used: positional and keyword, with default values, `*args` and
  `**kwargs` forms, etc.
* `{% if <expr> %}`, `{% elif <expr> %}`, `{% else %}`, `{% endif %}` -
  similar to Python's `if` statement
* `{% for <var> in <expr> %}`, `{% endfor %}` - similar to Python's
  `for` statement
* `{% while <expr> %}`, `{% endwhile %}` - similar to Python's `while`
  statement
* `{% set <var> = <expr> %}` - assignment statement
* `{% include "name.tpl" %}` - statically include another template
* `{% include {{name}} %}` - dynamically include template whose name is
  stored in variable `name`.

File Naming Conventions
-----------------------

* 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 with `import 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/](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.