ORM 映射类概述¶

ORM Mapped Class Overview

中文

ORM类映射配置概述。

对于SQLAlchemy ORM和/或Python新手来说，建议浏览 ORM 快速入门，最好是通读 SQLAlchemy 统一教程，其中在使用 ORM 声明形式定义表元数据首次介绍了ORM配置。

英文

Overview of ORM class mapping configuration.

For readers new to the SQLAlchemy ORM and/or new to Python in general, it’s recommended to browse through the ORM 快速入门 and preferably to work through the SQLAlchemy 统一教程, where ORM configuration is first introduced at 使用 ORM 声明形式定义表元数据.

ORM 映射风格¶

ORM Mapping Styles

中文

SQLAlchemy具有两种截然不同的映射配置风格，这些风格又进一步细分为不同的设置选项。映射风格的多样性是为了适应各种开发者的偏好，包括用户定义类与其映射到关系模式表和列的抽象程度、使用的类层次结构类型（包括是否存在自定义元类方案），以及是否存在其他类仪器化方法，例如是否同时使用Python数据类。

在现代SQLAlchemy中，这些风格之间的差异主要是表面的；当使用特定的SQLAlchemy配置风格来表示映射类的意图时，映射类的内部过程在每种情况下大致相同，其最终结果总是一个用户定义的类，该类具有一个配置为可选择单元的 Mapper，通常由 Table 对象表示，类本身已被仪器化 (instrumented) 以包括与关系操作相关的行为，无论是在类的级别还是在该类的实例上。由于过程在所有情况下基本相同，因此从不同风格映射的类始终可以完全互操作。协议 MappedClassProtocol 可用于在使用类型检查器（如mypy）时指示映射类。

最初的映射API通常被称为“经典”风格，而更自动化的映射风格称为“声明式”风格。SQLAlchemy现在将这两种映射风格称为 命令式映射(imperative mapping) 和 声明式映射(declarative mapping) 。

无论使用何种映射风格，自SQLAlchemy 1.4起，所有ORM映射都源自一个名为 registry 的单一对象，这是一个映射类的注册表。使用此注册表，可以作为一个组来最终确定一组映射器配置，并且特定注册表中的类可以在配置过程中按名称相互引用。

在 1.4 版本发生变更: 声明式映射和经典映射现在被称为“声明式(declarative)”和“命令式(imperative)”映射，并在内部统一，所有映射都源自表示相关映射集合的 registry 构造。

英文

SQLAlchemy features two distinct styles of mapper configuration, which then feature further sub-options for how they are set up. The variability in mapper styles is present to suit a varied list of developer preferences, including the degree of abstraction of a user-defined class from how it is to be mapped to relational schema tables and columns, what kinds of class hierarchies are in use, including whether or not custom metaclass schemes are present, and finally if there are other class-instrumentation approaches present such as if Python dataclasses are in use simultaneously.

In modern SQLAlchemy, the difference between these styles is mostly superficial; when a particular SQLAlchemy configurational style is used to express the intent to map a class, the internal process of mapping the class proceeds in mostly the same way for each, where the end result is always a user-defined class that has a Mapper configured against a selectable unit, typically represented by a Table object, and the class itself has been instrumented to include behaviors linked to relational operations both at the level of the class as well as on instances of that class. As the process is basically the same in all cases, classes mapped from different styles are always fully interoperable with each other. The protocol MappedClassProtocol can be used to indicate a mapped class when using type checkers such as mypy.

The original mapping API is commonly referred to as “classical” style, whereas the more automated style of mapping is known as “declarative” style. SQLAlchemy now refers to these two mapping styles as imperative mapping and declarative mapping.

Regardless of what style of mapping used, all ORM mappings as of SQLAlchemy 1.4 originate from a single object known as registry, which is a registry of mapped classes. Using this registry, a set of mapper configurations can be finalized as a group, and classes within a particular registry may refer to each other by name within the configurational process.

在 1.4 版本发生变更: Declarative and classical mapping are now referred to as “declarative” and “imperative” mapping, and are unified internally, all originating from the registry construct that represents a collection of related mappings.

声明式映射¶

Declarative Mapping

中文

声明式映射 是现代SQLAlchemy中构建映射的典型方式。最常见的模式是首先使用 DeclarativeBase 超类构造一个基类。当子类化时，生成的基类将对派生自它的所有子类应用声明式映射过程，默认情况下，相对于特定的 registry 是本地的。下面的示例说明了使用声明式基类然后在声明式表映射中的使用:

from sqlalchemy import Integer, String, ForeignKey
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column


