genshi.template.eval

Support for "safe" evaluation of Python expressions.

Code

Abstract base class for the Expression and Suite classes.

Expression

Evaluates Python expressions used in templates.

>>> data = dict(test='Foo', items=[1, 2, 3], dict={'some': 'thing'})
>>> Expression('test').evaluate(data)
'Foo'

>>> Expression('items[0]').evaluate(data)
1
>>> Expression('items[-1]').evaluate(data)
3
>>> Expression('dict["some"]').evaluate(data)
'thing'

Similar to e.g. Javascript, expressions in templates can use the dot notation for attribute access to access items in mappings:

>>> Expression('dict.some').evaluate(data)
'thing'

This also works the other way around: item access can be used to access any object attribute:

>>> class MyClass(object):
...     myattr = 'Bar'
>>> data = dict(mine=MyClass(), key='myattr')
>>> Expression('mine.myattr').evaluate(data)
'Bar'
>>> Expression('mine["myattr"]').evaluate(data)
'Bar'
>>> Expression('mine[key]').evaluate(data)
'Bar'

All of the standard Python operators are available to template expressions. Built-in functions such as len() are also available in template expressions:

>>> data = dict(items=[1, 2, 3])
>>> Expression('len(items)').evaluate(data)
3

evaluate(self, data)

Evaluate the expression against the given data dictionary.

param data:	a mapping containing the data to evaluate against
return:	the result of the evaluation

Suite

Executes Python statements used in templates.

>>> data = dict(test='Foo', items=[1, 2, 3], dict={'some': 'thing'})
>>> Suite("foo = dict['some']").execute(data)
>>> data['foo']
'thing'

execute(self, data)

Execute the suite in the given data dictionary.

param data:	a mapping containing the data to execute in

UndefinedError

Exception thrown when a template expression attempts to access a variable not defined in the context.

see:	LenientLookup, StrictLookup

Undefined

Represents a reference to an undefined variable.

Unlike the Python runtime, template expressions can refer to an undefined variable without causing a NameError to be raised. The result will be an instance of the Undefined class, which is treated the same as False in conditions, but raise an exception on any other operation:

>>> foo = Undefined('foo')
>>> bool(foo)
False
>>> list(foo)
[]
>>> print(foo)
undefined

However, calling an undefined variable, or trying to access an attribute of that variable, will raise an exception that includes the name used to reference that undefined variable.

>>> try:
...     foo('bar')
... except UndefinedError, e:
...     print e.msg
"foo" not defined

>>> try:
...     foo.bar
... except UndefinedError, e:
...     print e.msg
"foo" not defined

see:	LenientLookup

LookupBase

Abstract base class for variable lookup implementations.

globals(cls, data)

Construct the globals dictionary to use as the execution context for the expression or suite.

lookup_name(cls, data, name)

(Not documented)

lookup_attr(cls, obj, key)

(Not documented)

lookup_item(cls, obj, key)

(Not documented)

undefined(cls, key, owner=UNDEFINED)

Can be overridden by subclasses to specify behavior when undefined variables are accessed.

param key:	the name of the variable
param owner:	the owning object, if the variable is accessed as a member

LenientLookup

Default variable lookup mechanism for expressions.

When an undefined variable is referenced using this lookup style, the reference evaluates to an instance of the Undefined class:

>>> expr = Expression('nothing', lookup='lenient')
>>> undef = expr.evaluate({})
>>> undef
<Undefined 'nothing'>

The same will happen when a non-existing attribute or item is accessed on an existing object:

>>> expr = Expression('something.nil', lookup='lenient')
>>> expr.evaluate({'something': dict()})
<Undefined 'nil'>

See the documentation of the Undefined class for details on the behavior of such objects.

see:	StrictLookup

undefined(cls, key, owner=UNDEFINED)

Return an Undefined object.

StrictLookup

Strict variable lookup mechanism for expressions.

Referencing an undefined variable using this lookup style will immediately raise an UndefinedError:

>>> expr = Expression('nothing', lookup='strict')
>>> try:
...     expr.evaluate({})
... except UndefinedError, e:
...     print e.msg
"nothing" not defined

The same happens when a non-existing attribute or item is accessed on an existing object:

>>> expr = Expression('something.nil', lookup='strict')
>>> try:
...     expr.evaluate({'something': dict()})
... except UndefinedError, e:
...     print e.msg
{} has no member named "nil"

undefined(cls, key, owner=UNDEFINED)

Raise an UndefinedError immediately.

TemplateASTTransformer

Concrete AST transformer that implements the AST transformations needed for code embedded in templates.

visit_Str(self, node)

(Not documented)

visit_ClassDef(self, node)

(Not documented)

visit_Import(self, node)

(Not documented)

visit_ImportFrom(self, node)

(Not documented)

visit_FunctionDef(self, node)

(Not documented)

visit_GeneratorExp(self, node)

(Not documented)

visit_Lambda(self, node)

(Not documented)

visit_Name(self, node)

(Not documented)

ExpressionASTTransformer

Concrete AST transformer that implements the AST transformations needed for code embedded in templates.

visit_Attribute(self, node)

(Not documented)

visit_Subscript(self, node)

(Not documented)

---

See ApiDocs, Documentation