与dataclass和attrs的集成¶

Integration with dataclasses and attrs

中文

SQLAlchemy 自 2.0 版本起，支持“原生数据类”集成，通过在映射类中添加一个混入或装饰器，可以将 Annotated Declarative Table 映射转换为 Python 数据类_。

在 2.0 版本加入: 与 ORM 声明类集成的数据类创建

还有一些模式允许映射现有的数据类，以及映射由 attrs 第三方集成库注入的类。

英文

SQLAlchemy as of version 2.0 features “native dataclass” integration where an Annotated Declarative Table mapping may be turned into a Python dataclass by adding a single mixin or decorator to mapped classes.

在 2.0 版本加入: Integrated dataclass creation with ORM Declarative classes

There are also patterns available that allow existing dataclasses to be mapped, as well as to map classes instrumented by the attrs third party integration library.

将 ORM 映射应用于现有属性类¶

Applying ORM mappings to an existing attrs class

中文

警告

attrs 库不是 SQLAlchemy 的持续集成测试的一部分，由于任何一方引入的不兼容性，可能会在没有通知的情况下更改与该库的兼容性。

attrs 库是一个流行的第三方库，提供与数据类相似的功能，并提供许多普通数据类中没有的额外功能。

使用 attrs 增强的类使用 @define 装饰器。此装饰器启动一个过程，扫描定义类行为的类属性，然后用于生成方法、文档和注释。

SQLAlchemy ORM 支持使用 命令式 映射映射 attrs 类。这种风格的通用形式等同于使用数据类的使用命令式映射映射预先存在的数据类映射形式，其中类构造仅使用 attrs，ORM 映射在类构造之后应用，而不进行任何类属性扫描。

attrs 的 @define 装饰器默认情况下会用一个新的基于 __slots__ 的类替换注解类，这是不支持的。使用旧样式注解 @attr.s 或使用 define(slots=False) 时，类不会被替换。此外， attrs 在装饰器运行后会删除其自己的类绑定属性，以便 SQLAlchemy 的映射过程可以接管这些属性而不会出现任何问题。这两个装饰器 @attr.s 和 @define(slots=False) 均适用于 SQLAlchemy。

在 2.0 版本发生变更: SQLAlchemy 与 attrs 的集成仅适用于命令式映射风格，即不使用声明性。引入的 ORM 注解声明风格与 attrs 不兼容。

首先构建 attrs 类。SQLAlchemy ORM 映射可以在之后应用，使用 registry.map_imperatively():

from __future__ import annotations

from typing import List

from attrs import define
from sqlalchemy import Column
from sqlalchemy import ForeignKey
from sqlalchemy import Integer
from sqlalchemy import MetaData
from sqlalchemy import String
from sqlalchemy import Table
from sqlalchemy.orm import registry
from sqlalchemy.orm import relationship

mapper_registry = registry()


@define(slots=False)
class User:
    id: int
    name: str
    fullname: str
    nickname: str
    addresses: List[Address]


@define(slots=False)
class Address:
    id: int
    user_id: int
    email_address: Optional[str]


metadata_obj = MetaData()

user = Table(
    "user",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("name", String(50)),
    Column("fullname", String(50)),
    Column("nickname", String(12)),
)

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)

英文

警告

The attrs library is not part of SQLAlchemy’s continuous integration testing, and compatibility with this library may change without notice due to incompatibilities introduced by either side.

The attrs library is a popular third party library that provides similar features as dataclasses, with many additional features provided not found in ordinary dataclasses.

A class augmented with attrs uses the @define decorator. This decorator initiates a process to scan the class for attributes that define the class’ behavior, which are then used to generate methods, documentation, and annotations.

The SQLAlchemy ORM supports mapping an attrs class using Imperative mapping. The general form of this style is equivalent to the 使用命令式映射映射预先存在的数据类 mapping form used with dataclasses, where the class construction uses attrs alone, with ORM mappings applied after the fact without any class attribute scanning.

The @define decorator of attrs by default replaces the annotated class with a new __slots__ based class, which is not supported. When using the old style annotation @attr.s or using define(slots=False), the class does not get replaced. Furthermore attrs removes its own class-bound attributes after the decorator runs, so that SQLAlchemy’s mapping process takes over these attributes without any issue. Both decorators, @attr.s and @define(slots=False) work with SQLAlchemy.

在 2.0 版本发生变更: SQLAlchemy integration with attrs works only with imperative mapping style, that is, not using Declarative. The introduction of ORM Annotated Declarative style is not cross-compatible with attrs.

The attrs class is built first. The SQLAlchemy ORM mapping can be applied after the fact using registry.map_imperatively():

from __future__ import annotations

from typing import List

from attrs import define
from sqlalchemy import Column
from sqlalchemy import ForeignKey
from sqlalchemy import Integer
from sqlalchemy import MetaData
from sqlalchemy import String
from sqlalchemy import Table
from sqlalchemy.orm import registry
from sqlalchemy.orm import relationship

mapper_registry = registry()


@define(slots=False)
class User:
    id: int
    name: str
    fullname: str
    nickname: str
    addresses: List[Address]


@define(slots=False)
class Address:
    id: int
    user_id: int
    email_address: Optional[str]


metadata_obj = MetaData()

user = Table(
    "user",
    metadata_obj,
    Column("id", Integer, primary_key=True),
    Column("name", String(50)),
    Column("fullname", String(50)),
    Column("nickname", String(12)),
)

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)

与dataclass和attrs的集成¶

声明式Dataclass映射¶

类级功能配置¶

属性配置¶

列默认值¶

与注解集成¶

使用混合和抽象超类¶

关系配置¶

使用非映射数据类字段¶

与 Pydantic 等备用数据类提供程序集成¶

将 ORM 映射应用于现有数据类（旧式数据类使用）¶

使用声明式和命令式表映射预先存在的数据类¶

使用声明式样式字段映射预先存在的数据类¶

将声明式混合与预先存在的数据类结合使用¶

使用命令式映射映射预先存在的数据类¶

将 ORM 映射应用于现有属性类¶