访问者和遍历实用程序¶

这个 sqlalchemy.sql.visitors 模块由类和函数组成，它们通常用于 穿越 核心SQL表达式结构。不像 Python ast 其中的模块提供了一个系统，通过该系统，程序可以对SQL表达式的每个组件进行操作。它的共同目的是定位各种元素，例如 Table 或 BindParameter 对象，以及改变结构的状态，例如用其他子句替换某些FROM子句。

这个 sqlalchemy.sql.visitors 模块是 内构件 通常不被应用程序调用。但是，它在某些边缘情况下使用，例如在构造缓存例程时，以及在使用 Custom SQL Constructs and Compilation Extension .

访问者/遍历接口和库函数。

SQLAlchemy模式和表达式构造依赖于以Python为中心的经典“访问者”模式的版本，作为它们应用功能的主要方式。此模式最常见的用法是语句编译，其中单个表达式类与生成字符串结果的呈现方法相匹配。除此之外，访问者系统还用于检查表达式的各种信息和模式，以及对表达式应用转换的目的。

访问系统如何使用的示例可以在例如 sqlalchemy.sql.util 以及 sqlalchemy.sql.compiler 模块。有关子句改编的一些背景知识也请参见https://techspot.zzzeek.org/2008/01/23/expression-transformations/。

class sqlalchemy.sql.visitors.ExternalTraversal¶

访问器对象的基类，它可以使用 traverse() 功能。

直接使用 traverse() 通常优先考虑功能。

method sqlalchemy.sql.visitors.ExternalTraversal.chain(visitor)¶

将一个附加的子句查看器“链”到这个子句查看器上。

在此之后，连锁访客将收到所有访问事件。

method sqlalchemy.sql.visitors.ExternalTraversal.iterate(obj)¶

遍历给定的表达式结构，返回所有元素的迭代器。

method sqlalchemy.sql.visitors.ExternalTraversal.traverse(obj)¶

遍历并访问给定的表达式结构。

attribute sqlalchemy.sql.visitors.ExternalTraversal.visitor_iterator¶

迭代访问此访问者和每个“链接”访问者。

class sqlalchemy.sql.visitors.InternalTraversal¶

定义用于内部遍历的访问者符号。

这个 InternalTraversal 类有两种使用方式。其一是它可以充当实现类的各种访问方法的对象的超类。另一种是这些符号本身 InternalTraversal 都在 _traverse_internals 收藏。例如， Case 对象定义 _traverse_internals AS：：

_traverse_internals = [
    ("value", InternalTraversal.dp_clauseelement),
    ("whens", InternalTraversal.dp_clauseelement_tuples),
    ("else_", InternalTraversal.dp_clauseelement),
]

上面， Case 类将其内部状态指示为 value ， whens 和 else_ . 它们都与 InternalTraversal 方法，指示引用的数据结构类型。

使用 _traverse_internals 结构，对象类型 InternalTraversible 将自动实现以下方法：

• Traversible.get_children()

• Traversible._copy_internals()

• Traversible._gen_cache_key()

子类也可以直接实现这些方法，特别是对于 Traversible._copy_internals() 方法，当需要特殊步骤时。

1.4 新版功能.

method sqlalchemy.sql.visitors.InternalTraversal.dispatch(visit_symbol)¶

从给定的方法 InternalTraversal ，返回子类的相应方法。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_annotations_key = symbol('AK')¶

访问u annotations_cache_key元素。

这是一个字典，包含有关修改其角色的ClauseElement的附加信息。在比较或缓存对象时应该包含它，但是生成这个键相对来说比较昂贵。在创建这个密钥之前，访问者应该先检查“unu annotations”dict是否为None None。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_anon_name = symbol('AN')¶

访问潜在的“匿名”字符串值。

字符串值被认为对缓存密钥生成非常重要。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_boolean = symbol('B')¶

访问布尔值。

布尔值被认为对缓存密钥生成非常重要。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement = symbol('CE')¶

访问a ClauseElement 对象。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement_list = symbol('CL')¶

访问列表 ClauseElement 物体。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement_tuple = symbol('CT')¶

访问一组 ClauseElement 物体。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_clauseelement_tuples = symbol('CTS')¶

访问包含 ClauseElement 物体。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dialect_options = symbol('DO')¶

访问方言选项结构。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dml_multi_values = symbol('DML_MV')¶

访问的字典的values（）多值列表 Insert 对象。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dml_ordered_values = symbol('DML_OV')¶

访问 Update 对象。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_dml_values = symbol('DML_V')¶

访问 ValuesBase （例如插入或更新）对象。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_fromclause_canonical_column_collection = symbol('FC')¶

访问a FromClause 对象的上下文中 columns 属性。

列集合是“canonical”，这意味着它是 ColumnClause 物体。现在这意味着被访问的对象是 TableClause 或 Table 仅对象。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_fromclause_ordered_set = symbol('CO')¶

参观订购的 FromClause 物体。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_has_cache_key = symbol('HC')¶

访问a HasCacheKey 对象。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_has_cache_key_list = symbol('HL')¶

访问列表 HasCacheKey 物体。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_named_ddl_element = symbol('DD')¶

访问一个简单的命名DDL元素。

此方法使用的当前对象是 Sequence .

该对象只被认为是重要的缓存密钥生成只要它的名称，而不是它的任何其他方面。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_operator = symbol('O')¶

拜访接线员。

运算符是来自 sqlalchemy.sql.operators 模块。

运算符值被认为对缓存密钥生成非常重要。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_plain_dict = symbol('PD')¶

使用字符串键访问字典。

字典的键应该是字符串，值应该是不可变的和散列的。字典被认为是重要的缓存密钥生成。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_plain_obj = symbol('PO')¶

