Обзор сопоставленных классов ORM¶

Декларативное отображение¶

Декларативное отображение - это типичный способ построения отображений в современной 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


# 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]]

Выше, класс DeclarativeBase используется для создания нового базового класса (в документации SQLAlchemy он обычно называется Base, но может иметь любое желаемое имя), от которого могут наследоваться новые сопоставляемые классы, как показано выше, создается новый сопоставляемый класс User.

Базовый класс относится к объекту registry, который хранит коллекцию связанных сопоставленных классов. а также к объекту MetaData, который хранит коллекцию объектов Table, к которым сопоставлены классы.

Основные стили декларативного отображения более подробно описаны в следующих разделах:

• Использование декларативного базового класса - декларативное отображение с использованием базового класса.

• Декларативное отображение с использованием декоратора (без декларативной базы) - декларативное отображение с использованием декоратора, а не базового класса.

В рамках декларативного сопоставленного класса также существует две разновидности того, как могут быть объявлены метаданные Table. К ним относятся:

• Декларативная таблица с mapped_column() - столбцы таблицы объявляются inline внутри сопоставленного класса с помощью директивы mapped_column() (или в унаследованной форме, используя непосредственно объект Column). Директива mapped_column() также может быть опционально объединена с аннотациями типов с помощью класса Mapped, который может предоставить некоторые подробности о сопоставленных колонках напрямую. Директивы столбцов в сочетании с директивами __tablename__ и необязательными директивами __table_args__ уровня класса позволят процессу декларативного отображения построить объект Table для отображения.

• Декларатив с императивной таблицей (также известный как гибридный декларатив) - Вместо того чтобы отдельно указывать имя таблицы и атрибуты, явно созданный объект Table ассоциируется с классом, который иначе отображается декларативно. Этот стиль отображения представляет собой гибрид «декларативного» и «императивного» отображения и применяется к таким техникам, как отображение классов на объекты reflected Table, а также отображение классов на существующие конструкции Core, такие как соединения и подзапросы.

Документация по декларативному отображению продолжается на Сопоставление классов с декларативными.

Императивное картирование¶

императивное или классическое отображение относится к конфигурации отображаемого класса с помощью метода registry.map_imperatively(), когда целевой класс не включает никаких декларативных атрибутов класса.

В «классическом» виде метаданные таблицы создаются отдельно с помощью конструкции Table, затем ассоциируются с классом User через метод registry.map_imperatively(), после создания экземпляра 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, затем связанный с User через 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)

Обратите внимание, что классы, отображенные с помощью императивного подхода, полностью взаимозаменяемы с классами, отображенными с помощью декларативного подхода. Обе системы в конечном итоге создают одну и ту же конфигурацию, состоящую из Table, определяемого пользователем класса, связанного вместе с объектом Mapper. Когда мы говорим о «поведении Mapper», это относится и к использованию декларативной системы - она все еще используется, просто за кулисами.

Класс для отображения¶

Это класс, который мы создаем в нашем приложении. Обычно на структуру этого класса не накладывается никаких ограничений. [1] Когда класс Python сопоставлен, для него может быть только один Mapper объект. [2]

При отображении с помощью стиля отображения declarative, отображаемый класс либо является подклассом декларативного базового класса, либо обрабатывается декоратором или функцией, такой как registry.mapped().

При отображении в стиле imperative класс передается непосредственно как аргумент map_imperatively.class_.

Таблица или другой объект пункта from¶

В подавляющем большинстве случаев это экземпляр Table. Для более сложных случаев использования он может также относиться к любому виду объекта FromClause, наиболее распространенными альтернативными объектами являются Subquery и Join.

При отображении с помощью стиля отображения declarative предметная таблица либо генерируется декларативной системой на основе атрибута __tablename__ и представленных объектов Column, либо устанавливается с помощью атрибута __table__. Эти два стиля конфигурации представлены в Декларативная таблица с mapped_column() и Декларатив с императивной таблицей (также известный как гибридный декларатив).

При сопоставлении со стилем imperative таблица предметов передается позиционно как аргумент map_imperatively.local_table.

В отличие от требования «один отобразитель на класс» для отображаемого класса, объект Table или другой FromClause, который является предметом отображения, может быть связан с любым количеством отображений. Сопоставление Mapper применяет модификации непосредственно к определяемому пользователем классу, но никак не модифицирует данный Table или другой FromClause.

Словарь свойств¶

