Tips and tricks¶
This module contains some ustache integration tips alongside general Mustache syntax tricks which can be useful for other implementations too (as long they’re spec compliant).
Cache¶
Ustache implements a default cache storing the 1024 last used template
tokenizations to skip that slower parsing step for the common templates,
exposed as ustache.default_cache
.
Template pre-caching¶
As templates are parsed and cached on their first render, that cache can be prepared in advance by simply rendering them with dummy scope.
import ustache
render('Hello {{.}}', None)
Alternatively, consuming the template tokenization will have the same effect while skipping any rendering.
import ustache
template = 'Hello {{.}}'
all(ustache.tokenize(template.encode()))
Disable cache¶
Disabling ustache template cache, which can be specially useful for one-off
templates, can be achieved by providing your own cache mapping. For example,
by passing an empty disposable dict
, the compiled
template will be discarded during garbage collection.
import ustache
print(ustache.render('Hello {{.}}', 'world!', cache={}))
# Hello world
Lambda examples¶
Lambda functions are not always straightforward, especially when requiring context data, as they’re unable to directly access the current scope.
The standard solution is using the render function, usually multiple times, to retrieve the required data from context, as string, and then performing some parsing.
Datetime strformat¶
In this example we implement the common-case-scenario of formatting a
datetime.datetime
object using a lambda forwarding the custom
format to datetime.datetime.strftime()
.
import datetime
import typing
import ustache
def strftime(text: str, render: typing.Callable[[str], str]) -> str:
"""Render date/datetime scope with given strftime format."""
iso = render('{{.}}').replace(' ', 'T') # __str__ is stable
try:
dt = (
datetime.datetime.fromisoformat(iso)
if 'T' in iso else
datetime.date.fromisoformat(iso)
)
except ValueError:
return ''
return dt.strftime(render(text))
print(
ustache.render(
'{{#dt}}{{#_strftime}}%Y.%m.%d{{/_strftime}}{{/dt}}',
{
'dt': datetime.datetime.now(),
'_strftime': strftime, # prefixed to avoid collisions
},
),
)
# 2021.03.25
Virtual properties¶
Sometimes lambda functions are not enough to get the job done, and you might find yourself recursively patching your entire rendering scope with new keys or properties.
While in JavaScript would be way easier to temporarily patch the Object
prototype instead, using a similar approach on Python is a very bad idea.
To address this issue ustache.default_getter()
exposes a virtuals
argument you can use to include your custom virtual property implementations
(just remember to include those already defined by
ustache.default_virtuals
as well).
You can either use a custom getter wrapper or functools.partial()
to pass a custom ustache.default_getter()
including your virtuals to
ustache.render()
.
import functools
import ustache
def word_count(text):
return len(text.split())
print(
ustache.render(
'{{obj.word_count}} words',
{'obj': 'virtual properties are cool'},
getter=functools.partial(
ustache.default_getter,
virtuals={
**ustache.default_virtuals,
'word_count': word_count,
},
),
),
)
# 4 words
Please note both AttributeError
and TypeError
exceptions raised from virtual property functions are appropriately handled
by ustache.default_getter()
.
Streaming patterns¶
Streaming is a first-class citizen for ustache, enabling powerful patterns which are not only memory-efficient but more responsive than their buffered counterparts, especially over networks.
You can easily integrate ustache.stream()
on most common scenarios
with just a tiny bit of preprocessing, here are some examples.
JSON streaming¶
In this example we stream enveloped JSON by preprocessing that envelope as
our template and then serializing every generator item individually
(using enumerate()
to enable comma insertion logic) while rendering.
import json
import ustache
# Given any row generator (like a database row cursor)
rows = (
(i, 'a', 'b', 'c')
for i in range(1000, 10000)
)
# Serialize envelope with content placeholder
placeholder = '%CONTENT%'
envelope = json.dumps({'results': [placeholder]})
# Replace envelope placeholder with our mustache template
template = envelope.replace(
json.dumps(placeholder),
'{{#rows}}{{#0}},{{/0}}{{&1}}{{/rows}}', # row mustache template
)
# Stream enveloped JSON rows
stream = ustache.stream(
template,
{'rows': enumerate(map(json.dumps, rows))},
)
for chunk in stream:
print(chunk)
# {"results": [
# [1000, "a", "b", "c"]
# ,
# ...
# ,
# [9999, "a", "b", "c"]
# ]}