类映射 API

映射类的通用注册表。

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

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

• registry.generate_base() 返回一个新的声明性基类，并且是 declarative_base() 功能。

• registry.mapped() 提供一个类修饰符，它将在不使用声明性基类的情况下对类应用声明性映射。

• registry.map_imperatively() 会产生 Mapper 对于没有扫描类的声明性类属性的类。此方法适用于由 mapper() 经典映射函数。

1.4 新版功能.

参见

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

method sqlalchemy.orm.registry.__init__(metadata=None, class_registry=None, constructor=<function _declarative_constructor>, _bind=None)¶

构建新的 registry

参数

• metadata¶ -- 可选的 MetaData 实例。所有 Table 使用声明性表映射生成的对象将使用 MetaData 收藏。如果此参数的默认值为 None 一片空白 MetaData 集合已创建。

• constructor¶ -- 指定 __init__ 函数在没有 __init__ 它自己的。默认为分配 * *声明字段和实例关系的Kwarg。如果 None 供应，没有 __init__ 将提供和施工将回落到 cls.__init__ 通过普通的Python语义。

• class_registry¶ -- 可选字典，当字符串名称用于标识 relationship() 以及其他。允许两个或多个声明性基类共享相同的类名注册表，以简化基间关系。

method sqlalchemy.orm.registry.as_declarative_base(**kw)¶

将调用 registry.generate_base() 对于给定的基类。

例如。：：

from sqlalchemy.orm import registry

mapper_registry = registry()

@mapper_registry.as_declarative_base()
class Base(object):
    @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=False)¶

在此配置所有尚未配置的映射器 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=False)¶

释放此中的所有映射器 registry 。

调用之后，此注册表中映射的所有类将不再具有与其相关联的类检测。此方法是PER -registry 与整个应用程序类似 clear_mappers() 功能。

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

1.4.0b2 新版功能.

参见

clear_mappers()

method sqlalchemy.orm.registry.generate_base(mapper=None, cls=<class 'object'>, name='Base', metaclass=<class 'sqlalchemy.orm.decl_api.DeclarativeMeta'>)¶

生成一个声明性基类。

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

例如。：：

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

这个 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)¶

以声明方式映射类。

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

返回 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() -此函数的更常见的decorator接口。

registry.map_imperatively()

method sqlalchemy.orm.registry.map_imperatively(class_, local_table=None, **kw)¶

强制映射一个类。

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

此方法旨在完全等效于经典的SQLAlchemy mapper() 函数，但它是根据特定的注册表。

例如。：：

from sqlalchemy.orm import registry

mapper_registry = registry()

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

class MyClass:
    pass

mapper_registry.map_imperatively(MyClass, my_table)

见剖面图 命令（又称经典）映射 完整的背景和用法示例。

参数

• class_¶ -- 要映射的类。对应于 mapper.class_ 参数。

• local_table¶ -- 这个 Table 或其他 FromClause 对象作为映射的主题。对应于 mapper.local_table 参数。

• **kw¶ -- 所有其他关键字参数都传递给 mapper() 直接作用。

参见

命令（又称经典）映射

声明性映射

method sqlalchemy.orm.registry.mapped(cls)¶

将声明性映射过程应用于给定类的类修饰符。

例如。：：

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元类自动将声明性映射应用于子类。

attribute sqlalchemy.orm.registry.mappers¶

全部的只读集合 Mapper 对象。

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

新的基类将被赋予一个产生适当 Table 对象并使 mapper() 基于类和类的任何子类中声明性提供的信息进行调用。

这个 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 班级。函数也会移动到 sqlalchemy.orm 来自 declarative.ext 包裹。

参数

• bind¶ -- 可选的 Connectable ，将被分配 bind 属性 MetaData 实例。。已弃用：：1.4声明性u base的“bind”参数已弃用，将在SQLAlchemy 2.0中删除。

• metadata¶ -- 可选的 MetaData 实例。所有 Table 由基的子类隐式声明的对象将共享此元数据。如果未提供元数据实例，则将创建元数据实例。这个 MetaData 实例将通过 metadata 生成的声明性基类的属性。

• mapper¶ -- 可选的可调用文件，默认为 mapper() . 将用于将子类映射到它们的表。

• cls¶ -- 默认为 object . 用作生成的声明性基类的基的类型。可以是类或类的元组。