# 声明基类
class Base(DeclarativeBase):
    pass


# 使用基类的示例映射
class User(Base):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    fullname: Mapped[str] = mapped_column(String(30))
    nickname: Mapped[Optional[str]]

在上面，使用 DeclarativeBase 类生成一个新的基类（在SQLAlchemy的文档中通常称为 Base ，但可以具有任何所需的名称），新映射类可以继承该基类，如上所示，构造了一个新的映射类 User 。

在 2.0 版本发生变更: DeclarativeBase 超类取代了 declarative_base() 函数和 registry.generate_base() 方法的使用；超类方法无需插件即可与 PEP 484 工具集成。参见 ORM Declarative Models 了解迁移说明。

基类指的是一个 registry 对象，该对象维护一组相关的映射类集合，以及一个保留类映射到的 Table 对象集合的 MetaData 对象。

主要的声明式映射风格在以下部分中有进一步详细介绍：

使用声明性基类 - 使用基类的声明式映射。
使用装饰器进行声明性映射（无声明性基类） - 使用装饰器而不是基类的声明式映射。

在声明式映射类的范围内，也有两种声明 Table 元数据的方式。这些包括：

带有 mapped_column() 的声明表 - 使用 mapped_column() 指令在映射类中内联声明表列（或在遗留形式中，直接使用 Column 对象）。 mapped_column() 指令还可以选择性地与使用 Mapped 类的类型注释结合使用，以直接提供有关映射列的一些详细信息。列指令与 __tablename__ 和可选的 __table_args__ 类级别指令结合使用，将允许声明式映射过程构建一个要映射的 Table 对象。
使用命令式表的声明式（又名混合声明式） - 不单独指定表名和属性，而是将一个显式构造的 Table 对象与一个其他方面声明式映射的类关联。这种映射风格是“声明式”和“命令式”映射的混合体，适用于将类映射到反射的 Table 对象以及将类映射到现有Core构造（如连接和子查询）的技术。

声明式映射的文档在使用声明式映射类继续。

英文

The Declarative Mapping is the typical way that mappings are constructed in modern SQLAlchemy. The most common pattern is to first construct a base class using the DeclarativeBase superclass. The resulting base class, when subclassed will apply the declarative mapping process to all subclasses that derive from it, relative to a particular registry that is local to the new base by default. The example below illustrates the use of a declarative base which is then used in a declarative table mapping:

from sqlalchemy import Integer, String, ForeignKey
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column


# declarative base class
class Base(DeclarativeBase):
    pass


# an example mapping using the base
class User(Base):
    __tablename__ = "user"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]
    fullname: Mapped[str] = mapped_column(String(30))
    nickname: Mapped[Optional[str]]

Above, the DeclarativeBase class is used to generate a new base class (within SQLAlchemy’s documentation it’s typically referred to as Base, however can have any desired name) from which new classes to be mapped may inherit from, as above a new mapped class User is constructed.

在 2.0 版本发生变更: The DeclarativeBase superclass supersedes the use of the declarative_base() function and registry.generate_base() methods; the superclass approach integrates with PEP 484 tools without the use of plugins. See ORM Declarative Models for migration notes.

The base class refers to a registry object that maintains a collection of related mapped classes. as well as to a MetaData object that retains a collection of Table objects to which the classes are mapped.

The major Declarative mapping styles are further detailed in the following sections:

使用声明性基类 - declarative mapping using a base class.
使用装饰器进行声明性映射（无声明性基类） - declarative mapping using a decorator, rather than a base class.

Within the scope of a Declarative mapped class, there are also two varieties of how the Table metadata may be declared. These include:

带有 mapped_column() 的声明表 - table columns are declared inline within the mapped class using the mapped_column() directive (or in legacy form, using the Column object directly). The mapped_column() directive may also be optionally combined with type annotations using the Mapped class which can provide some details about the mapped columns directly. The column directives, in combination with the __tablename__ and optional __table_args__ class level directives will allow the Declarative mapping process to construct a Table object to be mapped.
使用命令式表的声明式（又名混合声明式） - Instead of specifying table name and attributes separately, an explicitly constructed Table object is associated with a class that is otherwise mapped declaratively. This style of mapping is a hybrid of “declarative” and “imperative” mapping, and applies to techniques such as mapping classes to reflected Table objects, as well as mapping classes to existing Core constructs such as joins and subqueries.

Documentation for Declarative mapping continues at 使用声明式映射类.

命令式映射¶

Imperative Mapping

中文

命令式 或经典映射指的是使用 registry.map_imperatively() 方法配置映射类，其中目标类不包含任何声明式类属性。

