5.6 Namespace cascading and the searchList

When Cheetah maps a variable name in a template to a Python value, it searches several namespaces in order:

Local variables: created by #set, #for, or predefined by Cheetah.
The searchList, consisting of:
1. #set global variables.
2. The searchList containers you passed to the Template constructor, if any.
3. The Template instance (``self''). This contains any attributes you assigned, #def methods and #block methods, attributes/methods inherited via #extends, and other attributes/methods built into Template or inherited by it (there's a list of all these methods in section 13.5).
Python globals: created by #import, #from ... import, or otherwise predefined by Cheetah.
Python builtins: None, max, etc.

The first matching name found is used.

Remember, these namespaces apply only to the first identifier after the $. In a placeholder like $a.b, only `a' is looked up in the searchList and other namespaces. `b' is looked up only inside `a'.

A searchList container can be any Python object with attributes or keys: dictionaries, instances, classes or modules. If an instance contains both attributes and keys, its attributes are searched first, then its keys.

Because the Template instance is part of the searchList, you can access its attributes/methods without `self': $myAttr. However, use the `self' if you want to make sure you're getting the Template attribute and not a same-name variable defined in a higher namespace: $self.myAttr. This works because ``self'' itself is a local variable.

The final resulting value, after all lookups and function calls (but before the filter is applied) is called the placeholder value, no matter which namespace it was found in.

Note carefully: if you put an object `myObject' in the searchList, you cannot look up $myObject! You can look up only the attributes/keys inside `myObject'.

Earlier versions of Cheetah did not allow you to override Python builtin names, but this was fixed in Cheetah 0.9.15.

If your template will be used as a Webware servlet, do not override methods 'name' and 'log' in the Template instance or it will interfere with Webware's logging. However, it is OK to use those variables in a higher namespace, since Webware doesn't know about Cheetah namespaces.