• name¶ -- 默认为 Base . 生成的类的显示名称。定制这不是必需的，但可以提高回溯和调试的清晰度。

• constructor¶ -- 指定 __init__ 函数在没有 __init__ 它自己的。默认为分配 * *声明字段和实例关系的Kwarg。如果 None 供应，没有 __init__ 将提供和施工将回落到 cls.__init__ 通过普通的Python语义。

• class_registry¶ -- 可选字典，当字符串名称用于标识 relationship() 以及其他。允许两个或多个声明性基类共享相同的类名注册表，以简化基间关系。

• metaclass¶ -- 默认为 DeclarativeMeta . 元类或 __metaclass__ 可兼容的可调用项，用作生成的声明性基类的元类型。

参见

registry

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

例如。：：

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 plugin 能够在不存在其他上下文的情况下识别SQLAlChemy声明性混合类。

1.4.6 新版功能.

参见

使用mixin组合映射层次

使用@DECLARATED_ATTR和声明性混合 - in the Mypy plugin documentation

类修饰符，它将把给定的类调整为 declarative_base() .

此函数利用 registry.as_declarative_base() 方法，首先创建 registry 然后调用decorator。

例如。：：

from sqlalchemy.orm import as_declarative

@as_declarative()
class Base(object):
    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()
    id = Column(Integer, primary_key=True)

class MyMappedClass(Base):
    # ...

参见

registry.as_declarative_base()

将类级方法标记为表示映射属性或特殊声明性成员名称的定义。

declared_attr 通常作为类级别方法的修饰符应用，将属性转换为可从未实例化的类调用的标量类属性。声明性映射过程查找以下内容 declared_attr 在扫描类时可调用，并采用任何标记有 declared_attr 将是一个可调用对象，它将生成特定于声明性映射或表配置的对象。

declared_attr 通常适用于混合，以定义要应用于类的不同实现者的关系。它还用于定义 Column 对象，这些对象包括 ForeignKey 构造，因为这些不容易在不同的映射之间重用。下面的示例说明了这两种情况：

class ProvidesUser(object):
    "A mixin that adds a 'user' relationship to classes."

    @declared_attr
    def user_id(self):
        return Column(ForeignKey("user_account.id"))

    @declared_attr
    def user(self):
        return relationship("User")

declared_attr 还可以应用于映射的类，例如为继承提供“多态”方案：

class Employee(Base):
    id = Column(Integer, primary_key=True)
    type = Column(String(50), nullable=False)

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

    @declared_attr
    def __mapper_args__(cls):
        if cls.__name__ == 'Employee':
            return {
                    "polymorphic_on":cls.type,
                    "polymorphic_identity":"Employee"
            }
        else:
            return {"polymorphic_identity":cls.__name__}

要使用 declared_attr 中讨论的Python数据类内部 示例2-使用声明性表的数据类 ，则可以使用lambda：：将其直接放置在字段元数据中

@dataclass
class AddressMixin:
    __sa_dataclass_metadata_key__ = "sa"

    user_id: int = field(
        init=False, metadata={"sa": declared_attr(lambda: Column(ForeignKey("user.id")))}
    )
    user: User = field(
        init=False, metadata={"sa": declared_attr(lambda: relationship(User))}
    )

declared_attr 也可以直接使用lambda在此表单中省略，如：：

user: User = field(
    init=False, metadata={"sa": lambda: relationship(User)}
)

参见

使用mixin组合映射层次 - illustrates how to use Declarative Mixins which is the primary use case for declared_attr

在数据类中使用声明性混合 -说明用于Python数据类的特殊表单

类签名

class sqlalchemy.orm.declared_attr (sqlalchemy.orm.base._MappedAttribute, builtins.property)

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

这在声明性混合中用于构建属性，这些属性的行为与继承层次结构中的子类不同。

参见

用mixin控制表继承

产生一个 synonym() 属性与Python描述符结合使用。

正在修饰的函数传递给 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

这个 hybrid properties sqlacalchemy的特性通常是首选的，而不是同义词，这是一个更传统的特性。

参见

同义词 -同义词概述

synonym() -映射器级别函数

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

直接构造函数，以创建新的 Mapper 对象。

这个 mapper() 函数通常通过使用 registry 通过 Declarative 或 Imperative 映射样式。

