module documentation

Visitor/traversal interface and library functions.

SQLAlchemy schema and expression constructs rely on a Python-centric version of the classic "visitor" pattern as the primary way in which they apply functionality. The most common use of this pattern is statement compilation, where individual expression classes match up to rendering methods that produce a string result. Beyond this, the visitor system is also used to inspect expressions for various information and patterns, as well as for the purposes of applying transformations to expressions.

Examples of how the visit system is used can be seen in the source code of for example the sqlalchemy.sql.util and the sqlalchemy.sql.compiler modules. Some background on clause adaption is also at https://techspot.zzzeek.org/2008/01/23/expression-transformations/ .

Class ​External​Traversal Base class for visitor objects which can traverse externally using the .visitors.traverse function.
Class ​Internal​Traversal Defines visitor symbols used for internal traversal.
Class ​Traversible Base class for visitable objects, applies the .visitors.TraversibleType metaclass.
Class ​Traversible​Type Metaclass which assigns dispatch attributes to various kinds of "visitable" classes.
Function cloned​_traverse Clone the given expression structure, allowing modifications by visitors.
Function iterate Traverse the given expression structure, returning an iterator.
Function replacement​_traverse Clone the given expression structure, allowing element replacement by a given replacement function.
Function traverse Traverse and visit the given expression structure using the default iterator.
Function traverse​_using Visit the given expression structure using the given iterator of objects.
Class _​Internal​Traversal​Type Undocumented
Class ​Cloning​External​Traversal Base class for visitor objects which can traverse using the .visitors.cloned_traverse function.
Class ​Extended​Internal​Traversal Defines additional symbols that are useful in caching applications.
Class ​Replacing​External​Traversal Base class for visitor objects which can traverse using the .visitors.replacement_traverse function.
Function ​_generate​_compiler​_dispatch Generate a _compiler_dispatch() external traversal on classes with a __visit_name__ attribute.
Function ​_generate​_dispatcher Undocumented
def cloned_traverse(obj, opts, visitors):

Clone the given expression structure, allowing modifications by visitors.

Traversal usage is the same as that of .visitors.traverse. The visitor functions present in the visitors dictionary may also modify the internals of the given structure as the traversal proceeds.

The central API feature used by the .visitors.cloned_traverse and .visitors.replacement_traverse functions, in addition to the _expression.ClauseElement.get_children function that is used to achieve the iteration, is the _expression.ClauseElement._copy_internals method. For a _expression.ClauseElement structure to support cloning and replacement traversals correctly, it needs to be able to pass a cloning function into its internal members in order to make copies of them.

See Also

.visitors.traverse

.visitors.replacement_traverse

def iterate(obj, opts=util.immutabledict()):

Traverse the given expression structure, returning an iterator.

Traversal is configured to be breadth-first.

The central API feature used by the .visitors.iterate function is the _expression.ClauseElement.get_children method of _expression.ClauseElement objects. This method should return all the _expression.ClauseElement objects which are associated with a particular _expression.ClauseElement object. For example, a .Case structure will refer to a series of _expression.ColumnElement objects within its "whens" and "else_" member variables.

Parameters
obj_expression.ClauseElement structure to be traversed
optsdictionary of iteration options. This dictionary is usually empty in modern usage.
def replacement_traverse(obj, opts, replace):

Clone the given expression structure, allowing element replacement by a given replacement function.

This function is very similar to the .visitors.cloned_traverse function, except instead of being passed a dictionary of visitors, all elements are unconditionally passed into the given replace function. The replace function then has the option to return an entirely new object which will replace the one given. If it returns None, then the object is kept in place.

The difference in usage between .visitors.cloned_traverse and .visitors.replacement_traverse is that in the former case, an already-cloned object is passed to the visitor function, and the visitor function can then manipulate the internal state of the object. In the case of the latter, the visitor function should only return an entirely different object, or do nothing.

The use case for .visitors.replacement_traverse is that of replacing a FROM clause inside of a SQL structure with a different one, as is a common use case within the ORM.

def traverse(obj, opts, visitors):

Traverse and visit the given expression structure using the default iterator.

e.g.:

from sqlalchemy.sql import visitors

stmt = select(some_table).where(some_table.c.foo == 'bar')

def visit_bindparam(bind_param):
    print("found bound value: %s" % bind_param.value)

visitors.traverse(stmt, {}, {"bindparam": visit_bindparam})

The iteration of objects uses the .visitors.iterate function, which does a breadth-first traversal using a stack.

Parameters
obj_expression.ClauseElement structure to be traversed
optsdictionary of iteration options. This dictionary is usually empty in modern usage.
visitorsdictionary of visit functions. The dictionary should have strings as keys, each of which would correspond to the __visit_name__ of a particular kind of SQL expression object, and callable functions as values, each of which represents a visitor function for that kind of object.
def traverse_using(iterator, obj, visitors):

Visit the given expression structure using the given iterator of objects.

.visitors.traverse_using is usually called internally as the result of the .visitors.traverse function.

See Also

.traverse

Parameters
iteratoran iterable or sequence which will yield _expression.ClauseElement structures; the iterator is assumed to be the product of the .visitors.iterate function.
objthe _expression.ClauseElement that was used as the target of the .iterate function.
visitorsdictionary of visit functions. See .traverse for details on this dictionary.
def _generate_compiler_dispatch(cls):
Generate a _compiler_dispatch() external traversal on classes with a __visit_name__ attribute.
def _generate_dispatcher(visitor, internal_dispatch, method_name):

Undocumented