PyFoam.ThirdParty.pyratemp module

Small, simple and powerful template-engine for python.

A template-engine for python, which is very simple, easy to use, small, fast, powerful, modular, extensible, well documented and pythonic.

See documentation for a list of features, template-syntax etc.

Version:

0.2.0

Usage:

see class Template and examples below.

Example:
quickstart::
>>> t = Template("hello @!name!@")
>>> print t(name="marvin")
hello marvin
generic usage::
>>> t = Template("output is in Unicode äöü€")
>>> t                                           
<...Template instance at 0x...>
>>> t()
u'output is in Unicode \xe4\xf6\xfc\u20ac'
>>> unicode(t)
u'output is in Unicode \xe4\xf6\xfc\u20ac'
with data::
>>> t = Template("hello @!name!@", data={"name":"world"})
>>> t()
u'hello world'
>>> t(name="worlds")
u'hello worlds'

# >>> t(note=”data must be Unicode or ASCII”, name=u”ä”) # u’hello xe4’

escaping::
>>> t = Template("hello escaped: @!name!@, unescaped: $!name!$")
>>> t(name='''<>&'"''')
u'hello escaped: &lt;&gt;&amp;&#39;&quot;, unescaped: <>&\'"'
result-encoding::

# encode the unicode-object to your encoding with encode() >>> t = Template(“hello äöü€”) >>> result = t() >>> result u’hello xe4xf6xfcu20ac’ >>> result.encode(“utf-8”) ‘hello xc3xa4xc3xb6xc3xbcxe2x82xac’ >>> result.encode(“ascii”) Traceback (most recent call last):

UnicodeEncodeError: ‘ascii’ codec can’t encode characters in position 6-9: ordinal not in range(128) >>> result.encode(“ascii”, ‘xmlcharrefreplace’) ‘hello &#228;&#246;&#252;&#8364;’

python-expressions::
>>> Template('formatted: @! "%8.5f" % value !@')(value=3.141592653)
u'formatted:  3.14159'
>>> Template("hello --@!name.upper().center(20)!@--")(name="world")
u'hello --       WORLD        --'
>>> Template("calculate @!var*5+7!@")(var=7)
u'calculate 42'
blocks (if/for/macros/…)::
>>> t = Template("<!--(if foo == 1)-->bar<!--(elif foo == 2)-->baz<!--(else)-->unknown(@!foo!@)<!--(end)-->")
>>> t(foo=2)
u'baz'
>>> t(foo=5)
u'unknown(5)'
>>> t = Template("<!--(for i in mylist)-->@!i!@ <!--(else)-->(empty)<!--(end)-->")
>>> t(mylist=[])
u'(empty)'
>>> t(mylist=[1,2,3])
u'1 2 3 '
>>> t = Template("<!--(for i,elem in enumerate(mylist))--> - @!i!@: @!elem!@<!--(end)-->")
>>> t(mylist=["a","b","c"])
u' - 0: a - 1: b - 2: c'
>>> t = Template('<!--(macro greetings)-->hello <strong>@!name!@</strong><!--(end)-->  @!greetings(name=user)!@')
>>> t(user="monty")
u'  hello <strong>monty</strong>'
exists::
>>> t = Template('<!--(if exists("foo"))-->YES<!--(else)-->NO<!--(end)-->')
>>> t()
u'NO'
>>> t(foo=1)
u'YES'
>>> t(foo=None)       # note this difference to 'default()'
u'YES'
default-values::

# non-existing variables raise an error >>> Template(‘hi @!optional!@’)() Traceback (most recent call last):

TemplateRenderError: Cannot eval expression ‘optional’. (NameError: name ‘optional’ is not defined)

>>> t = Template('hi @!default("optional","anyone")!@')
>>> t()
u'hi anyone'
>>> t(optional=None)
u'hi anyone'
>>> t(optional="there")
u'hi there'

