核心异常¶

SQLAlchemy 使用的异常。

基本异常类是 SQLAlchemyError。由于 DBAPI 异常而引发的异常都是 DBAPIError 的子类。

异常 sqlalchemy.exc.AmbiguousForeignKeysError¶: 当在两个 selectable 对象之间可以找到多个匹配的外键以进行连接时引发。

类签名

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

异常 sqlalchemy.exc.ArgumentError¶

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

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

类签名

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

异常 sqlalchemy.exc.AwaitRequired¶: 如果异步 greenlet 生成在需要异步操作时没有等待异步操作，则会引发错误。

类签名

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

异常 sqlalchemy.exc.Base20DeprecationWarning¶

针对 SQLAlchemy 2.0 中明确弃用或遗留的 API 的使用而发出。

另请参阅

SQLAlchemy 2.0 中的 <某个函数> 将不再 <某事>.

SQLAlchemy 2.0 弃用模式

类签名

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

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

异常 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)

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

异常 sqlalchemy.exc.CompileError¶: 在 SQL 编译期间发生错误时引发

类签名

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

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

2.0 版本新增。

类签名

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

异常 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)

方法 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)¶

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

类签名

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

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

类签名

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

异常 sqlalchemy.exc.DisconnectionError¶

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

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

类签名

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

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

类 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!")

异常 sqlalchemy.exc.DuplicateColumnError¶: 正在将 Column 添加到 Table，这将替换另一个 Column，但没有适当的参数来允许就地替换。

2.0.0b4 版本新增。

类签名

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

类 sqlalchemy.exc.HasDescriptionCode¶: helper，它添加 ‘code’ 作为属性，并添加 ‘_code_str’ 作为方法

异常 sqlalchemy.exc.IdentifierError¶: 当模式名称超出最大字符限制时引发

类签名

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

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

2.0 版本新增。

类签名

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

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

类签名

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

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

类签名

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

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

类签名

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

异常 sqlalchemy.exc.InvalidRequestError¶

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

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

类签名

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

异常 sqlalchemy.exc.InvalidatePoolError¶

当连接池应使所有过时连接失效时引发。

是 DisconnectionError 的子类，指示连接上遇到的断开连接情况可能意味着整个池应失效，因为数据库已重新启动。

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

1.2 版本新增。

类签名

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

异常 sqlalchemy.exc.LegacyAPIWarning¶: 指示处于 “遗留” 状态的 API，这是一个长期弃用。

类签名

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

异常 sqlalchemy.exc.MissingGreenlet¶: 如果异步 greenlet await_ 在未在 greenlet 生成上下文中调用时引发错误。

类签名

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

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

类签名

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

异常 sqlalchemy.exc.MultipleResultsFound¶: 需要单个数据库结果，但找到了多个结果。

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

类签名

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

异常 sqlalchemy.exc.NoForeignKeysError¶: 当在两个 selectable 对象之间找不到外键以进行连接时引发。

类签名

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

异常 sqlalchemy.exc.NoInspectionAvailable¶: 传递给 sqlalchemy.inspection.inspect() 的主题没有产生用于检查的上下文。

类签名

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

异常 sqlalchemy.exc.NoReferenceError¶: 由 ForeignKey 引发，以指示无法解析引用。

类签名

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

异常 sqlalchemy.exc.NoReferencedColumnError¶

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

类签名

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

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

异常 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。

类签名

class sqlalchemy.exc.NotSupportedError (sqlalchemy.exc.DatabaseError)

exception sqlalchemy.exc.ObjectNotExecutableError¶

当传递给 .execute() 的对象无法作为 SQL 执行时引发。

类签名

class sqlalchemy.exc.ObjectNotExecutableError (sqlalchemy.exc.ArgumentError)

method sqlalchemy.exc.ObjectNotExecutableError.__init__(target: Any)¶

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

类签名

class sqlalchemy.exc.OperationalError (sqlalchemy.exc.DatabaseError)

exception sqlalchemy.exc.PendingRollbackError¶: 事务失败，需要回滚才能继续。

1.4 版本新增。

类签名

class sqlalchemy.exc.PendingRollbackError (sqlalchemy.exc.InvalidRequestError)

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

类签名

class sqlalchemy.exc.ProgrammingError (sqlalchemy.exc.DatabaseError)

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

类签名

class sqlalchemy.exc.ResourceClosedError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.SADeprecationWarning¶

为使用已弃用的 API 而发出。

类签名

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

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

exception sqlalchemy.exc.SAPendingDeprecationWarning¶

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

类签名

class sqlalchemy.exc.SAPendingDeprecationWarning (builtins.PendingDeprecationWarning)

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

exception sqlalchemy.exc.SATestSuiteWarning¶

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

目前在 SAWarning 之外，以便我们可以解决像 Alembic 这样的工具对警告处理不当的问题。

类签名

class sqlalchemy.exc.SATestSuiteWarning (builtins.Warning)

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

类签名

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

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

类签名

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

exception sqlalchemy.exc.StatementError¶

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

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

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

类签名

class sqlalchemy.exc.StatementError (sqlalchemy.exc.SQLAlchemyError)

method 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)¶

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

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

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

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

exception sqlalchemy.exc.TimeoutError¶: 当连接池在获取连接时超时引发。

类签名

class sqlalchemy.exc.TimeoutError (sqlalchemy.exc.SQLAlchemyError)

exception sqlalchemy.exc.UnboundExecutionError¶: 尝试执行 SQL，但没有数据库连接。

类签名

class sqlalchemy.exc.UnboundExecutionError (sqlalchemy.exc.InvalidRequestError)

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

1.2 版本新增。

类签名

class sqlalchemy.exc.UnreflectableTableError (sqlalchemy.exc.InvalidRequestError)

exception sqlalchemy.exc.UnsupportedCompilationError¶

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

另请参阅

如何将 SQL 表达式渲染为字符串，可能内联绑定参数？

编译器 StrSQLCompiler 无法渲染 <element type> 类型的元素

类签名

class sqlalchemy.exc.UnsupportedCompilationError (sqlalchemy.exc.CompileError)

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

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy Core

项目版本

核心异常¶