Package: temptation
TemptationTemptation is a simple and straightforward template engine with an
extensible grammar.ObjectivesRegular-expression-basedSubstitution intemptationtemplates is based on regular expressions.Apart from the obvious limitations regarding nested
substitution-expressions (they may be supported to a certain extent)
this comes with two advantages:ExtensibilityEfficient regular-expression scanning rather than complex parsing.Semantic expression substitutionRather than always expecting key-value pairs as inputtemptationprovides the ability to apply different substitution algorithms on
different template-expressions.ExtensibilityThe regular-expression based grammar can easily be extended or
customized by adding custom matchers.MVC-based templatingTemplate languages are a way to separate the view (presentation) from
the data model.Many (if not most) template languages support control structures like
conditions or loops. So their templates combine presentation with
control.temptationintentionally doesn’t.This comes with limitations and with advantages. An obvious limitation
is that with usingtemptationon its own you can’t process data in a
non-linear way. There is only one path from the beginning to the end of
the template.Advantages are:The linear approach keeps templates simple and very well readable.Templates are easy to test.temptationtemplates can easily be be used by external controllers
that care about more complex transformation-related issues like
conditional processing or iteration.ynotis a transformator making use of thetemptationgrammar and
this reference-implementation. Seeynot overview on
github.Limited support for nested template expressionsThis is not implemented yet because I didn’t find a reasonable use-case.
But it could be added quite easily if it turns out that it makes sense.Setup$pipinstalltemptationBy installingtemptationviapipyou automatically get the command
line interface oftemptationinstalled as well.Command-Line-Interface (CLI)The purpose of the command line interface is to support processing
data-files (yamlorjson) against a single template-file.To get help on the (currently quite limited) command-line options just
entertemtation-hand you’ll see an output like this:Usage: scripts/temptation [OPTION] -t template datafile...

Resolve template for datafiles. Datafiles can be yaml or json

Options:
  --version             show program version number and exit
  -h, --help            show this help message and exit
  -t TEMPLATEFILENAME, --template=TEMPLATEFILENAME
                        Template to be resovedIn the current version if you use multiple data-files as input they need