# the 1st parameter can be any eval-expression >>> t = Template(‘@!default(“5*var1+var2”,”missing variable”)!@’) >>> t(var1=10) u’missing variable’ >>> t(var1=10, var2=2) u’52’

# also in blocks >>> t = Template(‘<!–(if default(“opt1+opt2”,0) > 0)–>yes<!–(else)–>no<!–(end)–>’) >>> t() u’no’ >>> t(opt1=23, opt2=42) u’yes’

>>> t = Template('<!--(for i in default("optional_list",[]))-->@!i!@<!--(end)-->')
>>> t()
u''
>>> t(optional_list=[1,2,3])
u'123'

# but make sure to put the expression in quotation marks, otherwise: >>> Template(‘@!default(optional,”fallback”)!@’)() Traceback (most recent call last):

TemplateRenderError: Cannot eval expression ‘default(optional,”fallback”)’. (NameError: name ‘optional’ is not defined)

setvar::
>>> t = Template('$!setvar("i", "i+1")!$@!i!@')
>>> t(i=6)
u'7'
>>> t = Template('''<!--(if isinstance(s, (list,tuple)))-->$!setvar("s", '"\\\\n".join(s)')!$<!--(end)-->@!s!@''')
>>> t(isinstance=isinstance, s="123")
u'123'
>>> t(isinstance=isinstance, s=["123", "456"])
u'123\n456'
Author:

Roland Koebler (rk at simple-is-better dot org)

Copyright:

Roland Koebler

License:

MIT/X11-like, see __license__

class PyFoam.ThirdParty.pyratemp.EvalPseudoSandbox[source]

Bases: object

An eval-pseudo-sandbox.

The pseudo-sandbox restricts the available functions/objects, so the code can only access:

  • some of the builtin python-functions, which are considered “safe” (see safe_builtins)
  • some additional functions (exists(), default(), setvar())
  • the passed objects incl. their methods.

Additionally, names beginning with “_” are forbidden. This is to prevent things like ‘0 .__class__’, with which you could easily break out of a “sandbox”.

Be careful to only pass “safe” objects/functions to the template, because any unsafe function/method could break the sandbox! For maximum security, restrict the access to as few objects/functions as possible!

Warning:

Note that this is no real sandbox! (And although I don’t know any way to break out of the sandbox without passing-in an unsafe object, I cannot guarantee that there is no such way. So use with care.)

Take care if you want to use it for untrusted code!!

compile(expr)[source]

Compile a python-eval-expression.

  • Use a compile-cache.
  • Raise a NameError if expr contains a name beginning with _.
Returns:

the compiled expr

Exceptions:
  • SyntaxError: for compile-errors
  • NameError: if expr contains a name beginning with _
eval(expr, locals)[source]

Eval a python-eval-expression.

Sets self.locals_ptr to locales and compiles the code before evaluating.

f_default(expr, default=None)[source]

default() for the sandboxed code.

Try to evaluate an expression and return the result or a fallback-/default-value; the default-value is used if expr does not exist/is invalid/results in None.

This is very useful for optional data.

Parameter:
  • expr: eval-expression
  • default: fallback-falue if eval(expr) fails or is None.
Returns:

the eval-result or the “fallback”-value.

Note:

the eval-expression has to be quoted! (like in eval)

Example:

see module-docstring

f_exists(varname)[source]

exists() for the sandboxed code.

Test if the variable varname exists in the current locals-namespace.

This only works for single variable names. If you want to test complicated expressions, use i.e. default. (i.e. default(“expr”,False))

Note:the variable-name has to be quoted! (like in eval)
Example:see module-docstring
f_import(name, *args, **kwargs)[source]

import/__import__() for the sandboxed code.

Since “import” is insecure, the PseudoSandbox does not allow to import other modules. But since some functions need to import other modules (e.g. “datetime.datetime.strftime” imports “time”), this function replaces the builtin “import” and allows to use modules which are already accessible by the sandboxed code.

