SqlAlchemy 2.0 中文文档（四十七）（4）

SqlAlchemy 2.0 中文文档（四十七）（3）https://developer.aliyun.com/article/1563047

成员

init(), cache_key, compile_state, construct_params(), dml_compile_state, execution_options, params, sql_compiler, state, statement, string

Compiled对象的__str__方法应生成语句的实际文本。Compiled对象特定于其底层数据库方言，并且可能特定于在特定绑定参数集中引用的列。在任何情况下，Compiled对象都不应依赖于这些绑定参数的实际值，即使它可能引用这些值作为默认值。

method __init__(dialect: Dialect, statement: ClauseElement | None, schema_translate_map: SchemaTranslateMapType | None = None, render_schema_translate: bool = False, compile_kwargs: Mapping[str, Any] = {})

构造一个新的Compiled对象。

参数：

• dialect – 编译的Dialect。
  
• statement – 要编译的ClauseElement。
  
• schema_translate_map –
  模式名称的字典，用于在形成结果 SQL 时进行翻译
  另请参阅
  模式名称的翻译
  
• compile_kwargs – 将传递给初始调用Compiled.process()的额外 kwargs。
  

attribute cache_key: CacheKey | None = None

创建此Compiled对象之前生成的CacheKey。

用于需要访问在首次缓存Compiled实例时生成的原始CacheKey实例的例程，通常是为了将原始的BindParameter对象列表与在每次调用时生成的每个语句列表进行对比。

attribute compile_state: CompileState | None = None

可选的CompileState对象，用于维护编译器使用的其他状态。

主要的可执行对象，例如Insert、Update、Delete、Select在编译时会生成此状态，以计算关于对象的其他信息。对于要执行的顶级对象，可以将状态存储在此处，也可以适用于结果集处理。

版本 1.4 中的新功能。

method construct_params(params: _CoreSingleExecuteParams | None = None, extracted_parameters: Sequence[BindParameter[Any]] | None = None, escape_names: bool = True) → _MutableCoreSingleExecuteParams | None

返回此编译对象的绑定参数。

参数：

params – 一个字符串/对象对的字典，其值将覆盖编译到语句中的绑定值。

attribute dml_compile_state: CompileState | None = None

可选的CompileState在分配.isinsert、.isupdate或.isdelete时分配。

这通常将是与.compile_state相同的对象，但有一种例外情况，例如ORMFromStatementCompileState对象。

版本 1.4.40 中的新功能。

attribute execution_options: _ExecuteOptions = {}

从语句传播的执行选项。在某些情况下，语句的子元素可以修改这些选项。

attribute params

返回此已编译对象的绑定参数。

attribute sql_compiler

返回一个能够处理 SQL 表达式的已编译对象。

如果此编译器是一个，那么它很可能只返回‘self’。

attribute state: CompilerState

编译器状态的描述

attribute statement: ClauseElement | None = None

要编译的语句。

attribute string: str = ''

statement的字符串表示

class sqlalchemy.engine.interfaces.DBAPIConnection

表示PEP 249数据库连接的协议。

版本 2.0 中的新内容。

另请参见

连接对象 - 在PEP 249中

成员

自动提交，close()，commit()，cursor()，rollback()

类签名

类sqlalchemy.engine.interfaces.DBAPIConnection（typing_extensions.Protocol）

attribute autocommit: bool

method close() → None

method commit() → None

method cursor() → DBAPICursor

method rollback() → None
• 1

class sqlalchemy.engine.interfaces.DBAPICursor

表示PEP 249数据库游标的协议。

版本 2.0 中的新内容。

另请参见

游标对象 - 在PEP 249中

成员

数组大小，callproc()，close()，description，execute()，executemany()，fetchall()，fetchmany()，fetchone()，lastrowid，nextset()，rowcount，setinputsizes()，setoutputsize()

类签名

类sqlalchemy.engine.interfaces.DBAPICursor（typing_extensions.Protocol）

attribute arraysize: int

method callproc(procname: str, parameters: Sequence[Any] = Ellipsis) → Any

method close() → None

attribute description

游标的描述属性。

另请参见

cursor.description - 在PEP 249中

method execute(operation: Any, parameters: Sequence[Any] | Mapping[str, Any] | None = None) → Any

method executemany(operation: Any, parameters: Sequence[Sequence[Any]] | Sequence[Mapping[str, Any]]) → Any

method fetchall() → Sequence[Any]

method fetchmany(size: int = Ellipsis) → Sequence[Any]

method fetchone() → Any | None

attribute lastrowid: int

method nextset() → bool | None

attribute rowcount

method setinputsizes(sizes: Sequence[Any]) → None

method setoutputsize(size: Any, column: Any) → None

