Module Expr Str ImportFrom alias Assign NameStore BinOpAdd Str Str Assign NameStore SubscriptLoad Str Slice Num Num Import alias ImportFrom alias alias alias alias ImportFrom alias Import alias Assign NameStore NameLoad Assign NameStore NameLoad Assign NameStore ListLoad Str Str Str Str Str Str Str ClassDef bases NameLoad body Pass decorator_list FunctionDef arguments args NameParam NameParam defaults body Assign NameStore BinOpMod Str NameLoad If NameLoad body AugAssignAdd NameStore BinOpMod Str Call NameLoad NameLoad Raise Call NameLoad NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults body If UnaryOpNot NameLoad body Raise orelse Assign NameStore SubscriptLoad AttributeLoad NameLoad attr Index Num If CompareEq Call AttributeLoad NameLoad attr Str Num body AugAssignAdd NameStore BinOpMod Str NameLoad If NameLoad body AugAssignAdd NameStore BinOpMod Str Call NameLoad NameLoad Assign AttributeStore NameLoad attr TupleLoad NameLoad Raise decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str If BoolOpAnd Call NameLoad NameLoad Str Call AttributeLoad NameLoad attr NameLoad body Return NameLoad orelse If Call NameLoad NameLoad NameLoad body Return NameLoad orelse Return NameLoad decorator_list FunctionDef arguments args NameParam NameParam defaults body If BoolOpAnd Call NameLoad NameLoad Str Call AttributeLoad NameLoad attr NameLoad body Return SubscriptLoad NameLoad Index NameLoad orelse If Call NameLoad NameLoad NameLoad body Return Call NameLoad NameLoad NameLoad orelse Expr Call NameLoad NameLoad NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults NameLoad body Assign NameStore Call AttributeLoad NameLoad attr Str For NameStore Call NameLoad Call NameLoad NameLoad body Assign NameStore SubscriptLoad NameLoad Index NameLoad If Call NameLoad NameLoad NameLoad body Assign NameStore Call NameLoad NameLoad NameLoad orelse If BoolOpAnd Call NameLoad NameLoad Str Call AttributeLoad NameLoad attr NameLoad body Assign NameStore SubscriptLoad NameLoad Index NameLoad orelse Expr Call NameLoad NameLoad NameLoad If BoolOpAnd NameLoad Call NameLoad NameLoad CompareNotIn Call NameLoad NameLoad TupleLoad NameLoad NameLoad body Assign NameStore Call NameLoad orelse Assign NameStore NameLoad Return NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults NameLoad body TryExcept body Return Call NameLoad NameLoad NameLoad NameLoad handlers ExceptHandler type NameLoad name NameStore body Expr Call NameLoad NameLoad keyword NameLoad keyword NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults NameLoad body Assign NameStore SubscriptLoad Call AttributeLoad NameLoad attr Str Index Num For NameStore NameLoad body If Call NameLoad NameLoad NameLoad body Return Call NameLoad NameLoad NameLoad keyword NameLoad Expr Call NameLoad NameLoad NameLoad decorator_list FunctionDef arguments args NameParam NameParam defaults NameLoad body Expr Yield AttributeLoad NameLoad attr If NameLoad body For NameStore NameLoad body Expr Yield NameLoad Expr Yield AttributeLoad NameLoad attr Expr Yield NameLoad decorator_list FunctionDef arguments args NameParam NameParam NameParam NameParam defaults NameLoad NameLoad body FunctionDef arguments args defaults body TryExcept body Return Call NameLoad NameLoad NameLoad keyword NameLoad handlers ExceptHandler type NameLoad name NameStore body Expr Call NameLoad NameLoad keyword NameLoad keyword NameLoad decorator_list TryFinally body If UnaryOpNot NameLoad body Assign NameStore SubscriptLoad SubscriptLoad Call AttributeLoad NameLoad attr Index Num Index Num Assign NameStore SubscriptLoad Call AttributeLoad NameLoad attr Str Index Num For NameStore Call NameLoad NameLoad NameLoad body If Call NameLoad NameLoad NameLoad body Return Call NameLoad Expr Call NameLoad NameLoad NameLoad finalbody Delete NameDel decorator_list FunctionDef arguments args NameParam NameParam NameParam defaults NameLoad NameLoad body TryFinally body If UnaryOpNot NameLoad body Assign NameStore SubscriptLoad SubscriptLoad Call AttributeLoad NameLoad attr Index Num Index Num Return Call NameLoad keyword NameLoad keyword NameLoad keyword NameLoad keyword NameLoad finalbody Delete NameDel decorator_list FunctionDef arguments args NameParam NameParam defaults body Expr Str Assign NameStore SubscriptLoad Call AttributeLoad NameLoad attr Str Index Num If UnaryOpNot Call NameLoad NameLoad NameLoad body Return NameLoad TryExcept body Expr Call NameLoad NameLoad NameLoad Return NameLoad handlers ExceptHandler type NameLoad body Return NameLoad decorator_list TryExcept body ImportFrom alias alias alias alias alias alias Assign NameStore NameLoad handlers ExceptHandler body Assign NameStore NameLoad ClassDef bases body Expr Str FunctionDef arguments args NameParam NameParam defaults body Return Call NameLoad NameLoad NameLoad decorator_list FunctionDef arguments args NameParam NameParam defaults body Return Call NameLoad NameLoad NameLoad decorator_list decorator_list FunctionDef arguments args defaults body ClassDef bases NameLoad body Assign NameStore Str FunctionDef arguments args NameParam NameParam defaults Str body Return NameLoad decorator_list FunctionDef arguments args NameParam NameParam defaults Str body Return Dict Str NameLoad decorator_list FunctionDef arguments args NameParam NameParam defaults Str body Return NameLoad decorator_list decorator_list ClassDef bases NameLoad body Assign NameStore Str decorator_list Assign NameStore Call NameLoad Assign AttributeStore NameLoad attr Str FunctionDef arguments args NameParam defaults Str body Assign NameStore Dict Str Str Str Str Str Str Return SubscriptLoad NameLoad Index NameLoad decorator_list Assign AttributeStore NameLoad attr Dict Str Str Str Str NameLoad AttributeLoad NameLoad attr Str Dict Str AttributeLoad NameLoad attr Assign NameStore Str Print Call NameLoad AttributeLoad NameLoad attr Str Print Call NameLoad NameLoad Str Print Call NameLoad Call NameLoad Str Print Call Call NameLoad NameLoad Str Print Call NameLoad Call NameLoad Str Print Call NameLoad Call NameLoad Str keyword NameLoad Print Call NameLoad Call NameLoad Str keyword NameLoad decorator_list If CompareEq NameLoad Str body Expr Call NameLoad
N/A N/A This module supports Cheetah's optional NameMapper syntax.