Это словарь всех атрибутов, которые будут связаны с отображаемым классом. По умолчанию Mapper генерирует записи для этого словаря, производные от заданного Table, в виде ColumnProperty объектов, каждый из которых ссылается на отдельную Column сопоставленную таблицу. Словарь свойств будет также содержать все другие виды MapperProperty объектов, которые необходимо настроить, чаще всего экземпляры, создаваемые конструкцией relationship().

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

При отображении в стиле imperative словарь свойств передается непосредственно как параметр properties в registry.map_imperatively(), который передает его в параметр Mapper.properties.

Другие параметры конфигурации картографа¶

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

При отображении в стиле imperative аргументы ключевых слов передаются методу to registry.map_imperatively(), который передает их классу Mapper.

Полный набор принимаемых параметров задокументирован в Mapper.

Конструктор по умолчанию¶

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

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]

Объект типа User выше будет иметь конструктор, который позволяет создавать объекты User как:

u1 = User(name="some name", fullname="some fullname")

Класс, включающий явный метод __init__(), будет поддерживать этот метод, и конструктор по умолчанию применяться не будет.

Чтобы изменить используемый по умолчанию конструктор, к параметру registry.constructor можно предоставить пользовательский вызываемый элемент Python, который будет использоваться в качестве конструктора по умолчанию.

Конструктор также применяется к императивным отображениям:

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


class User:
    pass


mapper_registry.map_imperatively(User, user_table)

Приведенный выше класс, отображенный императивно, как описано в Императивное картирование, также будет иметь конструктор по умолчанию, связанный с registry.

Runtime Introspection of Mapped classes, Instances and Mappers¶

Класс, который отображается с помощью registry, также будет иметь несколько атрибутов, общих для всех отображений:

• Атрибут __mapper__ будет ссылаться на Mapper, который связан с классом:

  mapper = User.__mapper__

  Это Mapper также то, что возвращается при использовании функции inspect() против сопоставленного класса:

  from sqlalchemy import inspect
  
  mapper = inspect(User)

• Атрибут __table__ будет ссылаться на Table, или более обобщенно на объект FromClause, к которому привязан класс:

  table = User.__table__

  Этот FromClause также возвращается при использовании атрибута Mapper.local_table в Mapper:

  table = inspect(User).local_table

  Для однотабличного отображения наследования, когда класс является подклассом, не имеющим собственной таблицы, атрибут Mapper.local_table, а также атрибут .__table__ будут None. Чтобы получить «selectable», который фактически выбирается во время запроса для данного класса, это можно сделать с помощью атрибута Mapper.selectable:

  table = inspect(User).selectable

>>> from sqlalchemy import inspect
>>> insp = inspect(User)

>>> insp.columns
<sqlalchemy.util._collections.OrderedProperties object at 0x102f407f8>

>>> list(insp.columns)
[Column('id', Integer(), table=<user>, primary_key=True, nullable=False), Column('name', String(length=50), table=<user>), Column('fullname', String(length=50), table=<user>), Column('nickname', String(length=50), table=<user>)]
>>> insp.columns.name
Column('name', String(length=50), table=<user>)

>>> insp.all_orm_descriptors
<sqlalchemy.util._collections.ImmutableProperties object at 0x1040e2c68>
>>> insp.all_orm_descriptors.keys()
['fullname', 'nickname', 'name', 'id']

>>> list(insp.column_attrs)
[<ColumnProperty at 0x10403fde0; id>, <ColumnProperty at 0x10403fce8; name>, <ColumnProperty at 0x1040e9050; fullname>, <ColumnProperty at 0x1040e9148; nickname>]
>>> insp.column_attrs.name
<ColumnProperty at 0x10403fce8; name>
>>> insp.column_attrs.name.expression
Column('name', String(length=50), table=<user>)

>>> u1 = session.scalars(select(User)).first()

>>> insp = inspect(u1)
>>> insp
<sqlalchemy.orm.state.InstanceState object at 0x7f07e5fec2e0>

>>> insp.mapper
<Mapper at 0x7f07e614ef50; User>

>>> insp.session
<sqlalchemy.orm.session.Session object at 0x7f07e614f160>

>>> insp.persistent
True
>>> insp.pending
False

>>> insp.unloaded
{'addresses'}

>>> insp.unmodified
{'nickname', 'name', 'fullname', 'id'}

>>> insp.attrs.nickname.value
'nickname'
>>> u1.nickname = "new nickname"
>>> insp.attrs.nickname.history
History(added=['new nickname'], unchanged=(), deleted=['nickname'])