类映射 API¶

对象名称	描述
add_mapped_attribute(target, key, attr)	向 ORM 映射类添加新的映射属性。
as_declarative(**kw)	类装饰器，用于将给定类适配为 `declarative_base()`。
class_mapper(class_[, configure])	给定一个类，返回与键关联的主 `Mapper`。
clear_mappers()	从所有类中删除所有映射器。
column_property(column, *additional_columns, [group, deferred, raiseload, comparator_factory, init, repr, default, default_factory, compare, kw_only, hash, active_history, expire_on_flush, info, doc])	提供列级属性以用于映射。
configure_mappers()	初始化到目前为止在所有 `registry` 集合中构建的所有映射器的映射器间关系。
declarative_base(*, [metadata, mapper, cls, name, class_registry, type_annotation_map, constructor, metaclass])	为声明式类定义构造基类。
declarative_mixin(cls)	将类标记为提供“声明式 mixin”功能。
DeclarativeBase	用于声明式类定义的基类。
DeclarativeBaseNoMeta	与 `DeclarativeBase` 相同，但不使用元类来拦截新属性。
declared_attr	将类级别方法标记为表示映射属性或声明式指令的定义。
has_inherited_table(cls)	给定一个类，如果它继承的任何类具有映射表，则返回 True，否则返回 False。
identity_key([class_, ident], *, [instance, row, identity_token])	生成“标识键”元组，就像在 `Session.identity_map` 字典中用作键一样。
mapped_column([__name_pos, __type_pos], args, [init, repr, default, default_factory, compare, kw_only, hash, nullable, primary_key, deferred, deferred_group, deferred_raiseload, use_existing_column, name, type_, autoincrement, doc, key, index, unique, info, onupdate, insert_default, server_default, server_onupdate, active_history, quote, system, comment, sort_order], *kw)	声明一个新的 ORM 映射的 `Column` 构造，用于声明式表配置中。
MappedAsDataclass	Mixin 类，指示何时映射此类，同时将其转换为数据类。
MappedClassProtocol	表示 SQLAlchemy 映射类的协议。
Mapper	定义 Python 类和数据库表或其他关系结构之间的关联，以便可以进行针对该类的 ORM 操作。
object_mapper(instance)	给定一个对象，返回与该对象实例关联的主 Mapper。
orm_insert_sentinel([name, type_], *, [default, omit_from_statements])	提供代理 `mapped_column()`，它生成所谓的哨兵列，允许对没有其他合格主键配置的表进行高效批量插入，并具有确定性的 RETURNING 排序。
polymorphic_union(table_map, typecolname[, aliasname, cast_nulls])	创建多态映射器使用的 `UNION` 语句。
reconstructor(fn)	将方法装饰为“重建器”钩子。
注册表	用于映射类的通用注册表。
synonym_for(name[, map_column])	装饰器，与 Python 描述符结合使用，生成 `synonym()` 属性。

class sqlalchemy.orm.registry¶

用于映射类的通用注册表。

registry 用作维护映射集合的基础，并提供用于映射类的配置钩子。

支持的三种通用映射类型是声明式基类、声明式装饰器和命令式映射。所有这些映射样式都可以互换使用

registry.generate_base() 返回一个新的声明式基类，并且是 declarative_base() 函数的底层实现。
registry.mapped() 提供了一个类装饰器，它将在不使用声明式基类的情况下将声明式映射应用于类。
registry.map_imperatively() 将为类生成 Mapper，而无需扫描类的声明式类属性。此方法适用于 sqlalchemy.orm.mapper() 经典映射函数提供的历史用例，该函数已在 SQLAlchemy 2.0 中删除。

1.4 版本新增。

成员

__init__(), as_declarative_base(), configure(), dispose(), generate_base(), map_declaratively(), map_imperatively(), mapped(), mapped_as_dataclass(), mappers, update_type_annotation_map()

另请参阅

ORM 映射类概述 - 类映射样式概述。

method sqlalchemy.orm.registry.__init__(*, metadata: Optional[MetaData] = None, class_registry: Optional[clsregistry._ClsRegistryType] = None, type_annotation_map: Optional[_TypeAnnotationMapType] = None, constructor: Callable[..., None] = <function _declarative_constructor>)¶

构造一个新的 registry

参数:

metadata¶ – 可选的 MetaData 实例。使用声明式表映射生成的所有 Table 对象都将使用此 MetaData 集合。如果此参数保留为默认值 None，则会创建一个空白的 MetaData 集合。
constructor¶ – 指定在没有自己的 __init__ 的映射类上 __init__ 函数的实现。默认为将 **kwargs 用于声明字段和关系分配给实例的实现。如果提供 None，则不会提供 __init__，并且构造将通过正常的 Python 语义回退到 cls.__init__。
class_registry¶ – 可选字典，当使用字符串名称来标识 relationship() 等中的类时，它将用作类名称->映射类的注册表。允许两个或多个声明式基类共享相同的类名称注册表，以简化基类间关系。
type_annotation_map¶ –
Python 类型到 SQLAlchemy TypeEngine 类或实例的可选字典。提供的字典将更新默认类型映射。这仅由 MappedColumn 构造使用，以根据 Mapped 类型中的注释生成列类型。

2.0 版本新增。

另请参阅

自定义类型映射

method sqlalchemy.orm.registry.as_declarative_base(**kw: Any) → Callable[[Type[_T]], Type[_T]]¶

类装饰器，它将为给定的基类调用 registry.generate_base()。

例如：

from sqlalchemy.orm import registry

mapper_registry = registry()


@mapper_registry.as_declarative_base()
class Base:
    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()

    id = Column(Integer, primary_key=True)


class MyMappedClass(Base): ...

传递给 registry.as_declarative_base() 的所有关键字参数都将传递给 registry.generate_base()。

method sqlalchemy.orm.registry.configure(cascade: bool = False) → None¶

配置此 registry 中所有尚未配置的映射器。

配置步骤用于协调和初始化映射类之间的 relationship() 链接，以及调用配置事件，例如 MapperEvents.before_configured() 和 MapperEvents.after_configured()，ORM 扩展或用户定义的扩展钩子可以使用它们。

如果此注册表中的一个或多个映射器包含引用其他注册表中的映射类的 relationship() 构造，则称此注册表依赖于这些注册表。为了自动配置这些依赖的注册表，应将 configure.cascade 标志设置为 True。否则，如果未配置它们，则会引发异常。此行为背后的基本原理是允许应用程序以编程方式调用注册表的配置，同时控制该过程是否隐式地访问其他注册表。

作为调用 registry.configure() 的替代方法，可以使用 ORM 函数 configure_mappers() 来确保完成所有内存中 registry 对象的配置。这通常更易于使用，并且也早于 registry 对象的总体使用。但是，此函数将影响整个正在运行的 Python 进程中的所有映射，并且对于具有许多用于可能不需要立即使用的不同目的的注册表的应用程序，可能会更耗内存/时间。

另请参阅

configure_mappers()

1.4.0b2 版本新增。

method sqlalchemy.orm.registry.dispose(cascade: bool = False) → None¶

处置此 registry 中的所有映射器。

调用后，在此注册表中映射的所有类将不再具有与其关联的类检测。此方法是应用程序范围的 clear_mappers() 函数的每个 registry 类似物。

如果此注册表包含其他注册表的依赖项的映射器（通常通过 relationship() 链接），则也必须处置这些注册表。当存在与此相关的此类注册表时，如果将 dispose.cascade 标志设置为 True，也会调用它们的 registry.dispose() 方法；否则，如果这些注册表尚未处置，则会引发错误。

1.4.0b2 版本新增。

另请参阅

clear_mappers

method sqlalchemy.orm.registry.generate_base(mapper: ~typing.Callable[[...], ~sqlalchemy.orm.mapper.Mapper[~typing.Any]] | None = None, cls: ~typing.Type[~typing.Any] = <class 'object'>, name: str = 'Base', metaclass: ~typing.Type[~typing.Any] = <class 'sqlalchemy.orm.decl_api.DeclarativeMeta'>) → Any¶

生成声明式基类。

从返回的类对象继承的类将使用声明式映射自动映射。

例如：

from sqlalchemy.orm import registry

mapper_registry = registry()

Base = mapper_registry.generate_base()


class MyClass(Base):
    __tablename__ = "my_table"
    id = Column(Integer, primary_key=True)

上面动态生成的类等效于下面的非动态示例

from sqlalchemy.orm import registry
from sqlalchemy.orm.decl_api import DeclarativeMeta

mapper_registry = registry()


class Base(metaclass=DeclarativeMeta):
    __abstract__ = True
    registry = mapper_registry
    metadata = mapper_registry.metadata

    __init__ = mapper_registry.constructor

在 2.0 版本中更改: 请注意，registry.generate_base() 方法已被新的 DeclarativeBase 类取代，后者使用子类化生成新的“基类”，而不是函数的返回值。这允许一种与 PEP 484 类型工具兼容的方法。

registry.generate_base() 方法为 declarative_base() 函数提供实现，该函数一次性创建 registry 和基类。

有关背景和示例，请参阅声明式映射部分。

参数:

mapper¶ – 可选的可调用对象，默认为 Mapper。此函数用于生成新的 Mapper 对象。
cls¶ – 默认为 object。用作生成的声明式基类的类型。可以是一个类或类元组。
name¶ – 默认为 Base。生成的类的显示名称。自定义此项不是必需的，但可以提高在回溯和调试中的清晰度。
metaclass¶ – 默认为 DeclarativeMeta。一个元类或 __metaclass__ 兼容的可调用对象，用作生成的声明式基类的元类型。

另请参阅

声明式映射

declarative_base()

method sqlalchemy.orm.registry.map_declaratively(cls: Type[_O]) → Mapper[_O]¶

以声明方式映射一个类。

在这种映射形式中，将扫描类以获取映射信息，包括要与表关联的列和/或实际的表对象。

返回 Mapper 对象。

例如：

from sqlalchemy.orm import registry

mapper_registry = registry()

class Foo:
    __tablename__ = "some_table"

    id = Column(Integer, primary_key=True)
    name = Column(String)

mapper = mapper_registry.map_declaratively(Foo)

此函数更方便的调用方式是通过 registry.mapped() 类装饰器或通过继承从 registry.generate_base() 生成的声明式元类。

有关完整详细信息和示例，请参见声明式映射部分。

参数:: cls¶ – 要映射的类。
返回:: 一个 Mapper 对象。

