e7 d Z ddlmZ ddlZddlmZ ddlmZ g dZ G d d e Z d
Z
G d d ej e e Z
G d
de Z G d de Z G d de Zd Zd Zd Zd Zd Zd Zd ZdS )a@ 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/ .
)dequeN )exc)util)
VisitableType Visitable
ClauseVisitorCloningVisitorReplacingCloningVisitoriterateiterate_depthfirsttraverse_usingtraversetraverse_depthfirstcloned_traversereplacement_traversec " e Zd ZdZ fdZ xZS )r ar 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.
c |dk r t | d rt | t t | ||| d S )Nr __visit_name__)hasattr_generate_dispatchsuperr __init__)clsclsnamebasesclsdict __class__s k/builddir/build/BUILD/cloudlinux-venv-1.0.10/venv/lib64/python3.11/site-packages/sqlalchemy/sql/visitors.pyr zVisitableType.__init__B sT k ! !gc3C&D&D ! s # # #
mS!!**7E7CCCCC )__name__
__module__ __qualname____doc__r
__classcell__)r s @r r r 1 sK D D D D D D D D Dr r c d j v rY j }t |t j j r t
j d|z fd}n fd}d|_ | _ dS dS )zZReturn an optimized visit dispatch function for the cls
for use by the compiler.
r visit_%sc | } || fi |S # t $ r4}t j t j | | Y d }~d S d }~ww xY w)Nreplace_context)AttributeErrorr raise_r UnsupportedCompilationError)selfvisitorkwmetherrr getters r _compiler_dispatchz._generate_dispatch.._compiler_dispatchW s ,!6'??D 4+++++
& K7EE(+ s
A)AAc d| j z } t || } || fi |S # t $ r4}t j t j | | Y d }~d S d }~ww xY w)Nr' r) )r getattrr+ r r, r r- )r. r/ r0
visit_attrr1 r2 r s r r4 z._generate_dispatch.._compiler_dispatchf s '$*= =
,"7J77D 4+++++
& K7EE(+ s &
A$)A A$zLook for an attribute named "visit_" + self.__visit_name__
on the visitor, and call it with the same kw params.
N)
__dict__r
isinstancer compat string_typesoperator
attrgetterr$ r4 )r
visit_namer4 r3 s ` @r r r I s
3<'''
j$+": ; ; , (j)@AAF
,
,
,
,
,
,
,
,
,
,
,
,&" "4 O ('r c e Zd ZdZdS )r zBase class for visitable objects, applies the
:class:`.visitors.VisitableType` metaclass.
The :class:`.Visitable` class is essentially at the base of the
:class:`_expression.ClauseElement` hierarchy.
N)r! r" r# r$ r r r r x s r r c d e Zd ZdZi Zd Zd Zd Zej d Z
e d Z d Z
dS ) r zBase class for visitor objects which can traverse using
the :func:`.visitors.traverse` function.
Direct usage of the :func:`.visitors.traverse` function is usually
preferred.
c f | j D ](}t |d|j z d }|r ||fi |c S )d S )Nr' )visitor_iteratorr6 r )r. objr0 vr1 s r traverse_singlez ClauseVisitor.traverse_single s^ & ' 'A1j3+= =tDDD
'tC2&&&
' ' 'r c , t || j S )zaTraverse the given expression structure, returning an iterator
of all elements.
)r __traverse_options__r. rD s r r zClauseVisitor.iterate s
sD 5666r c 8 t || j | j S 2Traverse and visit the given expression structure.)r rH
_visitor_dictrI s r r zClauseVisitor.traverse s T 68JKKKr c i }t | D ]2}| d rt | | ||dd < 3|S )Nvisit_ )dir
startswithr6 )r. visitorsnames r rM zClauseVisitor._visitor_dict sR II 9 9Dx((
9%,T4%8%8abb"r c # D K | }|r|V t |dd }|dS dS )z8Iterate through this visitor and each 'chained' visitor._nextN)r6 )r. rE s r rC z ClauseVisitor.visitor_iterator sM
*GGG7D))A * * * * *r c H t | j d }||_ | S )z'Chain' an additional ClauseVisitor onto this ClauseVisitor.
The chained visitor will receive all visit events after this one.
)listrC rV )r. r/ tails r chainzClauseVisitor.chain s% D)**2.
r N)r! r" r# r$ rH rF r r r memoized_propertyrM propertyrC r[ r@ r r r r s ' ' ' 7 7 7L L L
* * X* r r c e Zd ZdZd Zd ZdS )r
zBase class for visitor objects which can traverse using
the :func:`.visitors.cloned_traverse` function.
Direct usage of the :func:`.visitors.cloned_traverse` function is usually
preferred.
c fd|D S )z`Apply cloned traversal to the given list of elements, and return
the new list.
c : g | ]} | S r@ )r ).0xr. s r
z3CloningVisitor.copy_and_process.. s% 000Q
a 000r r@ )r. list_s ` r copy_and_processz CloningVisitor.copy_and_process s
1000%0000r c 8 t || j | j S rK )r rH rM rI s r r zCloningVisitor.traverse s# *D,>
r N)r! r" r# r$ re r r@ r r r
r
s< 1 1 1
r r
c e Zd ZdZd Zd ZdS )r zBase class for visitor objects which can traverse using
the :func:`.visitors.replacement_traverse` function.
Direct usage of the :func:`.visitors.replacement_traverse` function is
usually preferred.
c dS )a 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.
Nr@ )r. elems r replacez ReplacingCloningVisitor.replace s tr c : fd}t | j | S )rL c R j D ] }| | }||c S d S )N)rC rj )ri rE er. s r rj z1ReplacingCloningVisitor.traverse..replace sA *
IIdOO= HHH !
r )r rH )r. rD rj s ` r r z ReplacingCloningVisitor.traverse s3 $C)BGLLLr N)r! r" r# r$ rj r r@ r r r r sA M M M M Mr r c $ | j di |}|s| gS t }t | g }|rP| }| | |j di |D ]}| | |Pt | S )ar Traverse the given expression structure, returning an iterator.
Traversal is configured to be breadth-first.
The central API feature used by the :func:`.visitors.iterate` and
:func:`.visitors.iterate_depthfirst` functions is the
:meth:`_expression.ClauseElement.get_children` method of
:class:`_expression.ClauseElement` objects. This method should return all
the :class:`_expression.ClauseElement` objects which are associated with a
particular :class:`_expression.ClauseElement` object. For example, a
:class:`.Case` structure will refer to a series of
:class:`_expression.ColumnElement` objects within its "whens" and "else\_"
member variables.
:param obj: :class:`_expression.ClauseElement` structure to be traversed
:param opts: dictionary of iteration options. This dictionary is usually
empty in modern usage.
r@ ) get_childrenr popleftappenditer)rD optschildren traversalstacktcs r r r s , s ''$''H u I 3%LLE
MMOO ''$'' A LLOOOO
??r c $ | j di |}|s| gS t | g }t }|rP| }| | |j di |D ]}| | |Pt | S )a Traverse the given expression structure, returning an iterator.
Traversal is configured to be depth-first.
:param obj: :class:`_expression.ClauseElement` structure to be traversed
:param opts: dictionary of iteration options. This dictionary is usually
empty in modern usage.
.. seealso::
:func:`.visitors.iterate` - includes a general overview of iteration.
r@ )ro r pop
appendleftrq rr )rD rs rt rv ru rw rx s r r
r
s s ''$''H u 3%LLEI
IIKK Q ''$'' A LLOOOO
??r c ` | D ]*}| |j d }|r || +|S )ae Visit the given expression structure using the given iterator of
objects.
:func:`.visitors.traverse_using` is usually called internally as the result
of the :func:`.visitors.traverse` or :func:`.visitors.traverse_depthfirst`
functions.
:param iterator: an iterable or sequence which will yield
:class:`_expression.ClauseElement`
structures; the iterator is assumed to be the
product of the :func:`.visitors.iterate` or
:func:`.visitors.iterate_depthfirst` functions.
:param obj: the :class:`_expression.ClauseElement`
that was used as the target of the
:func:`.iterate` or :func:`.iterate_depthfirst` function.
:param visitors: dictionary of visit functions. See :func:`.traverse`
for details on this dictionary.
.. seealso::
:func:`.traverse`
:func:`.traverse_depthfirst`
N)getr )iteratorrD rS targetr1 s r r r 5 sD 8 ||F 1488 DLLL Jr c @ t t | | | | S )a 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 :func:`.visitors.iterate` function,
which does a breadth-first traversal using a stack.
:param obj: :class:`_expression.ClauseElement` structure to be traversed
:param opts: dictionary of iteration options. This dictionary is usually
empty in modern usage.
:param 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.
)r r rD rs rS s r r r X s < '#t,,c8 < <.clone s 7??K$xxv%%-1[[]]:r$xx 7''::e:r::: ||G$:DAA "DMMM"T((# #r N)setr} )rD rs rS r r r s `@@@r r r sn 6 F$((9b))**G
$
$
$
$
$
$
$
$ eCjj E Jr c | i d | dg D fd| | fi |} d| S )a] Clone the given expression structure, allowing element
replacement by a given replacement function.
This function is very similar to the :func:`.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 :func:`.visitors.cloned_traverse` and
:func:`.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 :func:`.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.
c , h | ]}t | S r@ )r )ra rb s r z'replacement_traverse.. s 666r!uu666r r c t | v s d| j v r| S | }|$ t | |S | vr(| x| < } |j ddi| | S )Nno_replacement_traverser r@ )r _annotationsaddr r )ri r0 r r r rj r s r r z#replacement_traverse..clone s tHH (D,===K gdmmG" BwKK((( v%%-1[[]]:F4L7+G+>>%>2>>> d|#r N)r} )rD rs rj r r r s `@@@r r r s~ 0 F66dhhy" 5 5666G$ $ $ $ $ $ $ $" eC 4 E Jr )r$ collectionsr r< r r __all__typer r with_metaclassobjectr r r
r r r
r r r r r r@ r r r s $
D D D D DD D D D0,4 ,4 ,4^ ##M6:: 7 7 7 7 7F 7 7 7t
]
2M M M M Mn M M M