类映射 API¶

对象名称	描述
add_mapped_attribute（目标、键、属性）	将新的 mapped 属性添加到 ORM 映射类中。
as_declarative（**kw）	类装饰器，它将把给定的类改编成一个 `declarative_base（）` 的
class_mapper（class_[，配置]）	给定一个类，返回与该键关联的主 `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（）	初始化到目前为止已在所有`注册表`中构建的所有映射器的映射器间关系收集。
declarative_base（*， [元数据，映射器， cls，名称， class_registry， type_annotation_map，构造函数，元类]）	为声明性类定义构造基类。
declarative_mixin （CLS）	将类标记为提供 “declarative mixin” 功能。
声明式基础	用于声明性类定义的基类。
声明式 BaseNoMeta	与 `DeclarativeBase` 相同，但不使用元类来拦截新属性。
declared_attr	将类级方法标记为表示映射属性或 Declarative 指令的定义。
has_inherited_table （CLS）	给定一个类，如果它继承自的任何类具有映射表，则返回 True，否则返回 False。
identity_key（[class_， ident]， *， [实例，行， identity_token]）	生成 “identity key” 元组，用作 `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` 结构，以便在声明式表中使用配置。
MappedAsData类	Mixin 类来指示在映射此类时，还要将其转换为数据类。
MappedClassProtocol 协议	表示 SQLAlchemy 映射类的协议。
映射	定义 Python 类与数据库表或其他关系结构之间的关联，以便针对该类的 ORM作可以继续进行。
object_mapper（实例）	给定一个对象，返回与该对象实例关联的主 Mapper。
orm_insert_sentinel（[名称， type_]， *， [默认， omit_from_statements]）	提供一个代理 `mapped_column（）` 生成所谓的 sentinel 列，允许对没有合格主键配置的表进行高效的批量插入和确定性的 RETURNING 排序。
polymorphic_union（table_map， typecolname[， aliasname， cast_nulls]）	创建多态映射器使用的 `UNION` 语句。
重建器（fn）	将方法装饰为 'reconstructor' 钩子。
注册表	用于映射类的通用注册表。
synonym_for（姓名[， map_column]）	生成`同义词（）` 的装饰器属性与 Python 描述符结合使用。

类 sqlalchemy.orm 中。注册表¶

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

注册表用作维护 Map 集合的基础，并提供用于 Map 类的配置钩子。

支持的三种常规映射类型是 Declarative Base、Declarative Decorator 和 Imperative Mapping。所有这些映射样式都可以互换使用：

registry.generate_base（） 返回一个新的声明性基类，并且是 declarative_base（） 函数。
registry.mapped（） 提供了一个类装饰器，它将声明式映射应用于类，而无需使用声明式基类。
registry.map_imperatively（） 将生成一个 类的映射器，而不扫描类的声明性类属性。此方法适合 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 映射类概述 - 类映射样式概述。

方法 sqlalchemy.orm.registry 中。__init__（*， metadata：可选[元数据] = 无， class_registry：可选[clsregistry._ClsRegistryType] = 无， type_annotation_map：可选[_TypeAnnotationMapType] = 无， 构造函数：Callable[...， None] = <函数 _declarative_constructor>）¶

构建新的注册表

参数

metadata¶– 一个可选的 MetaData 实例。都使用声明式表映射生成的表对象将使用此 MetaData 收集。如果此参数保留为默认值 None，则会创建一个空白的 MetaData 集合。
constructor¶– 指定 __init__ 函数在没有自己的 __init__ 的映射类上的实现。默认为将声明的字段和关系的 **kwargs 分配给实例的实现。如果提供 None，则不会提供任何 __init__，并且构造将通过正常的 Python 语义回退到 cls.__init__。
class_registry¶ – 可选字典，当字符串名称用于标识 relationship（） 中的类时，将用作类名>映射类的注册表和其他。允许两个或多个声明性基类共享相同的类名注册表以进行简化碱基间关系。
type_annotation_map¶ –

Python 类型的可选字典添加到 SQLAlchemy TypeEngine 类或实例。提供的 dict 将更新默认类型映射。这由 MappedColumn 构造独占使用要根据 映射类型。

2.0 版的新Function。

另请参阅

自定义类型映射

方法 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（）的。

方法 sqlalchemy.orm.registry 中。configure（cascade： bool = False）→ 无¶

在此 注册表。

configure 步骤用于协调和初始化 relationship（） 链接，以及调用配置事件（如 MapperEvents.before_configured() 和 MapperEvents.after_configured() ，它可能由 ORM 扩展或用户定义的扩展钩子使用。

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

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

另请参阅

configure_mappers（）

1.4.0b2 版本的新Function。

方法 sqlalchemy.orm.registry 中。dispose（cascade： bool = False）→ 无¶

释放此注册表中的所有映射器。

调用后，此注册表中映射的所有类将不再具有与之关联的类检测。此方法是应用程序范围的 clear_mappers（） 函数的每个注册表的模拟。

如果此注册表包含依赖于其他注册表的映射器，通常通过 relationship（） 链接，则还必须处理这些注册表。当此类注册表与此注册表相关时，如果 dispose.cascade 标志设置为 True，则还会调用其 registry.dispose（） 方法;否则，如果尚未释放这些注册表，则会引发错误。

1.4.0b2 版本的新Function。

另请参阅

clear_mappers（）

方法 sqlalchemy.orm.registry 中。generate_base（mapper：~打字。可调用的[[...]，~sqlalchemy.orm.mapper.Mapper[~typing.Any]]None=None，cls：~typing.键入[~typing.Any]=，name：str='Base'，metaclass：~typing。键入[~typing.Any]=）→ 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（） 函数提供实现，该函数同时创建注册表和基类。

有关背景和示例，请参阅 Declarative Mapping 部分。

参数

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

另请参阅

声明式映射

declarative_base（）

方法 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（） 中。

请参阅 Declarative Mapping 部分了解完整的详细信息和示例。

参数: cls¶ —— 要映射的类。
结果: Mapper 对象。

另请参阅

声明式映射

registry.mapped（） - 此函数的更常见装饰器接口。

registry.map_imperatively（）

方法 sqlalchemy.orm.registry 中。map_imperatively（class_： type[_O]， local_table：FromClauseNone=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 构造函数。

另请参阅

命令式映射

声明式映射

方法 sqlalchemy.orm.registry 中。mapped（cls： Type[_O]）→ Type[_O]¶

类装饰器，它将 Declarative 映射过程应用于给定的类。

例如：

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)

请参阅 Declarative Mapping 部分了解完整的详细信息和示例。

参数: cls¶ —— 要映射的类。
结果: 传递的类。

另请参阅

声明式映射

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

另请参阅

registry.mapped_as_dataclass()

方法 sqlalchemy.orm.registry 中。mapped_as_dataclass（_registry__cls：Type[_O]None=None， *， init：_NoArgbool=_NoArg.NO_ARG， repr：_NoArgbool=_NoArg.NO_ARG， eq：_NoArgbool=_NoArg.NO_ARG， order：_NoArgbool=_NoArg.NO_ARG， unsafe_hash：_NoArgbool=_NoArg.NO_ARG， match_args：_NoArgbool=_NoArg.NO_ARG， kw_only：_NoArgbool=_NoArg.NO_ARG， dataclass_callable：_NoArgCallable[...，Type[Any]]=_NoArg.NO_ARG）→Type[_O]Callable[[Type[_O]]，Type[_O]]¶: 类装饰器，它将声明式映射过程应用于给定类，并将该类额外转换为 Python 数据类。

另请参阅

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

2.0 版的新Function。

属性 sqlalchemy.orm.registry 中。映射器¶: 所有 Mapper 对象的只读集合。

方法 sqlalchemy.orm.registry 中。update_type_annotation_map（type_annotation_map： _TypeAnnotationMapType）→ 无¶: 使用新值更新registry.type_annotation_map。

函数 sqlalchemy.orm 中。add_mapped_attribute（target： Type[_O]， key： str， attr： MapperProperty[Any]）→ 无¶

将新的 mapped 属性添加到 ORM 映射类中。

例如：

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

这可用于不使用拦截属性集作的声明性元类的 ORM 映射。

2.0 版的新Function。

函数 sqlalchemy.orm 中。column_property（column： _ORMColumnExprArgument[_T]， *additional_columns： _ORMColumnExprArgument[Any]， group：strNone=None，deferred： bool = False， raiseload： bool = False， comparator_factory：Type[PropComparator[_T]]None=None， init：_NoArgbool=_NoArg.NO_ARG， repr：_NoArgbool=_NoArg.NO_ARG， default：AnyNone=_NoArg.NO_ARG， default_factory：_NoArgCallable[[]，_T]=_NoArg.NO_ARG， compare：_NoArgbool=_NoArg.NO_ARG， kw_only：_NoArgbool=_NoArg.NO_ARG， hash：_NoArgboolNone=_NoArg.NO_ARG， active_history： bool = False， expire_on_flush： bool = True， info：_InfoTypeNone=None， doc：strNone=None）→ MappedSQLExpression[_T]¶

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

使用声明式映射时，column_property（） 用于将只读 SQL 表达式映射到映射的类。

当使用 Imperative 映射时，column_property（） 还承担了使用其他功能映射 table 列的角色。当使用完全声明式映射时，mapped_column（） 构造（construct）应用于此目的。

使用声明式数据类映射时，column_property（） 被视为只读，并且不会包含在 Dataclass __init__（） 构造函数中。

column_property（） 函数返回 ColumnProperty 的 ColumnProperty。

另请参阅

使用 column_property - 一般用法 column_property（） 映射 SQL 表达式

为命令式表列应用 Load、Persistence 和 Mapping 选项 - 使用 column_property（） 替换为命令式表映射，以将其他选项应用于普通 Column 对象

参数

*cols¶ —— 要映射的 Column 对象列表。
active_history=False¶ – 仅用于命令式表映射，或传统风格的声明式映射（即尚未升级到 mapped_column（）），用于预期可写的基于列的属性;将 mapped_column（） 与 mapped_column.active_history 用于声明式映射。有关功能详细信息，请参阅该参数。
comparator_factory¶ —— 一个扩展 Comparator 提供自定义 SQL 子句生成以进行比较作。
group¶– 标记为 Deferred 时此属性的组名称。
deferred¶——当 True 时，column 属性为 “deferred”，这意味着它不会立即加载，而是在属性。另请参阅 deferred（） 的
doc¶ – 可选字符串，将作为 doc 应用于类绑定描述符。
expire_on_flush=True¶ – 禁用刷新过期。引用 SQL 表达式（而不是单个表绑定列）的 column_property（）被视为“只读”属性;填充它对数据的状态没有影响，它只能返回数据库状态。因此，每当父对象参与 flush 时，column_property（）的值就会过期，也就是说，在 flush 中具有任何类型的 “dirty” 状态。将此参数设置为 False 的效果是在刷新继续后保留任何现有值。请注意，具有默认过期设置的 Session 在 Session.commit（） 调用后仍会使所有属性过期。
info¶– 可选的数据字典，将被填充到 MapperProperty.info 对象的属性。
raiseload¶ –

如果为 True，则指示列在未延迟时应引发错误，而不是加载值。这可以在查询时使用带有 raiseload=False 的 deferred（） 选项来更改。

在 1.4 版本加入.

另请参阅

使用 raiseload 防止延迟的柱载荷
初始化¶ –

特定于声明性数据类映射，指定映射的属性是否应是 __init__（） 的一部分方法。

1.4 版后已移除： column_property.init 参数已弃用 column_property（）。此参数仅适用于 Declarative Dataclasses 配置中的 writeable-attribute，并且 column_property（） 在此上下文中被视为只读属性。
repr¶——特定于声明式数据类映射，指定映射的属性是否应该是 __repr__（） 的一部分方法。
default_factory¶ –

特定于 Declarative Dataclass Mapping，指定将作为 __init__（） 的一部分发生的默认值生成函数方法。

1.4 版后已移除：该 column_property.default_factory 参数已弃用 column_property（） 。此参数仅适用于 Declarative Dataclasses 配置中的 writeable-attribute，并且 column_property（） 在此上下文中被视为只读属性。

另请参阅

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

mapped_column.default

mapped_column.insert_default
比较¶ –

特定于 Declarative Dataclass Mapping，指示此字段是否在生成 __eq__（） 和 __ne__（） 方法。

2.0.0b4 版本的新Function。
kw_only¶ –

特定于 Declarative Dataclass Mapping，指示在生成 __init__（） 时是否应将此字段标记为仅关键字。

1.4 版后已移除： column_property.kw_only 参数已弃用 column_property（）。此参数仅适用于 Declarative Dataclasses 配置中的 writeable-attribute，并且 column_property（） 在此上下文中被视为只读属性。
哈希¶ –

特定于 Declarative Dataclass Mapping，控制在为映射的类生成 __hash__（） 方法时是否包含此字段。

在 2.0.36 版本加入.

函数 sqlalchemy.orm 中。declarative_base（*， metadata：可选[MetaData] = 无， mapper：可选[Callable[...， mapper[Any]]] = 无， cls： Type[Any] = <class 'object'>， name： str = 'base'， class_registry：可选[clsregistry._ClsRegistryType] = 无， type_annotation_map：可选[_TypeAnnotationMapType] = 无， 构造函数： Callable[...， None] = <函数 _declarative_constructor>，元类：Type[Any] = <class 'sqlalchemy.orm.decl_api。DeclarativeMeta'>）→ Any¶

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

新的基类将获得一个元类，该元类生成适当的 Table 对象，并根据类和类的任何子类中声明性提供的信息进行适当的 Mapper 调用。

在 2.0 版更改：请注意，declarative_base（） function 被新的 DeclarativeBase 类取代，该类使用子类化生成一个新的 “base” 类，而不是返回函数的值。这允许使用与 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（） function 现在是更通用的 Registry 类。该函数还会移动到 sqlalchemy.orm 包。

参数

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

Python 类型的可选字典添加到 SQLAlchemy TypeEngine 类或实例。这由 MappedColumn 构造独占使用要根据 映射类型。

2.0 版的新Function。

另请参阅

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

另请参阅

注册表

函数 sqlalchemy.orm 中。declarative_mixin（cls： Type[_T]）→ Type[_T]¶

将类标记为提供 “declarative 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 声明性 mixin 类。

在 1.4.6 版本加入.

另请参阅

使用 Mixin 组合映射的层次结构

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

函数 sqlalchemy.orm 中。as_declarative（**kw： Any）→ Callable[[Type[_T]]]， Type[_T]]¶

类装饰器，它将把给定的类改编成一个 declarative_base（） 的

此函数使用 registry.as_declarative_base() 方法，首先自动创建一个注册表，然后调用 decorator。

例如：

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()

函数 sqlalchemy.orm 中。mapped_column（__name_pos：str_TypeEngineArgument[Any]SchemaEventTargetNone=None， __type_pos：_TypeEngineArgument[Any]SchemaEventTargetNone=None， *args： SchemaEventTarget， init：_NoArgbool=_NoArg.NO_ARG， repr：_NoArgbool=_NoArg.NO_ARG， default：AnyNone=_NoArg.NO_ARG， default_factory：_NoArgCallable[[]，_T]=_NoArg.NO_ARG，比较：_NoArgbool=_NoArg.NO_ARG， kw_only：_NoArgbool=_NoArg.NO_ARG， hash：_NoArgboolNone=_NoArg.NO_ARG， nullable：boolLiteral[SchemaConst.NULL_UNSPECIFIED]None=SchemaConst.NULL_UNSPECIFIED， primary_key：boolNone=False， deferred：_NoArgbool=_NoArg.NO_ARG， deferred_group：strNone=None， deferred_raiseload：boolNone=None， use_existing_column： bool = False， name：strNone=无， type_：_TypeEngineArgument[Any]None=无， autoincrement： _AutoIncrementType = 'auto'， doc：strNone=None， key：strNone=None， index：boolNone=None， unique：boolNone=None， info：_InfoTypeNone=None， onupdate：AnyNone=无， insert_default：AnyNone=_NoArg.NO_ARG， server_default：_ServerDefaultArgumentNone=无， server_onupdate：_ServerOnUpdateArgumentNone=无， active_history： bool = False， quote：boolNone=无， 系统： bool = False， comment：strNone=None， sort_order：_NoArgint=_NoArg.NO_ARG， **kw： Any）→ MappedColumn[Any]¶

声明一个新的 ORM 映射 Column 结构，以便在声明式表中使用配置。

mapped_column（） 函数提供了一个 ORM 感知的与 Python typing-compatible 结构一起使用声明性映射，用于指示映射到 Core Column 对象的属性。它提供与将属性映射到 Column 对象，特别是使用 Declarative Table 时配置。

2.0 版的新Function。

mapped_column（） 通常与 Mapped 注解类型一起使用，它可以在其中派生 SQL type 和可为 null 性，具体取决于 映射的注释。它也可以在没有注释的情况下使用，作为 SQLAlchemy 1.x 样式的声明性映射中使用 Column 的直接替代品。

有关 mapped_column（） 的使用示例，请参阅使用 mapped_column（）的声明式表中的文档。

另请参阅

使用 mapped_column（）的声明式表 - 完整文档

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

参数

__name¶- 要提供给 Column 的字符串名称。这是一个可选的、仅位置参数，如果存在，则必须是传递的第一个位置参数。如果省略，则 mapped_column（） 映射到的属性名称将用作 SQL 列名。
__type¶– TypeEngine 类型或实例，它将指示要与 列 关联的数据类型。这是一个可选的、仅限位置的参数，如果存在，则必须紧跟在 __name 参数后面（如果存在），否则是第一个位置参数。如果省略，则该列可以从 annotated 类型派生，或者如果 ForeignKey 存在，来自引用列的数据类型。
args¶– 额外的位置参数包括 ForeignKey、CheckConstraint 和 Identity 等结构，这些结构被传递给构造的 列。
nullable¶- 可选 bool，列应该是 “NULL” 还是 “NOT NULL”。如果省略，则根据是否键入从类型注释派生可为 null。Optional 存在。 nullable 默认为 True（否则为非主键列），为 False（主键列）。
primary_key¶ – 可选 bool，表示 Column 是否是表主键的一部分。
延迟¶ –

可选 bool - 此关键字参数由 ORM 声明进程使用，并且不是 Column 的一部分本身;相反，它指示此列应为 “deferred” for 加载，就像由 deferred（） 映射一样。

另请参阅

在 Mapping 上配置列延迟
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 版本的新Function。
默认¶ –

直接传递给 Column.default 参数（如果 mapped_column.insert_default 参数不存在。此外，当与声明性数据类映射一起使用时，指示应应用于生成的 __init__（） 方法中的关键字构造函数的默认 Python 值。

请注意，在生成数据类的情况下，当 mapped_column.insert_default 不存在，这意味着 mapped_column.default 值在两个 places、__init__（） 方法以及 Column.default 参数。虽然此行为在未来版本中可能会更改，但目前这往往会“正常工作”;默认值 None 意味着 Column 没有默认生成器，而默认值引用非 None Python 或 SQL 表达式值将在对象前面分配 __init__（） 调用，该值与 Core Insert 构造将在任何情况下使用，从而导致相同的最终结果。

注意

当使用 Core 级别的列默认值时，这些默认值是由底层 Column 与 ORM 映射的数据类一起解释的，尤其是那些上下文感知默认函数， mapped_column.insert_default参数必须替换为这对于消除 callable 被解释为数据类级别默认值的歧义是必要的。

另请参阅

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

mapped_column.insert_default

mapped_column.default_factory
insert_default¶ –

直接传递给 Column.default 参数;将取代 mapped_column.default 的值（如果存在） mapped_column.default 将始终应用于 dataclasses 映射的构造函数 default。

另请参阅

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

mapped_column.default

mapped_column.default_factory
sort_order¶ –

一个整数，指示此映射列应该与其他 ORM 创建 表。在具有相同值的映射列之间，使用默认 Sequences，首先放置主类中定义的映射列，然后放置超类中的映射列。默认为 0。排序是升序的。

2.0.4 新版功能.
active_history=错误¶ –

如果为 True，则表示标量属性应在替换时加载，否则已经加载。通常，用于简单的非主键标量值只需要为知道 “new” 值以执行刷新。这标志可用于使用 get_history（） 或 Session.is_modified（） 还需要知道 attribute 的 “previous” 值。

在 2.0.10 版本加入.
init¶ – 特定于声明性数据类映射，指定 mapped 属性是否应成为 __init__（） 的一部分方法。
repr¶——特定于声明式数据类映射，指定映射的属性是否应该是 __repr__（） 的一部分方法。
default_factory¶ –

特定于 Declarative Dataclass Mapping，指定将作为 __init__（） 的一部分发生的默认值生成函数方法。

另请参阅

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

mapped_column.default

mapped_column.insert_default
比较¶ –

特定于 Declarative Dataclass Mapping，指示此字段是否在生成 __eq__（） 和 __ne__（） 方法。

2.0.0b4 版本的新Function。
kw_only¶ – 特定于 Declarative Dataclass Mapping，指示在生成 __init__（） 时是否应将此字段标记为仅关键字。
哈希¶ –

特定于 Declarative Dataclass Mapping，控制在为映射的类生成 __hash__（） 方法时是否包含此字段。

在 2.0.36 版本加入.
**kw¶– 所有剩余的关键字参数都传递给 Column 的构造函数。

类 sqlalchemy.orm 中。declared_attr¶

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

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

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

例：

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

当与 Declarative 指令（如 __tablename__）一起使用时，可以使用 declared_attr.directive（） 修饰符，它向 PEP 484 键入工具表明给定的方法没有处理 映射的属性：

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

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

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，可能需要这样做无法将 decorated 函数识别为具有 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 版本的新Function： - declared_attr 可以容纳一个用 @classmethod 修饰的函数来帮助 PEP 484 必要时集成。

另请参阅

使用 Mixin 编写映射的层次结构 - 声明性 Mixin 文档，其中包含 declared_attr 使用模式的背景。

成员

Cascading，指令

类签名

sqlalchemy.orm.declared_attr类（ sqlalchemy.orm.base._MappedAttribute ， sqlalchemy.orm.decl_api._declared_attr_common ）

属性sqlalchemy.orm.declared_attr。级联¶

将 declared_attr 标记为级联。

这是一个特殊用途的修饰符，它表示在 Mapped-inheritance 场景中，应该为每个 Map 的子类单独配置基于列或 MapperProperty 的声明属性。

警告

declared_attr.cascading 修饰符有几个限制：

该标志仅适用于 declared_attr 在声明性 mixin 类和 __abstract__ 类上;当前，当直接用于 Map 类时，它不起作用。
该标志仅适用于正常命名的属性，例如，不适用于任何特殊的下划线属性，例如 __tablename__。对这些属性没有影响。
该标志当前不允许在 class 层次结构中进一步覆盖;如果子类尝试覆盖该属性，则会发出警告并跳过 overridden 属性。这是一个希望在某个时候得到解决的限制。

下面，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 在名为 some_id 的属性下。

另请参阅

声明式继承

使用 _orm.declared_attr（）生成特定于表的继承列

属性sqlalchemy.orm.declared_attr。指令¶

将declared_attr标记为修饰 Declarative 指令，例如 __tablename__ 或 __mapper_args__。

declared_attr.directive 的目的是严格支持 PEP 484 类型工具，通过允许装饰函数具有不使用 Mapped generic 类，通常情况下declared_attr 用于列和映射的属性。在运行时，declared_attr.指令会返回 declared_attr类未修改。

例如：

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

2.0 版的新Function。

另请参阅

使用 Mixin 组合映射的层次结构

declared_attr

类 sqlalchemy.orm 中。声明式基础¶

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

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

from sqlalchemy.orm import DeclarativeBase


class Base(DeclarativeBase):
    pass

上面的 Base 类现在可用作新的声明性映射的基础。超类使用 __init_subclass__（） 方法来设置新类和元类。

首次使用时，DeclarativeBase 类会实例化一个新的 registry 与 base 一起使用，假设没有明确提供。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 集合。如果注册表是自动构建的，则此 MetaData 集合将用于构建它。否则，本地 MetaData 集合将取代使用 DeclarativeBase.registry 参数。
type_annotation_map¶ – 可选的类型注释映射，将作为 registry.type_annotation_map。
注册表¶ – 直接提供预先存在的注册表。

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

__init__行为

在普通 Python 类中，类层次结构中最基本的 __init__（） 方法是 object.__init__（） ，它不接受任何参数。但是，当首次声明 DeclarativeBase 子类时，该类将获得一个 __init__（） 方法，该方法链接到 registry.constructor 构造函数（如果没有 __init__（） 方法已存在;这是通常的声明式构造函数，该构造函数会将关键字参数分配为实例，假设这些属性是在类级别建立的（即被映射或链接到描述符）。这个构造函数是 在未通过 super（），因为映射类本身会直接被赋予一个 __init__（） 方法，该方法调用 registry.constructor，因此在默认情况下，它与最基本的 __init__（） 无关。方法确实如此。

在 2.0.1 版本发生变更： DeclarativeBase 有一个默认的构造函数，默认情况下它链接到 registry.constructor，因此对 super（）.__init__（） 的调用可以访问这个构造函数。以前，由于实现错误，这个默认构造函数丢失了，调用 super（）.__init__（） 会调用 object.__init__（） 中。

DeclarativeBase 子类还可以声明显式的 __init__（） 方法，该方法将替换 registry.constructor 函数的 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)

请注意，这与 legacy declarative_base（） 就可以了;这些函数创建的 base 将始终为 __init__（） 中。

成员

__mapper__、__mapper_args__、__table__、__table_args__、__tablename__、元数据、注册表

类签名

类 sqlalchemy.orm.DeclarativeBase （ sqlalchemy.inspection.Inspectable ）

属性 sqlalchemy.orm.DeclarativeBase. __mapper__：ClassVar[Mapper[Any]]¶

特定类映射到的 Mapper 对象。

也可以使用 inspect（） 获取，例如 inspect（klass） 的

属性 sqlalchemy.orm.DeclarativeBase. __mapper_args__： Any¶: 将传递给 Mapper 构造函数。

另请参阅

具有声明式的映射器配置选项

属性 sqlalchemy.orm.DeclarativeBase. __table__： ClassVar[FromClause]¶

特定子类映射到的 FromClause。

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

另请参阅

访问表和元数据

属性 sqlalchemy.orm.DeclarativeBase. __table_args__： Any¶: 将传递给 Table 构造函数。看声明式表配置了解此集合的具体结构的背景信息。

另请参阅

声明式表配置

属性 sqlalchemy.orm.DeclarativeBase. __tablename__： Any¶: 要分配给生成的 String name Table 对象，如果未直接通过 DeclarativeBase.__table__。

另请参阅

使用 mapped_column（）的声明式表

属性 sqlalchemy.orm.DeclarativeBase. 元数据： ClassVar[MetaData]¶: 引用将用于新 Table 对象的 MetaData 集合。

另请参阅

访问表和元数据

属性 sqlalchemy.orm.DeclarativeBase. 注册表： ClassVar[registry]¶: 指正在使用的注册表，其中新的 Mapper 对象将被关联。

类 sqlalchemy.orm 中。DeclarativeBaseNoMeta 的元器件¶

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

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

2.0 版的新Function。

成员

__mapper__、__mapper_args__、__table__、__table_args__、__tablename__、元数据、注册表

类签名

类 sqlalchemy.orm.DeclarativeBaseNoMeta （ sqlalchemy.inspection.Inspectable ）

属性 sqlalchemy.orm.DeclarativeBaseNoMeta. __mapper__：ClassVar[Mapper[Any]]¶

特定类映射到的 Mapper 对象。

也可以使用 inspect（） 获取，例如 inspect（klass） 的

属性 sqlalchemy.orm.DeclarativeBaseNoMeta. __mapper_args__： Any¶: 将传递给 Mapper 构造函数。

另请参阅

具有声明式的映射器配置选项

属性 sqlalchemy.orm.DeclarativeBaseNoMeta. __table__：FromClauseNone¶

特定子类映射到的 FromClause。

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

另请参阅

访问表和元数据

属性 sqlalchemy.orm.DeclarativeBaseNoMeta. __table_args__： Any¶: 将传递给 Table 构造函数。看声明式表配置了解此集合的具体结构的背景信息。

另请参阅

声明式表配置

属性 sqlalchemy.orm.DeclarativeBaseNoMeta. __tablename__： Any¶: 要分配给生成的 String name Table 对象，如果未直接通过 DeclarativeBase.__table__。

另请参阅

使用 mapped_column（）的声明式表

属性 sqlalchemy.orm.DeclarativeBaseNoMeta. 元数据： ClassVar[MetaData]¶: 引用将用于新 Table 对象的 MetaData 集合。

另请参阅

访问表和元数据

属性 sqlalchemy.orm.DeclarativeBaseNoMeta. 注册表： ClassVar[registry]¶: 指正在使用的注册表，其中新的 Mapper 对象将被关联。

函数 sqlalchemy.orm 中。has_inherited_table（cls： Type[_O]）→ bool¶

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

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

另请参阅

将 Mixin 和基类与映射继承模式结合使用

函数 sqlalchemy.orm 中。synonym_for（name： str， map_column： bool = False）→ Callable[[Callable[[...]， Any]]，同义词[Any]]¶

生成同义词（） 的装饰器属性与 Python 描述符结合使用。

被修饰的函数将作为 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（） - 映射器级函数

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

函数 sqlalchemy.orm 中。object_mapper（instance： _T）→ Mapper[_T]¶

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

提高 sqlalchemy.orm.exc.UnmappedInstanceError 如果未配置映射。

此功能可通过检测系统实现：

inspect(instance).mapper

使用检查系统会提高 sqlalchemy.exc.NoInspectionAvailable 如果实例不是映射的一部分。

函数 sqlalchemy.orm 中。class_mapper（class_： Type[_O]， configure： bool = True）→ Mapper[_O]¶

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

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

等效功能可通过 inspect（） 获得功能为：

inspect(some_mapped_class)

使用检查系统会提高 sqlalchemy.exc.NoInspectionAvailable 如果未映射类。

函数 sqlalchemy.orm 中。configure_mappers（）→ 无¶

初始化到目前为止已在所有注册表中构建的所有映射器的映射器间关系收集。

configure 步骤用于协调和初始化 relationship（） 链接，以及调用配置事件，例如 MapperEvents.before_configured() 和 MapperEvents.after_configured() ，它可能由 ORM 扩展或用户定义的扩展钩子使用。

Mapper 配置通常是自动调用的，第一次使用来自特定注册表的 Map，以及每当使用 Mapping 并构建其他尚未配置的 Mapper 时。但是，自动配置过程仅在涉及目标映射器和任何相关它可能依赖的 registry 对象;这相当于在特定注册表上调用 registry.configure（） 方法。

相比之下，configure_mappers（） 函数将调用所有注册表对象的配置过程，这些 registry 对象存在于内存中，并且可能适用于许多单个尽管如此，仍然相互关联的 Registry 对象正在使用中。

在 1.4 版本发生变更：从 SQLAlchemy 1.4.0b2 开始，此功能基于每个注册表工作，查找所有注册表 对象存在并在每个对象上调用 registry.configure（） 方法。registry.configure（） 方法可能优于将映射器的配置限制为特定 registry 和/或声明性基类。

调用自动配置的点包括当 Map 类实例化为实例时，以及使用 Session.query（） 或 Session.execute（） 发出 ORM 查询时替换为启用了 ORM 的语句。

mapper configure 进程，是否由 configure_mappers（） 或 registry.configure（） 提供几个事件钩子，可用于增强 Mapper 配置步骤。这些钩子包括：

MapperEvents.before_configured() - 之前调用一次 configure_mappers（） 或 registry.configure（） 可以做任何工作;这可用于在作继续之前建立其他选项、属性或相关映射。
MapperEvents.mapper_configured() - 称为每个个体 Mapper 在进程中配置;将包括所有 Mapper 状态，但其他 Mapper 设置的 backrefs 除外，这些 backrefs 仍有待配置。
MapperEvents.after_configured() - 之后调用一次 configure_mappers（） 或 registry.configure（） 已完成;在此阶段，所有属于配置作范围的 Mapper 对象都将被完全配置。请注意，调用应用程序可能仍具有尚未生成的其他映射，例如，如果它们在尚未导入的模块中，并且如果它们位于不属于当前配置范围的其他注册表集合中，则也可能具有仍待配置的映射。

函数 sqlalchemy.orm 中。clear_mappers（）→ 无¶

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

在 1.4 版本发生变更：此函数现在查找所有 Registry 对象并调用 registry.dispose（） 方法。

此函数从类中删除所有 instrumentation 并释放其关联的映射器。调用后，类将被取消映射，稍后可以使用新的映射器重新映射。

clear_mappers（） 不用于正常使用，因为在非常特定的测试场景之外，它实际上没有有效的用法。通常，映射器是用户定义类的永久结构组件，永远不会独立于其类而被丢弃。如果映射类本身被垃圾回收，则其映射器也会自动处理。因此， clear_mappers（） 仅用于重用具有不同映射的相同类的测试套件，这本身就是一个极其罕见的用例 - 唯一的此类用例实际上是 SQLAlchemy 自己的测试套件，也可能是其他 ORM 扩展库的测试套件，这些库打算在一组固定的类上测试映射器构造的各种组合。

函数 sqlalchemy.orm.util 中。identity_key（class_：Type[_T]None=None， ident：AnyTuple[Any,...]=None， *， instance：_TNone=None， row：Row[Any]RowMappingNone=None， identity_token：AnyNone=None）→ _IdentityKeyType[_T]¶

生成 “identity key” 元组，用作 Session.identity_map字典。

此函数有几种调用样式：

identity_key(class, ident, identity_token=token)

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

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

mapped 类（必须是位置参数）

param ident：

primary key，可以是标量或 Tuples 参数。

参数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 实例：

object 实例（必须作为关键字 arg 提供）
identity_key(class, row=row, identity_token=token)

此表单类似于类/元组表单，不同之处在于将数据库结果行作为 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 类：

mapped 类（必须是位置参数）

param 行：

CursorResult 返回的行 （必须作为关键字 arg 给出）

参数identity_token：

可选身份令牌

1.2 版本的新功能：添加了 identity_token

函数 sqlalchemy.orm 中。polymorphic_union（table_map， typecolname， aliasname='p_union'， cast_nulls=True）¶

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

有关如何使用此功能的示例，请参见 Concrete Table Inheritance 。

参数

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

函数 sqlalchemy.orm 中。orm_insert_sentinel（name：strNone=None， type_：_TypeEngineArgument[Any]None=None， *， default：AnyNone=None， omit_from_statements： bool = True）→ MappedColumn[Any]¶

提供一个代理 mapped_column（） 生成所谓的 sentinel 列，允许对没有合格主键配置的表进行高效的批量插入和确定性的 RETURNING 排序。

使用 orm_insert_sentinel（） 类似于使用 insert_sentinel（） 结构 Table 构造。

将此构造添加到 Declarative 映射类的准则与 insert_sentinel（） 构造的准则相同;数据库表本身还需要存在具有此名称的列。

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

另请参阅

insert_sentinel（）

INSERT 语句的 “Insert Many Values” 行为

配置 Sentinel 列

在 2.0.10 版本加入.

函数 sqlalchemy.orm 中。reconstructor（fn）¶

将方法装饰为 'reconstructor' 钩子。

将单个方法指定为“reconstructor”，这是一种类似 __init__ 的方法，在实例从数据库加载或以其他方式重组后，ORM 将调用该方法。

提示

reconstructor（） 装饰器使用 InstanceEvents.load（） 事件钩子，可以直接使用。

调用重构器时将不带任何参数。实例的标量（非集合）数据库映射属性将可用于函数。预先加载的集合通常尚不可用，通常只包含第一个元素。在此阶段对对象所做的 ORM 状态更改不会记录用于下一个 flush（）作，因此 reconstructor 中的 activity 应该是保守的。

另请参阅

InstanceEvents.load（）

类 sqlalchemy.orm 中。映射器¶

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

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

成员

__init__（）， add_properties（）， add_property（）， all_orm_descriptors， attrs， base_mapper， c， cascade_iterator（）， class_， class_manager， column_attrs，柱， common_parent（），复合材料，具体，已配置，实体， get_property（）， get_property_by_column（）， identity_key_from_instance（）， identity_key_from_primary_key（）， identity_key_from_row（），继承， is_mapper， is_sibling（）， isa（）、iterate_properties、local_table、mapped_table、映射器、non_primary、persist_selectable、polymorphic_identity、polymorphic_iterator（）、polymorphic_map、polymorphic_on、primary_key 、primary_key_from_instance（）、primary_mapper（）、relationships、可选、self_and_descendants、single、同义词、tables、validators with_polymorphic_mappers

类签名

类 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.通用）

方法 sqlalchemy.orm.Mapper 中。__init__（class_： Type[_O]， local_table：FromClauseNone=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]strMapperProperty[Any]None=None， _polymorphic_map：Dict[Any，Mapper[Any]]None=None， polymorphic_identity：AnyNone=None， 具体来说： bool = False， with_polymorphic：_WithPolymorphicArgNone=无， polymorphic_abstract： bool = False， polymorphic_load：Literal['selectin'，'inline']None=无， allow_partial_pks： bool = True， batch： bool = True， column_prefix：strNone=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 构造函数不是直接调用的，通常是通过使用注册表对象通过 Declarative 或命令式映射样式。

在 2.0 版更改：面向公众的 mapper（） 函数是删除;对于经典映射配置，请使用 registry.map_imperatively（） 方法。

下面记录的参数可以传递给 registry.map_imperatively（） 方法，或者可以在 __mapper_args__声明性类属性，如具有声明式的映射器配置选项。

参数

class_¶– 要映射的类。当使用 Declare 时，这个参数会自动作为声明的类本身传递。
local_table¶ – 表格或其他 FromClause（即 selectable）来映射该类。如果此映射器使用单表继承从另一个映射器继承，则可能是 None。使用 Declare 时，此参数由扩展根据通过 DeclarativeBase.__table__ 属性或通过 Table 的配置自动传递 DeclarativeBase.__tablename__ 属性。
polymorphic_abstract¶ –

指示此类将映射到多态层次结构，但不直接实例化。类为映射正常，只是它不需要 Mapper.polymorphic_identity 在继承中等级制度。但是，该类必须是多态继承方案，它使用 Mapper.polymorphic_on在底部。

2.0 版的新Function。

另请参阅

使用 polymorphic_abstract 构建更深的层次结构
always_refresh¶ – 如果为 True，则此类将覆盖已存在于会话中，使用从数据库加载的任何信息。此用途旗帜是非常不鼓励的;作为替代方法，请参阅方法 Query.populate_existing（） 中。
allow_partial_pks¶ –

默认为 True。指示应将具有一些 NULL 值的复合主键视为可能存在于数据库中。这会影响映射器是否将传入的行分配给现有身份，以及 Session.merge（） 是否会首先检查数据库的特定主键值。例如，如果已映射到 OUTER JOIN，则可能会出现“partial primary key”。

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

2.0.36 版本中的新功能：Mapper.allow_partial_pks 由关系 Lazy Loader 策略查询，使得当设置为 False 时，复合主键的 SELECT 命令具有部分 NULL 值。
batch¶ – 默认为 True，表示 save作可以一起批处理以提高效率。设置为 False 表示实例将在保存下一个实例。这在极其罕见的情况下使用，即 MapperEvents 侦听器需要在各个行持久性作之间调用。
column_prefix¶ –

一个字符串，当 Column 对象会自动作为属性分配给 mapped 类。不影响在 Mapper.properties 中显式映射的 Column 对象字典。

此参数通常适用于保持 Table 对象分离的命令式映射。下面，假设 user_tableTable 对象具有名为 user_id、user_name 和 password：
```
class User(Base):
    __table__ = user_table
    __mapper_args__ = {"column_prefix": "_"}