另请参阅

声明式映射

registry.mapped() - 此函数更常用的装饰器接口。

registry.map_imperatively()

method sqlalchemy.orm.registry.map_imperatively(class_: Type[_O], local_table: FromClause | None = None, **kw: Any) → Mapper[_O]¶

以命令方式映射一个类。

在这种映射形式中，不会扫描类以获取任何映射信息。相反，所有映射构造都作为参数传递。

此方法旨在与现已移除的 SQLAlchemy mapper() 函数完全等效，只是它基于特定的注册表。

例如：

from sqlalchemy.orm import registry

mapper_registry = registry()

my_table = Table(
    "my_table",
    mapper_registry.metadata,
    Column("id", Integer, primary_key=True),
)


class MyClass:
    pass


mapper_registry.map_imperatively(MyClass, my_table)

有关完整的背景和用法示例，请参见命令式映射部分。

参数:

class_¶ – 要映射的类。对应于 Mapper.class_ 参数。
local_table¶ – 作为映射主题的 Table 或其他 FromClause 对象。对应于 Mapper.local_table 参数。
**kw¶ – 所有其他关键字参数都直接传递给 Mapper 构造函数。

另请参阅

命令式映射

声明式映射

method sqlalchemy.orm.registry.mapped(cls: Type[_O]) → Type[_O]¶

类装饰器，将声明式映射过程应用于给定的类。

例如：

from sqlalchemy.orm import registry

mapper_registry = registry()


@mapper_registry.mapped
class Foo:
    __tablename__ = "some_table"

    id = Column(Integer, primary_key=True)
    name = Column(String)

有关完整详细信息和示例，请参见声明式映射部分。

参数:: cls¶ – 要映射的类。
返回:: 传递的类。

另请参阅

声明式映射

registry.generate_base() - 生成一个基类，该基类将使用 Python 元类自动将声明式映射应用于子类。

另请参阅

registry.mapped_as_dataclass()

method sqlalchemy.orm.registry.mapped_as_dataclass(_registry__cls: Type[_O] | None = None, *, init: _NoArg | bool = _NoArg.NO_ARG, repr: _NoArg | bool = _NoArg.NO_ARG, eq: _NoArg | bool = _NoArg.NO_ARG, order: _NoArg | bool = _NoArg.NO_ARG, unsafe_hash: _NoArg | bool = _NoArg.NO_ARG, match_args: _NoArg | bool = _NoArg.NO_ARG, kw_only: _NoArg | bool = _NoArg.NO_ARG, dataclass_callable: _NoArg | Callable[..., Type[Any]] = _NoArg.NO_ARG) → Type[_O] | Callable[[Type[_O]], Type[_O]]¶: 类装饰器，它将声明式映射过程应用于给定的类，并额外地将该类转换为 Python 数据类。

另请参阅

声明式数据类映射 - 关于 SQLAlchemy 原生数据类映射的完整背景信息

2.0 版本新增。

attribute sqlalchemy.orm.registry.mappers¶: 所有 Mapper 对象的只读集合。

method sqlalchemy.orm.registry.update_type_annotation_map(type_annotation_map: _TypeAnnotationMapType) → None¶: 使用新值更新 registry.type_annotation_map。

function sqlalchemy.orm.add_mapped_attribute(target: Type[_O], key: str, attr: MapperProperty[Any]) → None¶

向 ORM 映射类添加新的映射属性。

例如：

add_mapped_attribute(User, "addresses", relationship(Address))

这可以用于未使用声明式元类拦截属性设置操作的 ORM 映射。

2.0 版本新增。

function sqlalchemy.orm.column_property(column: _ORMColumnExprArgument[_T], *additional_columns: _ORMColumnExprArgument[Any], group: str | None = None, deferred: bool = False, raiseload: bool = False, comparator_factory: Type[PropComparator[_T]] | None = None, init: _NoArg | bool = _NoArg.NO_ARG, repr: _NoArg | bool = _NoArg.NO_ARG, default: Any | None = _NoArg.NO_ARG, default_factory: _NoArg | Callable[[], _T] = _NoArg.NO_ARG, compare: _NoArg | bool = _NoArg.NO_ARG, kw_only: _NoArg | bool = _NoArg.NO_ARG, hash: _NoArg | bool | None = _NoArg.NO_ARG, active_history: bool = False, expire_on_flush: bool = True, info: _InfoType | None = None, doc: str | None = None) → MappedSQLExpression[_T]¶

提供列级属性以用于映射。

对于声明式映射，column_property() 用于将只读 SQL 表达式映射到映射类。

当使用命令式映射时，column_property() 也承担了映射表列以及附加功能的角色。当使用完全声明式映射时，应使用 mapped_column() 构造来实现此目的。

对于声明式数据类映射，column_property() 被认为是只读的，并且不会包含在数据类 __init__() 构造函数中。

column_property() 函数返回 ColumnProperty 的实例。

另请参阅

使用 column_property - column_property() 映射 SQL 表达式的通用用法

为命令式表列应用加载、持久化和映射选项 - 将 column_property() 与命令式表映射一起使用，以将其他选项应用于纯 Column 对象

参数:

*cols¶ – 要映射的 Column 对象列表。
active_history=False¶ – 仅用于命令式表映射或传统风格的声明式映射（即，尚未升级到 mapped_column() 的映射），对于预期可写的基于列的属性；对于声明式映射，请使用带有 mapped_column.active_history 的 mapped_column()。有关功能详细信息，请参见该参数。
comparator_factory¶ – 一个扩展 Comparator 的类，它为比较操作提供自定义 SQL 子句生成。
group¶ – 当标记为延迟加载时，此属性的组名。
deferred¶ – 当为 True 时，列属性是“延迟加载”的，这意味着它不会立即加载，而是在首次访问实例上的属性时加载。另请参见 deferred()。
doc¶ – 可选字符串，将作为类绑定的描述符上的文档字符串应用。
expire_on_flush=True¶ – 禁用 flush 时过期。引用 SQL 表达式（而不是单个绑定到表的列）的 column_property() 被认为是“只读”属性；填充它对数据状态没有影响，并且只能返回数据库状态。因此，每当父对象参与 flush 时，即在 flush 中具有任何类型的“脏”状态时，column_property() 的值都会过期。将此参数设置为 False 将具有在 flush 继续后保留任何现有值的效果。但是请注意，具有默认过期设置的 Session 仍然会在 Session.commit() 调用后使所有属性过期。
info¶ – 可选数据字典，将填充到此对象的 MapperProperty.info 属性中。
raiseload¶ –
如果为 True，则指示列在取消延迟加载时应引发错误，而不是加载值。可以通过使用带有 raiseload=False 的 deferred() 选项在查询时更改此设置。

1.4 版本新增。

另请参阅

使用 raiseload 防止延迟列加载
init¶ –
特定于声明式数据类映射，指定映射的属性是否应作为数据类过程生成的 __init__() 方法的一部分。

Deprecated since version 1.4: column_property.init 参数对于 column_property() 已弃用。此参数仅适用于声明式数据类配置中的可写属性，并且在上下文中，column_property() 被视为只读属性。
repr¶ – 特定于声明式数据类映射，指定映射的属性是否应作为数据类过程生成的 __repr__() 方法的一部分。
default_factory¶ –
特定于声明式数据类映射，指定一个默认值生成函数，该函数将作为数据类过程生成的 __init__() 方法的一部分执行。

Deprecated since version 1.4: column_property.default_factory 参数对于 column_property() 已弃用。此参数仅适用于声明式数据类配置中的可写属性，并且在上下文中，column_property() 被视为只读属性。

另请参阅

什么是 default、default_factory 和 insert_default，我应该使用哪个？

mapped_column.default

mapped_column.insert_default
compare¶ –
特定于声明式数据类映射，指示在为映射类生成 __eq__() 和 __ne__() 方法时，是否应将此字段包含在比较操作中。

2.0.0b4 版本新增。
kw_only¶ –
特定于声明式数据类映射，指示在生成 __init__() 时，是否应将此字段标记为仅关键字。

自版本 1.4 起已弃用: column_property.kw_only 参数对于 column_property() 已弃用。此参数仅适用于声明式数据类配置中的可写属性，并且在当前上下文中，column_property() 被视为只读属性。
hash¶ –
特定于声明式数据类映射，控制在为映射类生成 __hash__() 方法时是否包含此字段。

2.0.36 版本新增。

function sqlalchemy.orm.declarative_base(*, metadata: Optional[MetaData] = None, mapper: Optional[Callable[..., Mapper[Any]]] = None, cls: Type[Any] = <class 'object'>, name: str = 'Base', class_registry: Optional[clsregistry._ClsRegistryType] = None, type_annotation_map: Optional[_TypeAnnotationMapType] = None, constructor: Callable[..., None] = <function _declarative_constructor>, metaclass: Type[Any] = <class 'sqlalchemy.orm.decl_api.DeclarativeMeta'>) → Any¶

为声明式类定义构造基类。

新的基类将被赋予一个元类，该元类生成适当的 Table 对象，并基于类及其子类中以声明方式提供的信息以及任何子类进行适当的 Mapper 调用。

在版本 2.0 中变更: 请注意，declarative_base() 函数已被新的 DeclarativeBase 类取代，后者使用子类化而不是函数的返回值来生成新的“基”类。这允许一种与 PEP 484 类型工具兼容的方法。

declarative_base() 函数是使用 registry.generate_base() 方法的简写版本。也就是说，以下代码：

from sqlalchemy.orm import declarative_base

Base = declarative_base()

等效于：

from sqlalchemy.orm import registry

mapper_registry = registry()
Base = mapper_registry.generate_base()

有关更多详细信息，请参阅 registry 和 registry.generate_base() 的文档字符串。

在版本 1.4 中变更: declarative_base() 函数现在是更通用的 registry 类的特化。该函数也从 declarative.ext 包移动到 sqlalchemy.orm 包。

参数:

metadata¶ – 一个可选的 MetaData 实例。基类的子类隐式声明的所有 Table 对象将共享此 MetaData。如果未提供 MetaData 实例，则将创建一个。 MetaData 实例将通过生成的声明式基类的 metadata 属性提供。
mapper¶ – 一个可选的可调用对象，默认为 Mapper。将用于将子类映射到其表。
cls¶ – 默认为 object。用作生成的声明式基类的基类型的类型。可以是类或类元组。
name¶ – 默认为 Base。生成的类的显示名称。自定义此名称不是必需的，但可以提高回溯和调试的清晰度。
constructor¶ – 指定在没有自己的 __init__ 的映射类上 __init__ 函数的实现。默认为将 **kwargs 分配给实例的声明字段和关系的实现。如果提供 None，则不会提供 __init__，并且构造将通过正常的 Python 语义回退到 cls.__init__。
class_registry¶ – 可选字典，当使用字符串名称来标识 relationship() 等中的类时，它将充当类名 -> 映射类的注册表。允许两个或多个声明式基类共享相同的类名注册表，以简化基类间的关系。
type_annotation_map¶ –
Python 类型到 SQLAlchemy TypeEngine 类或实例的可选字典。这专门由 MappedColumn 构造使用，以基于 Mapped 类型中的注释生成列类型。

2.0 版本新增。

另请参阅

自定义类型映射
metaclass¶ – 默认为 DeclarativeMeta。用作生成的声明式基类的元类型的元类或 __metaclass__ 兼容的可调用对象。

另请参阅

注册表

function sqlalchemy.orm.declarative_mixin(cls: Type[_T]) → Type[_T]¶

将类标记为提供“声明式 mixin”功能。

例如：

from sqlalchemy.orm import declared_attr
from sqlalchemy.orm import declarative_mixin


@declarative_mixin
class MyMixin:

    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()

    __table_args__ = {"mysql_engine": "InnoDB"}
    __mapper_args__ = {"always_refresh": True}

    id = Column(Integer, primary_key=True)


class MyModel(MyMixin, Base):
    name = Column(String(1000))

declarative_mixin() 装饰器目前不会以任何方式修改给定的类；它当前的目的严格来说是协助 Mypy 插件在没有其他上下文的情况下能够识别 SQLAlchemy 声明式混入类。

1.4.6 版本新增。

另请参阅

使用 Mixin 组合映射层级结构

使用 @declared_attr 和声明式 Mixin - 在 Mypy 插件文档中

function sqlalchemy.orm.as_declarative(**kw: Any) → Callable[[Type[_T]], Type[_T]]¶

类装饰器，用于将给定类适配为 declarative_base()。

此函数通过首先自动创建 registry 并调用装饰器，从而利用 registry.as_declarative_base() 方法。

例如：

from sqlalchemy.orm import as_declarative


@as_declarative()
class Base:
    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()

    id = Column(Integer, primary_key=True)


class MyMappedClass(Base): ...

另请参阅

registry.as_declarative_base()

声明一个新的 ORM 映射的 Column 构造，用于声明式表配置中。

mapped_column() 函数提供了一个 ORM 感知且与 Python 类型兼容的构造，该构造与声明式映射一起使用，以指示映射到 Core Column 对象的属性。它提供了与在使用声明式时将属性直接映射到 Column 对象等效的功能，尤其是在使用声明式表配置时。

2.0 版本新增。

mapped_column() 通常与显式类型和 Mapped 注释类型一起使用，在其中它可以根据 Mapped 注释中存在的内容推导出列的 SQL 类型和可空性。它也可以在没有注释的情况下用作 SQLAlchemy 1.x 样式中 Column 在声明式映射中如何使用的直接替代品。

有关 mapped_column() 的用法示例，请参阅带有 mapped_column() 的声明式表的文档。

另请参阅

带有 mapped_column() 的声明式表 - 完整文档

ORM 声明式模型 - 使用 1.x 样式映射的声明式映射的迁移说明

参数:

__name¶ – 要赋予 Column 的字符串名称。这是一个可选的位置专用参数，如果存在，则必须是传递的第一个位置参数。如果省略，则将 mapped_column() 映射到的属性名称将用作 SQL 列名。
__type¶ – TypeEngine 类型或实例，它将指示要与 Column 关联的数据类型。这是一个可选的位置专用参数，如果存在，则必须紧跟在 __name 参数（如果也存在）之后，否则为第一个位置参数。如果省略，则列的最终类型可以从注释类型派生，或者如果存在 ForeignKey，则从引用的列的数据类型派生。
*args¶ – 其他位置参数包括 ForeignKey、CheckConstraint 和 Identity 等构造，这些构造将传递给构造的 Column。
nullable¶ – 可选的布尔值，指示列应为 “NULL” 还是 “NOT NULL”。如果省略，则可空性从类型注释派生，具体取决于是否存在 typing.Optional。nullable 对于非主键列默认为 True，对于主键列默认为 False。
primary_key¶ – 可选的布尔值，指示 Column 是否为表主键的一部分。
deferred¶ –
可选的布尔值 - 此关键字参数由 ORM 声明式过程使用，而不是 Column 本身的一部分；相反，它指示应“延迟”加载此列，就像通过 deferred() 映射一样。

另请参阅

配置映射上的列延迟
deferred_group¶ –
暗示 mapped_column.deferred 为 True，并设置 deferred.group 参数。

另请参阅

按组加载延迟列
deferred_raiseload¶ –
暗示 mapped_column.deferred 为 True，并设置 deferred.raiseload 参数。

另请参阅

使用 raiseload 防止延迟列加载
use_existing_column¶ –
如果为 True，将尝试在继承的超类（通常是单继承超类）上查找给定的列名，如果存在，则不会生成新列，而是映射到超类列，就像它从此类中省略一样。这用于向继承的超类添加新列的 mixin。

另请参阅

使用 use_existing_column 解决列冲突

2.0.0b4 版本新增。
default¶ –
如果 mapped_column.insert_default 参数不存在，则直接传递给 Column.default 参数。此外，当与声明式数据类映射一起使用时，表示应该应用于生成的 __init__() 方法中的关键字构造函数的默认 Python 值。

请注意，在数据类生成的情况下，当 mapped_column.insert_default 不存在时，这意味着 mapped_column.default 值用于两个地方，即 __init__() 方法和 Column.default 参数。虽然此行为可能会在未来的版本中更改，但目前这往往“奏效”；None 的默认值将意味着 Column 不会获得默认生成器，而非 None Python 或 SQL 表达式值的默认值将在调用 __init__() 时预先分配到对象上，这与 Core Insert 构造在任何情况下都会使用的值相同，从而导致相同的结果。

注意

当使用核心级别列默认值（即可调用对象，由底层 Column 结合 ORM 映射数据类解释），尤其是那些上下文感知默认函数，必须使用 mapped_column.insert_default 参数代替。这对于消除可调用对象被解释为数据类级别默认值的情况是必要的。

另请参阅

什么是 default、default_factory 和 insert_default，我应该使用哪个？

mapped_column.insert_default

mapped_column.default_factory
insert_default¶ –
直接传递给 Column.default 参数；当存在时，将取代 mapped_column.default 的值，但是 mapped_column.default 将始终应用于数据类映射的构造函数默认值。

另请参阅

什么是 default、default_factory 和 insert_default，我应该使用哪个？

mapped_column.default

mapped_column.default_factory
sort_order¶ –
一个整数，指示在 ORM 创建 Table 时，此映射列应如何与其他列进行排序。在具有相同值的映射列中，使用默认排序，首先放置在主类中定义的映射列，然后放置在超类中定义的映射列。默认为 0。排序是升序的。

2.0.4 版本新增。
active_history=False¶ –
当 True 时，表示在替换标量属性时，如果尚未加载，则应加载该属性的“先前”值。通常，简单的非主键标量值的历史跟踪逻辑只需要知道“新”值即可执行刷新。此标志适用于使用 get_history() 或 Session.is_modified() 的应用程序，这些应用程序还需要知道属性的“先前”值。

2.0.10 版本新增。
init¶ – 专用于声明式数据类映射，指定映射属性是否应作为数据类过程生成的 __init__() 方法的一部分。
repr¶ – 专用于声明式数据类映射，指定映射属性是否应作为数据类过程生成的 __repr__() 方法的一部分。
default_factory¶ –
特定于声明式数据类映射，指定一个默认值生成函数，该函数将作为数据类过程生成的 __init__() 方法的一部分执行。

另请参阅

什么是 default、default_factory 和 insert_default，我应该使用哪个？

mapped_column.default

mapped_column.insert_default
compare¶ –
特定于声明式数据类映射，指示在为映射类生成 __eq__() 和 __ne__() 方法时，是否应将此字段包含在比较操作中。

2.0.0b4 版本新增。
kw_only¶ – 专用于声明式数据类映射，指示在生成 __init__() 时，此字段是否应标记为仅关键字。
hash¶ –
特定于声明式数据类映射，控制在为映射类生成 __hash__() 方法时是否包含此字段。

2.0.36 版本新增。
**kw¶ – 所有剩余的关键字参数都将传递给 Column 的构造函数。

class sqlalchemy.orm.declared_attr¶

将类级别方法标记为表示映射属性或声明式指令的定义。

declared_attr 通常用作类级别方法的装饰器，将属性转换为可以从非实例化类调用的标量式属性。声明式映射过程在扫描类时查找这些 declared_attr 可调用对象，并假定任何用 declared_attr 标记的属性都将是一个可调用对象，它将生成特定于声明式映射或表配置的对象。

declared_attr 通常适用于混入，以定义要应用于类的不同实现者的关系。它也可以用于定义动态生成的列表达式和其他声明式属性。

示例

class ProvidesUserMixin:
    "A mixin that adds a 'user' relationship to classes."

    user_id: Mapped[int] = mapped_column(ForeignKey("user_table.id"))

    @declared_attr
    def user(cls) -> Mapped["User"]:
        return relationship("User")

当与声明式指令（如 __tablename__）一起使用时，可以使用 declared_attr.directive() 修饰符，它向 PEP 484 类型工具指示给定的方法不处理 Mapped 属性

class CreateTableName:
    @declared_attr.directive
    def __tablename__(cls) -> str:
        return cls.__name__.lower()

declared_attr 也可以直接应用于映射类，以便在使用映射继承方案时，允许属性在子类上动态配置自身。下面说明了 declared_attr 来创建用于生成子类的 Mapper.polymorphic_identity 参数的动态方案

class Employee(Base):
    __tablename__ = "employee"

    id: Mapped[int] = mapped_column(primary_key=True)
    type: Mapped[str] = mapped_column(String(50))

    @declared_attr.directive
    def __mapper_args__(cls) -> Dict[str, Any]:
        if cls.__name__ == "Employee":
            return {
                "polymorphic_on": cls.type,
                "polymorphic_identity": "Employee",
            }
        else:
            return {"polymorphic_identity": cls.__name__}