在 1.4 版更改: 这个 mapper() 对于经典映射，不应直接调用函数；对于经典映射配置，请使用 registry.map_imperatively() 方法。这个 mapper() 函数可能在将来的版本中变为私有。

下面记录的参数可以传递给 registry.map_imperatively() 方法，或者可以在 __mapper_args__ 中描述的声明类属性 具有声明性的映射器配置选项 .

参数

• class_¶ -- 要映射的类。使用声明性时，此参数自动作为声明类本身传递。

• local_table¶ -- 这个 Table 或其他可选择的类。可能是 None 如果此映射器使用单表继承从另一个映射器继承。使用声明性时，根据通过 __table__ 争论或通过 Table 产生于 __tablename__ 和 Column 存在参数。

• always_refresh¶ -- 如果为true，则此映射类的所有查询操作都将覆盖会话中已存在的对象实例中的所有数据，用从数据库加载的任何信息擦除内存中的任何更改。不鼓励使用此标志；作为替代方法，请参阅方法 Query.populate_existing() .

• allow_partial_pks¶ -- 默认为true。指示应将具有一些空值的复合主键视为可能存在于数据库中。这会影响映射器是否将传入行分配给现有标识，以及 Session.merge() 将首先检查数据库中的特定主键值。例如，如果映射到外部联接，则可能发生“部分主键”。

• batch¶ -- 默认为 True 表示多个实体的保存操作可以一起批处理以提高效率。设置为false表示在保存下一个实例之前，将完全保存一个实例。这是在极为罕见的情况下使用的 MapperEvents 侦听器要求在单个行持久性操作之间调用。

• column_prefix¶ -- 一个字符串，当 Column 对象被自动指定为映射类的属性。不影响显式指定的基于列的属性。见剖面图 用前缀命名所有列 举个例子。

• concrete¶ -- 如果为true，则指示此映射器应将具体的表继承与其父映射器一起使用。见剖面图 具体的表继承 举个例子。

• confirm_deleted_rows¶ -- 默认值为true；当基于特定主键对多个行执行删除操作时，如果匹配的行数不等于预期的行数，则会发出警告。此参数可以设置为false，以处理数据库on delete级联规则可能会自动删除其中一些行的情况。警告可能在将来的版本中更改为异常。…版本已添加：：0.9.4-已添加 mapper.confirm_deleted_rows 以及删除时的条件匹配行检查。

• eager_defaults¶ -- 如果为true，则ORM将在插入或更新之后立即获取服务器生成的默认值的值，而不是将其保留为过期以便下次访问时提取。这可用于事件方案，其中在刷新完成前立即需要服务器生成的值。默认情况下，此方案将发出一个 SELECT 每行插入或更新一条语句，这会增加大量的性能开销。但是，如果目标数据库支持 RETURNING ，默认值将与insert或update语句内联返回，这可以大大提高需要频繁访问刚生成的服务器默认值的应用程序的性能。…参阅： 正在获取服务器生成的默认值 …版本已更改：：0.9.0 eager_defaults 选项现在可以利用 RETURNING 用于支撑它的后端。

• exclude_properties¶ -- 要从映射中排除的字符串列名的列表或集合。见 映射表列的子集 举个例子。

• include_properties¶ -- 要映射的包含列表或字符串列名集。见 映射表列的子集 举个例子。

• inherits¶ -- 映射类或相应的 Mapper 其中一个表示超类 Mapper 应该 继承 从…此处的映射类必须是其他映射器类的子类。使用声明性时，此参数将作为声明类的自然类层次结构的结果自动传递。…参阅： 映射类继承层次结构

• inherit_condition¶ -- 对于联接表继承，定义两个表联接方式的SQL表达式；默认为两个表之间的自然联接。

• inherit_foreign_keys¶ -- 什么时候？ inherit_condition 已使用，并且存在的列缺少 ForeignKey 配置，此参数可用于指定哪些列是“外部”列。在大多数情况下，可以保留为 None .

• legacy_is_orphan¶ -- 布尔值，默认为 False . 什么时候？ True ，指定将“旧”孤立考虑因素应用于此映射器映射的对象，这意味着挂起（即，非持久）对象将自动从所属对象中删除。 Session 仅当它与 all 指定的父级 delete-orphan 向这个映射器级联。新的默认行为是，当对象与 any 它的父级指定 delete-orphan 级联。这种行为与持久化对象的行为更为一致，并且允许行为在更多的场景中保持一致，而与孤立对象是否已刷新无关。请参阅中的更改说明和示例 把“悬而未决”的对象当作“孤儿”的考虑变得更具侵略性。 有关此更改的详细信息。

