Составление сопоставленных иерархий с помощью миксинов¶

Расширение базы¶

Помимо использования чистого миксина, большинство приемов, описанных в этом разделе, можно также применять непосредственно к базовому классу для получения шаблонов, которые должны применяться ко всем классам, производным от конкретной базы. Пример ниже иллюстрирует некоторые из примеров предыдущего раздела в терминах класса Base:

from sqlalchemy import ForeignKey
from sqlalchemy.orm import declared_attr
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    """define a series of common elements that may be applied to mapped
    classes using this class as a base class."""

    @declared_attr.directive
    def __tablename__(cls) -> str:
        return cls.__name__.lower()

    __table_args__ = {"mysql_engine": "InnoDB"}
    __mapper_args__ = {"eager_defaults": True}

    id: Mapped[int] = mapped_column(primary_key=True)


class HasLogRecord:
    """mark classes that have a many-to-one relationship to the
    ``LogRecord`` class."""

    log_record_id: Mapped[int] = mapped_column(ForeignKey("logrecord.id"))

    @declared_attr
    def log_record(self) -> Mapped["LogRecord"]:
        return relationship("LogRecord")


class LogRecord(Base):
    log_info: Mapped[str]


class MyModel(HasLogRecord, Base):
    name: Mapped[str]

Где выше, MyModel и LogRecord, производные от Base, будут иметь имя таблицы, производное от имени класса, столбец первичного ключа с именем id, а также вышеуказанные аргументы таблицы и маппера, определенные Base.__table_args__ и Base.__mapper_args__.

При использовании унаследованных declarative_base() или registry.generate_base(), параметр declarative_base.cls может быть использован следующим образом для создания эквивалентного эффекта, как показано в неаннотированном примере ниже:

# legacy declarative_base() use

from sqlalchemy import Integer, String
from sqlalchemy import ForeignKey
from sqlalchemy.orm import declared_attr
from sqlalchemy.orm import declarative_base
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base:
    """define a series of common elements that may be applied to mapped
    classes using this class as a base class."""

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

    __table_args__ = {"mysql_engine": "InnoDB"}
    __mapper_args__ = {"eager_defaults": True}

    id = mapped_column(Integer, primary_key=True)


Base = declarative_base(cls=Base)


class HasLogRecord:
    """mark classes that have a many-to-one relationship to the
    ``LogRecord`` class."""

    log_record_id = mapped_column(ForeignKey("logrecord.id"))

    @declared_attr
    def log_record(self):
        return relationship("LogRecord")


class LogRecord(Base):
    log_info = mapped_column(String)


class MyModel(HasLogRecord, Base):
    name = mapped_column(String)

Смешивание в колоннах¶

Колонки могут быть указаны в миксинах при условии использования стиля конфигурации Declarative table (в отличие от конфигурации imperative table), так что колонки, объявленные в миксине, могут быть затем скопированы, чтобы стать частью Table, который генерирует процесс Declarative. Все три конструкции mapped_column(), Mapped и Column могут быть объявлены inline в декларативном миксине:

class TimestampMixin:
    created_at: Mapped[datetime] = mapped_column(default=func.now())
    updated_at: Mapped[datetime]


class MyModel(TimestampMixin, Base):
    __tablename__ = "test"

    id: Mapped[int] = mapped_column(primary_key=True)
    name: Mapped[str]

Там, где указано выше, все декларативные классы, включающие TimestampMixin в свои базы классов, автоматически включают колонку created_at, которая применяет метку времени ко всем вставкам строк, а также колонку updated_at, которая не включает значение по умолчанию для целей примера (если бы она включала, мы бы использовали параметр Column.onupdate, который принимается mapped_column()). Эти конструкции столбцов всегда копируются из исходного миксина или базового класса, так что один и тот же миксин/базовый класс может быть применен к любому количеству целевых классов, каждый из которых будет иметь свои собственные конструкции столбцов.

Все декларативные формы колонок поддерживаются миксинами, включая:

• Аннотированные атрибуты - с присутствием или без присутствия mapped_column():

  class TimestampMixin:
      created_at: Mapped[datetime] = mapped_column(default=func.now())
      updated_at: Mapped[datetime]

• mapped_column - с или без Mapped присутствует:

  class TimestampMixin:
      created_at = mapped_column(default=func.now())
      updated_at: Mapped[datetime] = mapped_column()

• Колонна - наследие Декларативная форма:

  class TimestampMixin:
      created_at = Column(DateTime, default=func.now())
      updated_at = Column(DateTime)

В каждой из приведенных выше форм Declarative обрабатывает атрибуты на основе столбцов в классе mixin путем создания копии конструкции, которая затем применяется к целевому классу.

Смешение в отношениях¶

