SqlAlchemy 2.0 中文文档（十）（3）

SqlAlchemy 2.0 中文文档（十）（2）https://developer.aliyun.com/article/1562916

参数：

cls – 要映射的类。

返回：

一个Mapper对象。

另请参阅

声明式映射

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

registry.map_imperatively()

method 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构造函数。
  

另请参见

命令式映射

声明式映射

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

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

attribute mappers

所有Mapper对象的只读集合。

method update_type_annotation_map(type_annotation_map: _TypeAnnotationMapType) → None

使用新值更新registry.type_annotation_map。

function 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, 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 – 要映射的列对象列表。
  
• 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，则表示在未延迟加载列时应引发错误，而不是加载值。可以通过在查询时使用带有 raiseload=False 的 deferred() 选项来更改此行为。
  从版本 1.4 开始新增。
  另请参阅
  使用 raiseload 避免延迟列加载
  
• init –
  自版本 1.4 起弃用：column_property.init 参数对于 column_property() 已弃用。此参数仅适用于声明性数据类配置中的可写属性，而 column_property() 在此上下文中被视为只读属性。
  
• default –
  自版本 1.4 起弃用：column_property.default 参数对于 column_property() 已弃用。此参数仅适用于声明性数据类配置中的可写属性，而 column_property() 在此上下文中被视为只读属性。
  
• default_factory –
  自 1.4 版本起弃用：column_property.default_factory 参数已弃用于 column_property()。此参数仅适用于声明性数据类配置中的可写属性，而在此上下文中，column_property() 被视为只读属性。
  
• kw_only –
  自 1.4 版本起弃用：column_property.kw_only 参数已弃用于 column_property()。此参数仅适用于声明性数据类配置中的可写属性，而在此上下文中，column_property() 被视为只读属性。
  

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 属性可用。
  
• 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__兼容可调用项。
  

另请参见

registry

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

function sqlalchemy.orm.mapped_column(__name_pos: str | _TypeEngineArgument[Any] | SchemaEventTarget | None = None, __type_pos: _TypeEngineArgument[Any] | SchemaEventTarget | None = None, *args: SchemaEventTarget, 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, nullable: bool | Literal[SchemaConst.NULL_UNSPECIFIED] | None = SchemaConst.NULL_UNSPECIFIED, primary_key: bool | None = False, deferred: _NoArg | bool = _NoArg.NO_ARG, deferred_group: str | None = None, deferred_raiseload: bool | None = None, use_existing_column: bool = False, name: str | None = None, type_: _TypeEngineArgument[Any] | None = None, autoincrement: _AutoIncrementType = 'auto', doc: str | None = None, key: str | None = None, index: bool | None = None, unique: bool | None = None, info: _InfoType | None = None, onupdate: Any | None = None, insert_default: Any | None = _NoArg.NO_ARG, server_default: _ServerDefaultArgument | None = None, server_onupdate: FetchedValue | None = None, active_history: bool = False, quote: bool | None = None, system: bool = False, comment: str | None = None, sort_order: _NoArg | int = _NoArg.NO_ARG, **kw: Any) → MappedColumn[Any]

为在声明性表配置中使用的新的 ORM 映射的Column构造声明。

mapped_column()函数提供了一个与 ORM 兼容且与 Python 类型兼容的构造，用于声明性映射，指示映射到 Core Column 对象的属性。当使用声明性时，特别是在使用声明性表配置时，它提供了将属性映射到Column对象的等效功能。

2.0 版中的新功能。

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

对于mapped_column()的使用示例，请参阅使用 mapped_column() 的声明性表中的文档。

另请参阅

使用 mapped_column() 的声明性表 - 完整文档

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

参数：

• __name – 要为 Column 指定的字符串名称。这是一个可选的仅位置参数，如果存在，必须是传递的第一个位置参数。如果省略，则将使用 mapped_column() 映射到的属性名称作为 SQL 列名。
  
• __type – TypeEngine 类型或实例，指示与 Column 关联的数据类型。这是一个可选的仅位置参数，如果存在，则必须紧随 __name 参数，否则必须是第一个位置参数。如果省略，则列的最终类型可以从注释类型中推导出，或者如果存在 ForeignKey，则可以从引用列的数据类型中推导出。
  
• *args – 额外的位置参数包括诸如 ForeignKey、CheckConstraint 和 Identity 这样的结构，它们被传递到构造的 Column 中。
  
• nullable – 可选布尔值，指示列是否应为“NULL”或“NOT NULL”。如果省略，nullability 将根据类型注释推导而来，根据 typing.Optional 是否存在而定。否则，对于非主键列，nullable 默认为 True，对于主键列，默认为 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，则尝试在继承的超类（通常是单一继承的超类）上定位给定列名，如果存在，则不会生成新列，将映射到超类列，就好像该列从此类中省略一样。这用于将新列添加到继承的超类的混合类。
  另请参阅
  使用 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的默认值将在调用__init__()时提前分配给对象，在任何情况下，核心 Insert 构造将使用相同的值，从而导致相同的最终结果。
  注意
  当使用在 Core 级别的列默认值作为可调用对象，由底层Column与 ORM 映射的数据类，特别是那些是上下文感知的默认函数时，必须使用**mapped_column.insert_default参数**。这是必要的，以消除可调用对象被解释为数据类级别默认值的歧义。
  
• insert_default – 直接传递给Column.default参数；当存在时，将取代mapped_column.default的值，但无论何时，mapped_column.default都将应用于数据类映射的构造函数默认值。
  
• 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__()方法的一部分的默认值生成函数。
  
• compare –
  特定于声明式数据类映射，指示在为映射类生成__eq__()和__ne__()方法时，是否应包含此字段在比较操作中。
  在版本 2.0.0b4 中新增。
  
• kw_only – 特定于声明式数据类映射，指示在生成__init__()时，是否应将此字段标记为仅关键字。
  
• **kw – 所有剩余的关键字参数都传递给Column的构造函数。
  

class sqlalchemy.orm.declared_attr

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

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

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

示例：

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显式装饰的函数。从运行时的角度来看，这从未必要，但可能需要支持不认识已装饰函数具有类级行为的cls参数的PEP 484类型工具：

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集成。

另见

通过混合组合映射层次结构 - 附带对declared_attr使用模式的背景说明的声明性混合文档。

成员

级联，指令

类签名

类sqlalchemy.orm.declared_attr (sqlalchemy.orm.base._MappedAttribute, sqlalchemy.orm.decl_api._declared_attr_common)

attribute cascading

将declared_attr标记为级联。

这是一个特殊用途的修饰符，表明在映射继承场景中，列或基于 MapperProperty 的声明属性应该在映射的子类中独立配置。

警告

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

• 标志only适用于在声明性混合类和__abstract__类上使用declared_attr；当直接在映射类上使用时，它目前没有任何效果。
  
• 标志only仅适用于通常命名的属性，例如不是任何特殊下划线属性，例如__tablename__。在这些属性上它没有效果。
  
• 当前标志不允许进一步覆盖类层次结构下游；如果子类尝试覆盖属性，则会发出警告并跳过覆盖的属性。这是一个希望在某些时候解决的限制。
  

SqlAlchemy 2.0 中文文档（十）（4）https://developer.aliyun.com/article/1562918