数据库后端ORM【免费下载链接】sqlalchemyThe Database Toolkit for Python项目地址https://gitcode.com/gh_mirrors/sq/sqlalchemy点击查看免费下载导读本文聚焦 SQLAlchemy 内部模块sqlalchemy.sql.visitors它是 SQLAlchemy Core 中用于泛型遍历 SQL 表达式结构的核心设施功能上类似于 Python 标准库的ast模块程序可以借助它逐一访问 SQL 表达式中的每个组件定位Table、BindParameter等元素也可以就地修改或整体替换结构例如将一个 FROM 子句替换为另一个。读完本文你将掌握iterate、traverse、cloned_traverse、replacement_traverse四类遍历函数的用法与区别理解Visitable/HasTraverseInternals两套遍历体系的设计并能把这些能力应用到缓存键构建与自定义 SQL 构造扩展等实战场景中。文章内容以官方文档 visitors.rst 为骨架并以当前仓库源码 visitors.py 及测试用例为佐证。模块定位SQLAlchemy 内部 API 的表达式树遍历器sqlalchemy.sql.visitors模块由一组类与函数构成服务于一个统一目标泛型地遍历traverse一个 Core SQL 表达式结构。官方文档将其与 Python 标准库的ast模块类比——它提供了一种机制让程序能够对 SQL 表达式的每个组成部分进行操作。常见的用途包括定位各种元素例如sqlalchemy.schema.Table或BindParameter对象改变结构的内部状态例如将某些 FROM 子句替换为另外的 FROM 子句这正是 ORM 在关系加载与查询构造中大量依赖的能力。需要特别强调的是文档给出了明确的使用边界提示sqlalchemy.sql.visitors模块属于内部 API并非完全公开。它随时可能变化并且对于 SQLAlchemy 自身内部设计之外的用法可能无法按预期工作。也就是说普通应用代码通常不会直接使用它它主要在两类边缘场景中被用到构建缓存例程caching routines——SQLAlchemy 2.x 的语句缓存statement caching机制正是建立在这套遍历体系之上**使用 Custom SQL Constructs and Compilation Extension自定义 SQL 构造与编译扩展**构建自定义 SQL 表达式时。对应地官方文档通过automodule指令.. automodule:: sqlalchemy.sql.visitors:members:与:private-members:把该模块的全部公开与私有成员纳入文档下文将基于 visitors.py 的实际实现逐层展开。一切从__visit_name__开始Visitable与编译器分发模块中定义了两个平行的遍历体系理解它们的区别是掌握整个模块的关键。第一个体系是Visitable它是可访问对象visitable objects的基类其作用是为 SQL 编译器实现分发dispatch。Visitable的核心设计是每个子类声明一个类级字符串属性__visit_name__基类在__init_subclass__中检测到它后会自动调用_generate_compiler_dispatch()为该类生成一个_compiler_dispatch()方法visitors.py#L91-L132。生成的 dispatch 逻辑非常直白def _compiler_dispatch(self, visitor, **kw): Look for an attribute named visit_visit_name on the visitor, and call it with the same kw params. try: meth getter(visitor) # getter operator.attrgetter(visit_ visit_name) except AttributeError as err: return visitor.visit_unsupported_compilation(self, err, **kw) else: return meth(self, **kw)也就是说遍历器visitor只需要定义形如visit_visit_name的方法Visitable对象就会自动把自身投递到对应方法上。若遍历器缺少对应方法则会回退到visit_unsupported_compilation。这正是SQLCompiler编译任意表达式的基础编译器就是一个巨大的 visitor通过visit_select、visit_binary、visit_bindparam等方法逐一处理每种表达式节点。从版本历史上看Visitable在 1.4 系列中曾被命名为Traversible2.0 又改回Visitable也就是 1.4 之前的名字两个名字在两个大版本中都保持可导入见 visitors.py#L65-L79。此外模块底部保留了一组向后兼容的别名visitors.py#L794-L799Traversible Visitable ClauseVisitor ExternalTraversal CloningVisitor CloningExternalTraversal ReplacingCloningVisitor ReplacingExternalTraversal如果你在较老的代码或测试中看到ClauseVisitor、CloningVisitor、ReplacingCloningVisitor这些名字它们就是本文后面要介绍的三个外部遍历器基类的旧名称。第二个体系HasTraverseInternals与_traverse_internals自描述遍历与Visitable依赖外部 visitor 定义如何遍历不同HasTraverseInternals接口允许类自己定义如何被遍历——即访问哪些属性、以什么顺序访问visitors.py#L427-L436。其核心是一个类级描述结构_traverse_internals类型为List[Tuple[str, InternalTraversal]]——由若干(属性名, 内部遍历符号)元组组成。InternalTraversal符号指明了该属性存储的是什么类型的数据从而告诉遍历器该如何处理它。官方文档在InternalTraversal的 docstring 中给出了Case对象的示例visitors.py#L139-L177class Case(ColumnElement[_T]): _traverse_internals [ (value, InternalTraversal.dp_clauseelement), (whens, InternalTraversal.dp_clauseelement_tuples), (else_, InternalTraversal.dp_clauseelement), ]基于_traverse_internals描述HasTraverseInternals对象会自动获得以下方法的实现HasTraverseInternals.get_children—— 返回直接的子节点用于访问遍历HasTraverseInternals._copy_internals—— 将内部元素替换为自身的克隆用于克隆/替换遍历HasCacheKey._gen_cache_key—— 生成缓存键用于语句缓存。子类也可以按需直接实现这些方法尤其是_copy_internals以便执行特殊步骤。其中get_children的默认实现visitors.py#L444-L476会通过traversals模块预生成的 dispatch 函数把_traverse_internals展开为(attrname, obj, meth)三元组并收集所有非None且不在omit_attrs中的子对象——这也是iterate函数赖以工作的底层能力。关于符号的自动分发InternalTraversal的每个dp_*符号都对应一个简短的字符串值如dp_clauseelement CE、dp_string SHasTraversalDispatch.dispatch()会把这些符号映射到具体访问方法名dp_前缀替换为visit_。模块启动时_generate_traversal_dispatch()会一次性构建这个查找表visitors.py#L565-L578dispatch 函数体则通过exec_code_in_env动态生成并缓存到目标类上generate_dispatch/_generate_dispatcher见 visitors.py#L521-L559。外部遍历核心函数逐个拆解模块导出的四个函数构成了外部遍历external traversal的主体__all__明确列出visitors.py#L48-L58__all__ [ iterate, traverse_using, traverse, cloned_traverse, replacement_traverse, Visitable, ExternalTraversal, InternalTraversal, anon_map, ]iterate广度优先的节点产出器iterate(obj, optsEMPTY_DICT)遍历给定的表达式结构并返回一个迭代器遍历方式是广度优先breadth-firstvisitors.py#L802-L840。实现要点yield obj children obj.get_children(**opts) if not children: return stack deque([children]) while stack: t_iterator stack.popleft() for t in t_iterator: yield t stack.append(t.get_children(**opts))它依赖ClauseElement.get_children()方法返回与自身关联的所有子ClauseElement。例如一个Case结构会在其whens和else_成员变量中引用一系列ColumnElement。参数opts是遍历选项字典在现代用法中通常为空。traverse_using用现成迭代器驱动访问traverse_using(iterator, obj, visitors)使用给定的迭代器来访问表达式结构visitors.py#L859-L892。它通常是traverse的内部实现步骤——iterator被假定为iterate的产物。逻辑简单直接for target in iterator: meth visitors.get(target.__visit_name__, None) if meth: meth(target) return objvisitors是访问函数字典键为字符串对应某种 SQL 表达式对象的__visit_name__值为可调用对象即针对该类对象的访问函数。traverse只读遍历并执行访问函数traverse(obj, opts, visitors)使用默认迭代器遍历并访问给定表达式结构visitors.py#L911-L947。docstring 中的官方示例即是一个经典的找出所有绑定参数场景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})visitors字典的键bindparam正是BindParameter.__visit_name__。对象迭代使用iterate即广度优先的栈式遍历。注意traverse是只读的——它不克隆对象访问函数只能观察结构不能安全地就地改动结构。cloned_traverse克隆结构并允许就地修改cloned_traverse(obj, opts, visitors)克隆给定表达式结构同时允许访问函数修改可变对象visitors.py#L970-L1058。它与traverse的用法相同但访问函数在遍历过程中可以修改给定结构的内部状态。两个关键实现细节值得注意stop_on选项opts中的stop_on是一个对象集合命中的元素将原样保留不克隆用于切断遍历边界。Immutable对象被跳过2.0 变更cloned_traverse不会把实现了Immutable接口的对象交给访问方法——这主要包括ColumnClause、Column、TableClause和Table。原因在于该遍历只打算允许就地修改因此不可变对象被跳过但每个对象仍会调用_clone()以允许对象基于其子内部结构的克隆来替换自身例如ColumnClause克隆其关联的子查询并返回对应的新列。这一行为在 2.0 中正式生效visitors.py#L993-L995。cloned_traverse与replacement_traverse共同依赖的另一个核心 API 是ClauseElement._copy_internals()要使结构正确支持克隆与替换遍历它必须能把克隆函数传给内部成员从而复制它们visitors.py#L996-L1005。replacement_traverse整体替换元素replacement_traverse(obj, opts, replace)克隆给定表达式结构并允许通过一个替换函数整体替换元素visitors.py#L1085-L1153。它与cloned_traverse非常相似区别在于不再传访问函数字典而是把所有元素无条件传给replace函数replace可以返回一个全新对象来替换当前对象返回None则保持原对象不变。两种函数的用法差异被文档明确概括在cloned_traverse中访问函数收到的是已经克隆好的对象可以对对象内部状态做操作而在replacement_traverse中replace函数只应返回一个完全不同的对象或者什么都不做。文档同时点明了它的经典用例替换 SQL 结构内部的 FROM 子句——这正是 ORM 中的常见需求。实现上还有两点细节支持no_replacement_traverse注解若元素带有该注解则原样保留以id(elem)而非hash作为已见过的判断依据从而避免把带注解元素错误地替换为其非注解版本visitors.py#L1133-L1136。外部遍历器基类ExternalTraversal家族除了函数式接口模块还提供了三个面向对象的遍历器基类适合把多个访问方法组织在一个类里。它们都继承自util.MemoizedSlots通过反射收集类上所有visit_开头的方法构建_visitor_dict见_memoized_attr__visitor_dictvisitors.py#L676-L684。ExternalTraversal旧名ClauseVisitor对应traverse函数的类形式。核心成员visitors.py#L632-L703__traverse_options__类级遍历选项字典traverse_single(obj, **kw)仅对单个对象执行访问分发——沿visitor_iterator链查找匹配的visit_visit_name方法iterate(obj)等价于调用iterate(obj, self.__traverse_options__)traverse(obj)等价于调用traverse(obj, self.__traverse_options__, self._visitor_dict)chain(visitor)把另一个ExternalTraversal链接到当前对象之后链上的遍历器会依次收到所有访问事件visitor_iterator沿_next引用迭代。CloningExternalTraversal旧名CloningVisitor对应cloned_traverse函数的类形式visitors.py#L706-L742。额外提供copy_and_process(list_)对列表中的每个元素应用克隆遍历并返回新列表。ReplacingExternalTraversal旧名ReplacingCloningVisitor对应replacement_traverse函数的类形式visitors.py#L745-L791。子类通过覆写replace(elem)方法决定替换行为返回新元素则替换返回None则保留遍历遇到被替换产生的新元素时会停止继续深入。InternalTraversal符号表内部遍历的数据类型标注InternalTraversal是 1.4 引入的枚举类作用是双重的既可以作为实现各类visit_*方法的访问器基类其符号本身也用于_traverse_internals集合中标注属性类型visitors.py#L139-L177。了解这些符号有助于阅读 SQLAlchemy 各构造的_traverse_internals定义。下表整理了文档与源码中完整出现的符号符号值含义dp_has_cache_keyHC访问一个HasCacheKey对象dp_has_cache_key_listHL访问HasCacheKey对象列表dp_clauseelementCE访问一个ClauseElement对象dp_fromclause_canonical_column_collectionFC在columns属性上下文中访问FromClause列集合是canonical原始定义位置当前仅指TableClause或Tabledp_clauseelement_tuplesCTS访问包含ClauseElement的元组列表dp_clauseelement_listCL访问ClauseElement列表dp_clauseelement_tupleCT访问ClauseElement元组dp_executable_optionsEO访问可执行选项dp_compile_state_funcsWC访问编译状态函数dp_fromclause_ordered_setCO访问FromClause的有序集合dp_stringS访问普通字符串表名、列名、绑定参数键、UNION等关键字对缓存键生成有意义dp_string_listSL访问字符串列表dp_anon_nameAN访问可能被匿名化的字符串对缓存键生成有意义dp_booleanB访问布尔值对缓存键生成有意义dp_operatorO访问sqlalchemy.sql.operators中的运算符函数对缓存键生成有意义dp_typeT访问TypeEngine对象对缓存键生成有意义dp_plain_dictPD访问字符串键字典值需不可变、可哈希对缓存键生成有意义dp_dialect_optionsDO访问方言选项结构dp_string_clauseelement_dictCD访问字符串键到ClauseElement的字典dp_string_multi_dictMD访问字符串键到不可变值或HasCacheKey对象的字典dp_annotations_keyAK访问_annotations_cache_key生成成本相对高访问器应先检查_annotations非None再生成dp_plain_objPO访问普通 Python 对象需不可变、可哈希如整数对缓存键生成有意义dp_named_ddl_elementDD访问简单命名的 DDL 元素当前为Sequence缓存键只关心其名字dp_prefix_sequencePS访问HasPrefixes/HasSuffixes的序列dp_table_hint_listTH访问Select._hints集合dp_setup_join_tupleSJ访问 setup join 元组dp_memoized_select_entitiesME访问记忆化的 select 实体dp_statement_hint_listSH访问Select._statement_hints集合dp_unknown_structureUK访问未知结构dp_dml_ordered_valuesDML_OV访问Update.values()的有序元组列表dp_dml_valuesDML_V访问ValuesBaseInsert/Update的values()字典dp_dml_multi_valuesDML_MV访问Insert.values()的多值字典列表dp_propagate_attrsPA访问 propagate attrs 字典dp_ignoreIG完全忽略的对象用于函数调用参数缓存dp_inspectableIS访问可 inspect 对象返回值为HasCacheKeydp_multiM访问可能是HasCacheKey也可能是普通可哈希对象的元素dp_multi_listMT访问包含HasCacheKey或普通可哈希对象的元组dp_has_cache_key_tuplesHT访问包含HasCacheKey的元组列表dp_paramsPM访问ExecutableStatement._params集合其中从dp_ignore往后的符号被专门标注为对缓存应用额外有用——ClauseElement的遍历只需要InternalTraversal中已有的符号而 ORM 中的额外缓存用例则补充了这些涉及HasCacheKey的符号visitors.py#L373-L411。ExtendedInternalTraversal InternalTraversal也作为别名提供。深度应用一语句缓存键的生成文档明确指出visitors模块在构建缓存例程时会被使用。其衔接点在sqlalchemy.sql.cache_key模块HasCacheKey混入类通常与HasTraverseInternals处于同一继承层级其_cache_key_traversal属性声明了该对象如何参与缓存键生成cache_key.py#L74-L92。InternalTraversal的 docstring 中写道基于_traverse_internals结构HasTraverseInternals对象会自动实现HasCacheKey._gen_cache_keyvisitors.py#L161-L173。换句话说一条 SQL 语句的缓存键本质上就是沿着_traverse_internals描述的结构对整棵表达式树做一次规范化的遍历——每个被标记为对缓存键生成有意义的字符串、布尔、运算符、类型、字典都会被纳入键的计算。这里需要特别提醒两个与遍历直接相关的注意事项inherit_cache属性cache_key.py#L105-L120默认是None表示该构造尚未声明是否参与缓存功能上等同于False并会发出警告只有在类的局部属性不会改变对应 SQL 时才应显式设为Truedp_annotations_key符号明确警告生成该键相对昂贵遍历实现应优先检查_annotations字典是否非空。在traversals.py中还提供了基于同一套_traverse_internals的compare(obj1, obj2)比较策略TraversalComparatorStrategy以及使用代理列身份比较的ColIdentityComparatorStrategy见 traversals.py#L43-L50它被用于结构级比较——这同样体现了一份_traverse_internals描述、多种遍历用途的设计思想。深度应用二ORM 中 FROM 子句的替换replacement_traverse的经典用例——替换 SQL 结构中的 FROM 子句——在 ORM 的关系加载实现中随处可见。以 relationships.py 为例其中对primaryjoin/secondaryjoin的大量处理都建立在这套遍历之上cloned_traverse用于克隆连接条件如 relationships.py#L1310 的_annotate相关路径、relationships.py#L2713-L2717replacement_traverse用于替换连接条件中的表引用如 relationships.py#L2597、relationships.py#L2663-L2667、relationships.py#L2789-L2794 等大量位置traverse则用于只读地扫描连接条件中的元素如 relationships.py#L2743 中对BinaryExpression的访问。此外base.py 中的SchemaVisitable直接继承visitors.Visitablebase.py#L1694并在 base.py#L2603 使用visitors.iterate枚举语句元素——印证了Visitable是整个 Core 表达体系共同的基座。深度应用三自定义 SQL 构造与编译扩展文档提到的另一场景是使用 Custom SQL Constructs and Compilation Extension 构建自定义 SQL 表达式。这部分在 compiler.rst即sqlalchemy.ext.compiler源码见 ext/compiler.py中有完整叙述而它的底层机制正是Visitable._generate_compiler_dispatch自定义构造通过定义__visit_name__与visit_name编译方法即可无缝接入编译流程compiles装饰器可以把自定义编译方法注册到指定类或指定方言上模块在_generate_compiler_dispatch中还保留了一个细节如果类已有固定的_compiler_dispatch会先把它复制到_original_compiler_dispatch以便在compiles覆盖后仍能取回原始实现visitors.py#L100-L105。因此当你实现自定义 SQL 构造并需要①统计/定位结构中的特定节点②在不改变原对象的前提下生成变体③整体替换某个子结构时traverse/cloned_traverse/replacement_traverse就构成了完整的工具箱。测试验证test_external_traversal.py中的行为证据仓库的测试套件对上述行为提供了直接验证。最集中的测试文件是 test_external_traversal.py约 3100 行覆盖访问、克隆、替换、链式遍历等场景。值得关注的测试点包括自定义构造的遍历TraversalTest类中定义了两个虚构的ClauseElement子类A__visit_name__ a与B__visit_name__ b分别实现_copy_internals与get_children用以验证遍历器的深度语义test_external_traversal.py#L55-L124克隆与不克隆的区分test_clone验证CloningVisitor遍历后结构相等但对象身份不同test_no_clone验证ClauseVisitor遍历后对象身份保持不变test_external_traversal.py#L141-L173不可变对象的跳过test_dont_traverse_immutables验证 2.0 中cloned_traverse跳过Immutable对象的行为test_external_traversal.py#L916替换遍历多个测试通过visitors.replacement_traverse(s, {}, lambda elem: None)验证不做任何替换的遍历依然能正确克隆整棵结构并保持编译结果一致如 test_external_traversal.py#L1339-L1363这正是替换函数返回None则保留原对象语义的直接证据。使用边界与版本注意点综合文档与源码使用这套工具时请牢记以下边界内部 APIvisitors模块不保证对外稳定仅在构建缓存例程或实现自定义 SQL 构造时使用面向外部稳定支持的是sqlalchemy.ext.compiler扩展层。只读 vs 克隆 vs 替换需要观察用traverse需要生成可变副本用cloned_traverse访问函数可修改克隆后的可变对象需要整体换元素用replacement_traversereplace返回新对象或None。2.0 行为变更cloned_traverse不再把ColumnClause、Column、TableClause、Table等Immutable对象交给访问方法Visitable的名称在 2.0 中从 1.4 的Traversible改回两个名字均保留。性能细节dp_annotations_key的生成成本较高遍历依赖id()判断已克隆元素以避免重复克隆与无限递归。小结sqlalchemy.sql.visitors是 SQLAlchemy Core 表达系统的隐形骨架Visitable驱动编译器分发HasTraverseInternals_traverse_internals让每个表达式节点自描述其结构iterate/traverse/cloned_traverse/replacement_traverse四个函数则分别覆盖枚举、观察、克隆修改、整体替换四类遍历需求。理解这套机制不仅有助于读懂 SQLAlchemy 的编译、缓存与 ORM 关系加载源码cache_key.py、traversals.py、relationships.py也是编写自定义 SQL 构造和高级查询工具的基础。官方文档原文见 visitors.rst配套测试见 test_external_traversal.py。赞分享数据库后端ORM【免费下载链接】sqlalchemyThe Database Toolkit for Python项目地址https://gitcode.com/gh_mirrors/sq/sqlalchemy点击查看免费下载相关推荐PhotoMaker模型量化实践INT8精度下的性能与质量平衡PhotoMaker模型量化实践INT8精度下的性能与质量平衡 PhotoMaker作为一款强大的AI绘图模型在生成高质量人像方面表现出色。然而原始模型通Strapi traverseEntity基于 Visitor 模式的实体递归遍历工具深度解析Strapi traverseEntity基于 Visitor 模式的实体递归遍历工具深度解析 traverseEntity 是 Strapi strapi后端CMS前端Marko遍历器DOM树的遍历与操作Marko遍历器DOM树的遍历与操作 Marko遍历器是Marko框架中一个强大的工具专门用于DOM树的遍历和操作。无论你是前端开发新手还是资深工程师掌握前端后端Web框架上一篇ArcGIS Maps SDK for JavaScript 终极资源指南从零开始构建专业地图应用下一篇Nunu 开源项目安装与使用指南创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考