to be inyamlformat and every file must begin with a
document-separator (---).This limitation may be removed in future versions so that it will also
be possible to process multiple ‘json’ data-files which is currently not
possible because json doesn’t support multiple documents.Command-line ExpampleLet’s say we have this text file …temlate.txt:${greeting} ${name}!… and the following data-files:data1.yaml:---greeting:Helloname:worlddata2.yaml:---greeting:Good morningname:Donald DuckNow let’s see howtemptationapplies the template to the data-files:$ temptation -t template.text data*.yaml
Hello world!
Good morning Donald Duck!Quite simple, right?ImportsThe following samples assume that you have imported theTemplateclass like this:>>>fromtemptationimportTemplateSamplesJust static textAny text that’s not atemptationexpression is left unchanged.>>>Template("Hello world").resolve()u'Hello world'There are some pre-definedtemptationexpressions:${key}: Map resolution@{jsonpath}: Jsonpath resolution for single match@*{jsonpath}: Jsonpath resolution for multiple match!{python expression}: Python evaluation expressionIf you need to use a literal that matches those expressions you need to
escape it with a backslash\like this:\${whatever}In the expanded template the backslash will be removed but the
expression won’t be evaluated.Literal baskslashes can be escaped by a backslash as well. So\\in
the template will be presented as\in the output. You will see
samples for this further down.Let’s now see samples for the pre-definedtemptationexpressions and
how they are expanded.Map resolution:${key}One of the pre-definedtemptationexpressions is a simple key-value
substitution.The expression’s value is interpreted as a key that will be substituted
by the corresponding value of the input data.>>>Template("${greeting}${name}").resolve({"greeting":"Hello","name":"world"})u'Hello world'Escaping tags:\${key}Any pre-defined (or custom)temptationexpression can be escaped by
preceding it with a backslash. A backslash itself can be escaped by
another backslash.>>>Template(r"Hello \${name}").resolve({"name":"world"})u'Hello ${name}'>>>Template(r"Hello\\${name}").resolve({"name":"world"})u'Hello\\world'Jsonpath resolution for single match:@{jsonpath-espression}The jsonpath expansion is based on thejsonpath-ngimplementation, so the syntax is predetermined by this implementation.
Please read the linked documentation for details.A jsonpath result always returns an array of matches. This array may
contain 0..n items. To represent a result that matches multiple itemstemptationis enclosing the matches in brackets:[item1, item2,...].In a template you’re often interested in a single match and don’t want
this to be enclosed in brackets. That’s whytemptationsupports thesingle matchresolution. It will omit the enclosing brackets if there
is a single match. In case of multiple matches it will log a warning and
enclose the result in brackets.>>>context={"items":[{"item":"first item"},{"item":"second item"}]}>>>Template("Hello @{$.items[0].item} and @{$.items[1].item}").resolve(context)u'Hello first item and second item'>>>Template(u"Hello @{$..item}").resolve(context)u"Hello ['first item', 'second item']"Jsonpath resolution for multiple matches:@*{jsonpathexpression}Whenever you don’t expect a single match but want to consistently
present the result as a list, you can use thistemptationexpression.>>>context={"items":[{"item":"first item"},{"item":"second item"}]}>>>Template("Hello @*{$.items[0].item} and @*{$.items[1].item}").resolve(context)u"Hello ['first item'] and ['second item']">>>Template(u"Hello @*{$..item}").resolve(context)u"Hello ['first item', 'second item']"Evaluation resolution:!{python expression}The python-evaluation resolution allows to expand atemptationexpression to the result of any python expression.Currently the pre-defined evaluation expression is limited to the use of
modules that are imported in thetemplate.default_resolversmodule.
It’s planned to provide a more flexible solution for importing
additional modules to be accessible from evaluation expressions.>>>Template(u"Hello !{7 + 5}").resolve()u'Hello 12'>>>context={"values":[1,3,5,7]}>>>Template(u"Hello !{context['values'][2] + context['values'][3]}").resolve(context)u'Hello 12'>>>template="""${greeting}${name}... This is a very personal letter. To emphasize how well I know you
... I add best regards to your !{len(context['children'])} children !{", ".join([child for child in context["children"]])}.
... """>>>context=[{"name":"Mr. Template","greeting":"Hello","children":["Jeff","Henriette","Mark"]},{"name":"Mrs. Temptation","greeting":"Dear","children":[]}]>>>foritemincontext:...Template(template).resolve(item)u'Hello Mr. Template\nThis is a very personal letter. To emphasize how well I know you\nI add best regards to your 3 children Jeff, Henriette, Mark.\n'u'Dear Mrs. Temptation\nThis is a very personal letter. To emphasize how well I know you\nI add best regards to your 0 children .\n'Adding your own matchersYou can extendtemptation’s capabilities by implementing your own
matchers.To do so you must first import theResolversclass:Import Matcher>>>fromtemptationimportMatcherCustom matcher sample>>>defresolve_foo(expression,match,context):...return"foo-{0}".format(expression)>>>foomatcher=Matcher("foomatcher",tag=r"\$foo",samples=["$foo{}"],processor=resolve_foo)>>>barmatcher=Matcher("barmatcher",tag=r"\$bar",samples=["$bar{}"],processor=lambdaexpression,match,context:"{0}-bar".format(expression))>>>template="Hello $foo{something}and $bar{something_else}">>>Template(template).add_matcher(foomatcher).add_matcher(barmatcher).resolve()u'Hello foo-something and something_else-bar'Resolvers are validated against samplesIt is also ensured that samples don’t match with other matchers. This is
an attempt to help avoiding ambiguities (but obviously doesn’t guarantee
that there is no intersection between regular expressions of different
matchers).>>>foomatcher=Matcher("foomatcher",tag=r"\$x",samples=["$x{whatever}"])>>>barmatcher=Matcher("barmatcher",tag=r"\$xx*",samples=["$xxx{whatever}"])>>>template=Template("").add_matcher(foomatcher)>>>template.add_matcher(barmatcher)Traceback(mostrecentcalllast):...Exception:sample'$x{whatever}'formatcher'foomatcher'alsomatchesmatcher'barmatcher'