class Engineer(Employee):
    pass

declared_attr 支持装饰显式使用 @classmethod 装饰的函数。从运行时角度来看，这从来都不是必要的，但是为了支持 PEP 484 类型工具（否则无法识别装饰函数具有 cls 参数的类级别行为）可能需要这样做

class SomethingMixin:
    x: Mapped[int]
    y: Mapped[int]

    @declared_attr
    @classmethod
    def x_plus_y(cls) -> Mapped[int]:
        return column_property(cls.x + cls.y)

2.0 版本新增: - declared_attr 可以容纳用 @classmethod 装饰的函数，以帮助在需要时进行 PEP 484 集成。

另请参阅

使用 Mixin 组合映射层次结构 - 声明式 Mixin 文档，其中包含有关 declared_attr 的使用模式的背景信息。

成员

cascading, directive

类签名

class sqlalchemy.orm.declared_attr (sqlalchemy.orm.base._MappedAttribute, sqlalchemy.orm.decl_api._declared_attr_common)

attribute sqlalchemy.orm.declared_attr.cascading¶

将 declared_attr 标记为级联。

这是一个特殊用途的修饰符，指示应该在映射继承场景中，为每个映射子类分别配置基于列或 MapperProperty 的声明式属性。

警告

declared_attr.cascading 修饰符有几个限制

该标志仅适用于在声明式混入类和 __abstract__ 类上使用 declared_attr；当直接在映射类上使用时，它目前没有任何效果。
该标志仅适用于正常命名的属性，例如，不适用于任何特殊的下划线属性，如 __tablename__。在这些属性上，它没有效果。
该标志目前不允许进一步覆盖类层次结构；如果子类尝试覆盖该属性，则会发出警告并跳过被覆盖的属性。这是一个希望在某个时候解决的限制。

在下面，MyClass 和 MySubClass 都将建立不同的 id Column 对象

class HasIdMixin:
    @declared_attr.cascading
    def id(cls) -> Mapped[int]:
        if has_inherited_table(cls):
            return mapped_column(ForeignKey("myclass.id"), primary_key=True)
        else:
            return mapped_column(Integer, primary_key=True)


class MyClass(HasIdMixin, Base):
    __tablename__ = "myclass"
    # ...


class MySubClass(MyClass):
    """ """

    # ...

上述配置的行为是 MySubClass 将在其自己的 id 列以及 MyClass 的 id 列（在名为 some_id 的属性下）下引用。

另请参阅

声明式继承

使用 _orm.declared_attr() 生成特定于表的继承列

attribute sqlalchemy.orm.declared_attr.directive¶

将 declared_attr 标记为装饰声明式指令，如 __tablename__ 或 __mapper_args__。

declared_attr.directive 的目的是严格支持 PEP 484 类型工具，方法是允许装饰函数具有不使用 Mapped 泛型类的返回类型，就像通常在使用 declared_attr 用于列和映射属性时一样。在运行时，declared_attr.directive 返回未修改的 declared_attr 类。

例如：

class CreateTableName:
    @declared_attr.directive
    def __tablename__(cls) -> str:
        return cls.__name__.lower()

2.0 版本新增。

另请参阅

使用 Mixin 组合映射层级结构

declared_attr

class sqlalchemy.orm.DeclarativeBase¶

用于声明式类定义的基类。

DeclarativeBase 允许以与类型检查器兼容的方式创建新的声明式基类

from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass

上面的 Base 类现在可以用作新声明式映射的基类。超类使用 __init_subclass__() 方法来设置新类，并且不使用元类。

首次使用时，DeclarativeBase 类实例化一个新的 registry 以用于基类，假设没有显式提供注册表。 DeclarativeBase 类支持类级别属性，这些属性充当构建此注册表的参数；例如，指示特定的 MetaData 集合以及 registry.type_annotation_map 的特定值

from typing_extensions import Annotated

from sqlalchemy import BigInteger
from sqlalchemy import MetaData
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase

bigint = Annotated[int, "bigint"]
my_metadata = MetaData()


class Base(DeclarativeBase):
    metadata = my_metadata
    type_annotation_map = {
        str: String().with_variant(String(255), "mysql", "mariadb"),
        bigint: BigInteger(),
    }

可以指定的类级别属性包括

参数:

metadata¶ – 可选的 MetaData 集合。如果自动构造 registry，则此 MetaData 集合将用于构造它。否则，本地 MetaData 集合将取代使用 DeclarativeBase.registry 参数传递的现有 registry 使用的集合。
type_annotation_map¶ – 可选的类型注释映射，将作为 registry.type_annotation_map 传递给 registry。
registry¶ – 直接提供预先存在的 registry。

2.0 版本新增: 添加了 DeclarativeBase，以便可以以类型检查器 PEP 484 也可识别的方式构造声明式基类。因此，DeclarativeBase 和其他面向子类化的 API 应被视为取代以前的“函数返回的类”API，即 declarative_base() 和 registry.generate_base()，其中返回的基类无法被类型检查器识别，除非使用插件。

__init__ 行为

在普通的 Python 类中，类层次结构中最基本的 __init__() 方法是 object.__init__()，它不接受任何参数。但是，当首次声明 DeclarativeBase 子类时，如果 __init__() 方法尚不存在，则该类会被赋予链接到 registry.constructor 构造函数函数的 __init__() 方法；这是通常的声明式构造函数，它会将关键字参数作为实例上的属性分配，前提是这些属性是在类级别建立的（即，已映射或链接到描述符）。映射类永远不会在不通过 super() 显式调用的情况下访问此构造函数，因为映射类本身会被赋予直接调用 registry.constructor 的 __init__() 方法，因此在默认情况下，它的工作方式独立于最基本的 __init__() 方法的作用。

2.0.1 版本更改: DeclarativeBase 具有默认构造函数，默认情况下链接到 registry.constructor，以便调用 super().__init__() 可以访问此构造函数。以前，由于实现错误，此默认构造函数丢失了，调用 super().__init__() 将调用 object.__init__()。

DeclarativeBase 子类还可以声明一个显式的 __init__() 方法，该方法将在此级别替换 registry.constructor 函数的使用

class Base(DeclarativeBase):
    def __init__(self, id=None):
        self.id = id

映射类仍然不会隐式调用此构造函数；它仍然只能通过调用 super().__init__() 访问

class MyClass(Base):
    def __init__(self, id=None, name=None):
        self.name = name
        super().__init__(id=id)

请注意，这与旧版 declarative_base() 等函数的作用不同；这些函数创建的基类始终为 __init__() 安装 registry.constructor。

成员

__mapper__, __mapper_args__, __table__, __table_args__, __tablename__, metadata, registry

类签名

class sqlalchemy.orm.DeclarativeBase (sqlalchemy.inspection.Inspectable)

attribute sqlalchemy.orm.DeclarativeBase.__mapper__: ClassVar[Mapper[Any]]¶

特定类映射到的 Mapper 对象。

也可以使用 inspect() 获取，例如 inspect(klass)。

attribute sqlalchemy.orm.DeclarativeBase.__mapper_args__: Any¶: 将传递给 Mapper 构造函数的参数字典。

另请参阅

带有声明式的 Mapper 配置选项

attribute sqlalchemy.orm.DeclarativeBase.__table__: ClassVar[FromClause]¶

特定子类映射到的 FromClause。

这通常是 Table 的实例，但也可能引用其他类型的 FromClause，例如 Subquery，具体取决于类的映射方式。

另请参阅

访问表和元数据

attribute sqlalchemy.orm.DeclarativeBase.__table_args__: Any¶: 将传递给 Table 构造函数的字典或参数元组。有关此集合的特定结构的背景信息，请参阅声明式表配置。

另请参阅

声明式表配置

attribute sqlalchemy.orm.DeclarativeBase.__tablename__: Any¶: 要分配给生成的 Table 对象的字符串名称，如果未通过 DeclarativeBase.__table__ 直接指定。

另请参阅

带有 mapped_column() 的声明式表

attribute sqlalchemy.orm.DeclarativeBase.metadata: ClassVar[MetaData]¶: 指的是 MetaData 集合，该集合将用于新的 Table 对象。

另请参阅

访问表和元数据

attribute sqlalchemy.orm.DeclarativeBase.registry: ClassVar[registry]¶: 指的是正在使用的 registry，新的 Mapper 对象将与之关联。

class sqlalchemy.orm.DeclarativeBaseNoMeta¶

与 DeclarativeBase 相同，但不使用元类来拦截新属性。

当需要使用自定义元类时，可以使用 DeclarativeBaseNoMeta 基类。

2.0 版本新增。

成员

__mapper__, __mapper_args__, __table__, __table_args__, __tablename__, metadata, registry

类签名

class sqlalchemy.orm.DeclarativeBaseNoMeta (sqlalchemy.inspection.Inspectable)

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.__mapper__: ClassVar[Mapper[Any]]¶

特定类映射到的 Mapper 对象。

也可以使用 inspect() 获取，例如 inspect(klass)。

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.__mapper_args__: Any¶: 将传递给 Mapper 构造函数的参数字典。

另请参阅

带有声明式的 Mapper 配置选项

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.__table__: FromClause | None¶

特定子类映射到的 FromClause。

这通常是 Table 的实例，但也可能引用其他类型的 FromClause，例如 Subquery，具体取决于类的映射方式。

另请参阅

访问表和元数据

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.__table_args__: Any¶: 将传递给 Table 构造函数的字典或参数元组。有关此集合的特定结构的背景信息，请参阅声明式表配置。

另请参阅

声明式表配置

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.__tablename__: Any¶: 要分配给生成的 Table 对象的字符串名称，如果未通过 DeclarativeBase.__table__ 直接指定。

另请参阅

带有 mapped_column() 的声明式表

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.metadata: ClassVar[MetaData]¶: 指的是 MetaData 集合，该集合将用于新的 Table 对象。

另请参阅

访问表和元数据

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.registry: ClassVar[registry]¶: 指的是正在使用的 registry，新的 Mapper 对象将与之关联。

function sqlalchemy.orm.has_inherited_table(cls: Type[_O]) → bool¶

给定一个类，如果它继承的任何类具有映射表，则返回 True，否则返回 False。

这在声明式混入中用于构建在继承层次结构中对于基类与子类行为不同的属性。

另请参阅

将混入和基类与映射继承模式一起使用

function sqlalchemy.orm.synonym_for(name: str, map_column: bool = False) → Callable[[Callable[[...], Any]], Synonym[Any]]¶