小技巧

命令式映射形式是一种较少使用的映射形式，起源于2006年SQLAlchemy的最早版本。它本质上是一种绕过声明系统的方法，提供了一种更“简陋”的映射系统，并且不提供现代功能，如 PEP 484 支持。因此，大多数文档示例使用声明式形式，建议新用户从 Declarative Table 配置开始。

在 2.0 版本发生变更: 现在使用 registry.map_imperatively() 方法创建经典映射。独立函数 sqlalchemy.orm.mapper() 已有效移除。

在“经典”形式中，表元数据是使用 Table 构造单独创建的，然后通过 registry.map_imperatively() 方法与 User 类关联，在建立 registry 实例后。通常，共享的 registry 实例用于所有相关的映射类:

from sqlalchemy import Table, Column, Integer, String, ForeignKey
from sqlalchemy.orm import registry

mapper_registry = registry()

user_table = Table(
    "user",
    mapper_registry.metadata,
    Column("id", Integer, primary_key=True),
    Column("name", String(50)),
    Column("fullname", String(50)),
    Column("nickname", String(12)),
)


class User:
    pass


mapper_registry.map_imperatively(User, user_table)

有关映射属性的信息，例如与其他类的关系，通过 properties 字典提供。下面的示例说明了第二个 Table 对象，映射到一个名为 Address 的类，然后通过 relationship() 链接到 User

address = Table(
    "address",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("user_id", Integer, ForeignKey("user.id")),
    Column("email_address", String(50)),
)

mapper_registry.map_imperatively(
    User,
    user,
    properties={
        "addresses": relationship(Address, backref="user", order_by=address.c.id)
    },
)

mapper_registry.map_imperatively(Address, address)

注意，使用命令式方法映射的类与声明式方法映射的类是 完全可互换(fully interchangeable) 的。两种系统最终创建相同的配置，包括一个 Table，用户定义的类，与 Mapper 对象链接在一起。当我们谈论 Mapper 的行为时，这也包括使用声明式系统时——它仍然在使用，只是在幕后进行。

英文

An imperative or classical mapping refers to the configuration of a mapped class using the registry.map_imperatively() method, where the target class does not include any declarative class attributes.

小技巧

The imperative mapping form is a lesser-used form of mapping that originates from the very first releases of SQLAlchemy in 2006. It’s essentially a means of bypassing the Declarative system to provide a more “barebones” system of mapping, and does not offer modern features such as PEP 484 support. As such, most documentation examples use Declarative forms, and it’s recommended that new users start with Declarative Table configuration.

在 2.0 版本发生变更: The registry.map_imperatively() method is now used to create classical mappings. The sqlalchemy.orm.mapper() standalone function is effectively removed.

In “classical” form, the table metadata is created separately with the Table construct, then associated with the User class via the registry.map_imperatively() method, after establishing a registry instance. Normally, a single instance of registry shared for all mapped classes that are related to each other:

from sqlalchemy import Table, Column, Integer, String, ForeignKey
from sqlalchemy.orm import registry

mapper_registry = registry()

user_table = Table(
    "user",
    mapper_registry.metadata,
    Column("id", Integer, primary_key=True),
    Column("name", String(50)),
    Column("fullname", String(50)),
    Column("nickname", String(12)),
)


class User:
    pass


mapper_registry.map_imperatively(User, user_table)

Information about mapped attributes, such as relationships to other classes, are provided via the properties dictionary. The example below illustrates a second Table object, mapped to a class called Address, then linked to User via relationship():

address = Table(
    "address",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("user_id", Integer, ForeignKey("user.id")),
    Column("email_address", String(50)),
)

mapper_registry.map_imperatively(
    User,
    user,
    properties={
        "addresses": relationship(Address, backref="user", order_by=address.c.id)
    },
)

mapper_registry.map_imperatively(Address, address)

Note that classes which are mapped with the Imperative approach are fully interchangeable with those mapped with the Declarative approach. Both systems ultimately create the same configuration, consisting of a Table, user-defined class, linked together with a Mapper object. When we talk about “the behavior of Mapper”, this includes when using the Declarative system as well - it’s still used, just behind the scenes.

ORM 映射类概述¶

ORM 映射风格¶

声明式映射¶

命令式映射¶

映射类基本组件¶

要映射的类¶

表或其他 from 子句对象¶

属性字典¶

其他映射器配置参数¶

映射类行为¶

默认构造函数¶

在加载过程中维护非映射状态¶

映射类、实例和映射器的运行时自检¶

映射器对象的检查¶

映射实例的检查¶