Note:
  • This probably only works for rather simple imports.
  • For security, it may be better to avoid such (complex) modules which import other modules. (e.g. use time.localtime and time.strftime instead of datetime.datetime.strftime)
Example:
>>> from datetime import datetime
>>> import pyratemp
>>> t = pyratemp.Template('@!mytime.strftime("%H:%M:%S")!@')
>>> print t(mytime=datetime.now())
Traceback (most recent call last):
  ...
ImportError: import not allowed in pseudo-sandbox; try to import 'time' yourself and pass it to the sandbox/template
>>> import time
>>> print t(mytime=datetime.strptime("13:40:54", "%H:%M:%S"), time=time)
13:40:54

# >>> print t(mytime=datetime.now(), time=time) # 13:40:54

f_setvar(name, expr)[source]

setvar() for the sandboxed code.

Set a variable.

Example:see module-docstring
register(name, obj)[source]

Add an object to the “allowed eval-globals”.

Mainly useful to add user-defined functions to the pseudo-sandbox.

safe_builtins = {'abs': <built-in function abs>, 'bool': <class 'bool'>, 'chr': <built-in function chr>, 'complex': <class 'complex'>, 'dict': <class 'dict'>, 'divmod': <built-in function divmod>, 'enumerate': <class 'enumerate'>, 'float': <class 'float'>, 'hash': <built-in function hash>, 'hex': <built-in function hex>, 'int': <class 'int'>, 'len': <built-in function len>, 'list': <class 'list'>, 'max': <built-in function max>, 'min': <built-in function min>, 'oct': <built-in function oct>, 'ord': <built-in function ord>, 'pow': <built-in function pow>, 'range': <class 'range'>, 'reversed': <class 'reversed'>, 'round': <built-in function round>, 'sorted': <built-in function sorted>, 'str': <class 'str'>, 'sum': <built-in function sum>, 'tuple': <class 'tuple'>, 'zip': <class 'zip'>}
safe_builtins_python2 = {'False': '__builtin__.False', 'None': '__builtin__.None', 'True': '__builtin__.True', 'cmp': '__builtin__.cmp', 'long': '__builtin__.long', 'unichr': '__builtin__.unichr', 'unicode': '__builtin__.unicode', 'xrange': '__builtin__.xrange'}
class PyFoam.ThirdParty.pyratemp.LoaderFile(allowed_path=None, encoding='utf-8')[source]

Bases: object

Load template from a file.

When loading a template from a file, it’s possible to including other templates (by using ‘include’ in the template). But for simplicity and security, all included templates have to be in the same directory! (see allowed_path)

load(filename)[source]

Load a template from a file.

Check if filename is allowed and return its contens in unicode.

Parameters:
  • filename: filename of the template without path
Returns:

the contents of the template-file in unicode

Exceptions:
  • ValueError: if filename contains a path
class PyFoam.ThirdParty.pyratemp.LoaderString(encoding='utf-8')[source]

Bases: object

Load template from a string/unicode.

Note that ‘include’ is not possible in such templates.

load(string)[source]

Return template-string as unicode.

class PyFoam.ThirdParty.pyratemp.Parser(loadfunc=None, testexpr=None, escape=1)[source]

Bases: object

Parse a template into a parse-tree.

Includes a syntax-check, an optional expression-check and verbose error-messages.

See documentation for a description of the parse-tree.

parse(template)[source]

Parse a template.

Parameters:
  • template: template-unicode-string
Returns:

the resulting parse-tree

Exceptions:
  • TemplateSyntaxError: for template-syntax-errors
  • TemplateIncludeError: if template-inclusion failed
  • TemplateException
class PyFoam.ThirdParty.pyratemp.Renderer(evalfunc, escapefunc)[source]

Bases: object

Render a template-parse-tree.

Uses:TemplateBase for macros
render(parsetree, data)[source]

Render a parse-tree of a template.

