类映射 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)	将类标记为提供“声明式混合”功能。
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	混合类，指示映射此类时，还将其转换为 dataclass。
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 中的所有映射器。

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

如果此注册表包含依赖于其他注册表的映射器（通常通过 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

Changed in version 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 构造函数。

另请参阅

强制性映射

声明式映射

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

方法 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 版中的新功能。

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

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

函数 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() 并带 mapped_column.active_history。请参考该参数获取功能细节。
comparator_factory¶ – 扩展 Comparator 的类，该类为比较操作提供自定义 SQL 子句生成。
group¶ – 当标记为延迟加载时，此属性的组名。
deferred¶ – 当为 True 时，列属性为“延迟加载”，表示它不会立即加载，而是等到第一次访问实例上的属性时才会加载。另请参见 deferred().
doc¶ – 可选字符串，将被应用为类绑定描述符上的文档。
expire_on_flush=True¶ – 在刷新时禁用失效。引用 SQL 表达式（而不是单个绑定到表的列）的 column_property() 被认为是“只读”属性；填充它对数据状态没有影响，它只能返回数据库状态。因此，每当父对象参与刷新时，即在刷新中存在任何类型的“脏”状态时，column_property() 的值都会失效。将此参数设置为 False 将使刷新完成后任何现有值保持存在。请注意，具有默认失效设置的 Session 仍然会在 Session.commit() 调用后使所有属性失效，然而。
info¶ – 可选的数据字典，它将被填充到此对象的 MapperProperty.info 属性中。
raiseload¶ –
如果为 True，则表示当列未延迟加载时应该抛出错误，而不是加载值。这可以通过在查询时使用 deferred() 选项并将 raiseload 设置为 False 来更改。

版本 1.4 中新增。

另请参阅

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

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

已弃用，版本 1.4: 对于 column_property()，column_property.default_factory 参数已弃用。此参数仅适用于声明式数据类配置中的可写属性，并且 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()，column_property.kw_only 参数已弃用。此参数仅适用于声明式数据类配置中的可写属性，并且 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 实例将通过生成的声明式基类的 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]¶

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

例如：

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 中的新增功能。

另请参阅

使用 Mixins 组成映射层次结构

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

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

类装饰器，它将使给定类适应 declarative_base()。

此函数使用 registry.as_declarative_base() 方法，首先自动创建一个 registry，然后调用装饰器。

例如：

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 对象的属性。当使用 Declarative 时，它提供与将属性直接映射到 Column 对象等效的功能，特别是当使用 Declarative Table 配置时。

2.0 版中的新功能。

该 mapped_column() 通常与显式类型一起使用，以及 Mapped 注释类型，它可以根据 Mapped 注释中存在的内容来推导出 SQL 类型和列的可空性。它也可以在没有注释的情况下使用，作为在 SQLAlchemy 1.x 风格的 Declarative 映射中使用 Column 方式的替代品。

有关 mapped_column() 的使用示例，请参阅使用 mapped_column() 的 Declarative Table 中的文档。

另请参阅

使用 mapped_column() 的 Declarative Table - 完整文档

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

参数:

__name¶ – 要赋予 Column 的字符串名称。这是一个可选的、位置参数，如果存在，它必须是传递的第一个位置参数。如果省略，则将 mapped_column() 映射到的属性名称用作 SQL 列名称。
__type¶ – TypeEngine 类型或实例，它将指示与 Column 关联的数据类型。这是一个可选的、位置参数，如果存在，它必须紧随 __name 参数（如果也存在），否则必须是第一个位置参数。如果省略，列的最终类型可能从注释类型推导而来，或者如果存在 ForeignKey，则从引用列的数据类型推导而来。
*args¶ – 额外的位置参数包括 ForeignKey、CheckConstraint 和 Identity 等结构，这些结构将传递给构造的 Column。
nullable¶ – 可选的布尔值，表示列应该是“NULL”还是“NOT NULL”。如果省略，可空性将根据是否在类型注释中存在 typing.Optional 从类型注释推导而来。对于非主键列，nullable 默认值为 True，而对于主键列，nullable 默认值为 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 构造函数在任何情况下都会使用，从而导致相同的最终结果。

