SqlAlchemy 2.0 中文文档（四十七）（8）https://developer.aliyun.com/article/1563055
表示在为语句生成“扩展”和“编译后”绑定参数时使用的状态。
“扩展”参数是在语句执行时生成的参数，以适应传递的参数数量，最突出的例子是 IN 表达式中的各个元素。
“编译后”参数是在执行时将 SQL 文本值呈现到 SQL 语句中，而不是作为单独的参数传递给驱动程序的参数。
要创建一个ExpandedState实例，请在任何SQLCompiler实例上使用SQLCompiler.construct_expanded_state()方法。
成员
additional_parameters, parameter_expansion, parameters, positional_parameters, positiontup, processors, statement
类签名
类sqlalchemy.sql.compiler.ExpandedState（builtins.tuple）
attribute additional_parameters
ExpandedState.parameters的同义词。
attribute parameter_expansion: Mapping[str, List[str]]
表示从原始参数名称到“扩展”参数名称列表的中间链接的映射，用于那些已扩展的参数。
attribute parameters: _CoreSingleExecuteParams
参数字典，参数已完全展开。
对于使用命名参数的语句，此字典将与语句中的名称完全匹配。对于使用位置参数的语句，ExpandedState.positional_parameters将生成一个具有位置参数集的元组。
attribute positional_parameters
用于使用位置参数样式编译的语句的位置参数元组。
attribute positiontup: Sequence[str] | None
一个指示位置参数顺序的字符串名称序列
attribute processors: Mapping[str, _BindProcessorType[Any]]
绑定值处理器的映射
attribute statement: str
字符串 SQL 语句，参数已完全展开
class sqlalchemy.sql.compiler.GenericTypeCompiler
成员
ensure_kwarg
类签名
类sqlalchemy.sql.compiler.GenericTypeCompiler（sqlalchemy.sql.compiler.TypeCompiler）
attribute ensure_kwarg: str = 'visit_\\w+'
继承自 TypeCompiler 的 TypeCompiler.ensure_kwarg 属性
一个指示方法名称的正则表达式，该方法应接受**kw参数。
该类将扫描与名称模板匹配的方法，并在必要时装饰它们，以确保接受**kw参数。
class sqlalchemy.log.Identified
class sqlalchemy.sql.compiler.IdentifierPreparer
成员
init(), format_column(), format_label_name(), format_schema(), format_table(), format_table_seq(), quote(), quote_identifier(), quote_schema(), schema_for_object, unformat_identifiers(), validate_sql_phrase()
根据选项处理标识符的引用和大小写折叠。
method __init__(dialect, initial_quote='"', final_quote=None, escape_quote='"', quote_case_sensitive_collations=True, omit_schema=False)
构造一个新的IdentifierPreparer对象。
初始引号
开始定界标识符的字符。
最终引号
结束定界标识符的字符。默认为初始引号。
省略模式
防止添加模式名。适用于不支持模式的数据库。
method format_column(column, use_table=False, name=None, table_name=None, use_schema=False, anon_map=None)
准备一个带引号的列名。
method format_label_name(name, anon_map=None)
准备一个带引号的列名。
method format_schema(name)
准备一个带引号的模式名。
method format_table(table, use_schema=True, name=None)
准备一个带引号的表名和模式名。
method format_table_seq(table, use_schema=True)
将表名和模式格式化为元组。
method quote(ident: str, force: Any | None = None) → str
有条件地引用标识符。
如果标识符是保留字、包含引号必要字符或是一个包含quote设置为True的quoted_name的实例，则对标识符进行引用。
子类可以重写此方法，为标识符名称提供依赖于数据库的引用行为。
参数：
ident– 字符串标识符force–
未使用
从版本 0.9 开始弃用：IdentifierPreparer.quote.force参数已弃用，并将在将来的版本中移除。此标志对IdentifierPreparer.quote()方法的行为没有影响；请参考quoted_name。
method quote_identifier(value: str) → str
引用标识符。
子类应重写此方法以提供特定于数据库的引号行为。
method quote_schema(schema: str, force: Any | None = None) → str
有条件地引用模式名称。
如果名称是保留字，包含引号必要字符，或是包含quote设置为True的quoted_name的实例，则对名称进行引用。
子类可以重写此方法以提供特定于数据库的模式名称引用行为。
参数：
schema– 字符串模式名称force–
未使用
从版本 0.9 开始弃用：IdentifierPreparer.quote_schema.force参数已弃用，并将在将来的版本中移除。此标志对IdentifierPreparer.quote()方法的行为没有影响；请参考quoted_name。
attribute schema_for_object: _SchemaForObjectCallable = operator.attrgetter('schema')
返回对象的.schema 属性。
对于默认的 IdentifierPreparer，对象的模式始终是“.schema”属性的值。如果准备器被替换为具有非空 schema_translate_map 的准备器，则“.schema”属性的值将被呈现为一个符号，该符号将在编译后从映射转换为真实模式名称。
method unformat_identifiers(identifiers)
将类似‘schema.table.column’的字符串解包成组件。
method validate_sql_phrase(element, reg)
关键字序列过滤器。
用于表示关键字序列的元素的过滤器，例如“INITIALLY”，“INITIALLY DEFERRED”等。不应包含任何特殊字符。
版本 1.3 中的新功能。
class sqlalchemy.sql.compiler.SQLCompiler
Compiled的默认实现。
将ClauseElement对象编译成 SQL 字符串。
成员
init(), ansi_bind_rules, bind_names, bindname_escape_characters, binds, bindtemplate, compilation_bindtemplate, construct_expanded_state(), construct_params(), current_executable, default_from(), delete_extra_from_clause(), effective_returning, escaped_bind_names, get_select_precolumns(), group_by_clause(), has_out_parameters, implicit_returning, insert_prefetch, insert_single_values_expr, isupdate, literal_execute_params, order_by_clause(), params, positiontup, post_compile_params, postfetch, postfetch_lastrowid, render_literal_value(), render_table_with_column_in_update_from, returning, returning_precedes_values, sql_compiler, stack, translate_select_structure, update_from_clause(), update_limit_clause(), update_prefetch, update_tables_clause(), visit_override_binds()
类签名
类sqlalchemy.sql.compiler.SQLCompiler（sqlalchemy.sql.compiler.Compiled）
method __init__(dialect: Dialect, statement: ClauseElement | None, cache_key: CacheKey | None = None, column_keys: Sequence[str] | None = None, for_executemany: bool = False, linting: Linting = Linting.NO_LINTING, _supporting_against: SQLCompiler | None = None, **kwargs: Any)
构造一个新的SQLCompiler对象。
参数：
dialect– 要使用的Dialectstatement– 要编译的ClauseElementcolumn_keys– 一个列名列表，将被编译成一个 INSERT 或 UPDATE 语句。for_executemany– INSERT / UPDATE 语句是否应该期望以“executemany”样式调用，这可能会影响语句如何期望返回默认值和自增/序列等的值。根据使用的后端和驱动程序，检索这些值的支持可能已禁用，这意味着 SQL 表达式可能会被内联渲染，RETURNING 可能不会被渲染等。kwargs– 要被超类消耗的额外关键字参数。
attribute ansi_bind_rules: bool = False
SQL 92 不允许在 SELECT 的列子句中使用绑定参数，也不允许模糊表达式如“? = ?”。如果目标驱动程序/数据库强制执行此规则，编译器子类可以将此标志设置为 False
attribute bind_names: Dict[BindParameter[Any], str]
一个包含“编译”名称的 BindParameter 实例字典，这些名称实际上出现在生成的 SQL 中
attribute bindname_escape_characters: ClassVar[Mapping[str, str]] = {' ': '_', '%': 'P', '(': 'A', ')': 'Z', '.': '_', ':': 'C', '[': '_', ']': '_'}
一个映射（例如字典或类似结构），包含一个字符查找表，键为替换字符，这些字符将被应用于所有 SQL 语句中使用的“绑定名称”作为一种“转义”；当在 SQL 语句中呈现时，给定字符将完全替换为“替换”字符，并且对传递给Connection.execute()等方法的参数字典中使用的传入名称执行类似的转换。
这允许在bindparam()和其他构造中使用的绑定参数名称具有任意字符，而不必担心目标数据库上根本不允许的字符。
第三方方言可以在此处建立自己的字典以替换默认映射，这将确保映射中的特定字符永远不会出现在绑定参数名称中。
字典在类创建时进行评估，因此不能在运行时修改；在类首次声明时，必须存在于类上。
请注意，对于具有额外绑定参数规则的方言，例如对前导字符有额外限制的方言，可能需要增强SQLCompiler.bindparam_string()方法。请参考 cx_Oracle 编译器的示例。
在版本 2.0.0rc1 中新增。
attribute binds: Dict[str, BindParameter[Any]]
一个将绑定参数键与 BindParameter 实例关联的字典。
attribute bindtemplate: str
根据 paramstyle 渲染绑定参数的模板。
attribute compilation_bindtemplate: str
编译器在应用位置参数样式之前渲染参数时使用的模板。
method construct_expanded_state(params: _CoreSingleExecuteParams | None = None, escape_names: bool = True) → ExpandedState
为给定参数集返回一个新的ExpandedState。
对于使用“扩展”或其他晚期渲染参数的查询，此方法将提供特定参数集的最终 SQL 字符串以及将用于该特定参数集的参数。
自版本 2.0.0rc1 起新增。
method construct_params(params: _CoreSingleExecuteParams | None = None, extracted_parameters: Sequence[BindParameter[Any]] | None = None, escape_names: bool = True, _group_number: int | None = None, _check: bool = True, _no_postcompile: bool = False) → _MutableCoreSingleExecuteParams
返回一个绑定参数键和值的字典。
attribute current_executable
返回当前正在编译的“可执行”。
当前正在编译的是Select、Insert、Update、Delete、CompoundSelect对象。具体来说，它被分配给self.stack元素列表。
当编译类似上述语句时，通常也会分配给Compiler对象的.statement属性。然而，所有 SQL 构造最终都是可嵌套的，visit_方法永远不应该查询此属性，因为不能保证已分配，也不能保证与当前正在编译的语句对应。
自版本 1.3.21 起新增：为了与旧版本兼容，请使用以下方法：
statement = getattr(self, "current_executable", False) if statement is False: statement = self.stack[-1]["selectable"]
对于 1.4 及以上版本，请确保仅使用.current_executable；“self.stack”的格式可能会更改。
method default_from()
当 SELECT 语句没有 froms，并且不需要附加 FROM 子句时调用。
给 Oracle 一个机会将FROM DUAL附加到字符串输出中。
method delete_extra_from_clause(update_stmt, from_table, extra_froms, from_hints, **kw)
提供一个钩子来覆盖生成 DELETE…FROM 子句。
这可以用来实现 DELETE…USING 等。
MySQL 和 MSSQL 会覆盖此方法。
attribute effective_returning
INSERT、UPDATE 或 DELETE 的有效“返回”列。
这是所谓的“隐式返回”列，编译器根据需要在运行时计算的列，或者基于self.statement._returning中存在的列（使用._all_selected_columns属性展开为单独的列），即使用UpdateBase.returning()方法明确设置的列。
自版本 2.0 起新增。
attribute escaped_bind_names: util.immutabledict[str, str] = {}
晚期转义绑定参数名称，必须在查看参数字典时转换为原始名称。
method get_select_precolumns(select, **kw)
在构建SELECT语句时调用，位置位于列列表之前。
method group_by_clause(select, **kw)
允许方言自定义如何渲染 GROUP BY。
attribute has_out_parameters = False
如果为 True，则存在具有 isoutparam 标志设置的 bindparam() 对象。
attribute implicit_returning: Sequence[ColumnElement[Any]] | None = None
用于顶级 INSERT 或 UPDATE 语句的“隐式”返回列的列表，用于接收新生成的列值。
从版本 2.0 开始：implicit_returning 替换了先前的 returning 集合，后者不是一个通用的 RETURNING 集合，而实际上是特定于“隐式返回”功能的。
attribute insert_prefetch: Sequence[Column[Any]] = ()
列表，应在执行 INSERT 之前评估默认值的列。
attribute insert_single_values_expr
当 INSERT 与一个参数集合编译到一个 VALUES 表达式内时，该字符串被分配在此处，可以在插入批处理方案中用于重写 VALUES 表达式。
从版本 1.3.8 开始。
从版本 2.0 开始更改：此集合不再由 SQLAlchemy 内置方言使用，而是使用仅由 SQLCompiler 内部当前使用的 _insertmanyvalues 集合。
attribute isupdate: bool = False
类级别的默认值，可以在实例级别设置以定义此 Compiled 实例是否表示 INSERT/UPDATE/DELETE。
attribute literal_execute_params: FrozenSet[BindParameter[Any]] = frozenset({})
在语句执行时将渲染为文字值的 bindparameter 对象。
method order_by_clause(select, **kw)
允许方言定制如何呈现 ORDER BY。
attribute params
返回嵌入到此编译对象中的绑定参数字典，用于那些存在的值。
另请参阅
如何将 SQL 表达式呈现为字符串，可能包含内联的绑定参数？ - 包含用于调试用例的用法示例。
attribute positiontup: List[str] | None = None
对于使用位置参数风格的已编译构造，将是一个字符串序列，指示按顺序绑定参数的名称。
用于以正确顺序呈现绑定参数，并与 Compiled.params 字典结合使用以呈现参数。
此序列始终包含参数的未转义名称。
另请参阅
如何将 SQL 表达式呈现为字符串，可能包含内联的绑定参数？ - 包含用于调试用例的用法示例。
attribute post_compile_params: FrozenSet[BindParameter[Any]] = frozenset({})
在语句执行时将呈现为绑定参数占位符的 bindparameter 对象。
attribute postfetch: List[Column[Any]] | None
列表，可在 INSERT 或 UPDATE 后进行后提取以接收服务器更新的值。
attribute postfetch_lastrowid = False
如果为 True，并且这是插入操作，则使用 cursor.lastrowid 来填充 result.inserted_primary_key。
method render_literal_value(value, type_)
将绑定参数的值呈现为带引号的文字。
这用于目标驱动程序/数据库上不接受绑定参数的语句部分。
应由子类使用 DBAPI 的引用服务来实现此功能。
attribute render_table_with_column_in_update_from: bool = False
设置为 True 可以类别地表示多表 UPDATE 语句中的 SET 子句应该使用表名限定列（即仅适用于 MySQL）。
attribute returning
向后兼容性；返回有效的返回集合。
attribute returning_precedes_values: bool = False
设置为 True 可以类别地在 VALUES 或 WHERE 子句之前生成 RETURNING 子句（即 MSSQL）。
attribute sql_compiler
attribute stack: List[_CompilerStackEntry]
如 SELECT、INSERT、UPDATE、DELETE 等主要语句使用条目格式在此堆栈中进行跟踪。
attribute translate_select_structure: Any = None
如果不是 None，应该是一个可调用对象，接受 (select_stmt, **kw) 并返回一个 select 对象。这主要用于结构性变更，主要是为了适应 LIMIT/OFFSET 方案。
method update_from_clause(update_stmt, from_table, extra_froms, from_hints, **kw)
提供一个钩子来覆盖生成 UPDATE…FROM 子句。
MySQL 和 MSSQL 覆盖此项。
method update_limit_clause(update_stmt)
为 MySQL 提供一个钩子以在 UPDATE 中添加 LIMIT
attribute update_prefetch: Sequence[Column[Any]] = ()
在 UPDATE 发生之前应评估 onupdate 默认值的列列表
method update_tables_clause(update_stmt, from_table, extra_froms, **kw)
提供一个钩子来覆盖 UPDATE 语句中的初始表子句。
MySQL 覆盖此项。
method visit_override_binds(override_binds, **kw)
SQL 编译 OverrideBinds 的嵌套元素，并交换绑定参数。
OverrideBinds 通常不会被编译；它的使用是指当已经缓存的语句要被使用时，编译已经执行过，只需在执行时交换绑定参数。
然而，有测试用例会使用这个对象，而且 ORM 子查询加载器已知会在新查询中添加包含此结构的表达式（在 #11173 中发现），所以它也必须在编译时做正确的事情。
class sqlalchemy.sql.compiler.StrSQLCompiler
SQLCompiler 的一个子类，允许一小部分非标准 SQL 功能渲染为字符串值。
当 Core 表达式元素直接字符串化而不调用 ClauseElement.compile() 方法时，将调用 StrSQLCompiler。它可以渲染一组有限的非标准 SQL 构造以协助基本字符串化，但是对于更重要的自定义或方言特定的 SQL 构造，需要直接使用 ClauseElement.compile()。
另请参阅
如何将 SQL 表达式呈现为字符串，可能还包含内联的绑定参数？
成员
delete_extra_from_clause()，update_from_clause()
类签名
类 sqlalchemy.sql.compiler.StrSQLCompiler（sqlalchemy.sql.compiler.SQLCompiler）。
method delete_extra_from_clause(update_stmt, from_table, extra_froms, from_hints, **kw)
提供一个钩子来覆盖生成 DELETE…FROM 子句。
这可用于实现 DELETE…USING 等。
MySQL 和 MSSQL 覆盖此项。
method update_from_clause(update_stmt, from_table, extra_froms, from_hints, **kw)
提供一个钩子来覆盖生成 UPDATE…FROM 子句。
MySQL 和 MSSQL 覆盖此项。
class sqlalchemy.engine.AdaptedConnection
支持 DBAPI 协议的适配连接对象的接口。
用于 asyncio 方言，以在驱动程序提供的 asyncio 连接/游标 API 之上提供同步风格的 pep-249 门面。
成员
driver_connection, run_async()
版本 1.4.24 中的新功能。
attribute driver_connection
连接对象是驱动程序在连接后返回的对象。
method run_async(fn: Callable[[Any], Awaitable[_T]]) → _T
运行给定函数返回的可等待对象，该函数接收原始的 asyncio 驱动程序连接。
用于在“同步”方法的上下文中调用驱动程序连接上的仅可等待方法，例如连接池事件处理程序。
例如：
engine = create_async_engine(...) @event.listens_for(engine.sync_engine, "connect") def register_custom_types(dbapi_connection, ...): dbapi_connection.run_async( lambda connection: connection.set_type_codec( 'MyCustomType', encoder, decoder, ... ) )
版本 1.4.30 中的新功能。
另请参见
在连接池和其他事件中使用仅可等待的驱动程序方法