```
上面的映射将分配 user_id、 user_name 和 password 列添加到名为 _user_id 的属性， _user_name，并在映射的 User 类上_password。

Mapper.column_prefix 参数在现代使用。对于处理反射表，更灵活的自动化命名方案的方法是拦截反射时的柱对象;请参阅该部分 Automating Column Naming Scheme from Reflected Tables （从反射表中自动化列命名方案）有关此使用模式的说明。
具体¶ –

如果为 True，则表示此映射器应使用其父映射器的具体表继承。

有关示例，请参阅 Concrete Table Inheritance 部分。
confirm_deleted_rows¶ – 默认为 True;当基于特定主键的多一行发生 DELETE 时，当匹配的行数不等于预期的行数时，将发出警告。此参数可以设置为 False，以处理数据库 ON DELETE CASCADE 规则可能会自动删除其中一些行的情况。在将来的发行版中，该警告可能会更改为异常。
eager_defaults¶ –

如果为 True，则 ORM 将在 INSERT 或 UPDATE 后立即获取服务器生成的默认值的值，而不是将它们保留为过期以便在下次访问时获取。这可用于在 flush 完成之前需要服务器生成的值的事件方案。

通过在 INSERT 或 UPDATE 语句中使用 RETURNING 内联，或者在 INSERT 或 UPDATE，如果后端不支持 RETURNING。

RETURNING 的使用性能非常高，特别是对于 SQLAlchemy 可以利用的 INSERT 语句 insertmany值，而使用额外的 SELECT 性能相对较差，如果在任何情况下都无法访问这些新属性，则添加额外的 SQL 往返是不必要的。

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

在 2.0.0rc1 版本发生变更：添加了 “auto” 选项 Mapper.eager_defaults

另请参阅

获取 Server 生成的默认值

在 2.0.0 版本发生变更： RETURNING 现在可以处理多行 INSERTed 使用 insertmanyValues 功能，该功能允许 Mapper.eager_defaults 功能在支持后端上非常高性能。
exclude_properties¶ –

要从映射中排除的字符串列名列表或字符串列名集。

另请参阅

映射表列的子集
include_properties¶ –

要映射的包含列表或字符串列名称集。

另请参阅

映射表列的子集
继承¶ –

映射类或相应的 映射 of 1 表示此 Mapper 指向的超类应该继承自。此处的 mapped 类必须是其他映射器的类的子类。使用 Declare 时，此参数将作为已声明类的自然类层次结构的结果自动传递。

另请参阅

映射类继承层次结构
inherit_condition¶– 对于联接表继承，一个 SQL 表达式，它将定义两个表如何联接;默认为两个表之间的自然联接。
inherit_foreign_keys¶– 当使用 inherit_condition 并且存在的列缺少 ForeignKey 时 configuration，此参数可用于指定哪些列是 “foreign” 的。在大多数情况下，可以保留为 None。
legacy_is_orphan¶ –

Boolean 的 Normal，默认为 False。如果为 True，则指定将“遗留”孤立考虑应用于此映射器映射的对象，这意味着仅当挂起（即非持久）对象与指定指向此映射器的删除孤立级联的所有父对象取消关联时，才会从拥有 Session 中自动清除该对象。新的默认行为是，当对象与指定 delete-orphan 级联的任何父级取消关联时，该对象将被自动清除。此行为与持久对象的行为更一致，并且允许行为在更多情况下保持一致，而与孤立对象是否已刷新无关。

请参阅将 “pending” 对象视为 “orphan” 中的更改说明和示例已变得更加激进了解有关此更改的更多详细信息。
non_primary¶ –

指定此 Mapper 是到“主要”映射器，即用于持久性的映射器。此处创建的 Mapper 可用于将类临时映射到备用可选项，仅用于加载。

1.3 版后已移除： mapper.non_primary 参数已弃用，并将在未来发行版中删除。非主映射器的功能现在更适合使用 AliasedClass 结构，该结构也可以在 1.3 中用作 relationship（） 的目标。

另请参阅

Relationship to Aliased Class - 无需 Mapper.non_primary 标志的新模式。
passive_deletes¶ –

指示在删除联接表继承实体时外键列的 DELETE 行为。对于基本映射器，默认为 False;对于继承映射器，默认为 False，除非该值设置为 True 在 Superclass Mapper 上。

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

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

请注意，值 True 始终强制到子类映射器上;也就是说，如果 superclass 对所有 subclass Mapper 无效，则 superclass 无法指定 passive_deletes。

另请参阅

对 ORM 关系使用外键 ON DELETE 级联 - 描述与 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 将 Map 类保存到 discriminator 属性，从而将该值持久化到数据库中的 discriminator 列。

警告

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

另请参阅

映射类继承层次结构

polymorphic_identity¶ –

指定该值，该值将此特定类标识为 Mapper.polymorphic_on 设置引用的列表达式返回。如 rows 的 Mapper.polymorphic_on列表达式与此值进行比较，指示应该将哪个子类用于新重建的对象。

另请参阅

映射类继承层次结构
属性¶ –

一个字典，用于将对象属性的字符串名称映射到 MapperProperty 实例，这些实例定义了 persistence 行为。请注意， 列 存在于映射的 Table 会自动放入 ColumnProperty 实例，除非被覆盖。当使用 Declare 时，这个参数会根据在声明的类体中声明的所有 MapperProperty 实例自动传递。

另请参阅

properties 字典 - 在 ORM 映射类概述
primary_key¶ –

列的列表对象，或者是属性名称的字符串名称，其中请参阅 Column，它定义要用于此映射器的可选单元的主键。这通常只是 local_table 的主键，但可以在此处覆盖。

在 2.0.2 版本发生变更： Mapper.primary_key 参数也可以表示为 String 属性名称。

另请参阅

映射到一组显式主键列 - 背景和示例使用
version_id_col¶ –

A 列 这将用于保持 rows 的运行版本 ID 在表中。这用于检测并发更新或 flush 中存在过时的数据。方法是检测 UPDATE 语句是否与最后一个已知语句不匹配版本 ID，则 StaleDataError 异常。默认情况下，该列必须是 Integer 类型，除非 version_id_generator 指定了替代版本生成器。

另请参阅

配置版本计数器 - 讨论版本计数和基本原理。
version_id_generator¶ –

定义应如何生成新版本 ID。默认为 None，这表示采用简单的整数计数方案。要提供自定义版本控制方案，请提供以下形式的可调用函数：
```
def generate_version(version):
    return next_version
