核心异常¶

SQLAlchemy 中使用的异常。

基本异常类是 SQLAlchemyError。作为 DBAPI 异常结果而引发的异常都是 DBAPIError 的子类。

exception sqlalchemy.exc.AmbiguousForeignKeysError¶: 在联接过程中，如果在两个可选择项之间找到多个匹配的外键，则引发此异常。

类签名

class sqlalchemy.exc.AmbiguousForeignKeysError (sqlalchemy.exc.ArgumentError)

exception sqlalchemy.exc.ArgumentError¶

当提供无效或冲突的函数参数时引发此异常。

此错误通常对应于构造时间状态错误。

类签名

class sqlalchemy.exc.ArgumentError (sqlalchemy.exc.SQLAlchemyError)

exception sqlalchemy.exc.AwaitRequired¶: 如果异步 greenlet 生成器在需要异步操作时没有等待任何异步操作，则由它引发的错误。

类签名

class sqlalchemy.exc.AwaitRequired (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.Base20DeprecationWarning¶

用于 SQLAlchemy 2.0 中明确弃用或遗留 API 的用法。

另请参阅

SQLAlchemy 2.0 中的 <某个函数> 将不再 <某些行为>.

SQLAlchemy 2.0 弃用模式

类签名

class sqlalchemy.exc.Base20DeprecationWarning (sqlalchemy.exc.SADeprecationWarning)

attribute sqlalchemy.exc.Base20DeprecationWarning.deprecated_since: str | None = '1.4'¶: 指示开始引发此弃用警告的版本

exception sqlalchemy.exc.CircularDependencyError¶

在检测到循环依赖时，由拓扑排序引发。

此错误发生在两种情况下：

在 Session 刷新操作中，如果两个对象相互依赖，则它们无法仅通过 INSERT 或 DELETE 语句插入或删除；需要 UPDATE 来事后关联或事先解除关联其中一个外键约束值。指向自身的行/相互依赖的行中描述的 post_update 标志可以解决此循环。
在 MetaData.sorted_tables 操作中，两个 ForeignKey 或 ForeignKeyConstraint 对象相互引用。将 use_alter=True 标志应用于一个或两个，参见通过 ALTER 创建/删除外键约束。

类签名

class sqlalchemy.exc.CircularDependencyError (sqlalchemy.exc.SQLAlchemyError)

method sqlalchemy.exc.CircularDependencyError.__init__(message: str, cycles: Any, edges: Any, msg: str | None = None, code: str | None = None)¶

exception sqlalchemy.exc.CompileError¶: 在 SQL 编译过程中发生错误时引发此异常

类签名

class sqlalchemy.exc.CompileError (sqlalchemy.exc.SQLAlchemyError)

exception sqlalchemy.exc.ConstraintColumnNotFoundError¶: 当约束引用受约束表中不存在的字符串列名时引发。

版本 2.0 新增。

类签名

class sqlalchemy.exc.ConstraintColumnNotFoundError (sqlalchemy.exc.ArgumentError)

exception sqlalchemy.exc.DBAPIError¶

在数据库操作执行失败时引发此异常。

封装了数据库操作期间由底层 DB-API 引发的异常。在可能的情况下，标准 DB-API 异常类型的驱动程序特定实现将由 SQLAlchemy 的 DBAPIError 的匹配子类型进行封装。DB-API 的 Error 类型映射到 SQLAlchemy 中的 DBAPIError，否则名称相同。请注意，不能保证不同的 DB-API 实现会对任何给定的错误条件引发相同的异常类型。

DBAPIError 具有 StatementError.statement 和 StatementError.params 属性，这些属性提供了关于出现问题的语句细节的上下文，适用于在发出 SQL 语句的上下文中引发错误的典型情况。

封装的异常对象在 StatementError.orig 属性中可用。它的类型和属性是 DB-API 实现特定的。

类签名

class sqlalchemy.exc.DBAPIError (sqlalchemy.exc.StatementError)

method sqlalchemy.exc.DBAPIError.__init__(statement: str | None, params: _AnyExecuteParams | None, orig: BaseException, hide_parameters: bool = False, connection_invalidated: bool = False, code: str | None = None, ismulti: bool | None = None)¶

exception sqlalchemy.exc.DataError¶: 封装 DB-API DataError。

类签名

class sqlalchemy.exc.DataError (sqlalchemy.exc.DatabaseError)

exception sqlalchemy.exc.DatabaseError¶: 封装 DB-API DatabaseError。

类签名

class sqlalchemy.exc.DatabaseError (sqlalchemy.exc.DBAPIError)

exception sqlalchemy.exc.DisconnectionError¶

在原始 DB-API 连接上检测到断开连接。

此错误由连接池在内部引发并消耗。它可以在 PoolEvents.checkout() 事件中引发，以便主机池强制重试；在池放弃并引发有关连接尝试的 InvalidRequestError 之前，该异常将连续捕获三次。

类签名

class sqlalchemy.exc.DisconnectionError (sqlalchemy.exc.SQLAlchemyError)

对象名称	描述
DontWrapMixin	一个混合类，当应用于用户定义的异常类时，如果错误是在执行语句的过程中发出的，则不会封装在 `StatementError` 中。
HasDescriptionCode	帮助程序，它添加了“code”作为属性，并添加了“_code_str”作为方法。

class sqlalchemy.exc.DontWrapMixin¶

一个混合类，当应用于用户定义的异常类时，如果错误是在执行语句的过程中发出的，则不会封装在 StatementError 中。

例如：

from sqlalchemy.exc import DontWrapMixin

class MyCustomException(Exception, DontWrapMixin):
    pass

class MySpecialType(TypeDecorator):
    impl = String

    def process_bind_param(self, value, dialect):
        if value == 'invalid':
            raise MyCustomException("invalid!")

exception sqlalchemy.exc.DuplicateColumnError¶: 正在将一个 Column 添加到 Table 中，该 Column 将替换另一个 Column，但没有合适的参数允许在适当的位置进行添加。

版本 2.0.0b4 中的新增功能。

类签名

class sqlalchemy.exc.DuplicateColumnError (sqlalchemy.exc.ArgumentError)

class sqlalchemy.exc.HasDescriptionCode¶: 帮助程序，它添加了“code”作为属性，并添加了“_code_str”作为方法。

exception sqlalchemy.exc.IdentifierError¶: 当模式名称超过最大字符限制时引发。

类签名

class sqlalchemy.exc.IdentifierError (sqlalchemy.exc.SQLAlchemyError)

exception sqlalchemy.exc.IllegalStateChangeError¶: 跟踪状态的对象遇到某种非法状态更改。

版本 2.0 新增。

类签名

class sqlalchemy.exc.IllegalStateChangeError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.IntegrityError¶: 封装 DB-API IntegrityError。

类签名

class sqlalchemy.exc.IntegrityError (sqlalchemy.exc.DatabaseError)

exception sqlalchemy.exc.InterfaceError¶: 封装 DB-API InterfaceError。

类签名

class sqlalchemy.exc.InterfaceError (sqlalchemy.exc.DBAPIError)

exception sqlalchemy.exc.InternalError¶: 封装 DB-API InternalError。

类签名

class sqlalchemy.exc.InternalError (sqlalchemy.exc.DatabaseError)

exception sqlalchemy.exc.InvalidRequestError¶

SQLAlchemy 被要求做它无法做的事情。

此错误通常对应于运行时状态错误。

类签名

class sqlalchemy.exc.InvalidRequestError (sqlalchemy.exc.SQLAlchemyError)

exception sqlalchemy.exc.InvalidatePoolError¶

当连接池应该使所有陈旧连接失效时引发。

表示连接断开情况很可能意味着整个连接池应该失效的 DisconnectionError 的子类，因为数据库已重启。

此异常的处理方式与 DisconnectionError 相同，允许在放弃之前尝试重新连接三次。

版本 1.2 中的新增功能。

类签名

class sqlalchemy.exc.InvalidatePoolError (sqlalchemy.exc.DisconnectionError)

exception sqlalchemy.exc.LegacyAPIWarning¶: 表示处于“传统”状态的 API，长期弃用。

类签名

class sqlalchemy.exc.LegacyAPIWarning (sqlalchemy.exc.Base20DeprecationWarning)

exception sqlalchemy.exc.MissingGreenlet¶: 如果在 greenlet 生成上下文之外调用 async greenlet await_ 时引发的错误。

类签名

class sqlalchemy.exc.MissingGreenlet (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.MovedIn20Warning¶: RemovedIn20Warning 的子类型，用于指示仅移动的 API。

类签名

class sqlalchemy.exc.MovedIn20Warning (sqlalchemy.exc.Base20DeprecationWarning)

exception sqlalchemy.exc.MultipleResultsFound¶: 需要一个数据库结果，但找到多个结果。

版本 1.4 中的更改：此异常现在是 Core 中 sqlalchemy.exc 模块的一部分，从 ORM 中移出。该符号仍然可以从 sqlalchemy.orm.exc 中导入。

类签名

class sqlalchemy.exc.MultipleResultsFound (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.NoForeignKeysError¶: 在连接期间，在两个可选择项之间找不到任何外键时引发。

类签名

class sqlalchemy.exc.NoForeignKeysError (sqlalchemy.exc.ArgumentError)

exception sqlalchemy.exc.NoInspectionAvailable¶: 传递给 sqlalchemy.inspection.inspect() 的主体没有生成可检查的上下文。

类签名

class sqlalchemy.exc.NoInspectionAvailable (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.NoReferenceError¶: 由 ForeignKey 引发，表示无法解析引用。

类签名

class sqlalchemy.exc.NoReferenceError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.NoReferencedColumnError¶

当无法找到引用的 Column 时，由 ForeignKey 引发。

类签名

class sqlalchemy.exc.NoReferencedColumnError (sqlalchemy.exc.NoReferenceError)

method sqlalchemy.exc.NoReferencedColumnError.__init__(message: str, tname: str, cname: str)¶

exception sqlalchemy.exc.NoReferencedTableError¶

当无法找到引用的 Table 时，由 ForeignKey 引发。

类签名

class sqlalchemy.exc.NoReferencedTableError (sqlalchemy.exc.NoReferenceError)

method sqlalchemy.exc.NoReferencedTableError.__init__(message: str, tname: str)¶

exception sqlalchemy.exc.NoResultFound¶: 需要一个数据库结果，但未找到任何结果。

版本 1.4 中的更改：此异常现在是 Core 中 sqlalchemy.exc 模块的一部分，从 ORM 中移出。该符号仍然可以从 sqlalchemy.orm.exc 中导入。

类签名

class sqlalchemy.exc.NoResultFound (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.NoSuchColumnError¶: 从 Row 中请求不存在的列。

类签名

class sqlalchemy.exc.NoSuchColumnError (sqlalchemy.exc.InvalidRequestError, builtins.KeyError)

exception sqlalchemy.exc.NoSuchModuleError¶: 当无法找到特定名称的动态加载模块（通常是数据库方言）时引发。

类签名

class sqlalchemy.exc.NoSuchModuleError (sqlalchemy.exc.ArgumentError)

exception sqlalchemy.exc.NoSuchTableError¶: 表不存在或对连接不可见。

类签名

class sqlalchemy.exc.NoSuchTableError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.NotSupportedError¶: 包装 DB-API NotSupportedError。

类签名

类 sqlalchemy.exc.NotSupportedError (sqlalchemy.exc.DatabaseError)

异常 sqlalchemy.exc.ObjectNotExecutableError¶

当将无法以 SQL 形式执行的对象传递给 .execute() 时引发。

类签名

类 sqlalchemy.exc.ObjectNotExecutableError (sqlalchemy.exc.ArgumentError)

方法 sqlalchemy.exc.ObjectNotExecutableError.__init__(target: Any)¶

异常 sqlalchemy.exc.OperationalError¶: 包装 DB-API OperationalError。

类签名

类 sqlalchemy.exc.OperationalError (sqlalchemy.exc.DatabaseError)

异常 sqlalchemy.exc.PendingRollbackError¶: 事务失败，需要在继续之前回滚。

版本 1.4 中新增。

类签名

类 sqlalchemy.exc.PendingRollbackError (sqlalchemy.exc.InvalidRequestError)

异常 sqlalchemy.exc.ProgrammingError¶: 包装 DB-API ProgrammingError。

类签名

类 sqlalchemy.exc.ProgrammingError (sqlalchemy.exc.DatabaseError)

异常 sqlalchemy.exc.ResourceClosedError¶: 从处于关闭状态的连接、游标或其他对象请求操作。

类签名

类 sqlalchemy.exc.ResourceClosedError (sqlalchemy.exc.InvalidRequestError)

异常 sqlalchemy.exc.SADeprecationWarning¶

针对使用已弃用的 API 发出。

类签名

类 sqlalchemy.exc.SADeprecationWarning (sqlalchemy.exc.HasDescriptionCode, builtins.DeprecationWarning)

属性 sqlalchemy.exc.SADeprecationWarning.deprecated_since: str | None = None¶: 指示开始引发此弃用警告的版本

异常 sqlalchemy.exc.SAPendingDeprecationWarning¶

与 SADeprecationWarning 类似的警告，此警告在现代版本的 SQLAlchemy 中未使用。

类签名

类 sqlalchemy.exc.SAPendingDeprecationWarning (builtins.PendingDeprecationWarning)

属性 sqlalchemy.exc.SAPendingDeprecationWarning.deprecated_since: str | None = None¶: 指示开始引发此弃用警告的版本

异常 sqlalchemy.exc.SATestSuiteWarning¶

测试期间检测到的非致命条件的警告

目前位于 SAWarning 之外，以便我们可以解决 Alembic 等工具对警告处理不当的问题。

类签名

类 sqlalchemy.exc.SATestSuiteWarning (builtins.Warning)

异常 sqlalchemy.exc.SAWarning¶: 在运行时发出。

类签名

类 sqlalchemy.exc.SAWarning (sqlalchemy.exc.HasDescriptionCode, builtins.RuntimeWarning)

异常 sqlalchemy.exc.SQLAlchemyError¶: 通用错误类。

类签名

类 sqlalchemy.exc.SQLAlchemyError (sqlalchemy.exc.HasDescriptionCode, builtins.Exception)

异常 sqlalchemy.exc.StatementError¶

在执行 SQL 语句期间发生错误。

StatementError 包装执行期间引发的异常，并提供 statement 和 params 属性，这些属性提供了有关出现问题的语句的具体信息。

包装的异常对象在 orig 属性中可用。

类签名

类 sqlalchemy.exc.StatementError (sqlalchemy.exc.SQLAlchemyError)

方法 sqlalchemy.exc.StatementError.__init__(message: str, statement: str | None, params: _AnyExecuteParams | None, orig: BaseException | None, hide_parameters: bool = False, code: str | None = None, ismulti: bool | None = None)¶

属性 sqlalchemy.exc.StatementError.ismulti: bool | None = None¶: 传递给 repr_params() 的多参数。None 有意义。

属性 sqlalchemy.exc.StatementError.orig: BaseException | None = None¶: 抛出的原始异常。

属性 sqlalchemy.exc.StatementError.params: _AnyExecuteParams | None = None¶: 此异常发生时使用的参数列表。

属性 sqlalchemy.exc.StatementError.statement: str | None = None¶: 此异常发生时正在调用的字符串 SQL 语句。

异常 sqlalchemy.exc.TimeoutError¶: 连接池获取连接超时时引发。

类签名

类 sqlalchemy.exc.TimeoutError (sqlalchemy.exc.SQLAlchemyError)

异常 sqlalchemy.exc.UnboundExecutionError¶: 在没有数据库连接的情况下尝试执行 SQL。

类签名

类 sqlalchemy.exc.UnboundExecutionError (sqlalchemy.exc.InvalidRequestError)

异常 sqlalchemy.exc.UnreflectableTableError¶: 表存在，但由于某种原因无法反射。

版本 1.2 中的新增功能。

类签名

类 sqlalchemy.exc.UnreflectableTableError (sqlalchemy.exc.InvalidRequestError)

异常 sqlalchemy.exc.UnsupportedCompilationError¶

当给定编译器不支持操作时引发。

另请参阅

如何将 SQL 表达式呈现为字符串，可能包含内联的绑定参数？

编译器 StrSQLCompiler 无法呈现类型为 <元素类型> 的元素

类签名

类 sqlalchemy.exc.UnsupportedCompilationError (sqlalchemy.exc.CompileError)

方法 sqlalchemy.exc.UnsupportedCompilationError.__init__(compiler: Compiled | TypeCompiler, element_type: Type[ClauseElement], message: str | None = None)¶

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy Core

项目版本

核心异常¶