Overview
================================================================================

NameMapper provides a simple syntax for accessing Python data structures,
functions, and methods from Cheetah. It's called NameMapper because it 'maps'
simple 'names' in Cheetah templates to possibly more complex syntax in Python.

Its purpose is to make working with Cheetah easy for non-programmers.
Specifically, non-programmers using Cheetah should NOT need to be taught (a)
what the difference is between an object and a dictionary, (b) what functions
and methods are, and (c) what 'self' is.  A further aim (d) is to buffer the
code in Cheetah templates from changes in the implementation of the Python data
structures behind them.

Consider this scenario:

You are building a customer information system. The designers with you want to
use information from your system on the client's website --AND-- they want to
understand the display code and so they can maintian it themselves.

You write a UI class with a 'customers' method that returns a dictionary of all
the customer objects.  Each customer object has an 'address' method that returns
the a dictionary with information about the customer's address.  The designers
want to be able to access that information.

Using PSP, the display code for the website would look something like the
following, assuming your servlet subclasses the class you created for managing
customer information:

  <%= self.customer()[ID].address()['city'] %>   (42 chars)

Using Cheetah's NameMapper syntax it could be any of the following:

   $self.customers()[$ID].address()['city']       (39 chars)
   --OR--                                         
   $customers()[$ID].address()['city']           
   --OR--                                         
   $customers()[$ID].address().city              
   --OR--                                         
   $customers()[$ID].address.city                
   --OR--                                         
   $customers()[$ID].address.city
   --OR--
   $customers[$ID].address.city                   (27 chars)                   
   
   
Which of these would you prefer to explain to the designers, who have no
programming experience?  The last form is 15 characters shorter than the PSP
and, conceptually, is far more accessible. With PHP or ASP, the code would be
even messier than the PSP

This is a rather extreme example and, of course, you could also just implement
'$getCustomer($ID).city' and obey the Law of Demeter (search Google for more on that).
But good object orientated design isn't the point here.

Details
================================================================================
The parenthesized letters below correspond to the aims in the second paragraph.

DICTIONARY ACCESS (a)
---------------------