• non_primary¶ -- 指定此 Mapper 是“主”映射器（即用于持久性的映射器）之外的。这个 Mapper 在这里创建的可用于将类临时映射到另一个可选的，仅用于加载。。已弃用：：1.3 mapper.non_primary 参数已弃用，将在将来的版本中删除。非主映射器的功能现在更适合使用 AliasedClass 构造，也可以用作 relationship() 在1.3。。另请参见： 与别名类的关系 -新的模式消除了对 Mapper.non_primary 旗帜。

• passive_deletes¶ --

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

  什么时候？ True ，假定在删除时对将此映射器的表链接到其超类表的外键关系进行了配置，以便当工作单元尝试删除实体时，它只需要为超类表而不是此表发出一条删除语句。

  什么时候？ False ，将单独为此映射器的表发出一条DELETE语句。如果卸载了此表的本地主键属性，则必须发出一个选择以验证这些属性；请注意，联接表子类的主键列不是对象整体“主键”的一部分。

  请注意，值为 True 是 总是 强制到子类映射器上；也就是说，如果没有对所有子类映射器生效的话，超类就不可能指定被动删除。

  1.1 新版功能.

  参见

  在具有ORM关系的DELETE cascade中使用外键 - description of similar feature as used with relationship()

  mapper.passive_updates -支持联合表继承映射器的更新级联

• passive_updates¶ --

  指示在联接表继承映射上更改主键列时外键列的更新行为。默认为 True .

  如果为true，则假定在更新时对数据库中的外键配置级联，并且数据库将处理从源列到联接表行上的依赖列的更新传播。

  如果为false，则假定数据库不强制引用完整性，也不会为更新发出自己的级联操作。工作单元进程将在主键更改期间为依赖列发出更新语句。

  参见

  可变主键/更新级联 - description of a similar feature as used with relationship()

  mapper.passive_deletes -支持联合表继承映射器的删除级联

• polymorphic_load¶ --

  指定“多态加载”行为

  对于继承层次结构中的子类（仅限于联合表继承和单表继承）。有效值为：

  • “'inline'”-指定该类应是“with_polymorphic”映射器的一部分，例如，它的列将包含在对基的select查询中。

  • “'selectin'”—指定当加载此类的实例时，将发出一个附加的select来检索此子类的特定列。select使用in一次获取多个子类。

  1.2 新版功能.

  参见

  在映射器配置时使用多态性设置

  多态性选择素加载

• polymorphic_on¶ -- 指定当存在继承类时，用于确定传入行的目标类的列、属性或SQL表达式。此值通常是 Column 映射中存在的对象 Table ：：班级员工（基础）： __tablename__ ='Employee'id=column（integer，primary_key=true）discriminator=column（string（50））。 __mapper_args__ =“polymorphic_on”：鉴别器，“polymorphic_identity”：“employee”也可以指定为SQL表达式，在本例中，我们使用 case() 构造以提供条件方法：：类Employee（Base）： __tablename__ ='Employee'id=column（integer，primary_key=true）discriminator=column（string（50））。 __mapper_args__ =“多态性开启”：案例（ [ (discriminator == "EN", "engineer"), (discriminator == "MA", "manager"), ] ，else_uu=“employee”），“polymorphic_identity”：“employee”它还可以引用配置为 column_property() ，或指向one:：ClassEmployee（base）的字符串名称： __tablename__ ='Employee'id=column（integer，primary_key=true）discriminator=column（string（50））Employee_type=column_property（case（ [ (discriminator == "EN", "engineer"), (discriminator == "MA", "manager"), ] ，否则“员工”）） __mapper_args__ =“多态性开启”：员工类型，“多态性身份”：“员工”设置时 polymorphic_on 引用本地映射中不存在的属性或表达式 Table ，但鉴别器的值应保留到数据库中，鉴别器的值不会自动设置在新实例上；这必须由用户通过手动方式或通过事件侦听器进行处理。建立此类侦听器的典型方法类似于：：from sqlachemy import event from sqlachemy.orm import object_mapper@event.listens_for（employee，“init”，propagate=true）def set_identity（instance， 精氨酸 kw): mapper = object_mapper(instance) instance.discriminator = mapper.polymorphic_identity Where above, we assign the value of ``polymorphic_identity`` for the mapped class to the ``discriminator`` attribute, thus persisting the value to the ``discriminator`` column in the database. .. warning:: Currently, * *只能设置一个鉴别器列 *，通常位于层次结构中最基本的类上。“尚不支持层叠的“多态列”。…参阅： 映射类继承层次结构

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