装饰器，与 Python 描述符结合使用，生成 synonym() 属性。

被装饰的函数将作为 synonym() 的 synonym.descriptor 参数传递。

class MyClass(Base):
    __tablename__ = "my_table"

    id = Column(Integer, primary_key=True)
    _job_status = Column("job_status", String(50))

    @synonym_for("job_status")
    @property
    def job_status(self):
        return "Status: %s" % self._job_status

SQLAlchemy 的混合属性功能通常优于同义词，后者是更旧的功能。

另请参阅

同义词 - 同义词概述

synonym() - 映射器级别函数

使用描述符和混合属性 - 混合属性扩展提供了一种更新的方法，可以比使用同义词更灵活地增强属性行为。

function sqlalchemy.orm.object_mapper(instance: _T) → Mapper[_T]¶

给定一个对象，返回与该对象实例关联的主 Mapper。

如果未配置映射，则引发 sqlalchemy.orm.exc.UnmappedInstanceError。

此函数可以通过检查系统使用：

inspect(instance).mapper

如果实例不是映射的一部分，则使用检查系统将引发 sqlalchemy.exc.NoInspectionAvailable。

function sqlalchemy.orm.class_mapper(class_: Type[_O], configure: bool = True) → Mapper[_O]¶

给定一个类，返回与键关联的主 Mapper。

如果在给定的类上未配置映射，则引发 UnmappedClassError，如果传递了非类对象，则引发 ArgumentError。

等效功能可通过 inspect() 函数使用：

inspect(some_mapped_class)

如果类未被映射，则使用检查系统将引发 sqlalchemy.exc.NoInspectionAvailable。

function sqlalchemy.orm.configure_mappers() → None¶

初始化到目前为止在所有 registry 集合中构建的所有映射器的映射器间关系。

配置步骤用于协调和初始化映射类之间的 relationship() 链接，以及调用配置事件，例如 MapperEvents.before_configured() 和 MapperEvents.after_configured()，ORM 扩展或用户定义的扩展钩子可以使用它们。

映射器配置通常在首次使用来自特定 registry 的映射时，以及每当使用映射并且构建了其他尚未配置的映射器时自动调用。然而，自动配置过程仅限于 registry，涉及目标映射器及其可能依赖的任何相关 registry 对象；这等效于在特定的 registry 上调用 registry.configure() 方法。

相比之下，configure_mappers() 函数将对内存中存在的所有 registry 对象调用配置过程，并且可能适用于许多单独的但又相互关联的 registry 对象正在使用的情况。

在版本 1.4 中更改: 从 SQLAlchemy 1.4.0b2 开始，此函数在每个 registry 的基础上工作，定位所有存在的 registry 对象，并在每个对象上调用 registry.configure() 方法。可以优先使用 registry.configure() 方法，以将映射器的配置限制为特定 registry 和/或声明性基类的本地映射器。

调用自动配置的点包括当映射类实例化为实例时，以及当使用 Session.query() 或 Session.execute() 发出 ORM 查询并使用启用 ORM 的语句时。

映射器配置过程，无论是通过 configure_mappers() 还是来自 registry.configure() 调用，都提供了几个事件钩子，可用于增强映射器配置步骤。这些钩子包括

MapperEvents.before_configured() - 在 configure_mappers() 或 registry.configure() 执行任何工作之前调用一次；这可用于在操作继续之前建立其他选项、属性或相关映射。
MapperEvents.mapper_configured() - 在配置过程中的每个单独的 Mapper 配置时调用；将包括除其他仍待配置的映射器设置的反向引用之外的所有映射器状态。
MapperEvents.after_configured() - 在 configure_mappers() 或 registry.configure() 完成后调用一次；在此阶段，配置操作范围内的所有 Mapper 对象都将完全配置。请注意，调用应用程序可能仍然有其他尚未生成的映射，例如，如果它们在尚未导入的模块中，并且如果它们在不属于当前配置范围的其他 registry 集合中，则可能还有其他仍待配置的映射。

function sqlalchemy.orm.clear_mappers() → None¶

从所有类中删除所有映射器。

在版本 1.4 中更改: 此函数现在定位所有 registry 对象，并对每个对象调用 registry.dispose() 方法。

此函数从类中删除所有检测，并处置与其关联的映射器。一旦调用，这些类将被取消映射，并且稍后可以使用新的映射器重新映射。

clear_mappers() *不* 用于正常用途，因为它实际上在非常特定的测试场景之外没有任何有效的用法。通常，映射器是用户定义类的永久结构组件，并且永远不会独立于其类而被丢弃。如果映射类本身被垃圾回收，则其映射器也会自动处置。因此，clear_mappers() 仅用于在测试套件中使用，这些测试套件使用不同的映射重用相同的类，这本身就是一个极其罕见的用例 - 唯一的此类用例实际上是 SQLAlchemy 自己的测试套件，以及其他 ORM 扩展库的测试套件，这些库旨在测试对一组固定类进行映射器构建的各种组合。

生成“标识键”元组，就像在 Session.identity_map 字典中用作键一样。

此函数有多种调用样式

identity_key(class, ident, identity_token=token)

此形式接收一个映射类和一个主键标量或元组作为参数。

例如：
```
>>> identity_key(MyClass, (1, 2))
(<class '__main__.MyClass'>, (1, 2), None)
```
param class:

映射类（必须是位置参数）

param ident:

主键，可以是标量或元组参数。

param identity_token:

可选的身份令牌

在版本 1.2 中新增: 添加了 identity_token
identity_key(instance=instance)

此形式将为给定实例生成身份键。实例不必是持久的，只需其主键属性已填充（否则，对于那些缺失值，键将包含 None）。

例如：
```
>>> instance = MyClass(1, 2)
>>> identity_key(instance=instance)
(<class '__main__.MyClass'>, (1, 2), None)
```
在这种形式中，给定的实例最终会通过 Mapper.identity_key_from_instance() 运行，这将具有对过期对象执行数据库检查以查找相应行的效果。

param instance:

对象实例（必须作为关键字参数给出）
identity_key(class, row=row, identity_token=token)

此形式类似于 class/tuple 形式，不同之处在于它将数据库结果行作为 Row 或 RowMapping 对象传递。

例如：
```
>>> row = engine.execute(text("select * from table where a=1 and b=2")).first()
>>> identity_key(MyClass, row=row)
(<class '__main__.MyClass'>, (1, 2), None)
```
param class:

映射类（必须是位置参数）

param row:

由 CursorResult 返回的 Row 行（必须作为关键字参数给出）

param identity_token:

可选的身份令牌

在版本 1.2 中新增: 添加了 identity_token

function sqlalchemy.orm.polymorphic_union(table_map, typecolname, aliasname='p_union', cast_nulls=True)¶

创建多态映射器使用的 UNION 语句。

有关如何使用它的示例，请参阅具体表继承。

参数:

table_map¶ – 多态标识到 Table 对象的映射。
typecolname¶ – “鉴别器”列的字符串名称，它将从查询中派生，为每一行生成多态标识。如果为 None，则不生成多态鉴别器。
aliasname¶ – 生成的 alias() 构造的名称。
cast_nulls¶ – 如果为 True，则不存在的列（表示为标记的 NULL）将传递到 CAST 中。这是一种遗留行为，在某些后端（如 Oracle）上存在问题 - 在这种情况下，可以将其设置为 False。

function sqlalchemy.orm.orm_insert_sentinel(name: str | None = None, type_: _TypeEngineArgument[Any] | None = None, *, default: Any | None = None, omit_from_statements: bool = True) → MappedColumn[Any]¶

提供代理 mapped_column()，它生成所谓的哨兵列，允许对没有其他合格主键配置的表进行高效批量插入，并具有确定性的 RETURNING 排序。

使用 orm_insert_sentinel() 类似于在 Core Table 构造中使用 insert_sentinel() 构造。

将此构造添加到声明式映射类的指南与 insert_sentinel() 构造的指南相同；数据库表本身也需要有一个具有此名称的列。

有关如何使用此对象的背景信息，请参阅配置 Sentinel 列部分，该部分是 INSERT 语句的 “插入多个值” 行为部分的一部分。

另请参阅

insert_sentinel()

“插入多值”行为 для INSERT 语句

配置哨兵列

2.0.10 版本新增。

function sqlalchemy.orm.reconstructor(fn)¶

将方法装饰为“重建器”钩子。

指定一个方法作为“重构器”，一个类似 __init__ 的方法，将在实例从数据库加载或以其他方式重建后由 ORM 调用。

提示

reconstructor() 装饰器使用了 InstanceEvents.load() 事件钩子，可以直接使用。

重构器将在没有参数的情况下被调用。实例的标量（非集合）数据库映射属性将在函数内可用。急切加载的集合通常还不可用，并且通常只包含第一个元素。在此阶段对对象进行的 ORM 状态更改将不会被记录以用于下一次 flush() 操作，因此重构器中的活动应该是保守的。

另请参阅

InstanceEvents.load()

class sqlalchemy.orm.Mapper¶

定义 Python 类和数据库表或其他关系结构之间的关联，以便可以进行针对该类的 ORM 操作。

Mapper 对象是使用 registry 对象上的映射方法实例化的。有关实例化新的 Mapper 对象的信息，请参阅 ORM 映射类概述。

类签名

class sqlalchemy.orm.Mapper (sqlalchemy.orm.ORMFromClauseRole, sqlalchemy.orm.ORMEntityColumnsClauseRole, sqlalchemy.sql.cache_key.MemoizedHasCacheKey, sqlalchemy.orm.base.InspectionAttr, sqlalchemy.log.Identified, sqlalchemy.inspection.Inspectable, sqlalchemy.event.registry.EventTarget, typing.Generic)

