访客和遍历工具¶

sqlalchemy.sql.visitors 模块由类和函数组成，这些类和函数通常用于遍历 Core SQL 表达式结构。这与 Python ast 模块没有什么不同，因为它提供了一个系统，程序可以通过该系统对 SQL 表达式的每个组件进行作。它的常见用途是查找各种元素（如 Table 或 BindParameter 对象），以及更改结构的状态（如将某些 FROM 子句替换为其他子句）。

注意

sqlalchemy.sql.visitors 模块是内部 API，并非完全公开。它可能会发生变化，并且对于 SQLAlchemy 自己的内部结构中未考虑的使用模式，它可能无法按预期运行。

sqlalchemy.sql.visitors 模块是 SQLAlchemy 的 API，它通常不通过调用应用程序代码来使用。是的但是，在某些边缘情况下使用，例如在构造缓存例程时以及使用自定义 SQL 构造和编译扩展。

访客/遍历界面和库函数。

对象名称	描述
anon_map	`cache_anon_map` 的别名
cloned_traverse（对象、选项、访客）	克隆给定的表达式结构，允许访问者对可变对象进行修改。
外部遍历	访客对象的基类，这些对象可以使用 `traverse（）` 函数在外部遍历。
InternalTraversal 内部遍历	定义用于内部遍历的访客符号。
iterate（obj[， opts]）	遍历给定的表达式结构，返回一个迭代器。
replacement_traverse（obj， opts， replace）	克隆给定的表达式结构，允许用给定的替换函数替换元素。
traverse（对象、选项、访客）	使用默认迭代器遍历并访问给定的表达式结构。
traverse_using（iterator， obj， visitors）	使用给定的对象迭代器访问给定的表达式结构。
可参观	可访问对象的基类。

类 sqlalchemy.sql.visitors。ExternalTraversal（外部遍历）¶

访客对象的基类，这些对象可以使用 traverse（） 函数在外部遍历。

通常最好直接使用 traverse（） 函数。

成员

chain（）、iterate（）、traverse（） visitor_iterator

类签名

类 sqlalchemy.sql.visitors.ExternalTraversal （ sqlalchemy.util.langhelpers.MemoizedSlots ）

method sqlalchemy.sql.visitors.ExternalTraversal. chain（visitor： ExternalTraversal）→ _ExtT¶

将额外的 ExternalTraversal 'Chain' 到这个 ExternalTraversal 上

链式访客将收到此事件之后的所有访问事件。

method sqlalchemy.sql.visitors.ExternalTraversal. iterate（obj：ExternallyTraversibleNone）→ Iterator[ExternallyTraversible]¶: 遍历给定的表达式结构，返回所有元素的迭代器。

method sqlalchemy.sql.visitors.ExternalTraversal. traverse（obj：ExternallyTraversibleNone）→ExternallyTraversibleNone）¶: 遍历并访问给定的表达式结构。

属性 sqlalchemy.sql.visitors.ExternalTraversal. visitor_iterator¶: 遍历此访客和每个“链式”访客。

类 sqlalchemy.sql.visitors。InternalTraversal¶

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

InternalTraversal 类有两种使用方式。一个是它可以作为实现类的各种访问方法的对象的超类。另一个是 InternalTraversal 的 symbol 本身在 _traverse_internals 集合中使用。例如，案例 object 将_traverse_internals定义为

class Case(ColumnElement[_T]):
    _traverse_internals = [
        ("value", InternalTraversal.dp_clauseelement),
        ("whens", InternalTraversal.dp_clauseelement_tuples),
        ("else_", InternalTraversal.dp_clauseelement),
    ]

在上面，Case 类将其内部状态指示为名为 value、when's 和 else_ 的属性。它们都链接到一个 InternalTraversal 方法，该方法指示每个属性所引用的数据结构类型。

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

HasTraverseInternals.get_children()
HasTraverseInternals._copy_internals()
HasCacheKey._gen_cache_key（）

子类也可以直接实现这些方法，特别是对于 HasTraverseInternals._copy_internals() 方法。

在 1.4 版本加入.

类签名

class sqlalchemy.sql.visitors.InternalTraversal （enum.枚举）

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_annotations_key = 'AK'¶

访问 _annotations_cache_key 元素。

