SQLAlchemy 1.3 Documentation
SQLAlchemy Core
- SQL Expression Language Tutorial
- SQL Statements and Expressions API
- Column Elements and Expressions
- Selectables, Tables, FROM objects
- Insert, Updates, Deletes
- SQL and Generic Functions
- Custom SQL Constructs and Compilation Extension
- Expression Serializer Extension
- Visitor and Traversal Utilities¶
- Schema Definition Language
- Column and Data Types
- Engine and Connection Use
- Core API Basics
Project Versions
- Previous: Expression Serializer Extension
- Next: Schema Definition Language
- Up: Home
- On this page:
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.
Note
the sqlalchemy.sql.visitors
module is an internal API and
is not fully public. It is subject to change and may additionally not
function as expected for use patterns that aren’t considered within
SQLAlchemy’s own internals.
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/ .
Object Name | Description |
---|---|
Base class for visitor objects which can traverse using
the |
|
cloned_traverse(obj, opts, visitors) |
Clone the given expression structure, allowing modifications by visitors. |
Base class for visitor objects which can traverse using
the |
|
iterate(obj, opts) |
Traverse the given expression structure, returning an iterator. |
iterate_depthfirst(obj, opts) |
Traverse the given expression structure, returning an iterator. |
replacement_traverse(obj, opts, replace) |
Clone the given expression structure, allowing element replacement by a given replacement function. |
Base class for visitor objects which can traverse using
the |
|
traverse(obj, opts, visitors) |
Traverse and visit the given expression structure using the default iterator. |
traverse_depthfirst(obj, opts, visitors) |
traverse and visit the given expression structure using the depth-first iterator. |
traverse_using(iterator, obj, visitors) |
Visit the given expression structure using the given iterator of objects. |
Base class for visitable objects, applies the
|
|
Metaclass which assigns a |
- class sqlalchemy.sql.visitors.ClauseVisitor¶
Base class for visitor objects which can traverse using the
traverse()
function.Members
Direct usage of the
traverse()
function is usually preferred.-
method
sqlalchemy.sql.visitors.ClauseVisitor.
chain(visitor)¶ ‘Chain’ an additional ClauseVisitor onto this ClauseVisitor.
The chained visitor will receive all visit events after this one.
-
method
sqlalchemy.sql.visitors.ClauseVisitor.
iterate(obj)¶ Traverse the given expression structure, returning an iterator of all elements.
-
method
sqlalchemy.sql.visitors.ClauseVisitor.
traverse(obj)¶ Traverse and visit the given expression structure.
-
attribute
sqlalchemy.sql.visitors.ClauseVisitor.
visitor_iterator¶ Iterate through this visitor and each ‘chained’ visitor.
-
method
- class sqlalchemy.sql.visitors.CloningVisitor¶
Base class for visitor objects which can traverse using the
cloned_traverse()
function.Direct usage of the
cloned_traverse()
function is usually preferred.Members
Class signature
class
sqlalchemy.sql.visitors.CloningVisitor
(sqlalchemy.sql.visitors.ClauseVisitor
)-
method
sqlalchemy.sql.visitors.CloningVisitor.
copy_and_process(list_)¶ Apply cloned traversal to the given list of elements, and return the new list.
-
method
sqlalchemy.sql.visitors.CloningVisitor.
traverse(obj)¶ Traverse and visit the given expression structure.
-
method
- class sqlalchemy.sql.visitors.ReplacingCloningVisitor¶
Base class for visitor objects which can traverse using the
replacement_traverse()
function.Direct usage of the
replacement_traverse()
function is usually preferred.Members
Class signature
class
sqlalchemy.sql.visitors.ReplacingCloningVisitor
(sqlalchemy.sql.visitors.CloningVisitor
)-
method
sqlalchemy.sql.visitors.ReplacingCloningVisitor.
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.
-
method
sqlalchemy.sql.visitors.ReplacingCloningVisitor.
traverse(obj)¶ Traverse and visit the given expression structure.
-
method
- class sqlalchemy.sql.visitors.Visitable¶
Base class for visitable objects, applies the
VisitableType
metaclass.The
Visitable
class is essentially at the base of theClauseElement
hierarchy.
- class sqlalchemy.sql.visitors.VisitableType(clsname, bases, clsdict)¶
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 signature
class
sqlalchemy.sql.visitors.VisitableType
(builtins.type
)
- 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
traverse()
. The visitor functions present in thevisitors
dictionary may also modify the internals of the given structure as the traversal proceeds.The central API feature used by the
cloned_traverse()
andreplacement_traverse()
functions, in addition to theClauseElement.get_children()
function that is used to achieve the iteration, is theClauseElement._copy_internals()
method. For aClauseElement
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.
- function 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
iterate()
anditerate_depthfirst()
functions is theClauseElement.get_children()
method ofClauseElement
objects. This method should return all theClauseElement
objects which are associated with a particularClauseElement
object. For example, aCase
structure will refer to a series ofColumnElement
objects within its “whens” and “else_” member variables.- Parameters:
obj¶ –
ClauseElement
structure to be traversedopts¶ – dictionary of iteration options. This dictionary is usually empty in modern usage.
- function 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 traversedopts¶ – dictionary of iteration options. This dictionary is usually empty in modern usage.
See also
iterate()
- includes a general overview of iteration.
- function 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
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 returnsNone
, then the object is kept in place.The difference in usage between
cloned_traverse()
andreplacement_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
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.
- function 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
iterate()
function, which does a breadth-first traversal using a stack.- Parameters:
obj¶ –
ClauseElement
structure to be traversedopts¶ – 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.
- function 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
iterate_depthfirst()
function, which does a depth-first traversal using a stack.Usage is the same as that of
traverse()
function.
- function sqlalchemy.sql.visitors.traverse_using(iterator, obj, visitors)¶
Visit the given expression structure using the given iterator of objects.
traverse_using()
is usually called internally as the result of thetraverse()
ortraverse_depthfirst()
functions.- Parameters:
iterator¶ – an iterable or sequence which will yield
ClauseElement
structures; the iterator is assumed to be the product of theiterate()
oriterate_depthfirst()
functions.obj¶ – the
ClauseElement
that was used as the target of theiterate()
oriterate_depthfirst()
function.visitors¶ – dictionary of visit functions. See
traverse()
for details on this dictionary.
flambé! the dragon and The Alchemist image designs created and generously donated by Rotem Yaari.
Created using Sphinx 7.2.6. Documentation last generated: Sat 06 Jan 2024 12:16:05 PM