class sqlalchemy.engine.interfaces.DBAPIType

表示PEP 249数据库类型的协议。

版本 2.0 中的新内容。

另请参见

类型对象 - 在 PEP 249

类签名

类 sqlalchemy.engine.interfaces.DBAPIType (typing_extensions.Protocol) 的定义

class sqlalchemy.sql.compiler.DDLCompiler

成员

__init__(), cache_key, compile_state, construct_params(), define_constraint_remote_table(), dml_compile_state, execution_options, params, sql_compiler, state, statement, string

类签名

类 sqlalchemy.sql.compiler.DDLCompiler（sqlalchemy.sql.compiler.Compiled的一个子类）

method __init__(dialect: Dialect, statement: ClauseElement | None, schema_translate_map: SchemaTranslateMapType | None = None, render_schema_translate: bool = False, compile_kwargs: Mapping[str, Any] = {})

继承自 Compiled 的 sqlalchemy.sql.compiler.Compiled.__init__ 方法

构造一个新的 Compiled 对象。

参数:

• dialect – 要编译的 Dialect。
  
• statement – 待编译的 ClauseElement。
  
• schema_translate_map –
  用于形成生成 SQL 时要翻译的模式名称字典
  另请参见
  模式名称的翻译
  
• compile_kwargs – 将传递给初始调用 Compiled.process() 的额外 kwargs。
  

attribute cache_key: CacheKey | None = None

继承自 Compiled 的 Compiled.cache_key 属性

生成此 Compiled 对象之前生成的 CacheKey。

这用于需要访问在首次缓存Compiled实例时生成的原始CacheKey实例的例程，通常是为了调和原始的BindParameter对象列表与每次调用时生成的每个语句列表。

attribute compile_state: CompileState | None = None

继承自 Compiled 的 Compiled.compile_state 属性

可选的 CompileState 对象，用于维护编译器使用的其他状态。

主要的可执行对象，如Insert、Update、Delete、Select，在编译时会生成此状态，以计算有关对象的其他信息。对于要执行的顶级对象，该状态可以存储在这里，也可以适用于结果集处理。

1.4 版中的新功能。

method construct_params(params: _CoreSingleExecuteParams | None = None, extracted_parameters: Sequence[BindParameter[Any]] | None = None, escape_names: bool = True) → _MutableCoreSingleExecuteParams | None

返回此编译对象的绑定参数。

参数：

params – 一个字符串/对象对的字典，其值将覆盖编译到语句中的绑定值。

method define_constraint_remote_table(constraint, table, preparer)

格式化 CREATE CONSTRAINT 语句的远程表子句。

attribute dml_compile_state: CompileState | None = None

继承自 Compiled 的 Compiled.dml_compile_state 属性

在分配 .isinsert、.isupdate 或 .isdelete 的相同点分配的可选的 CompileState。

这通常是与 .compile_state 相同的对象，但有一些例外情况，比如 ORMFromStatementCompileState 对象。

1.4.40 版中的新功能。

attribute execution_options: _ExecuteOptions = {}

继承自 Compiled 的 Compiled.execution_options 属性

语句中传播的执行选项。在某些情况下，语句的子元素可以修改这些选项。

attribute params

继承自 Compiled 的 Compiled.params 属性

返回此编译对象的绑定参数。

attribute sql_compiler

attribute state: CompilerState

编译器状态的描述

attribute statement: ClauseElement | None = None

继承自 Compiled 的 Compiled.statement 属性

要编译的语句。

attribute string: str = ''

继承自 Compiled 的 Compiled.string 属性

statement 的字符串表示

class sqlalchemy.engine.default.DefaultDialect

Dialect 的默认实现

成员