这是有关修改其角色的 ClauseElement 的其他信息的字典。在比较或缓存对象时应包含它，但是生成此密钥的成本相对较高。在创建此键之前，访问者应先检查 “_annotations” dict 中的非 None。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_anon_name = 'AN'¶

访问可能 “匿名” 的字符串值。

字符串值被认为对于缓存键生成很重要。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_boolean = 'B'¶

访问布尔值。

布尔值被认为对于缓存键的生成很重要。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_clauseelement = 'CE'¶: 访问 ClauseElement 对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_clauseelement_list = 'CL'¶: 访问 ClauseElement 对象的列表。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_clauseelement_tuple = 'CT'¶: 访问 ClauseElement 对象的元组。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_clauseelement_tuples = 'CTS'¶: 访问包含 ClauseElement 的元组列表对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_dialect_options = 'DO'¶: 访问 dialect 选项结构。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_dml_multi_values = 'DML_MV'¶: 访问 values（）的多值字典列表 Insert 对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_dml_ordered_values = 'DML_OV'¶: 访问 values（）的有序元组列表 Update 对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_dml_values = 'DML_V'¶: 访问 ValuesBase 的 values（）字典（例如 Insert 或 Update）对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_fromclause_canonical_column_collection = 'FC'¶

在 columns 属性。

列集合是“规范的”，这意味着它是 ColumnClause 对象最初定义的位置。马上这意味着正在访问的对象是一个 TableClause 或 Table 对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_fromclause_ordered_set = 'CO'¶: 访问一组有序的 FromClause 对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_has_cache_key = 'HC'¶: 访问 HasCacheKey 对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_has_cache_key_list = 'HL'¶: 访问 HasCacheKey 对象的列表。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_has_cache_key_tuples = 'HT'¶: 访问包含 HasCacheKey 的元组列表对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_ignore = 'IG'¶

指定应完全忽略的对象。

这当前应用函数调用参数缓存，其中某些参数不应被视为缓存键的一部分。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_inspectable = 'IS'¶: 访问返回值为 HasCacheKey 对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_inspectable_list = 'IL'¶: 访问可检查对象列表，这些对象在检查时是 HasCacheKey 对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_multi = 'M'¶: 访问可能是 HasCacheKey 或普通可哈希对象的对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_multi_list = 'MT'¶: 访问包含元素的 Tuples，这些元素可能是 HasCacheKey 也可能是普通的可哈希对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_named_ddl_element = 'DD'¶

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

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

就其名称而言，该对象仅被认为对缓存键生成很重要，而对其任何其他方面都不重要。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_operator = 'O'¶

访问运营商。

运算符是 sqlalchemy.sql.operators 中的函数模块。

运算符值被认为对于缓存键生成很重要。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_plain_dict = 'PD'¶

访问带有字符串键的字典。

字典的键应该是字符串，值应该是不可变的和可哈希的。该字典被认为对缓存键生成很重要。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_plain_obj = 'PO'¶

访问普通 python 对象。

该值应该是不可变且可哈希的，例如整数。该值被认为对于缓存密钥生成很重要。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_prefix_sequence = 'PS'¶: 访问 HasPrefixes 表示的序列或 HasSuffixes 的 HasSuffixes 中。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_propagate_attrs = 'PA'¶: 访问 propagate attrs dict。这与我们现在关心的特定元素进行了硬编码。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_statement_hint_list = 'SH'¶: 访问 _statement_hints 的集合 选择 对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_string = 'S'¶

访问纯字符串值。

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

字符串值被认为对于缓存键生成很重要。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_string_clauseelement_dict = 'CD'¶: 访问 ClauseElement 的字符串键字典对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_string_list = 'SL'¶: 访问字符串列表。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_string_multi_dict = 'MD'¶: 访问字符串键的字典，这些值可能是普通的不可变/可哈希的，也可能是 HasCacheKey 对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_table_hint_list = 'TH'¶: 访问 Select 的 _hints 集合对象。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_type = 'T'¶

访问 TypeEngine 对象

类型对象被认为对缓存键生成很重要。

属性 sqlalchemy.sql.visitors.InternalTraversal. dp_unknown_structure = 'UK'¶: 访问未知结构。

类 sqlalchemy.sql.visitors。可访问¶