• properties¶ -- 将对象属性的字符串名称映射到 MapperProperty 实例，定义该属性的持久性行为。注意 Column 映射中存在的对象 Table 自动放入 ColumnProperty 映射时的实例，除非重写。使用声明性时，将根据所有这些参数自动传递此参数 MapperProperty 在声明的类主体中声明的实例。

• primary_key¶ -- 列表 Column 对象，该对象定义要用于此映射器的可选单元的主键。这通常只是 local_table ，但可以在此处重写。

• version_id_col¶ -- A Column 它将用于在表中保留行的运行版本ID。这用于检测并发更新或刷新中存在过时数据。方法是检测更新语句是否与上一个已知版本ID，a不匹配。 StaleDataError 引发异常。默认情况下，列必须为 Integer 类型，除非 version_id_generator 指定替代版本生成器。…参阅： 配置版本计数器 -讨论版本计数和基本原理。

• version_id_generator¶ --

  定义应如何生成新版本ID。默认为 None 表示采用简单的整数计数方案。要提供自定义版本控制方案，请提供表单的可调用函数：

  def generate_version(version):
      return next_version

  或者，可以通过指定值来使用服务器端版本控制功能（如触发器）或版本ID生成器外部的编程版本控制方案。 False . 请看 服务器端版本计数器 讨论使用此选项时的要点。

  0.9.0 新版功能: version_id_generator 支持服务器端版本号生成。

  参见

  自定义版本计数器/类型

  服务器端版本计数器

• with_polymorphic¶ -- 形式中的元组 (<classes>, <selectable>) 指示“多态”加载的默认样式，即一次查询哪些表。<classes>是任何单个或列表的映射器和/或类，指示应立即加载的继承类。特殊价值 '*' 可用于指示应立即加载所有降序类。第二个tuple参数<selectable>表示将用于查询多个类的可选参数。…参阅： 与多态性一起使用 -多态查询技术的讨论。

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

加薪 sqlalchemy.orm.exc.UnmappedInstanceError 如果未配置映射。

此功能通过检查系统可用，如下所示：

inspect(instance).mapper

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

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

加薪 UnmappedClassError 如果在给定的类上没有配置映射，或者 ArgumentError 如果传递了非类对象。

等效功能可通过 inspect() 功能如下：

inspect(some_mapped_class)

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

初始化到目前为止已构建的所有映射器的映射器间关系 registry 收藏品。

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

映射器配置通常是自动调用的，第一次从特定的 registry 以及每当使用映射并且构造了其他尚未配置的映射器时都会使用。但是，自动配置过程仅限于 registry 涉及目标映射器和任何相关的 registry 对象，这等效于调用 registry.configure() 方法对特定的 registry 。

相比之下， configure_mappers() 函数将调用所有 registry 对象存在于内存中，并且可能对许多个体 registry 仍然相互关联的对象正在使用中。

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

调用自动配置的时间点包括映射类实例化到实例的时间，以及使用以下命令发出ORM查询的时间 Session.query() 或 Session.execute() 使用启用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 集合不属于当前配置范围。

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

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

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

clear_mappers() 是 not 对于正常使用，因为在非常具体的测试场景之外，实际上没有对它的有效使用。通常，映射器是用户定义类的永久性结构组件，永远不会独立于类被丢弃。如果映射类本身被垃圾收集，那么它的映射器也会被自动释放。像这样的， clear_mappers() 仅适用于在具有不同映射的相同类中重复使用的测试套件，这本身是一个极其罕见的用例-唯一这样的用例实际上是SQLAlchemy自己的测试套件，并且可能是其他ORM扩展库的测试套件，这些库打算在固定的类集上测试映射器构造的各种组合。

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

此函数有几种调用样式：

• identity_key(class, ident, identity_token=token)

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

  例如。：：

  >>> identity_key(MyClass, (1, 2))
  (<class '__main__.MyClass'>, (1, 2), None)

  PARAM类

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

  参数识别

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

  参数标识令牌

  可选标识令牌

  1.2 新版功能: 添加标识令牌