注意

当使用 Core 级别的列默认值时，这些默认值是可调用函数，由底层的 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 通常适用于 mixins，用于定义要应用于类的不同实现者的关系。它也可以用于定义动态生成的列表达式和其他声明式属性。

示例

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 列，以及在名为 some_id 的属性下 MyClass 的列。

另请参阅

声明式继承

使用 _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 版中的新功能。

另请参阅

使用 Mixins 组成映射层次结构

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 集合将优先于使用 registry.type_annotation_map 参数传递的现有 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() 调用**，因为映射类本身被直接赋予一个 __init__() 方法，该方法直接调用 registry.constructor，因此在默认情况下，它独立于最基础的 __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 构造函数的参数字典。

另请参阅

使用声明式配置映射器选项

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]¶: 引用将用于新 Table 对象的 MetaData 集合。

另请参阅

访问表格和元数据

attribute sqlalchemy.orm.DeclarativeBase.registry: ClassVar[registry]¶: 引用将用于新 Mapper 对象的 registry。

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 构造函数的参数字典。

另请参阅

使用声明式配置映射器选项

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]¶: 引用将用于新 Table 对象的 MetaData 集合。

另请参阅

访问表格和元数据

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.registry: ClassVar[registry]¶: 引用将用于新 Mapper 对象的 registry。

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和/或声明性基类，可能更喜欢registry.configure()方法。

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

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

MapperEvents.before_configured() - 在configure_mappers()或registry.configure()执行任何操作之前调用一次；这可用于在操作继续之前建立其他选项、属性或相关映射。
MapperEvents.mapper_configured() - 每个单独的Mapper在过程中被配置时调用；将包括所有映射器状态，除了由其他映射器设置的尚未配置的 backrefs 之外。
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)
```
参数 class:

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

参数 ident:

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

参数 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() 运行，这将导致在对象过期时对相应行执行数据库检查。

参数 instance:

对象实例（必须作为关键字参数提供）
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)
```
参数 class:

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

参数 row:

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

参数 identity_token:

可选的身份令牌

版本 1.2 中的新增功能: 添加了 identity_token

函数 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。

函数 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() 类似于在核心 Table 结构中使用 insert_sentinel() 结构。

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

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

另请参阅

insert_sentinel()

“插入多值”行为用于 INSERT 语句

配置哨兵列

版本 2.0.10 中的新功能。

函数 sqlalchemy.orm.reconstructor(fn)¶

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

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

提示

The 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（即可选择）。如果此映射器从使用单表继承的另一个映射器继承，则可以为 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，则可能会出现“部分主键”。

The Mapper.allow_partial_pks 参数还指示 ORM 关系延迟加载器，在加载一对多关联对象时，如果包含部分 NULL 值的复合主键应该导致尝试从数据库加载，或者尝试加载不是必需的。

版本 2.0.36 中的新增功能： Mapper.allow_partial_pks 会被关系延迟加载器策略咨询，这样当设置为 False 时，不会为包含部分 NULL 值的复合主键发出 SELECT。
batch¶ – 默认值为 True，指示多个实体的保存操作可以为了效率而批处理在一起。设置为 False 表示在保存下一个实例之前，实例将被完全保存。这用于极少数情况下 MapperEvents 监听器需要在单个行持久化操作之间被调用。
column_prefix¶ –
一个字符串，当 Column 对象被自动分配为映射类的属性时，该字符串将被附加到映射的属性名称之前。不会影响在 Column 对象中显式映射的 Mapper.properties 字典。

此参数通常与将 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 的属性。

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

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

值的获取通过使用 RETURNING 与 INSERT 或 UPDATE 语句内联进行，或者通过在 INSERT 或 UPDATE 之后添加额外的 SELECT 语句进行，如果后端不支持 RETURNING。

使用 RETURNING 对于 INSERT 语句的性能非常高，在这些语句中，SQLAlchemy 可以利用 insertmanyvalues，而使用额外的 SELECT 的性能相对较差，会添加额外的 SQL 往返，如果没有要访问这些新属性，这些往返将是不必要的。

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

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