可访问对象的基类。

Visitable 用于实现 SQL 编译器调度函数。其他形式的遍历（例如用于缓存键生成）使用 HasTraverseInternals 单独实现接口。

在 2.0 版更改：已将 Visitable 类命名为在 1.4 系列中可穿越;在 2.0 中，该名称将更改回 Visitable，这是 1.4 之前的版本。

这两个名称在 1.4 和 2.0 版本中都可导入。

属性 sqlalchemy.sql.visitors..sqlalchemy.sql.visitors 访问。anon_map¶: cache_anon_map 的别名

函数 sqlalchemy.sql.visitors。cloned_traverse（obj：ExternallyTraversibleNone， opts： Mapping[str， Any]， 访客： Mapping[str， Callable[[Any]， None]]）→ExternallyTraversibleNone¶

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

遍历用法与 traverse（） 相同。随着遍历的进行，Visitors 字典中存在的 visitor 函数也可以修改给定结构的内部结构。

cloned_traverse（） 函数不提供属于 immutable 接口的对象给访问方法（这主要包括 ColumnClause、Column、 TableClause 和 Table 对象）。由于此遍历仅用于允许对象的就地更改，因此 Immutable 将跳过对象。Immutable._clone（） 方法仍被调用以允许对象将自身替换为不同的对象（例如，一个 ColumnClause 的 ColumnClause 中，克隆其子查询以返回新的 ColumnClause 的 ColumnClause 中）。

在 2.0 版更改： cloned_traverse（） 函数省略了属于 Immutable 接口的对象。

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

另请参阅

遍历（）

replacement_traverse（）

函数 sqlalchemy.sql.visitors。iterate（obj：ExternallyTraversibleNone， opts： Mapping[str， Any] = {}）→ Iterator[ExternallyTraversible]¶

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

遍历配置为广度优先。

iterate（） 使用的核心 API 功能 function 是 ClauseElement.get_children（） 方法 ClauseElement 对象。此方法应返回与特定 ClauseElement 对象关联的所有 ClauseElement 对象。例如， 案例结构将参考一系列 ColumnElement 对象else_。

参数

obj¶– 要遍历的 ClauseElement 结构
opts¶ —— 迭代选项字典。在现代用法中，此字典通常是空的。

函数 sqlalchemy.sql.visitors。replacement_traverse（obj：ExternallyTraversibleNone， opts： Mapping[str， Any]， replace： _TraverseTransformCallableType[Any]）→ExternallyTraversibleNone¶

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

此函数与 cloned_traverse（） 非常相似函数，而不是传递访问者字典，而是 all 元素无条件地传递到给定的 replace 函数中。然后，replace 函数可以选择返回一个全新的对象它将替换给定的那个。如果返回 None，则对象将保留在原位。

cloned_traverse（） 和 replacement_traverse（） 是指在前一种情况下，已经克隆的对象被传递给 visitor 函数，然后 visitor 函数可以作对象的内部状态。在后者的情况下，visitor 函数应该只返回一个完全不同的对象，或者什么都不做。

replacement_traverse（） 的用例是将 SQL 结构内的 FROM 子句替换为不同的子句，这是 ORM 中的常见用例。

函数 sqlalchemy.sql.visitors。traverse（obj：ExternallyTraversibleNone， opts： Mapping[str， Any]， visitors： Mapping[str， Callable[[Any]， None]]）→ExternallyTraversibleNone¶

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

例如：

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__特定类型的 SQL 表达式对象，并将可调用函数作为值，每个函数都表示该类型对象的一个访问者函数。

函数 sqlalchemy.sql.visitors。traverse_using（iterator： Iterable[ExternallyTraversible]， obj：ExternallyTraversibleNone， visitors： Mapping[str， Callable[[any]， None]]）→ExternallyTraversibleNone¶

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

traverse_using（） 通常作为 traverse（） 函数的结果在内部调用。

参数

iterator¶ —— 一个可迭代对象或序列，它将产生 子句元素 结构;迭代器假定为 的 product 的 Iterate（） 函数。
obj¶ —— ClauseElement ，该 iterate（） 函数。
visitors¶ —— 访问函数字典。参见 traverse（） 了解此词典的详细信息。

另请参阅

遍历（）

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy 核心

访客和遍历工具¶