Visitor and Traversal Utilities¶

The sqlalchemy.sql.visitors module consists of classes and functions that serve the purpose of generically traversing a Core SQL expression structure. This is not unlike the Python ast module in that is presents a system by which a program can operate upon each component of a SQL expression. Common purposes this serves are locating various kinds of elements such as Table or BindParameter objects, as well as altering the state of the structure such as replacing certain FROM clauses with others.

The sqlalchemy.sql.visitors module is part of the internals of SQLAlchemy and it is not usually used by calling application code. It is however used in certain edge cases such as when constructing caching routines as well as when building out custom SQL expressions using the Custom SQL Constructs and Compilation Extension.

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 http://techspot.zzzeek.org/2008/01/23/expression-transformations/ .

class sqlalchemy.sql.visitors.VisitableType(clsname, bases, clsdict)¶

Bases: builtins.type

Metaclass which assigns a _compiler_dispatch method to classes having a __visit_name__ attribute.

The _compiler_dispatch attribute becomes an instance method which looks approximately like the following:

def _compiler_dispatch (self, visitor, **kw):
    '''Look for an attribute named "visit_" + self.__visit_name__
    on the visitor, and call it with the same kw params.'''
    visit_attr = 'visit_%s' % self.__visit_name__
    return getattr(visitor, visit_attr)(self, **kw)

Classes having no __visit_name__ attribute will remain unaffected.

class sqlalchemy.sql.visitors.Visitable¶

Base class for visitable objects, applies the visitors.VisitableType metaclass.

The Visitable class is essentially at the base of the ClauseElement hierarchy.

class sqlalchemy.sql.visitors.ClauseVisitor¶

Base class for visitor objects which can traverse using the visitors.traverse() function.

Direct usage of the visitors.traverse() function is usually preferred.

chain(visitor)¶

‘chain’ an additional ClauseVisitor onto this ClauseVisitor.

the chained visitor will receive all visit events after this one.

iterate(obj)¶

traverse the given expression structure, returning an iterator of all elements.

traverse(obj)¶

traverse and visit the given expression structure.

visitor_iterator¶

iterate through this visitor and each ‘chained’ visitor.

class sqlalchemy.sql.visitors.CloningVisitor¶

Bases: sqlalchemy.sql.visitors.ClauseVisitor

Base class for visitor objects which can traverse using the visitors.cloned_traverse() function.

Direct usage of the visitors.cloned_traverse() function is usually preferred.

copy_and_process(list_)¶

Apply cloned traversal to the given list of elements, and return the new list.

traverse(obj)¶

traverse and visit the given expression structure.

class sqlalchemy.sql.visitors.ReplacingCloningVisitor¶

Bases: sqlalchemy.sql.visitors.CloningVisitor

Base class for visitor objects which can traverse using the visitors.replacement_traverse() function.

Direct usage of the visitors.replacement_traverse() function is usually preferred.

replace(elem)¶

receive pre-copied elements during a cloning traversal.

If the method returns a new element, the element is used instead of creating a simple copy of the element. Traversal will halt on the newly returned element if it is re-encountered.

traverse(obj)¶

traverse and visit the given expression structure.

sqlalchemy.sql.visitors.iterate(obj, opts)¶

traverse the given expression structure, returning an iterator.

traversal is configured to be breadth-first.

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

Parameters:	obj¶ – ClauseElement structure to be traversed opts¶ – dictionary of iteration options. This dictionary is usually empty in modern usage.

sqlalchemy.sql.visitors.iterate_depthfirst(obj, opts)¶

traverse the given expression structure, returning an iterator.

traversal is configured to be depth-first.

Parameters:	obj¶ – ClauseElement structure to be traversed opts¶ – dictionary of iteration options. This dictionary is usually empty in modern usage.

See also

visitors.iterate() - includes a general overview of iteration.

sqlalchemy.sql.visitors.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() or visitors.traverse_depthfirst() functions.

Parameters:	iterator¶ – an iterable or sequence which will yield ClauseElement structures; the iterator is assumed to be the product of the visitors.iterate() or visitors.iterate_depthfirst() functions. obj¶ – the ClauseElement that was used as the target of the iterate() or iterate_depthfirst() function. visitors¶ – dictionary of visit functions. See traverse() for details on this dictionary.

See also

traverse()

traverse_depthfirst()

sqlalchemy.sql.visitors.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¶ – ClauseElement structure to be traversed opts¶ – dictionary of iteration options. This dictionary is usually empty in modern usage. visitors¶ – dictionary 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.

sqlalchemy.sql.visitors.traverse_depthfirst(obj, opts, visitors)¶

traverse and visit the given expression structure using the depth-first iterator.

The iteration of objects uses the visitors.iterate_depthfirst() function, which does a depth-first traversal using a stack.

Usage is the same as that of visitors.traverse() function.

sqlalchemy.sql.visitors.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 ClauseElement.get_children() function that is used to achieve the iteration, is the ClauseElement._copy_internals() method. For a 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()

sqlalchemy.sql.visitors.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.