Отношения, созданные с помощью relationship(), снабжаются декларативными классами-миксинами исключительно с использованием подхода declared_attr, что устраняет любую двусмысленность, которая может возникнуть при копировании отношения и его, возможно, связанного с колонками содержимого. Ниже приведен пример, в котором столбец внешнего ключа и отношение сочетаются таким образом, что два класса Foo и Bar могут быть настроены так, чтобы ссылаться на общий целевой класс по принципу «многие-к-одному:»:

from sqlalchemy import ForeignKey
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import declared_attr
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship


class Base(DeclarativeBase):
    pass


class RefTargetMixin:
    target_id: Mapped[int] = mapped_column(ForeignKey("target.id"))

    @declared_attr
    def target(cls) -> Mapped["Target"]:
        return relationship("Target")


class Foo(RefTargetMixin, Base):
    __tablename__ = "foo"
    id: Mapped[int] = mapped_column(primary_key=True)


class Bar(RefTargetMixin, Base):
    __tablename__ = "bar"
    id: Mapped[int] = mapped_column(primary_key=True)


class Target(Base):
    __tablename__ = "target"
    id: Mapped[int] = mapped_column(primary_key=True)

С помощью приведенного выше отображения каждый из Foo и Bar содержит отношение к Target, доступ к которому осуществляется через атрибут .target:

>>> from sqlalchemy import select
>>> print(select(Foo).join(Foo.target))
{printsql}SELECT foo.id, foo.target_id
FROM foo JOIN target ON target.id = foo.target_id{stop}
>>> print(select(Bar).join(Bar.target))
{printsql}SELECT bar.id, bar.target_id
FROM bar JOIN target ON target.id = bar.target_id{stop}

Специальные аргументы, такие как relationship.primaryjoin, могут также использоваться в смешанных методах класса, которые часто должны ссылаться на сопоставляемый класс. Для схем, которым необходимо ссылаться на локально отображаемые столбцы, в обычных случаях эти столбцы предоставляются Declarative как атрибуты отображаемого класса, который передается в качестве аргумента cls в декорированный метод класса. Используя эту возможность, мы можем, например, переписать метод RefTargetMixin.target с помощью явного primaryjoin, который ссылается на ожидающие отображения столбцы в Target и cls:

class Target(Base):
    __tablename__ = "target"
    id: Mapped[int] = mapped_column(primary_key=True)


class RefTargetMixin:
    target_id: Mapped[int] = mapped_column(ForeignKey("target.id"))

    @declared_attr
    def target(cls) -> Mapped["Target"]:
        # illustrates explicit 'primaryjoin' argument
        return relationship("Target", primaryjoin=Target.id == cls.target_id)

Смешивание column_property() и других MapperProperty классов¶

Как и relationship(), другие подклассы MapperProperty, такие как column_property(), также нуждаются в создании локальных для класса копий, когда используются миксинами, поэтому они также объявляются внутри функций, оформленных declared_attr. Внутри функции другие обычные отображаемые колонки, которые были объявлены с помощью mapped_column(), Mapped или Column, будут доступны из аргумента cls, чтобы их можно было использовать для составления новых атрибутов, как в примере ниже, который складывает две колонки вместе:

from sqlalchemy.orm import column_property
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import declared_attr
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column


class Base(DeclarativeBase):
    pass


class SomethingMixin:
    x: Mapped[int]
    y: Mapped[int]

    @declared_attr
    def x_plus_y(cls) -> Mapped[int]:
        return column_property(cls.x + cls.y)


class Something(SomethingMixin, Base):
    __tablename__ = "something"

    id: Mapped[int] = mapped_column(primary_key=True)

Выше мы можем использовать Something.x_plus_y в операторе, где он выдает полное выражение:

>>> from sqlalchemy import select
>>> print(select(Something.x_plus_y))
{printsql}SELECT something.x + something.y AS anon_1
FROM something

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)

Использование миксинов и базовых классов с шаблонами сопоставленного наследования¶

При работе с шаблонами наследования mapper, документированными в Отображение иерархий наследования классов, некоторые дополнительные возможности появляются при использовании declared_attr либо с классами-миксинами, либо при дополнении как сопоставленных, так и несопоставленных суперклассов в иерархии классов.

При определении функций, украшенных declared_attr на миксинах или базовых классах для интерпретации подклассами в иерархии наследования с отображением, необходимо проводить важное различие между функциями, которые генерируют специальные имена, используемые Declarative, такие как __tablename__, __mapper_args__, и теми, которые могут генерировать обычные отображаемые атрибуты, такие как mapped_column() и relationship(). Функции, определяющие директивы Declarative, вызываются для каждого подкласса в иерархии, тогда как функции, генерирующие сопоставленные атрибуты, вызываются только для первого сопоставленного суперкласса в иерархии.