• 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实例

  对象实例（必须作为关键字arg提供）

• identity_key(class, row=row, identity_token=token)

  此窗体类似于类/元组窗体，但将数据库结果行作为 Row 对象。

  例如。：：

  >>> 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类

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

  参数行

  Row A返回的行 CursorResult （必须作为关键字arg提供）

  参数标识令牌

  可选标识令牌

  1.2 新版功能: 添加标识令牌

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

见 具体的表继承 例如如何使用它。

参数

• table_map¶ -- 多态性特征映射到 Table 物体。

• typecolname¶ -- “discriminator”列的字符串名称，该列将从查询中派生，为每一行生成多态标识。如果 None ，不生成多态鉴别器。

• aliasname¶ -- 名称 alias() 已生成构造。

• cast_nulls¶ -- 如果为true，则不存在的列（以标记为nulls的形式表示）将被传递到cast中。这是一种遗留行为，在某些后端（如Oracle）存在问题，在这种情况下，可以将其设置为false。

定义类属性与数据库表列的关联。

这个 Mapper 对象是使用 mapper() 功能。有关实例化新的信息 Mapper 对象，请参见该函数的文档。

什么时候？ mapper() 用于将用户定义的类与表元数据显式链接，这称为 经典映射 . 现代的SQLAlchemy用法倾向于 sqlalchemy.ext.declarative 类配置的扩展，它使用 mapper() 在幕后。

给定一个已知由ORM映射的特定类， Mapper 它可以通过 inspect() 功能：

from sqlalchemy import inspect

mapper = inspect(MyClass)

由映射的类 sqlalchemy.ext.declarative 扩展还将通过 __mapper__ 属性。

类签名

class sqlalchemy.orm.Mapper (sqlalchemy.orm.ORMFromClauseRole, sqlalchemy.orm.ORMEntityColumnsClauseRole, sqlalchemy.sql.traversals.MemoizedHasCacheKey, sqlalchemy.orm.base.InspectionAttr)

method sqlalchemy.orm.Mapper.__init__(class_, local_table=None, properties=None, primary_key=None, non_primary=False, inherits=None, inherit_condition=None, inherit_foreign_keys=None, always_refresh=False, version_id_col=None, version_id_generator=None, polymorphic_on=None, _polymorphic_map=None, polymorphic_identity=None, concrete=False, with_polymorphic=None, polymorphic_load=None, allow_partial_pks=True, batch=True, column_prefix=None, include_properties=None, exclude_properties=None, passive_updates=True, passive_deletes=False, confirm_deleted_rows=True, eager_defaults=False, legacy_is_orphan=False, _compiled_cache_size=100)¶

构建新的 Mapper 对象。

此构造函数被镜像为公共API函数；请参见 sqlalchemy.orm.mapper() 完整的用法和参数描述。

method sqlalchemy.orm.Mapper.add_properties(dict_of_properties)¶

将给定的属性字典添加到此映射器，使用 add_property .

method sqlalchemy.orm.Mapper.add_property(key, prop)¶

将单个映射器属性添加到此映射器。

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

attribute sqlalchemy.orm.Mapper.all_orm_descriptors¶

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

这些属性在所有情况下都是python descriptors 与映射类或其超类关联。

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

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

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

1. 按照从子类到超类的顺序遍历类及其超类（即遍历 cls.__mro__ ）

2. 对于每个类，按照属性出现的顺序生成属性 __dict__ ，但以下步骤3中的除外。在Python3.6及更高版本中，除了应用程序或映射器在事实之后添加的属性外，此顺序与类的构造顺序相同。

3. 如果某个属性键也在超类中 __dict__ ，则它将包含在该类的迭代中，而不是它第一次出现的类中。

上面的过程产生了一个确定的顺序，即属性分配给类的顺序。

在 1.3.19 版更改: 确保的确定性排序 Mapper.all_orm_descriptors() .

在处理 QueryableAttribute , the QueryableAttribute.property 属性引用 MapperProperty 属性，这是通过引用映射属性集合 Mapper.attrs .

警告

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

参见

Mapper.attrs

attribute sqlalchemy.orm.Mapper.attrs¶

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

这是一个对象，它基于每个属性的键名提供每个属性。例如，映射器 User 班级有 User.name 属性将提供 mapper.attrs.name ，这将是 ColumnProperty 代表 name 列。也可以迭代命名空间对象，这将生成 MapperProperty .