method sqlalchemy.orm.Mapper.__init__(class_: Type[_O], local_table: FromClause | None = None, properties: Mapping[str, MapperProperty[Any]] | None = None, primary_key: Iterable[_ORMColumnExprArgument[Any]] | None = None, non_primary: bool = False, inherits: Mapper[Any] | Type[Any] | None = None, inherit_condition: _ColumnExpressionArgument[bool] | None = None, inherit_foreign_keys: Sequence[_ORMColumnExprArgument[Any]] | None = None, always_refresh: bool = False, version_id_col: _ORMColumnExprArgument[Any] | None = None, version_id_generator: Literal[False] | Callable[[Any], Any] | None = None, polymorphic_on: _ORMColumnExprArgument[Any] | str | MapperProperty[Any] | None = None, _polymorphic_map: Dict[Any, Mapper[Any]] | None = None, polymorphic_identity: Any | None = None, concrete: bool = False, with_polymorphic: _WithPolymorphicArg | None = None, polymorphic_abstract: bool = False, polymorphic_load: Literal['selectin', 'inline'] | None = None, allow_partial_pks: bool = True, batch: bool = True, column_prefix: str | None = None, include_properties: Sequence[str] | None = None, exclude_properties: Sequence[str] | None = None, passive_updates: bool = True, passive_deletes: bool = False, confirm_deleted_rows: bool = True, eager_defaults: Literal[True, False, 'auto'] = 'auto', legacy_is_orphan: bool = False, _compiled_cache_size: int = 100)¶

新的 Mapper 对象的直接构造函数。

Mapper 构造函数不直接调用，通常通过使用 registry 对象，通过声明式或命令式映射样式来调用。

在 2.0 版本中变更: 公共的 mapper() 函数已被移除；对于经典映射配置，请使用 registry.map_imperatively() 方法。

下面记录的参数可以传递给 registry.map_imperatively() 方法，也可以在 __mapper_args__ 声明式类属性中传递，如使用声明式配置映射器选项中所述。

参数:

class_¶ – 要映射的类。当使用声明式时，此参数会自动作为声明的类本身传递。
local_table¶ – 类映射到的 Table 或其他 FromClause (即 selectable)。如果此映射器使用单表继承从另一个映射器继承，则可以为 None。当使用声明式时，此参数由扩展自动传递，基于通过 DeclarativeBase.__table__ 属性配置的内容，或通过作为 DeclarativeBase.__tablename__ 属性的结果而生成的 Table 生成。
polymorphic_abstract¶ –
指示此类将在多态层次结构中映射，但不会直接实例化。该类被正常映射，除了它在继承层次结构中没有对 Mapper.polymorphic_identity 的要求。但是，该类必须是使用基本类的 Mapper.polymorphic_on 的多态继承方案的一部分。

2.0 版本新增。

另请参阅

使用 polymorphic_abstract 构建更深层次的层次结构
always_refresh¶ – 如果为 True，则此映射类的所有查询操作都将覆盖会话中已存在的对象实例中的所有数据，从而使用从数据库加载的任何信息擦除任何内存中的更改。强烈不建议使用此标志；作为替代方案，请参阅方法 Query.populate_existing()。
allow_partial_pks¶ –
默认为 True。指示具有某些 NULL 值的复合主键应被视为可能存在于数据库中。这会影响映射器是否会将传入的行分配给现有标识，以及 Session.merge() 是否会首先检查数据库以查找特定的主键值。例如，如果映射到 OUTER JOIN，则可能会发生“部分主键”。

Mapper.allow_partial_pks 参数还指示 ORM 关系惰性加载器，当加载多对一相关对象时，如果具有部分 NULL 值的复合主键是否应导致尝试从数据库加载，或者是否不需要加载尝试。

在 2.0.36 版本中新增: 关系惰性加载器策略会查询 Mapper.allow_partial_pks，这样当设置为 False 时，将不会发出针对具有部分 NULL 值的复合主键的 SELECT。
batch¶ – 默认为 True，表示可以批量处理多个实体的保存操作以提高效率。设置为 False 表示将在保存下一个实例之前完全保存一个实例。这在极少数情况下使用，即 MapperEvents 监听器需要在各个行持久性操作之间被调用。
column_prefix¶ –
当 Column 对象自动分配为映射类的属性时，将添加到映射属性名称的字符串。不影响在 Mapper.properties 字典中显式映射的 Column 对象。

此参数通常用于命令式映射，这些映射将 Table 对象分开。下面，假设 user_table Table 对象具有名为 user_id、user_name 和 password 的列
```
class User(Base):
    __table__ = user_table
    __mapper_args__ = {"column_prefix": "_"}
```
上面的映射会将 user_id、user_name 和 password 列分配给映射的 User 类上的名为 _user_id、_user_name 和 _password 的属性。

Mapper.column_prefix 参数在现代用法中并不常见。对于处理反射表，自动化命名方案的更灵活方法是拦截 Column 对象，因为它们是反射的；请参阅从反射表中自动化列命名方案部分，了解有关此用法模式的说明。
concrete¶ –
如果为 True，则表示此映射器应将其父映射器与具体表继承一起使用。

有关示例，请参阅具体表继承部分。
confirm_deleted_rows¶ – 默认为 True；当基于特定主键删除一行或多行时，如果匹配的行数不等于预期的行数，则会发出警告。可以将此参数设置为 False，以处理数据库 ON DELETE CASCADE 规则可能自动删除其中一些行的情况。在未来的版本中，警告可能会更改为异常。
eager_defaults¶ –
如果为 True，ORM 将在 INSERT 或 UPDATE 操作后立即获取服务器生成的默认值，而不是将其保留为过期状态，以便在下次访问时获取。这可以用于事件方案，其中需要在刷新完成之前立即使用服务器生成的值。

值的获取可以通过使用内联于 INSERT 或 UPDATE 语句的 RETURNING 子句来实现，或者如果后端不支持 RETURNING，则通过在 INSERT 或 UPDATE 之后添加额外的 SELECT 语句来实现。

特别是在 INSERT 语句中，使用 RETURNING 非常高效，因为 SQLAlchemy 可以利用 insertmanyvalues，而使用额外的 SELECT 性能相对较差，会增加额外的 SQL 往返，如果无论如何都不会访问这些新属性，则这些往返是不必要的。

因此，Mapper.eager_defaults 默认值为字符串值 "auto"，这表示如果后端数据库支持 RETURNING 并且正在使用的方言支持 INSERT 语句的 “insertmanyreturning”，则应使用 RETURNING 获取 INSERT 的服务器默认值。如果后端数据库不支持 RETURNING 或 “insertmanyreturning” 不可用，则不会获取服务器默认值。

版本 2.0.0rc1 中变更：为 Mapper.eager_defaults 添加了 “auto” 选项

另请参阅

获取服务器生成的默认值

版本 2.0.0 中变更：RETURNING 现在可以与使用 insertmanyvalues 功能一次性 INSERT 多行的情况一起使用，这使得 Mapper.eager_defaults 功能在支持的后端上非常高效。
exclude_properties¶ –
要从映射中排除的字符串列名列表或集合。

另请参阅

映射表列的子集
include_properties¶ –
要映射的包含性字符串列名列表或集合。

另请参阅

映射表列的子集
inherits¶ –
一个映射类或相应的 Mapper，指示此 Mapper 应该继承自的超类。这里的映射类必须是另一个映射器的子类。当使用声明式（Declarative）时，此参数会作为声明类的自然类层次结构的结果自动传递。

另请参阅

映射类继承层次结构
inherit_condition¶ – 对于连接表继承，一个 SQL 表达式，它将定义两个表如何连接；默认为两个表之间的自然连接。
inherit_foreign_keys¶ – 当使用 inherit_condition 并且存在的列缺少 ForeignKey 配置时，可以使用此参数来指定哪些列是“外键”。在大多数情况下，可以将其保留为 None。
legacy_is_orphan¶ –
布尔值，默认为 False。当为 True 时，指定将“旧式”孤立对象考虑应用于由此映射器映射的对象，这意味着只有当待定（即，非持久化）对象与所有指定了朝向此映射器的 delete-orphan 级联的父对象取消关联时，才会从拥有它的 Session 中自动逐出。新的默认行为是，当对象与任何指定了 delete-orphan 级联的父对象取消关联时，它会被自动逐出。此行为与持久化对象的行为更加一致，并允许行为在更多场景中保持一致，而与孤立对象是否已被刷新无关。

有关此更改的更多详细信息，请参阅 “待定”对象作为“孤立对象”的考虑已变得更积极中的变更说明和示例。
non_primary¶ –
指定此 Mapper 是对“主”映射器（即用于持久化的映射器）的补充。此处创建的 Mapper 可以用于将类临时映射到备用可选对象，仅用于加载。

自版本 1.3 起已弃用：mapper.non_primary 参数已弃用，并将在未来的版本中删除。非主映射器的功能现在更适合使用 AliasedClass 构造，该构造也可以在 1.3 中用作 relationship() 的目标。

另请参阅

与别名类的关系 - 移除对 Mapper.non_primary 标志的需求的新模式。
passive_deletes¶ –
指示在删除连接表继承实体时外键列的 DELETE 行为。对于基本映射器，默认为 False；对于继承的映射器，默认为 False，除非在超类映射器上将值设置为 True。

当 True 时，假定在将此映射器的表链接到其超类表的外键关系上配置了 ON DELETE CASCADE，以便当工作单元尝试删除实体时，它只需要为超类表发出 DELETE 语句，而无需为此表发出 DELETE 语句。

当 False 时，将为此映射器的表单独发出 DELETE 语句。如果此表的本地主键属性已卸载，则必须发出 SELECT 以验证这些属性；请注意，连接表子类的主键列不属于整个对象的“主键”的一部分。

请注意，值 True 始终强制应用于子类映射器；也就是说，超类不可能指定 passive_deletes 而不影响所有子类映射器。

另请参阅

将外键 ON DELETE cascade 与 ORM 关系一起使用 - 描述与 relationship() 一起使用的类似功能

mapper.passive_updates - 支持连接表继承映射器的 ON UPDATE CASCADE
passive_updates¶ –
指示在连接表继承映射中主键列更改时外键列的 UPDATE 行为。默认为 True。

当为 True 时，假定在数据库中的外键上配置了 ON UPDATE CASCADE，并且数据库将处理从源列到连接表行上的依赖列的 UPDATE 传播。

当为 False 时，假定数据库不强制执行引用完整性，并且不会为其自身发出 CASCADE 操作以进行更新。工作单元进程将在主键更改期间为依赖列发出 UPDATE 语句。

另请参阅

可变主键 / 更新级联 - 描述与 relationship() 一起使用的类似功能

mapper.passive_deletes - 支持连接表继承映射器的 ON DELETE CASCADE
polymorphic_load¶ –
为继承层次结构（仅限连接表和单表继承）中的子类指定“多态加载”行为。有效值为
- “'inline'” - 指定此类应成为 “with_polymorphic” 映射器的一部分，例如，其列将包含在针对基表的 SELECT 查询中。
- “'selectin'” - 指定在加载此类实例时，将发出额外的 SELECT 来检索特定于此子类的列。SELECT 使用 IN 一次性获取多个子类。
版本 1.2 中的新增功能。