NameMapper allows access to items in a dictionary using the same dotted notation
used to access object attributes in Python.  This aspect of NameMapper is known
as 'Unified Dotted Notation'.

For example, with Cheetah it is possible to write:
   $customers()['kerr'].address()  --OR--  $customers().kerr.address()
where the second form is in NameMapper syntax.

This only works with dictionary keys that are also valid python identifiers:
  regex = '[a-zA-Z_][a-zA-Z_0-9]*'


AUTOCALLING (b,d)
-----------------

NameMapper automatically detects functions and methods in Cheetah $vars and calls
them if the parentheses have been left off.  

For example if 'a' is an object, 'b' is a method
  $a.b
is equivalent to
  $a.b()

If b returns a dictionary, then following variations are possible
  $a.b.c  --OR--  $a.b().c  --OR--  $a.b()['c']
where 'c' is a key in the dictionary that a.b() returns.

Further notes:
* NameMapper autocalls the function or method without any arguments.  Thus
autocalling can only be used with functions or methods that either have no
arguments or have default values for all arguments.

* NameMapper only autocalls functions and methods.  Classes and callable object instances
will not be autocalled.  

* Autocalling can be disabled using Cheetah's 'useAutocalling' setting.

LEAVING OUT 'self' (c,d)
------------------------

NameMapper makes it possible to access the attributes of a servlet in Cheetah
without needing to include 'self' in the variable names.  See the NAMESPACE
CASCADING section below for details.

NAMESPACE CASCADING (d)
--------------------
...

Implementation details
================================================================================

* NameMapper's search order is dictionary keys then object attributes

* NameMapper.NotFound is raised if a value can't be found for a name.

Performance and the C version
================================================================================

Cheetah comes with both a C version and a Python version of NameMapper.  The C
version is significantly faster and the exception tracebacks are much easier to
read.  It's still slower than standard Python syntax, but you won't notice the
difference in realistic usage scenarios.

Cheetah uses the optimized C version (_namemapper.c) if it has
been compiled or falls back to the Python version if not.

Meta-Data
================================================================================
Authors: Tavis Rudd <tavis@damnsimple.com>,
         Chuck Esterbrook <echuck@mindspring.com>
Version: $Revision: 1.2 $
Start Date: 2001/04/03
Last Revision Date: $Date: 2006-12-19 13:32:47 $
 __future__ generators N/A __author__ N/A Tavis Rudd <tavis@damnsimple.com>, 