Mapper 具有此属性的几个预筛选视图，这些视图限制返回的属性类型，包括 synonyms ， column_attrs ， relationships 和 composites .

警告

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

参见

Mapper.all_orm_descriptors

attribute sqlalchemy.orm.Mapper.base_mapper = None¶

最底 Mapper 在继承链中。

在非继承方案中，此属性将始终是 Mapper . 在继承场景中，它引用 Mapper 哪个是所有其他人的父母 Mapper 继承链中的对象。

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

attribute sqlalchemy.orm.Mapper.c = None¶

同义词 Mapper.columns .

method sqlalchemy.orm.Mapper.cascade_iterator(type_, state, halt_on=None)¶

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

参数

• type_¶ -- 级联规则的名称（即 "save-update" ， "delete" 等）。…注：： "all" 此处不接受层叠。有关一般对象遍历函数，请参见 如何浏览与给定对象相关的所有对象？ .

• state¶ -- Lead InstanceState。将根据为此对象的映射器定义的关系处理子项。

返回

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

参见

级联

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

attribute sqlalchemy.orm.Mapper.class_ = None¶

python类 Mapper 地图。

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

attribute sqlalchemy.orm.Mapper.class_manager = None¶

这个 ClassManager 它维护事件侦听器和类绑定描述符 Mapper .

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

attribute sqlalchemy.orm.Mapper.column_attrs¶

返回所有 ColumnProperty 由此维护的属性 Mapper .

参见

Mapper.attrs -全部的命名空间 MapperProperty 物体。

attribute sqlalchemy.orm.Mapper.columns = None¶

收藏 Column 或由它维护的其他标量表达式对象 Mapper .

集合的行为与 c 任何属性 Table 对象，但只有包含在此映射中的列才存在，并且根据映射中定义的属性名设置了键，不一定是 key 的属性 Column 本身。此外，标量表达式由映射 column_property() 也在这里。

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

method sqlalchemy.orm.Mapper.common_parent(other)¶

如果给定的映射器与此映射器共享一个公共继承父级，则返回true。

attribute sqlalchemy.orm.Mapper.composites¶

返回所有 CompositeProperty 由此维护的属性 Mapper .

参见

Mapper.attrs -全部的命名空间 MapperProperty 物体。

attribute sqlalchemy.orm.Mapper.concrete = None¶

代表 True 如果这样 Mapper 是一个具体的继承映射器。

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

attribute sqlalchemy.orm.Mapper.configured = False¶

代表 True 如果这样 Mapper 已配置。

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

参见

configure_mappers() .

attribute sqlalchemy.orm.Mapper.entity¶

检查API的一部分。

返回 self.class_.

method sqlalchemy.orm.Mapper.get_property(key, _configure_mappers=True)¶

返回与给定键关联的MapperProperty。

method sqlalchemy.orm.Mapper.get_property_by_column(column)¶

给出了一个 Column 对象，返回 MapperProperty 它映射了这个列。

method sqlalchemy.orm.Mapper.identity_key_from_instance(instance)¶

根据给定实例的主键属性返回该实例的标识键。

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

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

method sqlalchemy.orm.Mapper.identity_key_from_primary_key(primary_key, identity_token=None)¶

返回用于存储/检索标识映射中的项的标识映射键。

参数

primary_key¶ -- 指示标识符的值列表。

method sqlalchemy.orm.Mapper.identity_key_from_row(row, identity_token=None, adapter=None)¶

返回用于存储/检索标识映射中的项的标识映射键。

参数

row¶ -- A Row 实例。由此映射的列 Mapper 应可在行中定位，最好通过 Column 直接对象（如 select() 构造被执行），或者通过表单的字符串名称 <tablename>_<colname> .

attribute sqlalchemy.orm.Mapper.inherits = None¶

参考文献 Mapper 哪一个 Mapper 继承自（如果有）。

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

attribute sqlalchemy.orm.Mapper.is_mapper = True¶

检查API的一部分。

method sqlalchemy.orm.Mapper.is_sibling(other)¶

如果另一个映射器是此映射器的继承同级，则返回true。共母异支

method sqlalchemy.orm.Mapper.isa(other)¶

如果此映射器继承自给定的映射器，则返回true。

attribute sqlalchemy.orm.Mapper.iterate_properties¶