bind_typing, colspecs, connect(), construct_arguments, create_connect_args(), create_xid(), cte_follows_insert, dbapi, dbapi_exception_translation_map, ddl_compiler, default_isolation_level, default_metavalue_token, default_schema_name, default_sequence_base, delete_executemany_returning, delete_returning, delete_returning_multifrom, denormalize_name(), div_is_floordiv, do_begin(), do_begin_twophase(), do_close(), do_commit(), do_commit_twophase(), do_execute(), do_execute_no_params(), do_executemany(), do_ping(), do_prepare_twophase(), do_recover_twophase(), do_release_savepoint(), do_rollback(), do_rollback_to_savepoint(), do_rollback_twophase(), do_savepoint(), do_set_input_sizes(), do_terminate(), driver, engine_config_types, engine_created(), exclude_set_input_sizes, execute_sequence_format, execution_ctx_cls, favor_returning_over_lastrowid, full_returning, get_async_dialect_cls(), get_check_constraints(), get_columns(), get_default_isolation_level(), get_dialect_cls(), get_dialect_pool_class(), get_driver_connection(), get_foreign_keys(), get_indexes(), get_isolation_level(), get_isolation_level_values(), get_materialized_view_names(), get_multi_check_constraints(), get_multi_columns(), get_multi_foreign_keys(), get_multi_indexes(), get_multi_pk_constraint(), get_multi_table_comment(), get_multi_table_options(), get_multi_unique_constraints(), get_pk_constraint(), get_schema_names(), get_sequence_names(), get_table_comment(), get_table_names(), get_table_options(), get_temp_table_names(), get_temp_view_names(), get_unique_constraints(), get_view_definition(), get_view_names(), has_index(), has_schema(), has_sequence(), has_table(), has_terminate, identifier_preparer, import_dbapi(), include_set_input_sizes, initialize(), inline_comments, insert_executemany_returning, insert_executemany_returning_sort_by_parameter_order, insert_returning, insertmanyvalues_implicit_sentinel, insertmanyvalues_max_parameters, insertmanyvalues_page_size, is_async, is_disconnect(), label_length, load_provisioning(), loaded_dbapi, max_identifier_length, name, normalize_name(), on_connect(), on_connect_url(), paramstyle, positional, preexecute_autoincrement_sequences, preparer, reflection_options, reset_isolation_level(), returns_native_bytes, sequences_optional, server_side_cursors, server_version_info, set_connection_execution_options(), set_engine_execution_options(), set_isolation_level(), statement_compiler, supports_alter, supports_comments, supports_constraint_comments, supports_default_metavalue, supports_default_values, supports_empty_insert, supports_identity_columns, supports_multivalues_insert, supports_native_boolean, supports_native_decimal, supports_native_enum, supports_native_uuid, supports_sane_multi_rowcount, supports_sane_rowcount, supports_sane_rowcount_returning, supports_sequences, supports_server_side_cursors, supports_simple_order_by_label, supports_statement_cache, tuple_in_values, type_compiler, type_compiler_cls, type_compiler_instance, type_descriptor(), update_executemany_returning, update_returning, update_returning_multifrom, use_insertmanyvalues, use_insertmanyvalues_wo_returning

类签名

sqlalchemy.engine.default.DefaultDialect 类 (sqlalchemy.engine.interfaces.Dialect)

attribute bind_typing = 1

定义将类型信息传递给绑定参数的数据库和/或驱动程序的方法。

有关值，请参阅 BindTyping。

2.0 版本中新增。

attribute colspecs: MutableMapping[Type[TypeEngine[Any]], Type[TypeEngine[Any]]] = {}

从 sqlalchemy.types 映射到特定于方言类的子类的 TypeEngine 类字典。该字典仅适用于类级别，并且不是从方言实例本身访问的。

method connect(*cargs, **cparams)

使用此方言的 DBAPI 建立连接。

此方法的默认实现为：

def connect(self, *cargs, **cparams):
    return self.dbapi.connect(*cargs, **cparams)

*cargs, **cparams 参数直接从此方言的 Dialect.create_connect_args() 方法生成。

此方法可用于需要在从 DBAPI 获得新连接时执行程序化的每个连接步骤的方言。

参数：

• *cargs – 从 Dialect.create_connect_args() 方法返回的位置参数
  
• **cparams – 从 Dialect.create_connect_args() 方法返回的关键字参数。
  

返回：

一个 DBAPI 连接，通常来自于 PEP 249 模块级别的 .connect() 函数。

另请参阅

Dialect.create_connect_args()

Dialect.on_connect()

attribute construct_arguments: List[Tuple[Type[SchemaItem | ClauseElement], Mapping[str, Any]]] | None = None

继承自 Dialect 的 Dialect.construct_arguments 属性

各种 SQLAlchemy 构造的可选参数说明，通常是模式项。

要实现，将其建立为元组的系列，如下所示：

construct_arguments = [
    (schema.Index, {
        "using": False,
        "where": None,
        "ops": None
    })
]

如果以上结构在 PostgreSQL 方言上建立，则 Index 结构现在将接受关键字参数 postgresql_using、postgresql_where 和 postgresql_ops。构造函数中以 postgresql_ 为前缀的任何其他参数都将引发 ArgumentError。

不包括construct_arguments成员的方言将不参与参数验证系统。对于这样的方言，任何参数名称都被所有参与的构造接受，在以该方言名称为前缀的参数命名空间内。这里的原理是，尚未实现此功能的第三方方言将继续以旧方式运行。

另请参阅

DialectKWArgs - 实现基类，它消耗DefaultDialect.construct_arguments

method create_connect_args(url)

构建 DB-API 兼容的连接参数。

给定一个URL对象，返回一个包含(*args, **kwargs)的元组，适合直接发送到 dbapi 的 connect 函数。这些参数被发送到Dialect.connect()方法，然后运行 DBAPI 级别的connect()函数。