Chuck Esterbrook <echuck@mindspring.com> N/A __revision__ N/A $Revision: 1.2 $ N/A 11 -2 N/A types types StringType InstanceType ClassType TypeType pprint pformat N/A inspect N/A _INCLUDE_NAMESPACE_REPR_IN_NOTFOUND_EXCEPTIONS False N/A _ALLOW_WRAPPING_OF_NOTFOUND_EXCEPTIONS True N/A __all__ N/A NotFound hasKey valueForKey valueForName valueFromSearchList valueFromFrameOrSearchList valueFromFrame NotFound N/A LookupError N/A N/A N/A _raiseNotFoundException N/A N/A key namespace N/A N/A N/A excString N/A cannot find '%s' key N/A _INCLUDE_NAMESPACE_REPR_IN_NOTFOUND_EXCEPTIONS N/A N/A excString N/A  in the namespace %s N/A pformat namespace N/A N/A NotFound excString N/A _wrapNotFoundException N/A N/A exc fullName namespace N/A N/A N/A N/A _ALLOW_WRAPPING_OF_NOTFOUND_EXCEPTIONS N/A N/A N/A N/A excStr N/A N/A exc args N/A 0 N/A N/A N/A N/A excStr find while searching -1 N/A N/A excStr N/A  while searching for '%s' fullName N/A _INCLUDE_NAMESPACE_REPR_IN_NOTFOUND_EXCEPTIONS N/A N/A excString N/A  in the namespace %s N/A pformat namespace N/A N/A exc args N/A excStr N/A N/A hasKey N/A N/A obj key N/A N/A N/A Determine if 'obj' has 'key'  N/A N/A N/A hasattr obj has_key N/A N/A obj has_key key N/A N/A True N/A N/A N/A hasattr obj key N/A N/A True N/A N/A False N/A valueForKey N/A N/A obj key N/A N/A N/A N/A N/A hasattr obj has_key N/A N/A obj has_key key N/A N/A N/A obj N/A key N/A N/A N/A hasattr obj key N/A N/A N/A getattr obj key N/A N/A N/A _raiseNotFoundException key obj N/A _valueForName N/A N/A obj name executeCallables N/A False N/A N/A nameChunks N/A N/A name split . N/A i N/A range N/A len nameChunks N/A N/A key N/A nameChunks N/A i N/A N/A hasattr obj key N/A N/A nextObj N/A getattr obj key N/A N/A N/A N/A hasattr obj has_key N/A N/A obj has_key key N/A N/A nextObj N/A obj N/A key N/A N/A N/A _raiseNotFoundException key obj N/A N/A executeCallables N/A callable nextObj N/A N/A type nextObj N/A InstanceType ClassType N/A N/A obj N/A nextObj N/A N/A obj nextObj N/A obj N/A valueForName N/A N/A obj name executeCallables N/A False N/A N/A N/A N/A N/A _valueForName obj name executeCallables N/A N/A N/A NotFound N/A e N/A N/A N/A _wrapNotFoundException e fullName name namespace obj N/A valueFromSearchList N/A N/A searchList name executeCallables N/A False N/A N/A key N/A N/A N/A name split . N/A 0 N/A namespace searchList N/A N/A N/A hasKey namespace key N/A N/A N/A _valueForName namespace name executeCallables executeCallables N/A N/A _raiseNotFoundException key searchList N/A _namespaces N/A N/A callerFrame searchList N/A None N/A N/A N/A N/A callerFrame f_locals N/A searchList N/A N/A namespace searchList N/A N/A N/A namespace N/A N/A N/A callerFrame f_globals N/A N/A __builtins__ N/A valueFromFrameOrSearchList N/A N/A searchList name executeCallables frame N/A False None N/A __valueForName N/A N/A N/A N/A N/A N/A N/A N/A _valueForName namespace name executeCallables executeCallables N/A N/A N/A NotFound N/A e N/A N/A N/A _wrapNotFoundException e fullName name namespace searchList N/A N/A N/A N/A N/A frame N/A N/A frame N/A N/A N/A N/A inspect stack N/A 1 N/A 0 N/A key N/A N/A N/A name split . N/A 0 N/A namespace N/A _namespaces frame searchList N/A N/A N/A hasKey namespace key N/A N/A N/A __valueForName N/A N/A _raiseNotFoundException key searchList N/A N/A frame N/A valueFromFrame N/A N/A name executeCallables frame N/A False None N/A N/A N/A N/A N/A frame N/A N/A frame N/A N/A N/A N/A inspect stack N/A 1 N/A 0 N/A N/A valueFromFrameOrSearchList searchList None name name executeCallables executeCallables frame frame N/A N/A frame N/A hasName N/A N/A obj name N/A N/A N/A Determine if 'obj' has the 'name'  N/A key N/A N/A N/A name split . N/A 0 N/A N/A N/A hasKey obj key N/A N/A False N/A N/A N/A N/A valueForName obj name N/A True N/A N/A N/A NotFound N/A N/A False N/A N/A N/A _namemapper NotFound valueForKey valueForName valueFromSearchList valueFromFrameOrSearchList valueFromFrame N/A C_VERSION True N/A N/A N/A N/A C_VERSION False Mixin N/A N/A N/A @@ document me valueForName N/A N/A self name N/A N/A N/A N/A valueForName self name N/A valueForKey N/A N/A self key N/A N/A N/A N/A valueForKey self key N/A N/A example N/A N/A N/A N/A A N/A Mixin N/A N/A classVar classVar val method N/A N/A self arg N/A method 1 default arg N/A N/A arg N/A method2 N/A N/A self arg N/A meth 2 default arg N/A N/A N/A item1 arg N/A method3 N/A N/A self arg N/A meth 3 default N/A N/A arg N/A N/A B N/A A N/A N/A classBvar classBvar val N/A N/A a N/A A N/A N/A a one valueForOne function N/A N/A whichOne N/A default N/A N/A values N/A default one two default output output option one output option two N/A N/A values N/A whichOne N/A N/A N/A a dic N/A func method item subDict function N/A a method3 itemval N/A nestedMethod N/A a method3 N/A b this is local b N/A N/A valueForKey N/A a dic subDict N/A N/A valueForName a dic.item N/A N/A valueForName N/A vars b N/A N/A N/A valueForName __builtins__ dir N/A N/A valueForName N/A vars a.classVar N/A N/A valueForName N/A vars a.dic.func executeCallables True N/A N/A valueForName N/A vars a.method2.item1 executeCallables True N/A N/A N/A __name__ __main__ N/A N/A N/A example