SqlAlchemy 2.0 中文文档（三十七）（3）https://developer.aliyun.com/article/1562701
表达式序列化器扩展
用于与 SQLAlchemy 查询结构一起使用的序列化器/反序列化器对象，允许“上下文”反序列化。
遗留功能
序列化器扩展是遗留的，不应用于新开发。
可以使用任何 SQLAlchemy 查询结构，无论是基于 sqlalchemy.sql.* 还是 sqlalchemy.orm.*。结构引用的映射器、表、列、会话等在序列化形式中不会被持久化，而是在反序列化时重新关联到查询结构。
警告
序列化器扩展使用 pickle 对对象进行序列化和反序列化，因此与 python 文档 中提到的相同的安全注意事项适用。
使用方式几乎与标准 Python pickle 模块相同：
from sqlalchemy.ext.serializer import loads, dumps metadata = MetaData(bind=some_engine) Session = scoped_session(sessionmaker()) # ... define mappers query = Session.query(MyClass). filter(MyClass.somedata=='foo').order_by(MyClass.sortkey) # pickle the query serialized = dumps(query) # unpickle. Pass in metadata + scoped_session query2 = loads(serialized, metadata, Session) print query2.all()
使用原始 pickle 时适用的类似限制也适用；映射类必须本身可被 pickle 化，这意味着它们可以从模块级别的命名空间导入。
序列化器模块仅适用于查询结构。不需要：
- 用户定义类的实例。在典型情况下，这些类不包含对引擎、会话或表达式构造的引用，因此可以直接序列化。
- 完全从序列化结构加载的表元数据（即在应用程序中尚未声明的元数据）。可以使用常规的 pickle.loads()/dumps() 来完全转储任何
MetaData对象，通常是在以前的某个时间点从现有数据库反射的对象。序列化器模块专门用于相反的情况，即表元数据已经存在于内存中的情况。
| 对象名称 | 描述 |
| Deserializer(file[, metadata, scoped_session, engine]) | |
| dumps(obj[, protocol]) | |
| loads(data[, metadata, scoped_session, engine]) | |
| Serializer(*args, **kw) |
function sqlalchemy.ext.serializer.Deserializer(file, metadata=None, scoped_session=None, engine=None)
function sqlalchemy.ext.serializer.Serializer(*args, **kw)
function sqlalchemy.ext.serializer.dumps(obj, protocol=5)
function sqlalchemy.ext.serializer.loads(data, metadata=None, scoped_session=None, engine=None)
SQL 表达语言基础构造
用于组成 SQL 表达语言元素的基类和混合类。
| 对象名称 | 描述 |
| CacheKey | 用于在 SQL 编译缓存中标识 SQL 语句构造的键。 |
| ClauseElement | 用于程序化构建 SQL 表达式的元素的基类。 |
| DialectKWArgs | 建立一个类具有特定方言参数的能力，带有默认值和构造函数验证。 |
| HasCacheKey | 用于能够生成缓存键的对象的混合类。 |
| LambdaElement | 一个 SQL 构造，其中状态存储为未调用的 lambda。 |
| StatementLambdaElement | 代表一个可组合的 SQL 语句，作为LambdaElement。 |
class sqlalchemy.sql.expression.CacheKey
用于在 SQL 编译缓存中标识 SQL 语句构造的键。
另请参阅
SQL 编译缓存
成员
bindparams, key, to_offline_string()
类签名
类sqlalchemy.sql.expression.CacheKey (builtins.tuple)
attribute bindparams: Sequence[BindParameter[Any]]
字段编号 1 的别名
attribute key: Tuple[Any, ...]
字段编号 0 的别名
method to_offline_string(statement_cache: MutableMapping[Any, str], statement: ClauseElement, parameters: _CoreSingleExecuteParams) → str
生成这个CacheKey的“离线字符串”形式
“离线字符串”基本上是语句的字符串 SQL 加上一系列绑定参数值的 repr。而CacheKey对象依赖于内存中的标识以便作为缓存键工作，“离线”版本适用于其他进程也能工作的缓存。
给定的statement_cache是一个类似字典的对象，其中语句本身的字符串形式将被缓存。为了减少字符串化语句所花费的时间，这个字典应该在一个更长寿命的范围内。
class sqlalchemy.sql.expression.ClauseElement
用于程序化构建 SQL 表达式的元素的基类。
成员
compare(), compile(), get_children(), inherit_cache, params(), self_group(), unique_params()
类签名
类sqlalchemy.sql.expression.ClauseElement（sqlalchemy.sql.annotation.SupportsWrappingAnnotations、sqlalchemy.sql.cache_key.MemoizedHasCacheKey、sqlalchemy.sql.traversals.HasCopyInternals、sqlalchemy.sql.visitors.ExternallyTraversible、sqlalchemy.sql.expression.CompilerElement）
method compare(other: ClauseElement, **kw: Any) → bool
将此ClauseElement与给定的ClauseElement进行比较。
子类应该覆盖默认行为，即直接进行身份比较。
**kw 是子类compare()方法消耗的参数，可用于修改比较的标准（参见ColumnElement）。
method compile(bind: _HasDialect | None = None, dialect: Dialect | None = None, **kw: Any) → Compiled
从 CompilerElement 的 CompilerElement.compile() 方法继承
编译此 SQL 表达式。
返回值是一个Compiled对象。对返回值调用str()或unicode()将产生结果的字符串表示。Compiled对象还可以使用params访问器返回绑定参数名称和值的字典。
参数：
bind– 一个Connection或Engine，它可以提供一个Dialect以生成一个Compiled对象。如果bind和dialect参数都被省略，将使用默认的 SQL 编译器。column_keys– 用于 INSERT 和 UPDATE 语句，一个应该存在于编译后语句的 VALUES 子句中的列名列表。如果为None，则从目标表对象中渲染所有列。dialect– 一个Dialect实例，可以生成一个Compiled对象。此参数优先于bind参数。compile_kwargs–
额外参数的可选字典，这些参数将通过所有“访问”方法传递给编译器。这允许通过到自定义编译结构的任何自定义标志进行传递。它还用于通过以下方式传递literal_binds标志的情况：
from sqlalchemy.sql import table, column, select t = table('t', column('x')) s = select(t).where(t.c.x == 5) print(s.compile(compile_kwargs={"literal_binds": True}))
另请参阅
我如何将 SQL 表达式呈现为字符串，可能还包含内联的绑定参数？
method get_children(*, omit_attrs: Tuple[str, ...] = (), **kw: Any) → Iterable[HasTraverseInternals]
从 HasTraverseInternals.get_children() 方法继承 HasTraverseInternals
返回此 HasTraverseInternals 的直接子元素 HasTraverseInternals。
这用于访问遍历。
**kw 可包含更改返回集合的标志，例如返回子集以减少较大的遍历，或从不同上下文（例如模式级集合而不是子句级）返回子项的标志。
attribute inherit_cache: bool | None = None
从 HasCacheKey 的 HasCacheKey.inherit_cache 属性继承
指示此 HasCacheKey 实例是否应使用其直接超类使用的缓存键生成方案。
属性默认为 None，表示构造尚未考虑其是否适合参与缓存；这在功能上等同于将值设置为 False，只是还会发出警告。
如果对应于对象的 SQL 不根据此类的本地属性（而不是其超类）更改，则可以在特定类上将此标志设置为 True。
另请参阅
为自定义构造启用缓存支持 - 设置第三方或用户定义的 SQL 构造的 HasCacheKey.inherit_cache 属性的一般指南。
method params(_ClauseElement__optionaldict: Mapping[str, Any] | None = None, **kwargs: Any) → Self
返回一个副本，其中 bindparam() 元素已被替换。
返回此 ClauseElement 的副本，并用从给定字典中取出的值替换其中的 bindparam() 元素：
>>> clause = column('x') + bindparam('foo') >>> print(clause.compile().params) {'foo':None} >>> print(clause.params({'foo':7}).compile().params) {'foo':7}
method self_group(against: OperatorType | None = None) → ClauseElement
对此 ClauseElement 应用‘分组’。
子类重写此方法以返回一个“分组”构造，即括号。特别是当“二进制”表达式被放置到更大的表达式中时，它们会提供一个围绕自身的分组，以及当 select() 构造被放置到另一个 select() 的 FROM 子句中时。 （请注意，子查询通常应该使用 Select.alias() 方法创建，因为许多平台要求嵌套的 SELECT 语句必须被命名）。
随着表达式的组合，self_group() 的应用是自动的 - 最终用户代码不应直接使用此方法。请注意，SQLAlchemy 的子句构造考虑了运算符优先级 - 因此在像 x OR (y AND z) 这样的表达式中可能不需要括号 - AND 优先于 OR。
ClauseElement 的基础 self_group() 方法只返回自身。
method unique_params(_ClauseElement__optionaldict: Dict[str, Any] | None = None, **kwargs: Any) → Self
返回一个将 bindparam() 元素替换的副本。
与 ClauseElement.params() 相同的功能，只是对影响到的绑定参数添加了 unique=True，以便可以使用多个语句。
class sqlalchemy.sql.base.DialectKWArgs
建立类具有方言特定参数的能力，并具有默认值和构造函数验证。
DialectKWArgs 与方言上的 DefaultDialect.construct_arguments 交互。
成员
argument_for(), dialect_kwargs, dialect_options, kwargs
另请参阅
DefaultDialect.construct_arguments
classmethod argument_for(dialect_name, argument_name, default)
为这个类添加一种新的方言特定的关键字参数。
例如：
Index.argument_for("mydialect", "length", None) some_index = Index('a', 'b', mydialect_length=5)
DialectKWArgs.argument_for()方法是一种逐个参数地向DefaultDialect.construct_arguments字典添加额外参数的方式。该字典提供了各种模式级构造的方言接受的参数名称列表。
新方言通常应一次性指定该字典作为方言类的数据成员。通常情况下，用于临时添加参数名称的用例是为了终端用户代码，该代码还使用了消耗额外参数的自定义编译方案。
参数：
dialect_name– 方言的名称。方言必须是可定位的，否则会引发NoSuchModuleError。方言还必须包含一个现有的DefaultDialect.construct_arguments集合，指示其参与关键字参数验证和默认系统，否则会引发ArgumentError。如果方言不包含此集合，则已经可以为该方言指定任何关键字参数。SQLAlchemy 内置的所有方言都包含此集合，但对于第三方方言，支持可能有所不同。argument_name– 参数的名称。default– 参数的默认值。
attribute dialect_kwargs
作为特定方言选项指定的关键字参数集合。
这里的参数以其原始的_格式呈现。只包括实际传递的参数；不同于DialectKWArgs.dialect_options集合，后者包含了该方言已知的所有选项，包括默认值。
该集合也是可写的；接受形式为_的键，其值将被组装到选项列表中。
另请参阅
DialectKWArgs.dialect_options - 嵌套字典形式
attribute dialect_options
作为特定方言选项指定的关键字参数集合。
这是一个两级嵌套的注册表，以和为键。例如，postgresql_where参数可以定位为：
arg = my_object.dialect_options['postgresql']['where']
0.9.2 版本中新增。
另请参阅
DialectKWArgs.dialect_kwargs - 扁平字典形式
attribute kwargs
DialectKWArgs.dialect_kwargs 的别名。
class sqlalchemy.sql.traversals.HasCacheKey
用于可以生成缓存键的对象的混合类。
此类通常位于以 HasTraverseInternals 为基础的层次结构中，但这是可选的。目前，该类应该能够在不包括 HasTraverseInternals 的情况下独立工作。
成员
inherit_cache
另请参阅
CacheKey
SQL 编译缓存
attribute inherit_cache: bool | None = None
表明此 HasCacheKey 实例是否应该使用其直接超类使用的缓存键生成方案。
该属性默认为 None，表示构造尚未考虑是否适合参与缓存；这在功能上等同于将值设置为 False，除了还会发出警告。
如果对象对应的 SQL 不基于仅限于此类而非其超类的属性发生变化，则可以在特定类上将此标志设置为 True。
另请参阅
为自定义构造启用缓存支持 - 设置第三方或用户定义的 SQL 构造的 HasCacheKey.inherit_cache 属性的通用指南。
class sqlalchemy.sql.expression.LambdaElement
一个 SQL 构造，其中状态被存储为未调用的 lambda。
LambdaElement 在将 lambda 表达式传递给 SQL 构造时会透明地生成，例如：
stmt = select(table).where(lambda: table.c.col == parameter)
LambdaElement 是 StatementLambdaElement 的基础，它代表了 lambda 中的完整语句。
新版本 1.4 中新增。
另请参阅
使用 Lambdas 为语句生成带来显著的速度提升
类签名
类 sqlalchemy.sql.expression.LambdaElement (sqlalchemy.sql.expression.ClauseElement)
class sqlalchemy.sql.expression.StatementLambdaElement
将可组合的 SQL 语句表示为 LambdaElement。
使用 lambda_stmt() 函数构建 StatementLambdaElement：
from sqlalchemy import lambda_stmt stmt = lambda_stmt(lambda: select(table))
构建完成后，可以通过添加后续 lambda 将额外条件添加到语句中，这些 lambda 将现有语句对象作为单个参数接受：
stmt += lambda s: s.where(table.c.col == parameter)
版本 1.4 中的新功能。
另请参阅
使用 Lambda 添加显著的语句生成速度提升
成员
add_criteria(), is_delete, is_dml, is_insert, is_select, is_text, is_update, spoil()
类签名
类 sqlalchemy.sql.expression.StatementLambdaElement (sqlalchemy.sql.roles.AllowsLambdaRole, sqlalchemy.sql.expression.LambdaElement, sqlalchemy.sql.expression.Executable)
method add_criteria(other: Callable[[Any], Any], enable_tracking: bool = True, track_on: Any | None = None, track_closure_variables: bool = True, track_bound_values: bool = True) → StatementLambdaElement
向此 StatementLambdaElement 添加新条件。
例如：
>>> def my_stmt(parameter): ... stmt = lambda_stmt( ... lambda: select(table.c.x, table.c.y), ... ) ... stmt = stmt.add_criteria( ... lambda: table.c.x > parameter ... ) ... return stmt
StatementLambdaElement.add_criteria() 方法等同于使用 Python 加法运算符添加新的 lambda，不过可以添加额外的参数，包括 track_closure_values 和 track_on：
>>> def my_stmt(self, foo): ... stmt = lambda_stmt( ... lambda: select(func.max(foo.x, foo.y)), ... track_closure_variables=False ... ) ... stmt = stmt.add_criteria( ... lambda: self.where_criteria, ... track_on=[self] ... ) ... return stmt
有关可接受参数的说明，请参阅 lambda_stmt()。
attribute is_delete
attribute is_dml
attribute is_insert
attribute is_select
attribute is_text
attribute is_update
method spoil() → NullLambdaStatement
返回一个新的 StatementLambdaElement，每次运行所有 lambda 时都会无条件地运行。
SqlAlchemy 2.0 中文文档（三十七）（5）https://developer.aliyun.com/article/1562706