该方法通常利用URL.translate_connect_args()方法生成一个选项字典。

默认实现为：

def create_connect_args(self, url):
    opts = url.translate_connect_args()
    opts.update(url.query)
    return ([], opts)

参数：

url – 一个URL对象

返回：

一个将传递给Dialect.connect()方法的(*args, **kwargs)元组。

另请参阅

URL.translate_connect_args()

method create_xid()

创建一个随机的两阶段事务 ID。

此 ID 将传递给 do_begin_twophase()、do_rollback_twophase()、do_commit_twophase()。其格式未指定。

attribute cte_follows_insert: bool = False

给定 CTE 和 INSERT 语句时的目标数据库，需要 CTE 在 INSERT 语句之下。

attribute dbapi: ModuleType | None

DBAPI 模块对象本身的引用。

SQLAlchemy 方言使用 classmethod Dialect.import_dbapi() 导入 DBAPI 模块。其原因是任何方言模块都可以被导入和用于生成 SQL 语句，而无需安装实际的 DBAPI 驱动程序。只有在使用create_engine()构造Engine时，DBAPI 才会被导入；此时，创建过程将把 DBAPI 模块分配给此属性。

因此，方言应实现 Dialect.import_dbapi()，它将导入必要的模块并返回它，然后在方言代码中引用 self.dbapi 以引用 DBAPI 模块内容。

版本更改：Dialect.dbapi 属性专门用作每个Dialect 实例对 DBAPI 模块的引用。以前未完全记录的 .Dialect.dbapi() 类方法已被弃用，并由 Dialect.import_dbapi() 替换。

attribute dbapi_exception_translation_map: Mapping[str, str] = {}

继承自 Dialect 的 Dialect.dbapi_exception_translation_map 属性

一个名称字典，其值将包含作为值的 pep-249 异常的名称（“IntegrityError”、“OperationalError” 等），键入为替代类名，以支持 DBAPI 具有不以它们所引用的方式命名的异常类的情况（例如 IntegrityError = MyException）。在绝大多数情况下，此字典为空。

attribute ddl_compiler

DDLCompiler 的别名

attribute default_isolation_level: IsolationLevel | None

在新连接上隐含存在的隔离级别

attribute default_metavalue_token: str = 'DEFAULT'

对于 INSERT… VALUES (DEFAULT) 语法，括号中放置的令牌。

attribute default_schema_name: str | None = None

默认模式的名称。此值仅适用于支持的方言，并且通常在与数据库的初始连接期间填充。

attribute default_sequence_base: int = 1

将呈现为 CREATE SEQUENCE DDL 语句的“START WITH” 部分的默认值。

attribute delete_executemany_returning: bool = False

方言支持具有 executemany 的 DELETE…RETURNING。

attribute delete_returning: bool = False

如果方言支持带有 DELETE 的 RETURNING

版本 2.0 中的新功能。

attribute delete_returning_multifrom: bool = False

如果方言支持带有 DELETE…FROM 的 RETURNING

版本 2.0 中的新功能。

method denormalize_name(name)

如果给定的名称是全小写名称，则将其转换为后端的不区分大小写标识符。

此方法仅在方言定义 requires_name_normalize=True 时使用。

attribute div_is_floordiv: bool = True

目标数据库将 / 除法运算符视为“地板除法”

method do_begin(dbapi_connection)

提供给定 DB-API 连接的 connection.begin() 实现。

DBAPI 没有专用的“开始”方法，预期事务是隐式的。此挂钩是为了那些可能需要在此领域提供额外帮助的 DBAPI 而提供的。

参数：

dbapi_connection – 一个 DBAPI 连接，通常在 ConnectionFairy 中被代理。

method do_begin_twophase(connection: Connection, xid: Any) → None

继承自 Dialect 的 Dialect.do_begin_twophase() 方法

在给定连接上开始两阶段事务。

参数：

• connection – 一个 Connection。
  
• xid – xid
  

method do_close(dbapi_connection)

提供给定 DBAPI 连接的 connection.close() 实现。

当连接从池中分离或被返回超出池的正常容量时，将调用此钩子。

method do_commit(dbapi_connection)

提供 connection.commit() 的实现，给定一个 DB-API 连接。

参数：

dbapi_connection – 一个 DBAPI 连接，通常在 ConnectionFairy 中代理。

method do_commit_twophase(connection: Connection, xid: Any, is_prepared: bool = True, recover: bool = False) → None

继承自 Dialect 方法的 Dialect.do_commit_twophase()。

在给定连接上提交一个两阶段事务。

SqlAlchemy 2.0 中文文档（四十七）（5）https://developer.aliyun.com/article/1563051