Обоснование такого различия в поведении основано на том, что сопоставленные свойства уже наследуются классами, например, определенный столбец в сопоставленной таблице суперкласса не должен дублироваться и в подклассе, тогда как элементы, специфичные для конкретного класса или его сопоставленной таблицы, не наследуются, например, имя локально сопоставленной таблицы.

Разница в поведении между этими двумя вариантами использования демонстрируется в следующих двух разделах.

from typing import Optional

from sqlalchemy import ForeignKey
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import declared_attr
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column


class Base(DeclarativeBase):
    pass


class Tablename:
    @declared_attr.directive
    def __tablename__(cls) -> Optional[str]:
        return cls.__name__.lower()


class Person(Tablename, Base):
    id: Mapped[int] = mapped_column(primary_key=True)
    discriminator: Mapped[str]
    __mapper_args__ = {"polymorphic_on": "discriminator"}


class Engineer(Person):
    id: Mapped[int] = mapped_column(ForeignKey("person.id"), primary_key=True)

    primary_language: Mapped[str]

    __mapper_args__ = {"polymorphic_identity": "engineer"}


class Manager(Person):
    @declared_attr.directive
    def __tablename__(cls) -> Optional[str]:
        """override __tablename__ so that Manager is single-inheritance to Person"""

        return None

    __mapper_args__ = {"polymorphic_identity": "manager"}

from sqlalchemy import ForeignKey
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import declared_attr
from sqlalchemy.orm import has_inherited_table
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column


class Base(DeclarativeBase):
    pass


class Tablename:
    @declared_attr.directive
    def __tablename__(cls):
        if has_inherited_table(cls):
            return None
        return cls.__name__.lower()


class Person(Tablename, Base):
    id: Mapped[int] = mapped_column(primary_key=True)
    discriminator: Mapped[str]
    __mapper_args__ = {"polymorphic_on": "discriminator"}


class Engineer(Person):
    @declared_attr.directive
    def __tablename__(cls):
        """override __tablename__ so that Engineer is joined-inheritance to Person"""

        return cls.__name__.lower()

    id: Mapped[int] = mapped_column(ForeignKey("person.id"), primary_key=True)

    primary_language: Mapped[str]

    __mapper_args__ = {"polymorphic_identity": "engineer"}


class Manager(Person):
    __mapper_args__ = {"polymorphic_identity": "manager"}

class HasId:
    id: Mapped[int] = mapped_column(primary_key=True)


class Person(HasId, Base):
    __tablename__ = "person"

    discriminator: Mapped[str]
    __mapper_args__ = {"polymorphic_on": "discriminator"}


# this mapping will fail, as there's no primary key
class Engineer(Person):
    __tablename__ = "engineer"

    primary_language: Mapped[str]
    __mapper_args__ = {"polymorphic_identity": "engineer"}

class HasIdMixin:
    @declared_attr.cascading
    def id(cls) -> Mapped[int]:
        if has_inherited_table(cls):
            return mapped_column(ForeignKey("person.id"), primary_key=True)
        else:
            return mapped_column(Integer, primary_key=True)


class Person(HasIdMixin, Base):
    __tablename__ = "person"

    discriminator: Mapped[str]
    __mapper_args__ = {"polymorphic_on": "discriminator"}


class Engineer(Person):
    __tablename__ = "engineer"

    primary_language: Mapped[str]
    __mapper_args__ = {"polymorphic_identity": "engineer"}

Объединение аргументов таблицы/маппера из нескольких миксинов¶

В случае __table_args__ или __mapper_args__, заданных с помощью декларативных миксинов, вы можете захотеть объединить некоторые параметры из нескольких миксинов с теми, которые вы хотите определить в самом классе. Декоратор declared_attr может быть использован здесь для создания определяемых пользователем процедур свертки, которые берут данные из нескольких коллекций:

from sqlalchemy.orm import declarative_mixin, declared_attr


class MySQLSettings:
    __table_args__ = {"mysql_engine": "InnoDB"}


class MyOtherMixin:
    __table_args__ = {"info": "foo"}


class MyModel(MySQLSettings, MyOtherMixin, Base):
    __tablename__ = "my_model"

    @declared_attr
    def __table_args__(cls):
        args = dict()
        args.update(MySQLSettings.__table_args__)
        args.update(MyOtherMixin.__table_args__)
        return args

    id = mapped_column(Integer, primary_key=True)

Создание индексов с помощью миксинов¶

Чтобы определить именованный, потенциально многоколоночный Index, который применяется ко всем таблицам, полученным из миксина, используйте «inline» форму Index и установите его как часть __table_args__:

class MyMixin:
    a = mapped_column(Integer)
    b = mapped_column(Integer)

    @declared_attr
    def __table_args__(cls):
        return (Index(f"test_idx_{cls.__tablename__}", "a", "b"),)


class MyModel(MyMixin, Base):
    __tablename__ = "atable"
    c = mapped_column(Integer, primary_key=True)