另请参阅

在映射器上配置 with_polymorphic()

使用 selectin_polymorphic()

polymorphic_on¶ –

指定用于确定传入行的目标类的列、属性或 SQL 表达式，当存在继承类时。

可以指定为字符串属性名称，或 SQL 表达式，例如 Column，或者在声明式映射中为 mapped_column() 对象。通常期望 SQL 表达式对应于最底层的映射 Table 中的列

class Employee(Base):
    __tablename__ = "employee"

    id: Mapped[int] = mapped_column(primary_key=True)
    discriminator: Mapped[str] = mapped_column(String(50))

    __mapper_args__ = {
        "polymorphic_on": discriminator,
        "polymorphic_identity": "employee",
    }

它也可以指定为 SQL 表达式，如本例所示，我们使用 case() 构造来提供条件方法

class Employee(Base):
    __tablename__ = "employee"

    id: Mapped[int] = mapped_column(primary_key=True)
    discriminator: Mapped[str] = mapped_column(String(50))

    __mapper_args__ = {
        "polymorphic_on": case(
            (discriminator == "EN", "engineer"),
            (discriminator == "MA", "manager"),
            else_="employee",
        ),
        "polymorphic_identity": "employee",
    }

它也可以使用其字符串名称引用任何属性，这在使用带注释的列配置时特别有用

class Employee(Base):
    __tablename__ = "employee"

    id: Mapped[int] = mapped_column(primary_key=True)
    discriminator: Mapped[str]

    __mapper_args__ = {
        "polymorphic_on": "discriminator",
        "polymorphic_identity": "employee",
    }

当设置 polymorphic_on 以引用本地映射的 Table 中不存在的属性或表达式时，但鉴别器的值应持久化到数据库中，鉴别器的值不会在新实例上自动设置；这必须由用户处理，可以通过手动方式或通过事件监听器。建立此类监听器的典型方法如下所示

from sqlalchemy import event
from sqlalchemy.orm import object_mapper


@event.listens_for(Employee, "init", propagate=True)
def set_identity(instance, *arg, **kw):
    mapper = object_mapper(instance)
    instance.discriminator = mapper.polymorphic_identity

在上面，我们将映射类的 polymorphic_identity 值分配给 discriminator 属性，从而将值持久化到数据库中的 discriminator 列中。

警告

目前，只能设置一个鉴别器列，通常在层次结构中最底层的类上。“级联”多态列尚不支持。

另请参阅

映射类继承层次结构

polymorphic_identity¶ –
指定一个值，该值标识此特定类，由 Mapper.polymorphic_on 设置引用的列表达式返回。当接收到行时，会将与 Mapper.polymorphic_on 列表达式对应的值与此值进行比较，以指示应将哪个子类用于新重建的对象。

另请参阅

映射类继承层次结构
properties¶ –
一个字典，将对象属性的字符串名称映射到 MapperProperty 实例，这些实例定义了该属性的持久化行为。请注意，映射的 Table 中存在的 Column 对象在映射时会自动放入 ColumnProperty 实例中，除非被覆盖。当使用声明式时，此参数会自动传递，基于声明类主体中声明的所有 MapperProperty 实例。

另请参阅

属性字典 - 在 ORM 映射类概述中
primary_key¶ –
Column 对象列表，或者是指向 Column 的属性名称的字符串名称列表，它们定义了要对此映射器的可选单元使用的主键。这通常只是 local_table 的主键，但可以在此处覆盖。

版本 2.0.2 中变更：Mapper.primary_key 参数也可以指示为字符串属性名称。

另请参阅

映射到显式主键列集合 - 背景和示例用法
version_id_col¶ –
一个 Column，将用于保持表中行的运行版本 ID。这用于检测并发更新或刷新中是否存在陈旧数据。方法是检测 UPDATE 语句是否与上次已知的版本 ID 不匹配，如果否，则会抛出 StaleDataError 异常。默认情况下，列必须是 Integer 类型，除非 version_id_generator 指定了备用版本生成器。

另请参阅

配置版本计数器 - 版本计数和原理的讨论。
version_id_generator¶ –
定义应如何生成新版本 ID。默认为 None，表示应采用简单的整数计数方案。要提供自定义版本控制方案，请提供以下形式的可调用函数
```
def generate_version(version):
    return next_version
```
或者，可以使用服务器端版本控制功能（如触发器）或版本 ID 生成器之外的编程版本控制方案，方法是指定值 False。有关使用此选项时的重要事项的讨论，请参阅服务器端版本计数器。

另请参阅

自定义版本计数器/类型

服务器端版本计数器
with_polymorphic¶ –
一个元组，形式为 (<classes>, <selectable>)，指示“多态”加载的默认样式，即一次查询哪些表。'*' 可用于指示应立即加载所有后代类。第二个元组参数
在现代映射中，Mapper.polymorphic_load 参数可能比使用 Mapper.with_polymorphic 更可取，以指示指示多态加载样式的每个子类技术。

另请参阅

在映射器上配置 with_polymorphic()

method sqlalchemy.orm.Mapper.add_properties(dict_of_properties)¶: 使用 add_property 将给定的属性字典添加到此映射器。

method sqlalchemy.orm.Mapper.add_property(key: str, prop: Column[Any] | MapperProperty[Any]) → None¶

向此映射器添加单个 MapperProperty。

如果映射器尚未配置，则只需将属性添加到发送给构造函数的初始属性字典中。如果此 Mapper 已配置，则会立即配置给定的 MapperProperty。

attribute sqlalchemy.orm.Mapper.all_orm_descriptors¶

与映射类关联的所有 InspectionAttr 属性的命名空间。

这些属性在所有情况下都是与映射类或其超类关联的 Python 描述符。

此命名空间包括映射到类的属性以及扩展模块声明的属性。它包括任何继承自 InspectionAttr 的 Python 描述符类型。这包括 QueryableAttribute，以及扩展类型，例如 hybrid_property， hybrid_method 和 AssociationProxy。

为了区分映射属性和扩展属性，属性 InspectionAttr.extension_type 将引用一个常量，该常量区分不同的扩展类型。

属性的排序基于以下规则

按从子类到超类的顺序迭代类及其超类（即，迭代 cls.__mro__）
对于每个类，按照它们在 __dict__ 中出现的顺序生成属性，但以下步骤 3 中的属性除外。在 Python 3.6 及更高版本中，此排序将与类的构造顺序相同，但应用程序或映射器在事后添加的属性除外。
如果某个属性键也在超类 __dict__ 中，则它包含在该类的迭代中，而不是它首次出现的类中。

以上过程产生的排序在属性分配给类的顺序方面是确定性的。

版本 1.3.19 中变更：确保了 Mapper.all_orm_descriptors() 的确定性排序。

当处理 QueryableAttribute 时，QueryableAttribute.property 属性引用 MapperProperty 属性，这是您通过 Mapper.attrs 引用映射属性集合时获得的内容。

警告

The Mapper.all_orm_descriptors 访问器命名空间是 OrderedProperties 的实例。这是一个类似字典的对象，包含少量命名方法，例如 OrderedProperties.items() 和 OrderedProperties.values()。当动态访问属性时，建议使用字典访问方案，例如 mapper.all_orm_descriptors[somename] 而不是 getattr(mapper.all_orm_descriptors, somename)，以避免名称冲突。

另请参阅

Mapper.attrs

attribute sqlalchemy.orm.Mapper.attrs¶

所有与此 mapper 关联的 MapperProperty 对象的命名空间。

这是一个基于其键名提供每个属性的对象。例如，具有 User.name 属性的 User 类的 mapper 将提供 mapper.attrs.name，这将是代表 name 列的 ColumnProperty。命名空间对象也可以被迭代，这将产生每个 MapperProperty。

Mapper 具有此属性的几个预过滤视图，这些视图限制了返回的属性类型，包括 synonyms、column_attrs、relationships 和 composites。

警告

The Mapper.attrs 访问器命名空间是 OrderedProperties 的实例。这是一个类似字典的对象，包含少量命名方法，例如 OrderedProperties.items() 和 OrderedProperties.values()。当动态访问属性时，建议使用字典访问方案，例如 mapper.attrs[somename] 而不是 getattr(mapper.attrs, somename)，以避免名称冲突。

另请参阅

Mapper.all_orm_descriptors

attribute sqlalchemy.orm.Mapper.base_mapper: Mapper[Any]¶

继承链中最底层的 Mapper。

在非继承场景中，此属性将始终是这个 Mapper。在继承场景中，它引用作为继承链中所有其他 Mapper 对象的父级的 Mapper。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

attribute sqlalchemy.orm.Mapper.c: ReadOnlyColumnCollection[str, Column[Any]]¶: Mapper.columns 的同义词。

method sqlalchemy.orm.Mapper.cascade_iterator(type_: str, state: InstanceState[_O], halt_on: Callable[[InstanceState[Any]], bool] | None = None) → Iterator[Tuple[object, Mapper[Any], InstanceState[Any], _InstanceDict]]¶

在对象图中迭代每个元素及其 mapper，针对满足给定级联规则的所有关系。

参数:

type_¶ –
级联规则的名称（即 "save-update"、 "delete" 等）。

注意

此处不接受 "all" 级联。有关通用对象遍历函数，请参阅如何遍历与给定对象相关的所有对象？。
state¶ – 引导 InstanceState。子项将根据为此对象的 mapper 定义的关系进行处理。

返回:

该方法产生单个对象实例。

另请参阅

级联

如何遍历与给定对象相关的所有对象？ - 说明了一个通用的函数，用于遍历所有对象，而无需依赖级联。

attribute sqlalchemy.orm.Mapper.class_: Type[_O]¶: 此 Mapper 映射到的类。

attribute sqlalchemy.orm.Mapper.class_manager: ClassManager[_O]¶

ClassManager 为此 Mapper 维护事件监听器和类绑定的描述符。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

attribute sqlalchemy.orm.Mapper.column_attrs¶: 返回由此 Mapper 维护的所有 ColumnProperty 属性的命名空间。

另请参阅

Mapper.attrs - 所有 MapperProperty 对象的命名空间。

attribute sqlalchemy.orm.Mapper.columns: ReadOnlyColumnCollection[str, Column[Any]]¶

由此 Mapper 维护的 Column 或其他标量表达式对象的集合。