Parameters:
  • parsetree: the parse-tree
  • data: the data to fill into the template (dictionary)
Returns:

the rendered output-unicode-string

Exceptions:
  • TemplateRenderError
class PyFoam.ThirdParty.pyratemp.Template(string=None, filename=None, parsetree=None, encoding='utf-8', data=None, escape=1, loader_class=<class 'PyFoam.ThirdParty.pyratemp.LoaderFile'>, parser_class=<class 'PyFoam.ThirdParty.pyratemp.Parser'>, renderer_class=<class 'PyFoam.ThirdParty.pyratemp.Renderer'>, eval_class=<class 'PyFoam.ThirdParty.pyratemp.EvalPseudoSandbox'>, escape_func=<function escape>)[source]

Bases: PyFoam.ThirdParty.pyratemp.TemplateBase

Template-User-Interface.

Usage:
::

t = Template(…) (<- see __init__) output = t(…) (<- see TemplateBase.__call__)

Example:

see module-docstring

class PyFoam.ThirdParty.pyratemp.TemplateBase(parsetree, renderfunc, data=None)[source]

Bases: object

Basic template-class.

Used both for the template itself and for ‘macro’s (“subtemplates”) in the template.

exception PyFoam.ThirdParty.pyratemp.TemplateException[source]

Bases: Exception

Base class for template-exceptions.

exception PyFoam.ThirdParty.pyratemp.TemplateIncludeError(err, errpos)[source]

Bases: PyFoam.ThirdParty.pyratemp.TemplateParseError

Template ‘include’ failed.

exception PyFoam.ThirdParty.pyratemp.TemplateParseError(err, errpos)[source]

Bases: PyFoam.ThirdParty.pyratemp.TemplateException

Template parsing failed.

exception PyFoam.ThirdParty.pyratemp.TemplateRenderError[source]

Bases: PyFoam.ThirdParty.pyratemp.TemplateException

Template rendering failed.

exception PyFoam.ThirdParty.pyratemp.TemplateSyntaxError(err, errpos)[source]

Bases: PyFoam.ThirdParty.pyratemp.TemplateParseError, SyntaxError

Template syntax-error.

PyFoam.ThirdParty.pyratemp.dictkeyclean(d)[source]

Convert all keys of the dict d to strings.

PyFoam.ThirdParty.pyratemp.dummy(*args, **kwargs)[source]

Dummy function, doing nothing.

PyFoam.ThirdParty.pyratemp.dummy_raise(exception, value)[source]

Create an exception-raising dummy function.

Returns:dummy function, raising exception(value)
PyFoam.ThirdParty.pyratemp.escape(s, format=1)[source]

Replace special characters by their escape sequence.

Parameters:
  • s: string or unicode-string to escape
  • format:
    • NONE: nothing is replaced
    • HTML: replace &<>’” by &…;
    • LATEX: replace #$%&_{} (TODO! - this is very incomplete!)
Returns:

the escaped string in unicode

Exceptions:
  • ValueError: if format is invalid.
TODO:

complete LaTeX-escaping, optimize speed

PyFoam.ThirdParty.pyratemp.scol(string, i)[source]

Get column number of string[i] in string.

Returns:column, starting at 1 (but may be <1 if i<0)
Note:This works for text-strings with \n or \r\n.
PyFoam.ThirdParty.pyratemp.sindex(string, row, col)[source]

Get index of the character at row/col in string.

Parameters:
  • row: row number, starting at 1.
  • col: column number, starting at 1.
Returns:

i, starting at 0 (but may be <1 if row/col<0)

Note:

This works for text-strings with ‘n’ or ‘rn’.

PyFoam.ThirdParty.pyratemp.srow(string, i)[source]

Get line numer of string[i] in string.

Returns:row, starting at 1
Note:This works for text-strings with \n or \r\n.
PyFoam.ThirdParty.pyratemp.toUniCode(s)[source]