```
或者，通过指定值 False，可以使用服务器端版本控制函数（如触发器）或版本 ID 生成器之外的编程版本控制方案。请参阅服务器端版本计数器，了解使用此选项时的重要要点的讨论。

另请参阅

自定义版本计数器/类型

服务器端版本计数器
with_polymorphic¶ –

形式为 （<classes>， <可选>）指示 “polymorphic” 的默认样式 loading，即一次查询哪些表。是任何单个或列表的映射器和/或类，指示继承的类，这些类应该立即加载。特殊值 '*' 可用于表示应立即加载所有降序类。第二个 tuple 参数表示将用于查询多个类的 selectable。

Mapper.polymorphic_load 参数可能比使用 Mapper.with_polymorphic 更可取在现代映射中，以指示指示多态加载样式。

另请参阅

在映射器上配置 with_polymorphic（）

方法 sqlalchemy.orm.Mapper 中。add_properties（dict_of_properties）¶: 使用 add_property 将给定的属性字典添加到此映射器中。

方法 sqlalchemy.orm.Mapper 中。add_property（key： str， prop：Column[Any]MapperProperty[Any]）→ 无¶

将单个 MapperProperty 添加到此映射器中。

如果尚未配置 mapper，则只需将 property 添加到发送到构造函数的初始 properties 字典中。如果已配置此 Mapper，则立即配置给定的 MapperProperty。

属性 sqlalchemy.orm.Mapper 的all_orm_descriptors¶

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

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

此命名空间包括映射到类的属性以及扩展模块声明的属性。它包括继承自 InspectionAttr 的这包括 QueryableAttribute 以及扩展类型（如 hybrid_property、hybrid_method 和 AssociationProxy 的

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

属性的排序基于以下规则：

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

上述过程会生成一个排序，该排序在将属性分配给类的顺序方面是确定性的。

在 1.3.19 版本发生变更：确保的确定性排序 Mapper.all_orm_descriptors（） 中。

在处理 QueryableAttribute 时， QueryableAttribute.property 属性引用 MapperProperty 属性，这是您在通过 Mapper.attrs 的

警告

Mapper.all_orm_descriptors accessor 命名空间是一个 instance.这是一个类似字典的对象，其中包含少量命名方法，例如 OrderedProperties.items（） 和 OrderedProperties.values（） 的当动态访问属性时，优先使用 dict-access 方案，例如 mapper.all_orm_descriptors[somename] over getattr(mapper.all_orm_descriptors, somename) 以避免名称冲突。

另请参阅

Mapper.attrs

属性 sqlalchemy.orm.Mapper 的属性¶

与此映射器关联的所有 MapperProperty 对象的命名空间。

这是一个对象，它根据它的密钥名称。例如，一个 具有 User.name 属性的 User 类将提供 mapper.attrs.name，即表示名称的 ColumnProperty 列。 namespace 对象也可以迭代，这将产生每个 MapperProperty。

Mapper 具有此属性的多个预过滤视图，这些视图限制了返回的属性类型，包括同义词、column_attrs、 关系和复合。

警告

Mapper.attrs 访问器命名空间是 OrderedProperties 的一个实例。这是一个类似字典的对象，其中包含少量命名方法，例如 OrderedProperties.items（） 和 OrderedProperties.values（） 的当动态访问 attribute 时，首选使用 dict 访问方案，例如 mapper.attrs[somename] over getattr(mapper.attrs, somename) 以避免名称冲突。

另请参阅

Mapper.all_orm_descriptors

属性 sqlalchemy.orm.Mapper 的base_mapper： Mapper[Any]¶

继承链中最基本的 Mapper。

在非继承场景中，此属性将始终为 this 映射器。在继承场景中，它引用 Mapper，该 Mapper 是所有其他 Mapper 的父级对象。

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

属性 sqlalchemy.orm.Mapper 的c： ReadOnlyColumnCollection[str， Column[Any]]¶: Mapper.columns 的同义词。

方法 sqlalchemy.orm.Mapper 中。cascade_iterator（type_： str， state： InstanceState[_O]， halt_on：Callable[[InstanceState[Any]]，bool]None=None）→ 迭代器[元[object， Mapper[Any]， InstanceState[Any]， _InstanceDict]]¶

对于满足给定级联规则的所有关系，迭代对象图中的每个元素及其映射器。

参数

type_¶ –

级联规则的名称（即 “save-update”、“delete” 等）。

注意

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

结果

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

另请参阅

叶栅

如何遍历与给定对象相关的所有对象？- 说明了一个通用函数，用于在不依赖 Cascade 的情况下遍历所有对象。

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

属性 sqlalchemy.orm.Mapper 的class_manager： ClassManager[_O]¶

ClassManager，它维护此 Mapper 的事件侦听器和类绑定描述符。

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

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

另请参阅

Mapper.attrs - 所有 Mapper属性 对象。

属性 sqlalchemy.orm.Mapper 的columns： ReadOnlyColumnCollection[str， Column[Any]]¶

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

该集合的行为与任何 Table 对象上的 c 属性的行为相同，不同之处在于仅存在此映射中包含的列，并且根据映射中定义的属性名称进行键控，而不一定是 列本身。此外，此处还存在由 column_property（） 映射的标量表达式。

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

方法 sqlalchemy.orm.Mapper 中。common_parent（其他： Mapper[Any]）→ bool¶: 如果给定的映射器与此映射器共享一个共同的继承父级，则返回 true。

属性 sqlalchemy.orm.Mapper 的复合材料¶: 返回所有 Composite 的命名空间属性。

另请参阅

Mapper.attrs - 所有 Mapper属性 对象。

属性 sqlalchemy.orm.Mapper 的具体： bool¶

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

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

属性 sqlalchemy.orm.Mapper 的配置： bool = False¶

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

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

另请参阅

configure_mappers（） 中。

属性 sqlalchemy.orm.Mapper 的实体¶

检查 API 的一部分。

返回 self.class_。

方法 sqlalchemy.orm.Mapper 中。get_property（键：str，_configure_mappers：bool = False）→ MapperProperty[Any]¶: 返回与给定键关联的 MapperProperty。

方法 sqlalchemy.orm.Mapper 中。get_property_by_column（column： ColumnElement[_T]）→ MapperProperty[_T]¶: 给定一个 Column 对象，返回 MapperProperty 映射此列。

方法 sqlalchemy.orm.Mapper 中。identity_key_from_instance（实例： _O）→ _IdentityKeyType[_O]¶

根据给定实例的主键属性返回给定实例的身份键。

如果实例的状态为 expired，则调用该方法将导致数据库检查以查看对象是否已被删除。如果该行不再存在，则 ObjectDeletedError 的 Bug 请求。

此值通常也可以在实例状态的 attribute name 键下找到。

方法 sqlalchemy.orm.Mapper 中。identity_key_from_primary_key（primary_key：元组[Any， ...]， identity_token：AnyNone=None）→ _IdentityKeyType[_O]¶

返回一个身份映射键，用于存储/检索身份映射中的项目。

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

方法 sqlalchemy.orm.Mapper 中。identity_key_from_row（row：Row[Any]RowMappingNone， identity_token：AnyNone=None， adapter：ORMAdapterNone=None）→ _IdentityKeyType[_O]¶

返回一个身份映射键，用于存储/检索身份映射中的项目。

参数

行¶ –

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

在 2.0 版更改： “row” 参数接受 Row 或 RowMapping

属性 sqlalchemy.orm.Mapper 的inherits：Mapper[Any]无¶: 引用此 Mapper inherit from （如果有）。

属性 sqlalchemy.orm.Mapper 的 is_mapper = 真¶: 检查 API 的一部分。

方法 sqlalchemy.orm.Mapper 中。is_sibling（其他： Mapper[Any]）→ bool¶: 如果另一个 Mapper 是此 Mapper 的继承同级，则返回 true。父级相同，但分支不同

方法 sqlalchemy.orm.Mapper 中。isa（other： Mapper[Any]）→ bool¶: 如果 this 映射器继承自给定的映射器，则返回 True。

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

属性 sqlalchemy.orm.Mapper 的local_table： FromClause¶

此 Mapper 引用。

通常是 Table 的实例，可以是任何 From子句。

“local” 表是 Mapper 从属性访问和刷新角度直接负责管理的可选表。对于非继承映射器，Mapper.local_table 将与 Mapper.persist_selectable 相同。对于继承映射器， Mapper.local_table 是指 Mapper.persist_selectable，其中包括此 Mapper 正在加载/保存到的列，例如特定的 联接中的 Table。

另请参阅

Mapper.persist_selectable。

Mapper.selectable 的

属性 sqlalchemy.orm.Mapper 的mapped_table¶: 1.3 版后已移除：使用 .persist_selectable

属性 sqlalchemy.orm.Mapper 的映射器¶

检查 API 的一部分。

返回 self。

属性 sqlalchemy.orm.Mapper 的non_primary： bool （布尔值） ¶

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

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

属性 sqlalchemy.orm.Mapper 的persist_selectable： FromClause¶

此 Mapper 的 FromClause 已映射。

通常是 Table 的实例，可以是任何 From子句。

Mapper.persist_selectable类似于 Mapper.local_table，但表示 FromClause，该 FromClause 表示继承方案中总体上的继承类层次结构。

：attr.' 的Mapper.persist_selectable' 也与 Mapper.selectable 属性，后者可能是用于选择列的替代子查询。：attr.' 的Mapper.persist_selectable' 面向将在 persist作中写入的列。

另请参阅

Mapper.selectable 的

Mapper.local_table。

属性 sqlalchemy.orm.Mapper 的polymorphic_identity：AnyNone¶

表示与 Mapper.polymorphic_on 结果行加载期间的列。

仅用于继承，此对象可以是任何类型的与表示的列类型相当 Mapper.polymorphic_on。

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

方法 sqlalchemy.orm.Mapper 中。polymorphic_iterator（）→ Iterator[Mapper[Any]]¶

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

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

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

属性 sqlalchemy.orm.Mapper 的polymorphic_map： Dict[Any， Mapper[Any]]¶

映射到 Mapper 实例。

标识符可以是任何类型，这与 Mapper.polymorphic_on 表示的列类型相当。

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

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

属性 sqlalchemy.orm.Mapper 的polymorphic_on：KeyedColumnElement[Any]无¶

指定为 polymorphic_on继承方案中此 Mapper 的参数。

此属性通常是 Column 实例，但也可以是表达式，例如派生自 cast（）的

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

属性 sqlalchemy.orm.Mapper 的primary_key： Tuple[Column[Any]， ...]¶

包含 Column 集合的可迭代对象对象，它包含映射表的 'primary key'，来自此 Mapper 的视角。

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

该列表也不一定与与基础表关联的主键列集合相同;映射器 具有 primary_key 参数，该参数可以覆盖 Mapper 将 Tarper 视为主键列。

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

方法 sqlalchemy.orm.Mapper 中。primary_key_from_instance（instance： _O）→ Tuple[Any， ...]¶

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

如果实例的状态为 expired，则调用该方法将导致数据库检查以查看对象是否已被删除。如果该行不再存在，则 ObjectDeletedError 的 Bug 请求。

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

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

警告

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

另请参阅

Mapper.attrs - 所有 Mapper属性 对象。

属性 sqlalchemy.orm.Mapper 的可选¶

FromClause 构造此 默认情况下，Mapper 会选择 from。

通常，这相当于 persist_selectable，除非正在使用 with_polymorphic 功能，在这种情况下，将返回完整的 “polymorphic” selectable。

属性 sqlalchemy.orm.Mapper 的self_and_descendants¶

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

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

属性 sqlalchemy.orm.Mapper 的single： bool¶

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

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

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

属性 sqlalchemy.orm.Mapper 的同义词¶: 返回所有 Synonym 的命名空间属性。

另请参阅

Mapper.attrs - 所有 Mapper属性 对象。

属性 sqlalchemy.orm.Mapper 的表： Sequence[TableClause]¶

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

如果映射器映射到 Join，或者 别名 表示 Select，则表示个人 桌子 构成完整构造的对象将在此处表示。

这是在映射器构造期间确定的只读属性。如果直接修改，则行为未定义。

属性 sqlalchemy.orm.Mapper 的验证者： util.immutabledict[str， Tuple[str， Dict[str， Any]]]¶

一个不可变的属性字典，已使用 validates（） 装饰器进行装饰。

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

属性 sqlalchemy.orm.Mapper 的with_polymorphic_mappers¶: 默认 “polymorphic” 查询中包含的 Mapper 对象列表。

类 sqlalchemy.orm 中。MappedAsData类¶: Mixin 类来指示在映射此类时，还要将其转换为数据类。

另请参阅

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

2.0 版的新Function。

类 sqlalchemy.orm 中。MappedClassProtocol¶

表示 SQLAlchemy 映射类的协议。

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

类签名

类 sqlalchemy.orm.MappedClassProtocol （typing_extensions.协议）

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

类映射 API¶