另请参阅

获取服务器生成的默认值

版本 2.0.0 中的变更： RETURNING 现在可以使用 insertmanyvalues 功能一次插入多行，该功能允许 Mapper.eager_defaults 功能在支持的后端上具有很高的性能。
exclude_properties¶ –
要从映射中排除的字符串列名称列表或集合。

另请参阅

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

另请参阅

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

另请参阅

映射类继承层次结构
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。

另请参阅

在 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 值分配给 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
```
或者，可以通过指定值 False 来使用服务器端版本控制函数（如触发器）或版本生成器之外的程序化版本控制方案。请参见服务器端版本计数器以讨论使用此选项时的重要事项。

另请参阅

自定义版本计数器/类型

服务器端版本计数器
with_polymorphic¶ –
一个形如 (<classes>, <selectable>) 的元组，表示默认的“多态”加载方式，即一次查询哪些表。 <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。

如果映射器尚未配置，则只需将属性添加到发送到构造函数的初始属性字典中。如果此映射器已经配置，则立即配置给定的 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 引用映射属性集合时获得的。

警告

访问器命名空间 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¶

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

这是一个根据键名提供每个属性的对象。例如，对于具有 User.name 属性的 User 类，映射器将提供 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 对象的父级。

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

attribute sqlalchemy.orm.Mapper.c: ReadOnlyColumnCollection[str, Column[Any]]¶: The 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]]¶

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

参数:

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

注意

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

返回值：:

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

另请参阅

级联

如何遍历与给定对象相关的全部对象？ - 说明了在不依赖级联的情况下遍历全部对象的通用函数。

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

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

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

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

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() 映射的标量表达式也存在于此。

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

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

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

另请参阅

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

attribute sqlalchemy.orm.Mapper.concrete: bool¶

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

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

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

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

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

另请参阅

configure_mappers().

attribute sqlalchemy.orm.Mapper.entity¶

检查 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 | None, identity_token: Any | None = None, adapter: ORMAdapter | None = None) → _IdentityKeyType[_O]¶

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

参数:

row¶ –

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

Changed in version 2.0: 对于“row”参数，接受 Row 或 RowMapping

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

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

method sqlalchemy.orm.Mapper.is_sibling(other: Mapper[Any]) → bool¶: 如果另一个映射器是此映射器的继承兄弟节点，则返回 True。共同的父节点，但不同的分支

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

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

attribute sqlalchemy.orm.Mapper.local_table: FromClause¶

此 Mapper 直接引用的立即 FromClause。

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

“本地”表是 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¶: 从版本 1.3 开始弃用: 使用 .persist_selectable

attribute sqlalchemy.orm.Mapper.mapper¶

检查 API 的一部分。

返回 self。

attribute sqlalchemy.orm.Mapper.non_primary: bool¶

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

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

attribute sqlalchemy.orm.Mapper.persist_selectable: FromClause¶

此 Mapper 映射到的 FromClause。

通常是 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 所表示的列类型相比较。

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

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表示的列类型进行比较。

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

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

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

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

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

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

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

包含组成映射表的“主键”的Column对象集合的可迭代对象，从这个Mapper的角度来看。

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

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

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

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

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

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

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

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。

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

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

另请参阅

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

属性 sqlalchemy.orm.Mapper.tables: Sequence[TableClause]¶

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

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

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

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

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

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

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

类 sqlalchemy.orm.MappedAsDataclass¶: 混合类，指示映射此类时，还将其转换为 dataclass。

另请参阅

声明式数据类映射 - SQLAlchemy 本地数据类映射的完整背景

2.0 版中的新功能。

类 sqlalchemy.orm.MappedClassProtocol¶

表示 SQLAlchemy 映射类的协议。

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

类签名

class sqlalchemy.orm.MappedClassProtocol (typing_extensions.Protocol)

SQLAlchemy 2.0 文档

SQLAlchemy 2.0 文档

SQLAlchemy ORM

项目版本

类映射 API¶