此集合的行为与任何 Table 对象上的 c 属性的行为相同，但只有此映射中包含的列才会出现，并且基于映射中定义的属性名称进行键控，不一定是 Column 本身的 key 属性。此外，通过 column_property() 映射的标量表达式也在此处存在。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

method sqlalchemy.orm.Mapper.common_parent(other: Mapper[Any]) → bool¶: 如果给定的 mapper 与此 mapper 共享一个共同的继承父级，则返回 true。

attribute sqlalchemy.orm.Mapper.composites¶: 返回由此 Mapper 维护的所有 Composite 属性的命名空间。

另请参阅

Mapper.attrs - 所有 MapperProperty 对象的命名空间。

attribute sqlalchemy.orm.Mapper.concrete: bool¶

如果此 Mapper 是具体继承 mapper，则表示 True。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

attribute sqlalchemy.orm.Mapper.configured: bool = False¶

如果此 Mapper 已配置，则表示 True。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

另请参阅

configure_mappers().

attribute sqlalchemy.orm.Mapper.entity¶

inspection API 的一部分。

返回 self.class_。

method sqlalchemy.orm.Mapper.get_property(key: str, _configure_mappers: bool = False) → MapperProperty[Any]¶: 返回与给定键关联的 MapperProperty。

method sqlalchemy.orm.Mapper.get_property_by_column(column: ColumnElement[_T]) → MapperProperty[_T]¶: 给定一个 Column 对象，返回映射此列的 MapperProperty。

method sqlalchemy.orm.Mapper.identity_key_from_instance(instance: _O) → _IdentityKeyType[_O]¶

基于给定实例的主键属性，返回其标识键。

如果实例的状态已过期，则调用此方法将导致数据库检查以查看对象是否已被删除。如果该行不再存在，则会引发 ObjectDeletedError。

此值通常也在实例状态下的 *key* 属性名下找到。

method sqlalchemy.orm.Mapper.identity_key_from_primary_key(primary_key: Tuple[Any, ...], identity_token: Any | None = None) → _IdentityKeyType[_O]¶

返回一个标识映射键，用于在标识映射中存储/检索项。

参数:: primary_key¶ – 指示标识符的值列表。

method sqlalchemy.orm.Mapper.identity_key_from_row(row: Row[Any] | RowMapping, identity_token: Any | None = None, adapter: ORMAdapter | None = None) → _IdentityKeyType[_O]¶

返回一个标识映射键，用于在标识映射中存储/检索项。

参数:

row¶ –

从结果集中生成的 Row 或 RowMapping，该结果集是从 ORM 映射的主键列中选择的。

在版本 2.0 中更改： Row 或 RowMapping 被接受作为 “row” 参数

attribute sqlalchemy.orm.Mapper.inherits: Mapper[Any] | None¶: 引用此 Mapper 继承自的 Mapper（如果有）。

attribute sqlalchemy.orm.Mapper.is_mapper = True¶: inspection API 的一部分。

method sqlalchemy.orm.Mapper.is_sibling(other: Mapper[Any]) → bool¶: 如果另一个 mapper 是此 mapper 的继承兄弟（sibling），则返回 true。共同的父级但不同的分支

method sqlalchemy.orm.Mapper.isa(other: Mapper[Any]) → bool¶: 如果此 mapper 继承自给定的 mapper，则返回 True。

attribute sqlalchemy.orm.Mapper.iterate_properties¶: 返回所有 MapperProperty 对象的迭代器。

attribute sqlalchemy.orm.Mapper.local_table: FromClause¶

此 Mapper 引用的直接 FromClause。

通常是 Table 的实例，可以是任何 FromClause。

“local” 表是 Mapper 直接负责从属性访问和刷新角度进行管理的可选对象。对于非继承映射器，Mapper.local_table 将与 Mapper.persist_selectable 相同。对于继承映射器，Mapper.local_table 指的是 Mapper.persist_selectable 的特定部分，该特定部分包含此 Mapper 正在加载/持久化的列，例如连接中的特定 Table。

另请参阅

Mapper.persist_selectable.

Mapper.selectable.

attribute sqlalchemy.orm.Mapper.mapped_table¶: Deprecated since version 1.3: 使用 .persist_selectable，此属性已弃用

attribute sqlalchemy.orm.Mapper.mapper¶

inspection API 的一部分。

返回自身。

attribute sqlalchemy.orm.Mapper.non_primary: bool¶

如果此 Mapper 是“非主”映射器（例如，仅用于选择行但不用于持久性管理的映射器），则表示 True。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

attribute sqlalchemy.orm.Mapper.persist_selectable: FromClause¶

此 FromClause 是此 Mapper 映射到的对象。

通常是 Table 的实例，可以是任何 FromClause。

Mapper.persist_selectable 类似于 Mapper.local_table，但在继承场景中，它表示 FromClause，该对象表示整个继承类层次结构。

:attr.`.Mapper.persist_selectable` 也与 Mapper.selectable 属性分开，后者可能是用于选择列的备用子查询。 :attr.`.Mapper.persist_selectable` 面向将在持久化操作中写入的列。

另请参阅

Mapper.selectable.

Mapper.local_table.

attribute sqlalchemy.orm.Mapper.polymorphic_identity: Any | None¶

表示一个标识符，在结果行加载期间，该标识符与 Mapper.polymorphic_on 列进行匹配。

仅在继承中使用，此对象可以是任何类型，该类型可与 Mapper.polymorphic_on 表示的列的类型进行比较。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

method sqlalchemy.orm.Mapper.polymorphic_iterator() → Iterator[Mapper[Any]]¶

迭代遍历包含此映射器和所有后代映射器的集合。

这不仅包括直接继承的映射器，还包括它们的所有继承映射器。

要遍历整个层次结构，请使用 mapper.base_mapper.polymorphic_iterator()。

attribute sqlalchemy.orm.Mapper.polymorphic_map: Dict[Any, Mapper[Any]]¶

在继承场景中，“多态标识”标识符映射到 Mapper 实例的映射。

标识符可以是任何类型，该类型可与 Mapper.polymorphic_on 表示的列的类型进行比较。

映射器的继承链都将引用相同的多态映射对象。该对象用于将传入的结果行与目标映射器相关联。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

attribute sqlalchemy.orm.Mapper.polymorphic_on: KeyedColumnElement[Any] | None¶

在继承场景中，指定为此 Mapper 的 polymorphic_on 参数的 Column 或 SQL 表达式。

此属性通常是 Column 实例，但也可能是一个表达式，例如从 cast() 派生的表达式。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

attribute sqlalchemy.orm.Mapper.primary_key: Tuple[Column[Any], ...]¶

一个可迭代对象，其中包含 Column 对象的集合，这些对象构成了从此 Mapper 的角度来看，映射表的“主键”。

此列表针对 Mapper.persist_selectable 中的可选对象。在继承映射器的情况下，某些列可能由超类映射器管理。例如，在 Join 的情况下，主键由 Join 引用的所有表的所有主键列确定。

此列表也不一定与基础表关联的主键列集合相同； Mapper 具有 primary_key 参数，该参数可以覆盖 Mapper 视为主键列的内容。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

method sqlalchemy.orm.Mapper.primary_key_from_instance(instance: _O) → Tuple[Any, ...]¶

返回给定实例的主键值列表。

如果实例的状态已过期，则调用此方法将导致数据库检查以查看对象是否已被删除。如果该行不再存在，则会引发 ObjectDeletedError。

method sqlalchemy.orm.Mapper.primary_mapper() → Mapper[Any]¶: 返回与此映射器的类键（class）对应的主映射器。

attribute sqlalchemy.orm.Mapper.relationships¶: 此 Mapper 维护的所有 Relationship 属性的命名空间。

警告

Mapper.relationships 访问器命名空间是 OrderedProperties 的实例。这是一个类似字典的对象，其中包括少量命名方法，例如 OrderedProperties.items() 和 OrderedProperties.values()。当动态访问属性时，请优先使用字典访问方案，例如 mapper.relationships[somename] 而不是 getattr(mapper.relationships, somename)，以避免名称冲突。

另请参阅

Mapper.attrs - 所有 MapperProperty 对象的命名空间。

attribute sqlalchemy.orm.Mapper.selectable¶

此 Mapper 默认从中选择的 FromClause 构造。

通常，这等同于 persist_selectable，除非正在使用 with_polymorphic 功能，在这种情况下，将返回完整的“多态”可选对象。

attribute sqlalchemy.orm.Mapper.self_and_descendants¶

包含此映射器和所有后代映射器的集合。

这不仅包括直接继承的映射器，还包括它们的所有继承映射器。

attribute sqlalchemy.orm.Mapper.single: bool¶

如果此 Mapper 是单表继承映射器，则表示 True。

如果设置了此标志，则 Mapper.local_table 将为 None。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

attribute sqlalchemy.orm.Mapper.synonyms¶: 返回由此 Mapper 维护的所有 Synonym 属性的命名空间。

另请参阅

Mapper.attrs - 所有 MapperProperty 对象的命名空间。

attribute sqlalchemy.orm.Mapper.tables: Sequence[TableClause]¶

一个序列，其中包含此 Mapper 知道的 Table 或 TableClause 对象的集合。

如果映射器映射到 Join 或表示 Select 的 Alias，则构成完整构造的各个 Table 对象将在此处表示。

这是一个在 mapper 构建期间确定的只读属性。如果直接修改，行为是未定义的。

attribute sqlalchemy.orm.Mapper.validators: util.immutabledict[str, Tuple[str, Dict[str, Any]]]¶

使用 validates() 装饰器装饰的属性的不可变字典。

字典包含字符串属性名称作为键，映射到实际的验证方法。

attribute sqlalchemy.orm.Mapper.with_polymorphic_mappers¶: 默认“多态”查询中包含的 Mapper 对象列表。

class sqlalchemy.orm.MappedAsDataclass¶: Mixin 类，指示何时映射此类，同时将其转换为数据类。

另请参阅

声明式数据类映射 - 关于 SQLAlchemy 原生数据类映射的完整背景信息

2.0 版本新增。

class sqlalchemy.orm.MappedClassProtocol¶

表示 SQLAlchemy 映射类的协议。

该协议是类类型的泛型，使用 MappedClassProtocol[Any] 以允许任何映射类。

类签名

class sqlalchemy.orm.MappedClassProtocol (typing_extensions.Protocol)

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

项目版本

类映射 API¶