访问一个纯python对象。

该值应该是不可变的和散列的，例如整数。该值被认为对缓存密钥生成非常重要。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_prefix_sequence = symbol('PS')¶

访问代表的序列 HasPrefixes 或 HasSuffixes .

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_propagate_attrs = symbol('PA')¶

请访问宣传性的ATTRS判决书。这将硬编码到我们现在关心的特定元素。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_statement_hint_list = symbol('SH')¶

参观 _statement_hints A的集合 Select 对象。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_string = symbol('S')¶

访问纯字符串值。

示例包括表名和列名、绑定参数键、特殊关键字，如“UNION”、“UNION ALL”。

字符串值被认为对缓存密钥生成非常重要。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_string_clauseelement_dict = symbol('CD')¶

访问字符串键字典 ClauseElement 物体。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_string_list = symbol('SL')¶

访问字符串列表。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_string_multi_dict = symbol('MD')¶

访问字符串键的字典，这些值可以是普通的不可变/散列的，或者 HasCacheKey 物体。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_table_hint_list = symbol('TH')¶

参观 _hints A的集合 Select 对象。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_type = symbol('T')¶

访问a TypeEngine 对象

类型对象被认为对缓存密钥生成非常重要。

attribute sqlalchemy.sql.visitors.InternalTraversal.dp_unknown_structure = symbol('UK')¶

访问未知结构。

class sqlalchemy.sql.visitors.Traversible¶

可访问对象的基类，应用 TraversibleType 元类。

method sqlalchemy.sql.visitors.Traversible.get_children(omit_attrs=(), **kw)¶

返回直接子对象 Traversible 这其中的要素 Traversible 。

这用于访问遍历。

**kw可能包含更改返回的集合的标志，例如，返回项的子集以减少更大的遍历，或者从不同的上下文返回子项(例如模式级集合而不是子句级集合)。

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

元类，它为各种“可访问”类分配分派属性。

属性包括：

• 这个 _compiler_dispatch 方法，对应于 __visit_name__ . 这称为“外部遍历”，因为每个visit（）方法的调用方负责子遍历每个对象的内部元素。这适用于字符串编译器和其他需要调用特定模式中的内部元素的遍历。

• 内部遍历集合 _children_traversal ， _cache_key_traversal ， _copy_internals_traversal ，从可选 _traverse_internals 源于 InternalTraversal 符号列表。这就是所谓的“内部遍历”标记

类签名

class sqlalchemy.sql.visitors.TraversibleType (builtins.type)

function sqlalchemy.sql.visitors.cloned_traverse(obj, opts, visitors)¶

克隆给定的表达式结构，允许访问者进行修改。

遍历用法与的相同 traverse() . 访问者的功能存在于 visitors dictionary还可以在遍历过程中修改给定结构的内部结构。

使用的中央API功能 cloned_traverse() 和 replacement_traverse() 除了 ClauseElement.get_children() 用于实现迭代的函数是 ClauseElement._copy_internals() 方法。为了 ClauseElement 结构以正确地支持克隆和替换遍历，它需要能够将克隆函数传递到其内部成员中，以便复制它们。

参见

traverse()

replacement_traverse()

function sqlalchemy.sql.visitors.iterate(obj, opts={})¶

遍历给定的表达式结构，返回迭代器。

遍历配置为宽度优先。

使用的中央API功能 iterate() 功能就是 ClauseElement.get_children() 方法 ClauseElement 物体。此方法应返回所有 ClauseElement 与特定的 ClauseElement 对象。例如，A Case 结构将引用一系列 ColumnElement 对象在其“whens”和“else\”成员变量中。

参数

• obj¶ -- ClauseElement 要遍历的结构

• opts¶ -- 迭代选项字典。这本词典在现代用法中通常是空的。

function sqlalchemy.sql.visitors.replacement_traverse(obj, opts, replace)¶

克隆给定的表达式结构，允许用给定的替换函数替换元素。

此函数与 cloned_traverse() 函数，除了不传递访问者字典之外，所有元素都无条件地传递到给定的replace函数中。replace函数可以选择返回一个全新的对象来替换给定的对象。如果它回来了 None ，则对象保持在原位。

在用法上的区别 cloned_traverse() 和 replacement_traverse() 在前一种情况下，一个已经克隆的对象被传递给visitor函数，然后visitor函数可以操作对象的内部状态。对于后者，visitor函数应该只返回一个完全不同的对象，或者什么都不做。

的用例 replacement_traverse() 是用不同的语句替换SQL结构中的FROM子句，这是ORM中的一个常见用例。

function sqlalchemy.sql.visitors.traverse(obj, opts, visitors)¶

使用默认迭代器遍历和访问给定的表达式结构。

例如。：：

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})

对象的迭代使用 iterate() 函数，它使用堆栈执行宽度优先遍历。

参数

• obj¶ -- ClauseElement 要遍历的结构

• opts¶ -- 迭代选项字典。这本词典在现代用法中通常是空的。

• visitors¶ -- 访问函数词典。字典应该有字符串作为键，每个字符串都对应于 __visit_name__ 作为一个特殊的对象，它代表了一个特殊的函数类型。

function sqlalchemy.sql.visitors.traverse_using(iterator, obj, visitors)¶

使用给定的对象迭代器访问给定的表达式结构。

traverse_using() 通常在内部调用，因为 traverse() 功能。

参数

• iterator¶ -- 一种可以产生的结果或序列 ClauseElement 结构；迭代器假定为 iterate() 功能。

• obj¶ -- 这个 ClauseElement 被用作目标 iterate() 功能。

• visitors¶ -- 访问函数词典。看到了吗 traverse() 关于这本字典的细节。

参见

traverse()