返回所有MapperProperty对象的迭代器。

attribute sqlalchemy.orm.Mapper.local_table = None¶

这个 Selectable 哪一个 Mapper 管理。

通常是 Table 或 Alias . 也可能是 None .

“本地”表是可选择的 Mapper 直接负责从属性访问和刷新的角度进行管理。对于非继承映射器，本地表与“mapped”表相同。对于已联接的表继承映射器，本地表将是整个“联接”的特定子表，此 Mapper 代表。如果此映射器是继承映射器的单个表，则本地表将 None .

参见

Mapper.persist_selectable .

attribute sqlalchemy.orm.Mapper.mapped_table¶

1.3 版后已移除: 使用.persistu可选

attribute sqlalchemy.orm.Mapper.mapper¶

检查API的一部分。

返回自我。

attribute sqlalchemy.orm.Mapper.non_primary = None¶

代表 True 如果这样 Mapper 是一个“非主”映射器，例如，仅用于选择行但不用于持久性管理的映射器。

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

attribute sqlalchemy.orm.Mapper.persist_selectable = None¶

这个 Selectable 对此 Mapper 被映射。

通常是 Table ， Join 或 Alias .

这个 Mapper.persist_selectable 与…分开 Mapper.selectable 其中前者表示映射到此类或其超类上的列，而后者可能是一个“多态”可选择的列，其中包含附加的列，实际上只映射到子类上。

“持久可选”是“映射器写入的内容”，“可选”是“映射器选择的内容”。

Mapper.persist_selectable 也与 Mapper.local_table ，它表示直接在此类上本地映射的列集。

参见

Mapper.selectable .

Mapper.local_table .

attribute sqlalchemy.orm.Mapper.polymorphic_identity = None¶

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

仅与继承一起使用，此对象可以是任何类型的，与由表示的列的类型相比较。 Mapper.polymorphic_on .

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

method sqlalchemy.orm.Mapper.polymorphic_iterator()¶

循环访问集合，包括此映射器和所有子代映射器。

这不仅包括立即继承的映射器，还包括所有继承的映射器。

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

attribute sqlalchemy.orm.Mapper.polymorphic_map = None¶

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

标识符可以是任何类型的，与列的类型类似，列的类型由 Mapper.polymorphic_on .

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

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

attribute sqlalchemy.orm.Mapper.polymorphic_on = None¶

这个 Column 或指定为 polymorphic_on 关于这个的论点 Mapper 在继承方案中。

此属性通常是 Column 实例，但也可以是表达式，例如派生自 cast() .

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

attribute sqlalchemy.orm.Mapper.primary_key = None¶

包含以下集合的iterable Column 从这个角度来看，组成映射表的“主键”的对象 Mapper .

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

该列表也不一定与与基础表关联的主键列集合相同；该 Mapper 特征A primary_key 可以重写 Mapper 视为主键列。

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

method sqlalchemy.orm.Mapper.primary_key_from_instance(instance)¶

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

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

method sqlalchemy.orm.Mapper.primary_mapper()¶

返回对应于此映射器的类键（类）的主映射器。

attribute sqlalchemy.orm.Mapper.relationships¶

所有名称空间 RelationshipProperty 由此维护的属性 Mapper .

警告

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

参见

Mapper.attrs -全部的命名空间 MapperProperty 物体。

attribute sqlalchemy.orm.Mapper.selectable¶

这个 FromClause 构建这个 Mapper 默认情况下从中选择。

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

attribute sqlalchemy.orm.Mapper.self_and_descendants¶

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

这不仅包括立即继承的映射器，还包括所有继承的映射器。

attribute sqlalchemy.orm.Mapper.single = None¶

代表 True 如果这样 Mapper 是单个表继承映射器。

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

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

attribute sqlalchemy.orm.Mapper.synonyms¶

返回所有 SynonymProperty 由此维护的属性 Mapper .

参见

Mapper.attrs -全部的命名空间 MapperProperty 物体。

attribute sqlalchemy.orm.Mapper.tables = None¶

包含以下集合的iterable Table 对象 Mapper 意识到。

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

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

attribute sqlalchemy.orm.Mapper.validators = None¶

使用 validates() 装饰者。

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

attribute sqlalchemy.orm.Mapper.with_polymorphic_mappers¶

名单 Mapper 默认“多态”查询中包含的对象。