API отображения классов¶

class sqlalchemy.orm.registry¶

Обобщенный реестр для отображения классов.

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

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

• registry.generate_base() возвращает новый декларативный базовый класс и является базовой реализацией функции declarative_base().

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

• registry.map_imperatively() будет выдавать Mapper для класса без сканирования класса на наличие декларативных атрибутов класса. Этот метод соответствует случаю использования, который исторически обеспечивался классической функцией отображения sqlalchemy.orm.mapper(), которая была удалена в SQLAlchemy 2.0.

Добавлено в версии 1.4.

Members

__init__(), as_declarative_base(), configure(), dispose(), generate_base(), map_declaratively(), map_imperatively(), mapped(), mapped_as_dataclass(), mappers, update_type_annotation_map()

См.также

Обзор сопоставленных классов ORM - обзор стилей отображения классов.

method sqlalchemy.orm.registry.__init__(*, metadata: Optional[MetaData] = None, class_registry: Optional[clsregistry._ClsRegistryType] = None, type_annotation_map: Optional[_TypeAnnotationMapType] = None, constructor: Callable[..., None] = <function _declarative_constructor>)¶

Постройте новый registry

Параметры:

• metadata – Необязательный экземпляр MetaData. Все объекты Table, созданные с помощью декларативного отображения таблиц, будут использовать эту коллекцию MetaData. Если оставить этот аргумент по умолчанию None, будет создана пустая коллекция MetaData.

• constructor – Укажите реализацию для функции __init__ на сопоставленном классе, который не имеет собственного __init__. По умолчанию используется реализация, которая присваивает экземпляру **kwargs для объявленных полей и отношений. Если указано None, то __init__ не будет предоставлен, и конструкция вернется к cls.__init__ в соответствии с обычной семантикой Python.

• class_registry – необязательный словарь, который будет служить реестром имен классов-> сопоставленных классов, когда строковые имена используются для идентификации классов внутри relationship() и других. Позволяет двум или более декларативным базовым классам использовать один и тот же реестр имен классов для упрощения межбазовых отношений.

• type_annotation_map – необязательный словарь типов Python к классам или экземплярам SQLAlchemy TypeEngine. Предоставленный dict обновит отображение типов по умолчанию. Оно используется исключительно конструкцией MappedColumn для создания типов столбцов на основе аннотаций в типе Mapped. … версия добавлена:: 2.0 … seealso:: Настройка карты типов

method sqlalchemy.orm.registry.as_declarative_base(**kw: Any) → Callable[[Type[_T]], Type[_T]]¶

Декоратор класса, который будет вызывать registry.generate_base() для заданного базового класса.

Например:

from sqlalchemy.orm import registry

mapper_registry = registry()

@mapper_registry.as_declarative_base()
class Base:
    @declared_attr
    def __tablename__(cls):
        return cls.__name__.lower()
    id = Column(Integer, primary_key=True)

class MyMappedClass(Base):
    # ...

Все аргументы ключевых слов, переданные в registry.as_declarative_base(), передаются в registry.generate_base().

method sqlalchemy.orm.registry.configure(cascade: bool = False) → None¶

Настройте все еще не настроенные картографы в этом registry.

Шаг configure используется для согласования и инициализации связей relationship() между сопоставленными классами, а также для вызова событий конфигурации, таких как MapperEvents.before_configured() и MapperEvents.after_configured(), которые могут использоваться ORM-расширениями или пользовательскими крючками расширения.

Если один или несколько мапперов в этом реестре содержат конструкции relationship(), которые ссылаются на сопоставленные классы в других реестрах, то считается, что этот реестр является зависимым от этих реестров. Для автоматической настройки этих зависимых реестров флаг configure.cascade должен быть установлен в значение True. В противном случае, если они не настроены, будет вызвано исключение. Смысл такого поведения заключается в том, чтобы позволить приложению программно вызывать конфигурацию реестров, контролируя при этом, обращается ли процесс неявно к другим реестрам.

В качестве альтернативы вызову registry.configure() можно использовать функцию ORM configure_mappers() для обеспечения завершения конфигурации для всех registry объектов в памяти. Это обычно проще в использовании, а также предшествует использованию объектов registry в целом. Однако эта функция будет влиять на все сопоставления во всем запущенном процессе Python и может потребовать больше памяти/времени для приложения, в котором много реестров, используемых для различных целей, которые могут не понадобиться немедленно.

См.также

configure_mappers()

Добавлено в версии 1.4.0b2.

method sqlalchemy.orm.registry.dispose(cascade: bool = False) → None¶

Утилизация всех картографов в этом registry.

После вызова метода все классы, которые были отображены в этом реестре, больше не будут иметь инструментарий класса, связанный с ними. Этот метод является пер-registry аналогом функции clear_mappers() для всего приложения.

Если этот реестр содержит отображатели, которые являются зависимыми от других реестров, обычно через ссылки relationship(), то эти реестры также должны быть утилизированы. Когда такие реестры существуют по отношению к данному, их метод registry.dispose() также будет вызван, если флаг dispose.cascade установлен в значение True; в противном случае, если эти реестры еще не были утилизированы, будет выдана ошибка.

Добавлено в версии 1.4.0b2.

См.также

clear_mappers()

method sqlalchemy.orm.registry.generate_base(mapper: ~typing.Optional[~typing.Callable[[...], ~sqlalchemy.orm.mapper.Mapper[~typing.Any]]] = None, cls: ~typing.Type[~typing.Any] = <class 'object'>, name: str = 'Base', metaclass: ~typing.Type[~typing.Any] = <class 'sqlalchemy.orm.decl_api.DeclarativeMeta'>) → Any¶

Создайте декларативный базовый класс.

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

Например:

from sqlalchemy.orm import registry

mapper_registry = registry()

Base = mapper_registry.generate_base()

class MyClass(Base):
    __tablename__ = "my_table"
    id = Column(Integer, primary_key=True)

Приведенный выше динамически созданный класс эквивалентен приведенному ниже нединамическому примеру:

from sqlalchemy.orm import registry
from sqlalchemy.orm.decl_api import DeclarativeMeta

mapper_registry = registry()

class Base(metaclass=DeclarativeMeta):
    __abstract__ = True
    registry = mapper_registry
    metadata = mapper_registry.metadata

    __init__ = mapper_registry.constructor

Изменено в версии 2.0: Обратите внимание, что метод registry.generate_base() заменен новым классом DeclarativeBase, который генерирует новый «базовый» класс, используя подклассификацию, а не возвращаемое значение функции. Это позволяет использовать подход, совместимый с инструментами типизации PEP 484.

Метод registry.generate_base() обеспечивает реализацию функции declarative_base(), которая создает registry и базовый класс одновременно.

Общие сведения и примеры см. в разделе Декларативное отображение.

Параметры:

• mapper – Необязательная вызываемая функция, по умолчанию Mapper. Эта функция используется для генерации новых объектов Mapper.

• cls – По умолчанию имеет значение object. Тип, используемый в качестве основы для создаваемого декларативного базового класса. Может быть классом или кортежем классов.

• name – По умолчанию имеет значение Base. Отображаемое имя для сгенерированного класса. Настройка этого имени не обязательна, но может улучшить ясность при отслеживании и отладке.

• metaclass – По умолчанию DeclarativeMeta. Метакласс или совместимый с __metaclass__ вызываемый класс для использования в качестве метатипа создаваемого декларативного базового класса.

См.также

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

declarative_base()

method sqlalchemy.orm.registry.map_declaratively(cls: Type[_O]) → Mapper[_O]¶

Декларативно отобразите класс.

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

Возвращает объект Mapper.

Например:

from sqlalchemy.orm import registry

mapper_registry = registry()

class Foo:
    __tablename__ = 'some_table'

    id = Column(Integer, primary_key=True)
    name = Column(String)

mapper = mapper_registry.map_declaratively(Foo)

Эту функцию удобнее вызывать косвенно через декоратор класса registry.mapped() или путем подклассификации декларативного метакласса, созданного на основе registry.generate_base().

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

Параметры:

cls – класс для отображения.

Результат:

объект Mapper.

См.также

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

registry.mapped() - более распространенный интерфейс декоратора к этой функции.

registry.map_imperatively()

method sqlalchemy.orm.registry.map_imperatively(class_: Type[_O], local_table: Optional[FromClause] = 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 sqlalchemy.orm.registry.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 sqlalchemy.orm.registry.mapped_as_dataclass(_registry__cls: Optional[Type[_O]] = None, *, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, eq: Union[_NoArg, bool] = _NoArg.NO_ARG, order: Union[_NoArg, bool] = _NoArg.NO_ARG, unsafe_hash: Union[_NoArg, bool] = _NoArg.NO_ARG, match_args: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, dataclass_callable: Union[_NoArg, Callable[..., Type[Any]]] = _NoArg.NO_ARG) → Union[Type[_O], Callable[[Type[_O]], Type[_O]]]¶

Декоратор класса, который будет применять процесс декларативного отображения к заданному классу и дополнительно преобразовывать класс в Python dataclass.

См.также

Декларативное отображение классов данных - полная информация о нативном отображении классов данных SQLAlchemy

Добавлено в версии 2.0.

attribute sqlalchemy.orm.registry.mappers¶

коллекция всех объектов Mapper только для чтения.

method sqlalchemy.orm.registry.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: Optional[str] = None, deferred: bool = False, raiseload: bool = False, comparator_factory: Optional[Type[PropComparator[_T]]] = None, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, default: Optional[Any] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, active_history: bool = False, expire_on_flush: bool = True, info: Optional[_InfoType] = None, doc: Optional[str] = None) → MappedSQLExpression[_T]¶

Предоставьте свойство уровня столбца для использования с отображением.

При использовании декларативных отображений column_property() используется для отображения SQL-выражений, доступных только для чтения, на отображаемый класс.

При использовании императивных отображений конструкция column_property() также берет на себя роль отображения столбцов таблицы с дополнительными характеристиками. При использовании полностью декларативных отображений для этой цели следует использовать конструкцию mapped_column().

При использовании декларативных отображений Dataclass, column_property() считается только для чтения, и не будет включен в конструктор Dataclass __init__().

Функция column_property() возвращает экземпляр ColumnProperty.

См.также

Использование свойства_столбца - общее использование column_property() для отображения выражений SQL

Применение опций загрузки, сохранения и отображения для столбцов императивной таблицы - использование column_property() с отображениями Imperative Table для применения дополнительных опций к простому объекту Column

Параметры:

• *cols – список объектов Column, подлежащих отображению.

• active_history=False – Используется только для Imperative Table mappings, или declarative mappings в стиле наследия (т.е. которые не были обновлены до mapped_column()), для атрибутов на основе столбцов, которые, как ожидается, будут доступны для записи; используйте mapped_column() с mapped_column.active_history для declarative mappings. Функциональные подробности см. в этом параметре.

• comparator_factory – класс, расширяющий Comparator, который обеспечивает генерацию пользовательских предложений SQL для операций сравнения.

• group – имя группы для этого свойства, если оно помечено как отложенное.

• deferred – при значении True свойство колонки является «отложенным», то есть оно не загружается немедленно, а загружается при первом обращении к атрибуту экземпляра. См. также deferred().

• doc – необязательная строка, которая будет применяться в качестве doc для дескриптора, связанного с классом.

• expire_on_flush=True – Отключите истечение срока действия при флеше. Свойство column_property(), которое ссылается на SQL-выражение (а не на отдельный столбец, связанный с таблицей), считается свойством «только для чтения»; его заполнение не влияет на состояние данных, и оно может только возвращать состояние базы данных. По этой причине значение параметра column_property() теряет силу всякий раз, когда родительский объект участвует в flush, то есть имеет какое-либо «грязное» состояние в рамках flush. Установка этого параметра в значение False приведет к тому, что любое существующее значение будет сохранено после завершения работы flush. Обратите внимание, что Session с настройками истечения срока действия по умолчанию, тем не менее, истекает срок действия всех атрибутов после вызова Session.commit().

• info – Необязательный словарь данных, который будет заполнен в атрибут MapperProperty.info этого объекта.

• raiseload – если True, указывает, что столбец должен выдать ошибку при отложенном запросе, а не загружать значение. Это можно изменить во время запроса, используя опцию deferred() с raiseload=False. … versionadded:: 1.4 .. seealso:: Использование рейсмусования для предотвращения отложенных нагрузок на колонны

• init – … deprecated:: 1.4 Параметр column_property.init устарел для column_property(). Этот параметр применяется только к атрибуту с возможностью записи в конфигурации декларативных классов данных, а column_property() рассматривается как атрибут только для чтения в этом контексте.

• default – … deprecated:: 1.4 Параметр column_property.default устарел для column_property(). Этот параметр применяется только к атрибуту с возможностью записи в конфигурации декларативных классов данных, а column_property() рассматривается как атрибут только для чтения в этом контексте.

• default_factory – … deprecated:: 1.4 Параметр column_property.default_factory устарел для column_property(). Этот параметр применяется только к атрибуту с возможностью записи в конфигурации декларативных классов данных, а column_property() рассматривается как атрибут только для чтения в этом контексте.

• kw_only – … deprecated:: 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()

Более подробную информацию смотрите в docstring для registry и registry.generate_base().

Изменено в версии 1.4: Функция declarative_base() теперь является специализацией более общего класса registry. Функция также переходит в пакет sqlalchemy.orm из пакета declarative.ext.

Параметры:

• metadata – Необязательный экземпляр MetaData. Все объекты Table, неявно объявленные подклассами базы, будут разделять эти МетаДанные. Экземпляр MetaData будет создан, если он не указан. Экземпляр MetaData будет доступен через атрибут metadata созданного декларативного базового класса.

• mapper – Необязательный вызываемый элемент, по умолчанию Mapper. Будет использоваться для сопоставления подклассов с их Таблицами.

• cls – По умолчанию имеет значение object. Тип, используемый в качестве основы для создаваемого декларативного базового класса. Может быть классом или кортежем классов.

• name – По умолчанию имеет значение Base. Отображаемое имя для сгенерированного класса. Настройка этого имени не обязательна, но может улучшить ясность при отслеживании и отладке.

• constructor – Укажите реализацию для функции __init__ на сопоставленном классе, который не имеет собственного __init__. По умолчанию используется реализация, которая присваивает экземпляру **kwargs для объявленных полей и отношений. Если указано None, то __init__ не будет предоставлен, и конструкция вернется к cls.__init__ в соответствии с обычной семантикой Python.

• class_registry – необязательный словарь, который будет служить реестром имен классов-> сопоставленных классов, когда строковые имена используются для идентификации классов внутри relationship() и других. Позволяет двум или более декларативным базовым классам использовать один и тот же реестр имен классов для упрощения межбазовых отношений.

• type_annotation_map – необязательный словарь типов Python для SQLAlchemy TypeEngine классов или экземпляров. Он используется исключительно конструкцией MappedColumn для создания типов столбцов на основе аннотаций внутри типа Mapped. … версия добавлена:: 2.0 … seealso:: Настройка карты типов

• 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 plugin в определении декларативных классов-миксинов SQLAlchemy, когда нет другого контекста.

Добавлено в версии 1.4.6.

См.также

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

Использование @declared_attr и декларативных миксинов - в Mypy plugin documentation

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: Optional[Union[str, _TypeEngineArgument[Any], SchemaEventTarget]] = None, __type_pos: Optional[Union[_TypeEngineArgument[Any], SchemaEventTarget]] = None, *args: SchemaEventTarget, init: Union[_NoArg, bool] = _NoArg.NO_ARG, repr: Union[_NoArg, bool] = _NoArg.NO_ARG, default: Optional[Any] = _NoArg.NO_ARG, default_factory: Union[_NoArg, Callable[[], _T]] = _NoArg.NO_ARG, compare: Union[_NoArg, bool] = _NoArg.NO_ARG, kw_only: Union[_NoArg, bool] = _NoArg.NO_ARG, nullable: Optional[Union[bool, Literal[SchemaConst.NULL_UNSPECIFIED]]] = SchemaConst.NULL_UNSPECIFIED, primary_key: Optional[bool] = False, deferred: Union[_NoArg, bool] = _NoArg.NO_ARG, deferred_group: Optional[str] = None, deferred_raiseload: bool = False, use_existing_column: bool = False, name: Optional[str] = None, type_: Optional[_TypeEngineArgument[Any]] = None, autoincrement: _AutoIncrementType = 'auto', doc: Optional[str] = None, key: Optional[str] = None, index: Optional[bool] = None, unique: Optional[bool] = None, info: Optional[_InfoType] = None, onupdate: Optional[Any] = None, insert_default: Optional[Any] = _NoArg.NO_ARG, server_default: Optional[_ServerDefaultArgument] = None, server_onupdate: Optional[FetchedValue] = None, active_history: bool = False, quote: Optional[bool] = None, system: bool = False, comment: Optional[str] = None, sort_order: int = 0, **kw: Any) → MappedColumn[Any]¶

объявить новую ORM-сопоставленную конструкцию Column для использования в конфигурации Declarative Table.

Функция mapped_column() предоставляет ORM-aware и Python-typing-совместимую конструкцию, которая используется с отображениями declarative для указания атрибута, который отображается на объект Core Column. Она обеспечивает эквивалентную возможность отображения атрибута на объект Column непосредственно при использовании Declarative, в частности, при использовании конфигурации Declarative Table.

Добавлено в версии 2.0.

mapped_column() обычно используется с явной типизацией вместе с типом аннотации Mapped, где он может вывести тип SQL и возможность обнуления для столбца на основе того, что присутствует в аннотации Mapped. Он также может использоваться без аннотаций в качестве замены того, как Column используется в декларативных связках в стиле SQLAlchemy 1.x.

Примеры использования 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 – Необязательный параметр bool, должен ли столбец быть «NULL» или «NOT NULL». Если опущено, то возможность нулевого значения определяется из аннотации типа на основе наличия или отсутствия typing.Optional. nullable по умолчанию True в противном случае для столбцов без первичного ключа, и False для столбцов с первичным ключом.

• primary_key – необязательный bool, указывает, будет ли Column частью первичного ключа таблицы или нет.

• deferred – Необязательный bool - этот аргумент ключевого слова потребляется декларативным процессом ORM и не является частью самого Column; вместо этого он указывает, что этот столбец должен быть «отложен» для загрузки, как если бы он был отображен deferred(). … см. также:: Настройка отсрочки колонок в сопоставлениях

• deferred_group – Подразумевает mapped_column.deferred к True, и устанавливает параметр deferred.group. … см. также:: Загрузка отложенных столбцов в группах

• deferred_raiseload – Подразумевает mapped_column.deferred к True, и устанавливает параметр deferred.raiseload. … см. также:: Использование рейсмусования для предотвращения отложенных нагрузок на колонны

• use_existing_column – если True, попытается найти заданное имя колонки в наследуемом суперклассе (обычно в единственном наследуемом суперклассе), и если оно присутствует, не будет создавать новую колонку, отображая колонку суперкласса так, как если бы она была опущена в этом классе. Это используется для миксинов, которые добавляют новые колонки в наследуемый суперкласс. … seealso:: ``use_existing_column``R … versionadded:: 2.0.0b4

• default – Передается непосредственно в параметр Column.default, если параметр mapped_column.insert_default отсутствует. Дополнительно, при использовании с Декларативное отображение классов данных, указывает значение по умолчанию Python, которое должно быть применено к конструктору ключевых слов внутри сгенерированного метода __init__(). Обратите внимание, что в случае генерации класса данных, когда mapped_column.insert_default отсутствует, это означает, что значение mapped_column.default используется в двух местах, как в методе __init__(), так и в параметре Column.default. Хотя это поведение может измениться в будущем выпуске, на данный момент это имеет тенденцию «работать»; значение по умолчанию None будет означать, что Column не получает генератора по умолчанию, в то время как значение по умолчанию, которое ссылается на не``None`` значение выражения Python или SQL, будет назначено перед объектом при вызове __init__(), что является тем же значением, которое конструкция Core Insert будет использовать в любом случае, что приводит к тому же конечному результату.

• insert_default – Передается непосредственно в параметр Column.default; заменяет значение mapped_column.default, если присутствует, однако mapped_column.default всегда будет применяться к конструктору по умолчанию для отображения классов данных.

• sort_order – Целое число, указывающее, как этот сопоставленный столбец должен быть отсортирован по сравнению с другими, когда ORM создает Table. Среди сопоставленных столбцов, имеющих одинаковое значение, используется порядок по умолчанию, располагая сначала сопоставленные столбцы, определенные в главном классе, затем в суперклассах. Значение по умолчанию равно 0. Сортировка идет по возрастанию. … versionadded:: 2.0.4

• active_history=False – Когда True, указывает, что «предыдущее» значение для скалярного атрибута должно быть загружено при замене, если оно еще не загружено. Обычно логика отслеживания истории для простых скалярных значений, не являющихся первичными ключами, должна знать о «новом» значении только для того, чтобы выполнить очистку. Этот флаг доступен для приложений, использующих get_history() или Session.is_modified(), которым также необходимо знать «предыдущее» значение атрибута. … версия добавлена:: 2.0.10

• init – Специфично для Декларативное отображение классов данных, указывает, должен ли сопоставленный атрибут быть частью метода __init__(), создаваемого процессом класса данных.

• repr – Специфично для Декларативное отображение классов данных, указывает, должен ли сопоставленный атрибут быть частью метода __repr__(), создаваемого процессом класса данных.

• default_factory – Специфично для Декларативное отображение классов данных, определяет функцию генерации значения по умолчанию, которая будет иметь место как часть метода __init__(), генерируемого процессом dataclass.

• compare – Специфично для Декларативное отображение классов данных, указывает, следует ли включать это поле в операции сравнения при генерации методов __eq__() и __ne__() для сопоставленного класса. … versionadded:: 2.0.0b4

• kw_only – Специфично для Декларативное отображение классов данных, указывает, должно ли это поле быть помечено как предназначенное только для ключевого слова при генерации __init__().

• **kw – Все остальные аргументы ключевых слов передаются в конструктор для Column.

class sqlalchemy.orm.declared_attr¶

Пометить метод уровня класса как представляющий определение сопоставленного свойства или директивы Declarative.

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

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

Пример:

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. Это никогда не требуется с точки зрения времени выполнения, однако может потребоваться для поддержки инструментов типизации PEP 484, которые иначе не распознают декорированную функцию как имеющую поведение на уровне класса для параметра cls:

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 can accommodate a function decorated with @classmethod to help with PEP 484 integration where needed.

См.также

Составление сопоставленных иерархий с помощью миксинов - документация по декларативному миксину с описанием шаблонов использования declared_attr.

Members

cascading, directive

Классная подпись

класс sqlalchemy.orm.declared_attr (sqlalchemy.orm.base._MappedAttribute, sqlalchemy.orm.decl_api._declared_attr_common)

attribute sqlalchemy.orm.declared_attr.cascading¶

Пометьте declared_attr как каскадный.

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

Предупреждение

Модификатор declared_attr.cascading имеет несколько ограничений:

• Флаг только применяется к использованию declared_attr на декларативных классах-миксинах и классах __abstract__; в настоящее время он не имеет эффекта при использовании непосредственно на сопоставленном классе.

• Флаг только применяется к атрибутам с обычным именем, например, не к специальным атрибутам с подчеркиванием, таким как __tablename__. На эти атрибуты он не имеет **эффекта.

• В настоящее время флаг не позволяет дальнейшие переопределения вниз по иерархии классов; если подкласс пытается переопределить атрибут, выдается предупреждение и переопределяемый атрибут пропускается. Это ограничение, которое, как мы надеемся, когда-нибудь будет устранено.

Ниже, как MyClass, так и MySubClass будут иметь отдельные id установленные объекты Column:

class HasIdMixin:
    @declared_attr.cascading
    def id(cls):
        if has_inherited_table(cls):
            return Column(ForeignKey("myclass.id"), primary_key=True)
        else:
            return Column(Integer, primary_key=True)


class MyClass(HasIdMixin, Base):
    __tablename__ = "myclass"
    # ...


class MySubClass(MyClass):
    """ """

    # ...

При такой конфигурации MySubClass будет ссылаться как на свой столбец id, так и на столбец MyClass под атрибутом с именем some_id.

См.также

Декларативное наследование

Использование _orm.declared_attr() для создания столбцов наследования для конкретной таблицы

attribute sqlalchemy.orm.declared_attr.directive¶

Пометьте declared_attr как украшающую декларативную директиву, такую как __tablename__ или __mapper_args__.

Цель declared_attr.directive - строго поддерживать средства типизации PEP 484, позволяя декорированной функции иметь возвращаемый тип, который не использует общий класс Mapped, как это обычно бывает, когда declared_attr используется для столбцов и отображаемых свойств. Во время выполнения функция declared_attr.directive возвращает класс declared_attr без изменений.

Например:

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

Добавлено в версии 2.0.

См.также

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

declared_attr

class sqlalchemy.orm.DeclarativeBase¶

Базовый класс, используемый для декларативных определений классов.

DeclarativeBase позволяет создавать новые декларативные базы таким образом, чтобы они были совместимы с программами проверки типов:

from sqlalchemy.orm import DeclarativeBase

class Base(DeclarativeBase):
    pass

Приведенный выше класс Base теперь можно использовать в качестве основы для новых декларативных отображений. Суперкласс использует метод __init_subclass__() для установки новых классов, а метаклассы не используются.

При первом использовании класс DeclarativeBase инстанцирует новый registry для использования с базой, если таковая не была предоставлена явно. Класс DeclarativeBase поддерживает атрибуты уровня класса, которые действуют как параметры для построения этого регистра; например, для указания конкретной коллекции MetaData, а также конкретного значения для registry.type_annotation_map:

from typing_extensions import Annotated

from sqlalchemy import BigInteger
from sqlalchemy import MetaData
from sqlalchemy import String
from sqlalchemy.orm import DeclarativeBase

bigint = Annotated[int, "bigint"]
my_metadata = MetaData()

class Base(DeclarativeBase):
    metadata = my_metadata
    type_annotation_map = {
        str: String().with_variant(String(255), "mysql", "mariadb"),
        bigint: BigInteger()
    }

Атрибуты уровня класса, которые могут быть указаны, включают:

Параметры:

• metadata – необязательная коллекция MetaData. Если registry строится автоматически, эта коллекция MetaData будет использована для ее построения. В противном случае локальная коллекция MetaData будет заменять коллекцию, используемую существующей коллекцией registry, переданной с помощью параметра DeclarativeBase.registry.

• type_annotation_map – необязательная карта аннотаций типов, которая будет передана в registry как registry.type_annotation_map.

• registry – поставлять уже существующий registry напрямую.

Добавлено в версии 2.0: Добавлено DeclarativeBase, чтобы декларативные базовые классы могли быть построены таким образом, чтобы их также распознавали программы проверки типов PEP 484. В результате, DeclarativeBase и другие API, ориентированные на подклассы, должны рассматриваться как замена предыдущих API «класс, возвращаемый функцией», а именно declarative_base() и registry.generate_base(), где возвращаемый базовый класс не может быть распознан средствами проверки типов без использования плагинов.

__init__ behavior

В обычном классе Python самым базовым методом __init__() в иерархии класса является object.__init__(), который не принимает никаких аргументов. Однако, когда подкласс DeclarativeBase объявляется впервые, класс получает метод __init__(), который ссылается на функцию конструктора registry.constructor, если метод __init__() уже отсутствует; это обычный декларативный конструктор, который будет назначать аргументы ключевых слов в качестве атрибутов экземпляра, предполагая, что эти атрибуты установлены на уровне класса (т.е. отображены или связаны с дескриптором). К этому конструктору никогда не обращается сопоставленный класс без явного вызова через super(), поскольку сопоставленные классы сами наделяются методом __init__(), который непосредственно вызывает registry.constructor, поэтому в стандартном случае работает независимо от того, что делает самый базовый метод __init__().

Изменено в версии 2.0.1: DeclarativeBase имеет конструктор по умолчанию, который по умолчанию ссылается на registry.constructor, так что вызовы super().__init__() могут обращаться к этому конструктору. Ранее, из-за ошибки в реализации, этот конструктор по умолчанию отсутствовал, и вызов super().__init__() вызывал object.__init__().

Подкласс DeclarativeBase может также объявить явный метод __init__(), который заменит использование функции registry.constructor на этом уровне:

class Base(DeclarativeBase):
    def __init__(self, id=None):
        self.id = id

Сопоставленные классы по-прежнему не будут вызывать этот конструктор неявно; он остается доступным только при вызове super().__init__():

class MyClass(Base):
    def __init__(self, id=None, name=None):
        self.name = name
        super().__init__(id=id)

Обратите внимание, что это поведение отличается от поведения функций, подобных унаследованной declarative_base(); база, созданная этими функциями, всегда будет устанавливать registry.constructor для __init__().

Members

__mapper__, __mapper_args__, __table__, __table_args__, __tablename__, metadata, registry

Классная подпись

класс sqlalchemy.orm.DeclarativeBase (sqlalchemy.inspection.Inspectable)

attribute sqlalchemy.orm.DeclarativeBase.__mapper__: ClassVar[Mapper[Any]]¶

Объект Mapper, с которым сопоставлен конкретный класс.

Также может быть получен с помощью inspect(), например, inspect(klass).

attribute sqlalchemy.orm.DeclarativeBase.__mapper_args__: Any¶

Словарь аргументов, которые будут переданы конструктору Mapper.

См.также

Опции конфигурации картографа с помощью декларативного метода

attribute sqlalchemy.orm.DeclarativeBase.__table__: ClassVar[FromClause]¶

FromClause, с которым сопоставлен конкретный подкласс.

Обычно это экземпляр Table, но может ссылаться и на другие виды FromClause, например Subquery, в зависимости от того, как отображается класс.

См.также

Доступ к таблице и метаданным

attribute sqlalchemy.orm.DeclarativeBase.__table_args__: Any¶

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

См.также

Декларативная конфигурация таблиц

attribute sqlalchemy.orm.DeclarativeBase.__tablename__: Any¶

Строковое имя для присвоения сгенерированному объекту Table, если оно не указано непосредственно через DeclarativeBase.__table__.

См.также

Декларативная таблица с mapped_column()

attribute sqlalchemy.orm.DeclarativeBase.metadata: ClassVar[MetaData]¶

Ссылается на коллекцию MetaData, которая будет использоваться для новых объектов Table.

См.также

Доступ к таблице и метаданным

attribute sqlalchemy.orm.DeclarativeBase.registry: ClassVar[registry]¶

Относится к используемому registry, с которым будут связаны новые объекты Mapper.

class sqlalchemy.orm.DeclarativeBaseNoMeta¶

Аналогично DeclarativeBase, но не использует метакласс для перехвата новых атрибутов.

База DeclarativeBaseNoMeta может быть использована, когда желательно использовать пользовательские метаклассы.

Добавлено в версии 2.0.

Members

__mapper__, __mapper_args__, __table__, __table_args__, __tablename__, metadata, registry

Классная подпись

класс sqlalchemy.orm.DeclarativeBaseNoMeta (sqlalchemy.inspection.Inspectable)

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.__mapper__: ClassVar[Mapper[Any]]¶

Объект Mapper, с которым сопоставлен конкретный класс.

Также может быть получен с помощью inspect(), например, inspect(klass).

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.__mapper_args__: Any¶

Словарь аргументов, которые будут переданы конструктору Mapper.

См.также

Опции конфигурации картографа с помощью декларативного метода

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.__table__: Optional[FromClause]¶

FromClause, с которым сопоставлен конкретный подкласс.

Обычно это экземпляр Table, но может ссылаться и на другие виды FromClause, например Subquery, в зависимости от того, как отображается класс.

См.также

Доступ к таблице и метаданным

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.__table_args__: Any¶

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

См.также

Декларативная конфигурация таблиц

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.__tablename__: Any¶

Строковое имя для присвоения сгенерированному объекту Table, если оно не указано непосредственно через DeclarativeBase.__table__.

См.также

Декларативная таблица с mapped_column()

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.metadata: ClassVar[MetaData]¶

Ссылается на коллекцию MetaData, которая будет использоваться для новых объектов Table.

См.также

Доступ к таблице и метаданным

attribute sqlalchemy.orm.DeclarativeBaseNoMeta.registry: ClassVar[registry]¶

Относится к используемому registry, с которым будут связаны новые объекты Mapper.

function sqlalchemy.orm.has_inherited_table(cls: Type[_O]) → bool¶

При задании класса возвращает True, если любой из классов, от которых он наследуется, имеет сопоставленную таблицу, в противном случае возвращает False.

Это используется в декларативных миксинах для создания атрибутов, которые ведут себя по-разному для базового класса и подкласса в иерархии наследования.

См.также

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

function sqlalchemy.orm.synonym_for(name: str, map_column: bool = False) → Callable[[Callable[[...], Any]], Synonym[Any]]¶

Декоратор, создающий атрибут synonym() в сочетании с дескриптором Python.

Украшаемая функция передается в synonym() в качестве параметра synonym.descriptor:

class MyClass(Base):
    __tablename__ = 'my_table'

    id = Column(Integer, primary_key=True)
    _job_status = Column("job_status", String(50))

    @synonym_for("job_status")
    @property
    def job_status(self):
        return "Status: %s" % self._job_status

Функция hybrid properties в SQLAlchemy обычно предпочитается вместо синонимов, которые являются более унаследованной функцией.

См.также

Синонимы - Обзор синонимов

synonym() - функция уровня картографа

Использование дескрипторов и гибридов - Расширение Hybrid Attribute обеспечивает обновленный подход к расширению поведения атрибутов более гибко, чем это может быть достигнуто с помощью синонимов.

function sqlalchemy.orm.object_mapper(instance: _T) → Mapper[_T]¶

Учитывая объект, возвращает первичный Mapper, связанный с экземпляром объекта.

Вызывает sqlalchemy.orm.exc.UnmappedInstanceError, если сопоставление не настроено.

Эта функция доступна через систему контроля следующим образом:

inspect(instance).mapper

Использование системы проверки вызовет ошибку sqlalchemy.exc.NoInspectionAvailable, если экземпляр не является частью отображения.

function sqlalchemy.orm.class_mapper(class_: Type[_O], configure: bool = True) → Mapper[_O]¶

Учитывая класс, возвращает первичный Mapper, связанный с ключом.

Вызывает UnmappedClassError, если для данного класса не настроено отображение, или ArgumentError, если передан объект, не относящийся к классу.

Эквивалентная функциональность доступна через функцию inspect() в виде:

inspect(some_mapped_class)

Использование системы проверки приведет к появлению sqlalchemy.exc.NoInspectionAvailable, если класс не сопоставлен.

function sqlalchemy.orm.configure_mappers()¶

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

Шаг configure используется для согласования и инициализации связей relationship() между сопоставленными классами, а также для вызова событий конфигурации, таких как MapperEvents.before_configured() и MapperEvents.after_configured(), которые могут использоваться ORM-расширениями или пользовательскими крючками расширения.

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

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

Изменено в версии 1.4: Начиная с SQLAlchemy 1.4.0b2, эта функция работает на основе каждого registry, находя все присутствующие registry объекты и вызывая метод registry.configure() для каждого из них. Метод registry.configure() может быть предпочтительным, чтобы ограничить конфигурацию отобразителей теми, которые локальны для определенного registry и/или декларативного базового класса.

Точки, в которых вызывается автоматическая конфигурация, включают инстанцирование сопоставленного класса в экземпляр, а также выполнение ORM-запросов с использованием Session.query() или Session.execute() с оператором, поддерживающим ORM.

Процесс mapper configure, вызываемый configure_mappers() или из registry.configure(), предоставляет несколько крючков событий, которые могут быть использованы для дополнения шага конфигурации mapper. К этим крючкам относятся:

• MapperEvents.before_configured() - вызывается один раз перед тем, как configure_mappers() или registry.configure() выполнят какую-либо работу; это может быть использовано для установки дополнительных опций, свойств или связанных отображений перед выполнением операции.

• MapperEvents.mapper_configured() - вызывается по мере конфигурирования каждого отдельного Mapper в процессе; включает все состояние картографа, за исключением обратных ссылок, установленных другими картографами, которые еще должны быть сконфигурированы.

• MapperEvents.after_configured() - вызывается один раз после завершения configure_mappers() или registry.configure(); на этом этапе все объекты Mapper, попадающие в область действия операции конфигурирования, будут полностью сконфигурированы. Обратите внимание, что вызывающее приложение может иметь другие отображения, которые еще не были созданы, например, если они находятся в еще не импортированных модулях, а также может иметь отображения, которые еще должны быть сконфигурированы, если они находятся в других коллекциях registry, не входящих в текущую область конфигурации.

function sqlalchemy.orm.clear_mappers() → None¶

Удалить всех картографов из всех классов.

Изменено в версии 1.4: Теперь эта функция находит все объекты registry и вызывает метод registry.dispose() каждого из них.

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

clear_mappers() не предназначен для обычного использования, так как для него нет буквально никакого применения за пределами очень специфических сценариев тестирования. Обычно мапперы являются постоянными структурными компонентами определяемых пользователем классов и никогда не удаляются независимо от своего класса. Если сам отображаемый класс собирается в мусор, его отображатель также автоматически утилизируется. Таким образом, clear_mappers() предназначен только для использования в тестовых наборах, которые повторно используют одни и те же классы с различными отображениями, что само по себе является крайне редким случаем использования - единственным таким случаем является собственный тестовый набор SQLAlchemy и, возможно, тестовые наборы других библиотек расширения ORM, которые собираются тестировать различные комбинации построения отображений на фиксированном наборе классов.

function sqlalchemy.orm.util.identity_key(class_: Optional[Type[_T]] = None, ident: Union[Any, Tuple[Any, ...]] = None, *, instance: Optional[_T] = None, row: Optional[Union[Row[Any], RowMapping]] = None, identity_token: Optional[Any] = None) → _IdentityKeyType[_T]¶

Генерировать кортежи «identity key», которые используются в качестве ключей в словаре Session.identity_map.

Эта функция имеет несколько стилей вызова:

• identity_key(class, ident, identity_token=token)

  Эта форма получает в качестве аргумента сопоставленный класс и скаляр или кортеж первичного ключа.

  Например:

  >>> identity_key(MyClass, (1, 2))
  (<class '__main__.MyClass'>, (1, 2), None)

  класс param:

  сопоставленный класс (должен быть позиционным аргументом)

  param ident:

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

  param identity_token:

  необязательный маркер идентификации

  Добавлено в версии 1.2: добавлен identity_token

• identity_key(instance=instance)

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

  Например:

  >>> instance = MyClass(1, 2)
  >>> identity_key(instance=instance)
  (<class '__main__.MyClass'>, (1, 2), None)

  В этой форме данный экземпляр в конечном итоге запускается через Mapper.identity_key_from_instance(), что приведет к выполнению проверки базы данных для соответствующей строки, если объект просрочен.

  параметр экземпляр:

  экземпляр объекта (должен быть указан как ключевое слово arg)

• identity_key(class, row=row, identity_token=token)

  Эта форма аналогична форме класс/кортеж, за исключением того, что передается строка результата базы данных в виде объекта Row или RowMapping.

  Например:

  >>> row = engine.execute(\
      text("select * from table where a=1 and b=2")\
      ).first()
  >>> identity_key(MyClass, row=row)
  (<class '__main__.MyClass'>, (1, 2), None)

  класс param:

  сопоставленный класс (должен быть позиционным аргументом)

  строка param:

  Row строка, возвращаемая CursorResult (должна быть задана как ключевое слово arg)

  param identity_token:

  необязательный маркер идентификации

  Добавлено в версии 1.2: добавлен identity_token

function sqlalchemy.orm.polymorphic_union(table_map, typecolname, aliasname='p_union', cast_nulls=True)¶

Создайте оператор UNION, используемый полиморфным отображателем.

Смотрите Наследование конкретной таблицы для примера того, как это используется.

Параметры:

• table_map – отображение полиморфных тождеств на объекты Table.

• typecolname – строковое имя столбца «дискриминатора», который будет получен из запроса, создавая полиморфную идентичность для каждой строки. Если None, полиморфный дискриминатор не создается.

• aliasname – имя создаваемой конструкции alias().

• cast_nulls – если True, то в CAST будут передаваться несуществующие столбцы, которые представляются как помеченные NULL. Это унаследованное поведение, которое является проблематичным для некоторых бэкендов, таких как Oracle - в этом случае можно установить значение False.

function sqlalchemy.orm.orm_insert_sentinel(name: Optional[str] = None, type_: Optional[_TypeEngineArgument[Any]] = None, *, default: Optional[Any] = None, omit_from_statements: bool = True) → MappedColumn[Any]¶

Предоставляет суррогат mapped_column(), который генерирует так называемый столбец sentinel, позволяя осуществлять эффективные массовые вставки с детерминированной сортировкой RETURNING для таблиц, которые иначе не имеют соответствующих конфигураций первичного ключа.

Использование orm_insert_sentinel() аналогично использованию конструкции insert_sentinel() внутри конструкции Core Table.

Рекомендации по добавлению этой конструкции в декларативный сопоставленный класс такие же, как и для конструкции insert_sentinel(); в самой таблице базы данных также должен присутствовать столбец с таким именем.

О том, как используется этот объект, см. раздел Настройка столбцов часовых в составе раздела Поведение «Вставка многих значений» для операторов INSERT.

См.также

insert_sentinel()

Поведение «Вставка многих значений» для операторов INSERT

Настройка столбцов часовых

Добавлено в версии 2.0.10.

function sqlalchemy.orm.reconstructor(fn)¶

Украсьте метод как крючок „реконструктора“.

Назначает один метод в качестве «реконструктора», __init__-подобного метода, который будет вызываться ORM после того, как экземпляр будет загружен из базы данных или иным образом восстановлен.

Совет

Декоратор reconstructor() использует крючок события InstanceEvents.load(), который можно использовать напрямую.

Реконструктор будет вызван без аргументов. Скалярные (не коллекционные) атрибуты экземпляра, сопоставленные с базой данных, будут доступны для использования в функции. Коллекции, загружаемые с нетерпением, как правило, еще не доступны и обычно содержат только первый элемент. Изменения состояния ORM, внесенные в объекты на этом этапе, не будут записаны для следующей операции flush(), поэтому деятельность внутри реконструктора должна быть консервативной.

См.также

InstanceEvents.load()

class sqlalchemy.orm.Mapper¶

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

Объект Mapper инстанцируется с использованием методов отображения, присутствующих на объекте registry. Для получения информации о создании новых объектов Mapper смотрите раздел Обзор сопоставленных классов ORM.

Members

__init__(), add_properties(), add_property(), all_orm_descriptors, attrs, base_mapper, c, cascade_iterator(), class_, class_manager, column_attrs, columns, common_parent(), composites, concrete, configured, entity, get_property(), get_property_by_column(), identity_key_from_instance(), identity_key_from_primary_key(), identity_key_from_row(), inherits, is_mapper, is_sibling(), isa(), iterate_properties, local_table, mapped_table, mapper, non_primary, persist_selectable, polymorphic_identity, polymorphic_iterator(), polymorphic_map, polymorphic_on, primary_key, primary_key_from_instance(), primary_mapper(), relationships, selectable, self_and_descendants, single, synonyms, tables, validators, with_polymorphic_mappers

Классная подпись

class sqlalchemy.orm.Mapper (sqlalchemy.orm.ORMFromClauseRole, sqlalchemy.orm.ORMEntityColumnsClauseRole, sqlalchemy.sql.cache_key.MemoizedHasCacheKey, sqlalchemy.orm.base.InspectionAttr, sqlalchemy.log.Identified, sqlalchemy.inspection.Inspectable, sqlalchemy.event.registry.EventTarget, typing.Generic)

method sqlalchemy.orm.Mapper.__init__(class_: Type[_O], local_table: Optional[FromClause] = None, properties: Optional[Mapping[str, MapperProperty[Any]]] = None, primary_key: Optional[Iterable[_ORMColumnExprArgument[Any]]] = None, non_primary: bool = False, inherits: Optional[Union[Mapper[Any], Type[Any]]] = None, inherit_condition: Optional[_ColumnExpressionArgument[bool]] = None, inherit_foreign_keys: Optional[Sequence[_ORMColumnExprArgument[Any]]] = None, always_refresh: bool = False, version_id_col: Optional[_ORMColumnExprArgument[Any]] = None, version_id_generator: Optional[Union[Literal[False], Callable[[Any], Any]]] = None, polymorphic_on: Optional[Union[_ORMColumnExprArgument[Any], str, MapperProperty[Any]]] = None, _polymorphic_map: Optional[Dict[Any, Mapper[Any]]] = None, polymorphic_identity: Optional[Any] = None, concrete: bool = False, with_polymorphic: Optional[_WithPolymorphicArg] = None, polymorphic_abstract: bool = False, polymorphic_load: Optional[Literal['selectin', 'inline']] = None, allow_partial_pks: bool = True, batch: bool = True, column_prefix: Optional[str] = None, include_properties: Optional[Sequence[str]] = None, exclude_properties: Optional[Sequence[str]] = None, passive_updates: bool = True, passive_deletes: bool = False, confirm_deleted_rows: bool = True, eager_defaults: Literal[True, False, 'auto'] = 'auto', legacy_is_orphan: bool = False, _compiled_cache_size: int = 100)¶

Прямой конструктор для нового объекта Mapper.

Конструктор Mapper не вызывается напрямую, а обычно вызывается через использование объекта registry через стили отображения Declarative или Imperative.

Изменено в версии 2.0: Функция публичного отображения mapper() удалена; для классической конфигурации отображения используйте метод registry.map_imperatively().

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

Параметры:

• class_ – Класс, который должен быть отображен. При использовании Declarative этот аргумент автоматически передается как сам объявленный класс.

• local_table – Table или другой FromClause (т.е. выбираемый), с которым сопоставляется класс. Может быть None, если этот маппер наследуется от другого маппера, использующего наследование одной таблицы. При использовании Declarative этот аргумент передается расширением автоматически, на основе того, что настроено через атрибут DeclarativeBase.__table__ или через Table, созданный в результате присутствия атрибута DeclarativeBase.__tablename__.

• polymorphic_abstract – Указывает, что этот класс будет отображен в полиморфной иерархии, но не будет непосредственно инстанцирован. Класс отображается нормально, за исключением того, что для него не требуется Mapper.polymorphic_identity в иерархии наследования. Однако класс должен быть частью полиморфной схемы наследования, которая использует Mapper.polymorphic_on в основе. … версия добавлена:: 2.0 .. seealso:: Построение более глубоких иерархий с помощью polymorphic_abstract

• always_refresh – Если True, все операции запроса для этого сопоставленного класса будут перезаписывать все данные в экземплярах объектов, которые уже существуют в сессии, стирая любые изменения в памяти той информацией, которая была загружена из базы данных. Использовать этот флаг крайне не рекомендуется; в качестве альтернативы смотрите метод Query.populate_existing().

• allow_partial_pks – По умолчанию имеет значение True. Указывает, что составной первичный ключ с некоторыми значениями NULL должен рассматриваться как возможно существующий в базе данных. Это влияет на то, будет ли сопоставитель присваивать входящий ряд существующему идентификатору, а также на то, будет ли Session.merge() сначала проверять базу данных на наличие определенного значения первичного ключа. Неполный первичный ключ» может возникнуть, например, при сопоставлении с OUTER JOIN.

• batch – По умолчанию имеет значение True, что указывает на то, что операции сохранения нескольких экземпляров могут быть объединены для повышения эффективности. Значение False означает, что экземпляр будет полностью сохранен перед сохранением следующего экземпляра. Это используется в крайне редких случаях, когда требуется вызов слушателя MapperEvents между отдельными операциями сохранения строк.

• column_prefix – Строка, которая будет добавлена к имени сопоставленного атрибута, когда объекты Column автоматически назначаются в качестве атрибутов сопоставленного класса. Не влияет на объекты Column, которые отображаются явно в словаре Mapper.properties. Этот параметр обычно полезен в императивных отображениях, которые сохраняют объект Table отдельно. Ниже, в предположении, что объект user_table Table имеет колонки с именами user_id, user_name и password:: class User(Base): __table__ = user_table __mapper_args__ = {„column_prefix“:“_“} Приведенное выше отображение назначит столбцы user_id, user_name и password атрибутам _user_id, _user_name и _password в отображенном классе User. Параметр Mapper.column_prefix в современном использовании встречается редко. Для работы с отраженными таблицами более гибким подходом к автоматизации схемы именования является перехват объектов Column по мере их отражения; см. раздел Автоматизация схем именования столбцов из отраженных таблиц для заметок по этой схеме использования.

• concrete – Если True, указывает, что этот отображатель должен использовать наследование конкретных таблиц со своим родительским отображателем. Пример смотрите в разделе Наследование конкретной таблицы.

• confirm_deleted_rows – по умолчанию равен True; когда происходит DELETE еще одной строки, основанной на определенных первичных ключах, выдается предупреждение, если количество совпавших строк не равно ожидаемому количеству строк. Этот параметр может быть установлен в False для обработки случая, когда правила базы данных ON DELETE CASCADE могут удалять некоторые из этих строк автоматически. Предупреждение может быть заменено на исключение в будущем выпуске.

• eager_defaults – если True, ORM будет немедленно извлекать значение генерируемых сервером значений по умолчанию после INSERT или UPDATE, а не оставлять их как просроченные для извлечения при следующем доступе. Это может быть использовано в схемах событий, где значения, сгенерированные сервером, нужны непосредственно перед завершением флеша. Выборка значений происходит либо путем использования RETURNING в строке с оператором INSERT или UPDATE, либо путем добавления дополнительного оператора SELECT после INSERT или UPDATE, если бэкенд не поддерживает RETURNING. Использование RETURNING является чрезвычайно производительным, особенно для операторов INSERT, где SQLAlchemy может использовать преимущества insertmanyvalues, тогда как использование дополнительного SELECT является относительно низкопроизводительным, добавляя дополнительные обходы SQL, которые были бы излишними, если бы эти новые атрибуты не были доступны в любом случае. По этой причине Mapper.eager_defaults по умолчанию имеет строковое значение "auto", которое указывает, что серверные значения по умолчанию для INSERT должны быть получены с помощью RETURNING, если база данных поддерживает это и если используемый диалект поддерживает «insertmanyreturning» для оператора INSERT. Если опорная база данных не поддерживает RETURNING или «insertmanyreturning» недоступен, серверные значения по умолчанию не будут найдены. … versionchanged:: 2.0.0rc1 добавлена опция «auto» для Mapper.eager_defaults .. seealso:: Получение генерируемых сервером значений по умолчанию … versionchanged:: 2.0.0 RETURNING теперь работает с несколькими строками, вставляемыми одновременно с помощью функции insertmanyvalues, что, помимо прочего, позволяет функции Mapper.eager_defaults быть очень производительной на поддерживающих бэкендах.

• exclude_properties – Список или набор строковых имен столбцов, которые должны быть исключены из отображения. … seealso:: Сопоставление подмножества столбцов таблицы

• include_properties – Список или набор строковых имен столбцов для отображения. … см. также:: Сопоставление подмножества столбцов таблицы

• inherits – Сопоставленный класс или соответствующий Mapper одного, указывающий на суперкласс, от которого этот Mapper должен наследоваться. Сопоставленный класс должен быть подклассом класса другого сопоставителя. При использовании Declarative этот аргумент передается автоматически в результате естественной иерархии объявленных классов. … seealso:: Отображение иерархий наследования классов

• inherit_condition – Для наследования объединенных таблиц - SQL-выражение, определяющее способ объединения двух таблиц; по умолчанию используется естественное объединение двух таблиц.

• inherit_foreign_keys – Когда используется inherit_condition и присутствующие столбцы не имеют конфигурации ForeignKey, этот параметр может быть использован для указания того, какие столбцы являются «чужими». В большинстве случаев можно оставить значение None.

• legacy_is_orphan – Булево, по умолчанию False. Когда True, указывает, что «legacy» orphan consideration должен применяться к объектам, отображаемым этим отображателем, что означает, что отложенный (то есть, не постоянный) объект автоудаляется из владеющего Session только тогда, когда он де-ассоциирован от всех родителей, которые указывают delete-orphan каскад к этому отображателю. Новое поведение по умолчанию заключается в том, что объект автоматически удаляется, когда он де-ассоциирован с любым из своих родителей, которые указывают каскад delete-orphan. Такое поведение более соответствует поведению постоянного объекта и позволяет обеспечить согласованность поведения в большем количестве сценариев, независимо от того, был ли объект-сирота уже удален или нет. Более подробную информацию об этом изменении смотрите в примечании к изменению и примере Рассмотрение «сиротского» объекта стало более агрессивным.

• non_primary – Укажите, что этот Mapper является дополнением к «основному» мапперу, то есть используемому для персистентности. Созданный здесь Mapper может быть использован для специального отображения класса на альтернативный selectable, только для загрузки. … deprecated:: 1.3 Параметр mapper.non_primary является устаревшим и будет удален в одном из будущих выпусков. Для функциональности не первичных отображателей теперь лучше использовать конструкцию AliasedClass, которая также может быть использована как цель relationship() в 1.3. … seealso:: Взаимосвязь с классом Aliased - новый шаблон, который устраняет необходимость в использовании флага Mapper.non_primary.

• passive_deletes – Указывает поведение DELETE столбцов внешнего ключа при удалении наследуемой сущности объединенной таблицы. Значение по умолчанию False для базового картографа; для наследующего картографа значение по умолчанию False, если только значение не установлено True на картографе суперкласса. Когда True, предполагается, что ON DELETE CASCADE настроен на отношения внешних ключей, которые связывают таблицу этого картографа с таблицей его суперкласса, так что когда рабочая единица пытается удалить сущность, ей нужно выпустить оператор DELETE только для таблицы суперкласса, а не для этой таблицы. Когда False, оператор DELETE выдается для этой таблицы отображения отдельно. Если атрибуты первичного ключа, локальные для этой таблицы, выгружены, то для проверки этих атрибутов необходимо выполнить SELECT; обратите внимание, что столбцы первичного ключа объединенного подкласса таблицы не являются частью «первичного ключа» объекта в целом. Обратите внимание, что значение True всегда навязывается отобразителям подклассов; то есть, невозможно для суперкласса указать passive_deletes без того, чтобы это не вступило в силу для всех отобразителей подклассов. … см. также:: Использование каскада внешних ключей ON DELETE с отношениями ORM - описание аналогичной возможности, используемой в relationship() mapper.passive_updates - поддержка ON UPDATE CASCADE для отобразителей наследования объединенных таблиц

• passive_updates – Указывает поведение UPDATE столбцов внешнего ключа при изменении столбца первичного ключа в отображении наследования объединенных таблиц. По умолчанию имеет значение True. Когда True, предполагается, что ON UPDATE CASCADE настроен на внешний ключ в базе данных, и что база данных будет обрабатывать распространение UPDATE от исходного столбца к зависимым столбцам в строках объединенной таблицы. При значении False предполагается, что база данных не обеспечивает ссылочную целостность и не будет выпускать собственную операцию CASCADE для обновления. Процесс единицы работы будет выдавать оператор UPDATE для зависимых столбцов во время изменения первичного ключа. … см. также:: Изменяемые первичные ключи / Каскады обновлений - описание аналогичной функции, используемой в relationship() mapper.passive_deletes - поддержка ON DELETE CASCADE для сопоставителей наследования объединенных таблиц

• polymorphic_load – Определяет поведение «полиморфной загрузки» для подкласса в иерархии наследования (только объединенное и однотабличное наследование). Допустимыми значениями являются: * «„inline“» - указывает, что этот класс должен быть частью мапперов «with_polymorphic», например, его колонки будут включены в запрос SELECT к базе. * «„selectin“» - указывает, что при загрузке экземпляров этого класса будет выдан дополнительный SELECT для получения столбцов, специфичных для этого подкласса. SELECT использует IN для одновременной выборки нескольких подклассов. … versionadded:: 1.2 .. seealso:: Настройка функции with_polymorphic() на картографах Использование функции selectin_polymorphic()

• polymorphic_on – Указывает столбец, атрибут или выражение SQL, используемое для определения целевого класса для входящей строки, если присутствуют наследуемые классы. Может быть указано как строковое имя атрибута или как SQL-выражение, например Column или в декларативном отображении объект mapped_column(). Обычно ожидается, что SQL-выражение соответствует столбцу в самом базовом отображении Table:: class Employee(Base): __tablename__ = „employee“ id: Mapped[int] = mapped_column(primary_key=True) discriminator: Mapped[str] = mapped_column(String(50)) __mapper_args__ = { «polymorphic_on»:discriminator, «polymorphic_identity»: «employee» } Он также может быть указан как выражение SQL, как в этом примере, где мы используем конструкцию case() для обеспечения условного подхода:: class Employee(Base): __tablename__ = „employee“ id: Mapped[int] = mapped_column(primary_key=True) discriminator: Mapped[str] = mapped_column(String(50)) __mapper_args__ = { «polymorphic_on»:case( (discriminator == «EN», «engineer»), (discriminator == «MA», «manager»), else_=»employee»), «polymorphic_identity»: «employee» } Он также может ссылаться на любой атрибут, используя его строковое имя, что особенно полезно при использовании аннотированных конфигураций столбцов:: class Employee(Base): __tablename__ = „employee“ id: Mapped[int] = mapped_column(primary_key=True) discriminator: Mapped[str] __mapper_args__ = { «polymorphic_on»: «discriminator», «polymorphic_identity»: «employee» } При установке polymorphic_on для ссылки на атрибут или выражение, которого нет в локально отображаемом Table, но значение дискриминатора должно быть сохранено в базе данных, значение дискриминатора не устанавливается автоматически на новых экземплярах; это должно быть обработано пользователем, либо вручную, либо с помощью слушателей событий. Типичный подход к созданию такого слушателя выглядит следующим образом:: from sqlalchemy import event from sqlalchemy.orm import object_mapper @event.listens_for(Employee, «init», propagate=True) def set_identity(instance, arg, **kw): mapper = object_mapper(instance) instance. discriminator = mapper.polymorphic_identity Где выше, мы присваиваем значение ``polymorphic_identity`` для сопоставленного класса атрибуту ``discriminator``, тем самым сохраняя значение в колонке ``discriminator`` в базе данных. … предупреждение:: В настоящее время **только один столбец дискриминатора может быть установлен*, обычно на самом базовом классе в иерархии. «Каскадные» полиморфные колонки пока не поддерживаются. … см. также:: Отображение иерархий наследования классов

• polymorphic_identity – Указывает значение, которое идентифицирует данный конкретный класс, возвращенный выражением столбца, на которое ссылается параметр Mapper.polymorphic_on. По мере получения строк значение, соответствующее выражению столбца Mapper.polymorphic_on, сравнивается с этим значением, указывая, какой подкласс должен быть использован для нового реконструированного объекта. … см. также:: Отображение иерархий наследования классов

• properties – Словарь, отображающий строковые имена атрибутов объектов на экземпляры MapperProperty, которые определяют поведение персистентности этого атрибута. Обратите внимание, что объекты Column, присутствующие в отображаемом Table, автоматически помещаются в экземпляры ColumnProperty при отображении, если это не переопределено. При использовании Declarative этот аргумент передается автоматически, на основе всех тех экземпляров MapperProperty, которые объявлены в объявленном теле класса. …seealso:: Словарь свойств - в Обзор сопоставленных классов ORM.

• primary_key – Список объектов Column, или, альтернативно, строковых имен атрибутов, которые ссылаются на Column, которые определяют первичный ключ, который будет использоваться в отношении выбираемого блока этого картографа. Обычно это просто первичный ключ local_table, но может быть переопределено здесь. … versionchanged:: 2.0.2 Аргументы Mapper.primary_key могут быть указаны и как имена строковых атрибутов. … seealso:: Сопоставление с явным набором столбцов первичного ключа - предыстория и пример использования

• version_id_col – Column, который будет использоваться для хранения идентификатора текущей версии строк в таблице. Это используется для обнаружения одновременных обновлений или наличия устаревших данных во флеше. Методология заключается в том, что если оператор UPDATE не соответствует последнему известному идентификатору версии, то выбрасывается исключение StaleDataError. По умолчанию столбец должен быть типа Integer, если version_id_generator не указан альтернативный генератор версий. … см. также:: Настройка счетчика версий - обсуждение подсчета версий и обоснование.

• version_id_generator – Определите, как должны генерироваться идентификаторы новых версий. По умолчанию None, что указывает на использование простой схемы подсчета целых чисел. Чтобы обеспечить пользовательскую схему версионирования, предоставьте вызываемую функцию вида:: def generate_version(version): return next_version В качестве альтернативы можно использовать функции версионирования на стороне сервера, такие как триггеры, или программные схемы версионирования вне генератора идентификаторов версий, указав значение False. Пожалуйста, смотрите Счетчики версий на стороне сервера для обсуждения важных моментов при использовании этой опции. … seealso:: Пользовательские счетчики версий / типы Счетчики версий на стороне сервера

• with_polymorphic – Кортеж в форме (<classes>, <selectable>), указывающий на стиль по умолчанию «полиморфной» загрузки, то есть, какие таблицы запрашиваются сразу. <classes> - это любой единичный или список мапперов и/или классов, указывающий на наследуемые классы, которые должны быть загружены сразу. Специальное значение '*' может быть использовано для указания того, что все нисходящие классы должны быть загружены немедленно. Второй аргумент кортежа <selectable> указывает на возможность выбора, которая будет использоваться для запроса нескольких классов. Параметр Mapper.polymorphic_load может быть предпочтительнее, чем использование Mapper.with_polymorphic в современных связках для указания полиморфных стилей загрузки для каждого подкласса. …seealso:: Настройка функции with_polymorphic() на картографах

method sqlalchemy.orm.Mapper.add_properties(dict_of_properties)¶

Добавьте заданный словарь свойств к этому мапперу, используя add_property.

method sqlalchemy.orm.Mapper.add_property(key: str, prop: Union[Column[Any], MapperProperty[Any]]) → None¶

Добавьте отдельное свойство MapperProperty к этому мапперу.

Если маппер еще не был настроен, то просто добавляет свойство в начальный словарь свойств, переданный конструктору. Если этот маппер уже был настроен, то данное свойство MapperProperty будет настроено немедленно.

attribute sqlalchemy.orm.Mapper.all_orm_descriptors¶

Пространство имен всех InspectionAttr атрибутов, связанных с сопоставленным классом.

Эти атрибуты во всех случаях Python descriptors связаны с сопоставленным классом или его суперклассами.

Это пространство имен включает атрибуты, сопоставленные с классом, а также атрибуты, объявленные модулями расширения. Оно включает любой тип дескриптора Python, который наследуется от InspectionAttr. Сюда входят QueryableAttribute, а также типы расширения, такие как hybrid_property, hybrid_method и AssociationProxy.

Чтобы отличить сопоставленные атрибуты от атрибутов расширения, атрибут InspectionAttr.extension_type будет ссылаться на константу, которая различает различные типы расширений.

Сортировка атрибутов основана на следующих правилах:

1. Итерация по классу и его суперклассам в порядке от подкласса к суперклассу (т.е. итерация по cls.__mro__)

2. Для каждого класса приведите атрибуты в том порядке, в котором они появляются в __dict__, за исключением тех, которые указаны в шаге 3 ниже. В Python 3.6 и выше этот порядок будет таким же, как и при создании класса, за исключением атрибутов, которые были добавлены приложением или маппером.

3. Если определенный ключ атрибута также находится в суперклассе __dict__, то он включается в итерацию для этого класса, а не для класса, в котором он появился впервые.

В результате вышеописанного процесса получается упорядочение, которое является детерминированным с точки зрения порядка, в котором атрибуты были присвоены классу.

Изменено в версии 1.3.19: обеспечил детерминированное упорядочивание для Mapper.all_orm_descriptors().

При работе с QueryableAttribute атрибут QueryableAttribute.property ссылается на свойство MapperProperty, что и получается при обращении к коллекции сопоставленных свойств через Mapper.attrs.

Предупреждение

Пространство имен доступа Mapper.all_orm_descriptors является экземпляром OrderedProperties. Это словареподобный объект, который включает небольшое количество именованных методов, таких как OrderedProperties.items() и OrderedProperties.values(). При динамическом доступе к атрибутам лучше использовать схему диктуемого доступа, например, mapper.all_orm_descriptors[somename], а не getattr(mapper.all_orm_descriptors, somename), чтобы избежать коллизии имен.

См.также

Mapper.attrs

attribute sqlalchemy.orm.Mapper.attrs¶

Пространство имен всех объектов MapperProperty, связанных с этим отобразителем.

Это объект, который предоставляет каждое свойство на основе его ключевого имени. Например, отображатель для класса User, который имеет атрибут User.name, предоставит mapper.attrs.name, который будет ColumnProperty, представляющим колонку name. Объект пространства имен также может быть итерирован, что даст каждый MapperProperty.

Mapper имеет несколько предварительно отфильтрованных представлений этого атрибута, которые ограничивают типы возвращаемых свойств, включая synonyms, column_attrs, relationships и composites.

Предупреждение

Пространство имен доступа Mapper.attrs является экземпляром OrderedProperties. Это словареподобный объект, который включает небольшое количество именованных методов, таких как OrderedProperties.items() и OrderedProperties.values(). При динамическом доступе к атрибутам лучше использовать схему диктуемого доступа, например, mapper.attrs[somename], а не getattr(mapper.attrs, somename), чтобы избежать коллизии имен.

См.также

Mapper.all_orm_descriptors

attribute sqlalchemy.orm.Mapper.base_mapper: Mapper[Any]¶

Самый нижний Mapper в цепочке наследования.

В сценарии без наследования этот атрибут всегда будет этим Mapper. В сценарии наследования он ссылается на Mapper, который является родительским для всех остальных объектов Mapper в цепочке наследования.

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

attribute sqlalchemy.orm.Mapper.c: ReadOnlyColumnCollection[str, Column[Any]]¶

Синоним для Mapper.columns.

method sqlalchemy.orm.Mapper.cascade_iterator(type_: str, state: InstanceState[_O], halt_on: Optional[Callable[[InstanceState[Any]], bool]] = None) → Iterator[Tuple[object, Mapper[Any], InstanceState[Any], _InstanceDict]]¶

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

Параметры:

• type_ – Имя правила каскада (т.е. "save-update", "delete" и т.д.). … Примечание:: каскад "all" здесь не принимается. Для общей функции обхода объектов смотрите Как пройтись по всем объектам, связанным с данным объектом?.

• state – Ведущий InstanceState. дочерние элементы будут обрабатываться в соответствии с отношениями, определенными для отображателя этого объекта.

Результат:

метод выдает отдельные экземпляры объектов.

См.также

Каскады

Как пройтись по всем объектам, связанным с данным объектом? - иллюстрирует общую функцию для обхода всех объектов, не полагаясь на каскады.

attribute sqlalchemy.orm.Mapper.class_: Type[_O]¶

Класс, с которым сопоставлен данный Mapper.

attribute sqlalchemy.orm.Mapper.class_manager: ClassManager[_O]¶

ClassManager, который поддерживает слушателей событий и привязанные к классу дескрипторы для данного Mapper.

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

attribute sqlalchemy.orm.Mapper.column_attrs¶

Возвращает пространство имен всех свойств ColumnProperty, поддерживаемых данным Mapper.

См.также

Mapper.attrs - пространство имен всех объектов MapperProperty.

attribute sqlalchemy.orm.Mapper.columns: ReadOnlyColumnCollection[str, Column[Any]]¶

Коллекция Column или других объектов скалярных выражений, поддерживаемых этим Mapper.

Коллекция ведет себя так же, как и атрибут c на любом объекте Table, за исключением того, что здесь присутствуют только те столбцы, которые включены в это отображение, и ключ определяется по имени атрибута, определенному в отображении, а не обязательно по атрибуту key самого Column. Кроме того, здесь также присутствуют скалярные выражения, отображаемые с помощью column_property().

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

method sqlalchemy.orm.Mapper.common_parent(other: Mapper[Any]) → bool¶

Возвращает true, если данный отображатель имеет общего наследуемого родителя с этим отображателем.

attribute sqlalchemy.orm.Mapper.composites¶

Возвращает пространство имен всех свойств Composite, поддерживаемых данным Mapper.

См.также

Mapper.attrs - пространство имен всех объектов MapperProperty.

attribute sqlalchemy.orm.Mapper.concrete: bool¶

Представляет True, если данный Mapper является конкретным отображателем наследования.

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

attribute sqlalchemy.orm.Mapper.configured: bool = False¶

Представляет True, если этот Mapper был настроен.

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

См.также

configure_mappers().

attribute sqlalchemy.orm.Mapper.entity¶

Часть API инспекции.

Возвращает self.class_.

method sqlalchemy.orm.Mapper.get_property(key: str, _configure_mappers: bool = False) → MapperProperty[Any]¶

возвращает MapperProperty, связанный с заданным ключом.

method sqlalchemy.orm.Mapper.get_property_by_column(column: ColumnElement[_T]) → MapperProperty[_T]¶

Учитывая объект Column, верните MapperProperty, который отображает этот столбец.

method sqlalchemy.orm.Mapper.identity_key_from_instance(instance: _O) → _IdentityKeyType[_O]¶

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

Если состояние экземпляра истекло, вызов этого метода приведет к проверке базы данных на предмет удаления объекта. Если строка больше не существует, выдается сообщение ObjectDeletedError.

Это значение обычно также находится в состоянии экземпляра под именем атрибута key.

method sqlalchemy.orm.Mapper.identity_key_from_primary_key(primary_key: Tuple[Any, ...], identity_token: Optional[Any] = None) → _IdentityKeyType[_O]¶

Возвращает ключ карты идентификации для использования при хранении/извлечении элемента из карты идентификации.

Параметры:

primary_key – Список значений, указывающих на идентификатор.

method sqlalchemy.orm.Mapper.identity_key_from_row(row: Optional[Union[Row[Any], RowMapping]], identity_token: Optional[Any] = None, adapter: Optional[ORMAdapter] = None) → _IdentityKeyType[_O]¶

Возвращает ключ карты идентификации для использования при хранении/извлечении элемента из карты идентификации.

Параметры:

row – Row или RowMapping, полученный из набора результатов, который выбран из столбцов первичного ключа, сопоставленных ORM. … versionchanged:: 2.0 Для аргумента «row» принимаются Row или RowMapping.

attribute sqlalchemy.orm.Mapper.inherits: Optional[Mapper[Any]]¶

Ссылается на Mapper, от которого наследуется данный Mapper, если таковой имеется.

attribute sqlalchemy.orm.Mapper.is_mapper = True¶

Часть API инспекции.

method sqlalchemy.orm.Mapper.is_sibling(other: Mapper[Any]) → bool¶

возвращает true, если другой картограф является наследственным родственником этого. общий родитель, но разные ветви

method sqlalchemy.orm.Mapper.isa(other: Mapper[Any]) → bool¶

Возвращает True, если этот отображатель наследует от данного отображателя.

attribute sqlalchemy.orm.Mapper.iterate_properties¶

возвращает итератор всех объектов MapperProperty.

attribute sqlalchemy.orm.Mapper.local_table: FromClause¶

Непосредственный FromClause, к которому относится данный Mapper.

Обычно является экземпляром Table, может быть любым FromClause.

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

См.также

Mapper.persist_selectable.

Mapper.selectable.

attribute sqlalchemy.orm.Mapper.mapped_table¶

Не рекомендуется, начиная с версии 1.3: Используйте .persist_selectable

attribute sqlalchemy.orm.Mapper.mapper¶

Часть API инспекции.

Возвращает себя.

attribute sqlalchemy.orm.Mapper.non_primary: bool¶

Представьте True, если этот Mapper является «не основным» маппером, например, маппером, который используется только для выбора строк, но не для управления персистентностью.

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

attribute sqlalchemy.orm.Mapper.persist_selectable: FromClause¶

FromClause, с которым сопоставлен данный Mapper.

Обычно является экземпляром Table, может быть любым FromClause.

Mapper.persist_selectable аналогичен Mapper.local_table, но представляет FromClause, который представляет иерархию наследуемого класса в целом в сценарии наследования.

:attr.`.Mapper.persist_selectable` также отделен от атрибута Mapper.selectable, последний может быть альтернативным подзапросом, используемым для выбора колонок. :attr.`.Mapper.persist_selectable` ориентирован на колонки, которые будут записаны при операции persist.

См.также

Mapper.selectable.

Mapper.local_table.

attribute sqlalchemy.orm.Mapper.polymorphic_identity: Optional[Any]¶

Представляет собой идентификатор, который сопоставляется с колонкой Mapper.polymorphic_on во время загрузки строки результата.

Используется только при наследовании, этот объект может быть любого типа, который сопоставим с типом колонки, представленной Mapper.polymorphic_on.

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

method sqlalchemy.orm.Mapper.polymorphic_iterator() → Iterator[Mapper[Any]]¶

Итерация по коллекции, включая этот отображатель и все потомки отображателей.

Это касается не только непосредственно наследующих отобразителей, но и всех наследующих отобразителей.

Для итерации по всей иерархии используйте mapper.base_mapper.polymorphic_iterator().

attribute sqlalchemy.orm.Mapper.polymorphic_map: Dict[Any, Mapper[Any]]¶

Отображение идентификаторов «полиморфной идентичности», сопоставленных с экземплярами Mapper, в рамках сценария наследования.

Идентификаторы могут быть любого типа, который сопоставим с типом колонки, представленной Mapper.polymorphic_on.

Наследуемая цепочка картографов будет ссылаться на один и тот же объект полиморфной карты. Этот объект используется для соотнесения входящих строк результатов с целевыми картографами.

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

attribute sqlalchemy.orm.Mapper.polymorphic_on: Optional[KeyedColumnElement[Any]]¶

Column или SQL-выражение, указанное в качестве polymorphic_on аргумента для данного Mapper, в рамках сценария наследования.

Этот атрибут обычно является экземпляром Column, но может быть и выражением, например, производным от cast().

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

attribute sqlalchemy.orm.Mapper.primary_key: Tuple[Column[Any], ...]¶

Итерабельность, содержащая коллекцию объектов Column, которые составляют «первичный ключ» сопоставленной таблицы, с точки зрения данного Mapper.

Этот список находится против выбираемого в Mapper.persist_selectable. В случае наследования отобразителей некоторые столбцы могут управляться отобразителем суперкласса. Например, в случае Join первичный ключ определяется всеми столбцами первичного ключа во всех таблицах, на которые ссылается Join.

Список также не обязательно совпадает с коллекцией столбцов первичного ключа, связанных с базовыми таблицами; Mapper имеет аргумент primary_key, который может переопределять то, что Mapper считает столбцами первичного ключа.

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

method sqlalchemy.orm.Mapper.primary_key_from_instance(instance: _O) → Tuple[Any, ...]¶

Возвращает список значений первичного ключа для данного экземпляра.

Если состояние экземпляра истекло, вызов этого метода приведет к проверке базы данных на предмет удаления объекта. Если строка больше не существует, выдается сообщение ObjectDeletedError.

method sqlalchemy.orm.Mapper.primary_mapper() → Mapper[Any]¶

Возвращает первичный отображатель, соответствующий ключу класса этого отображателя (class).

attribute sqlalchemy.orm.Mapper.relationships¶

Пространство имен всех свойств Relationship, поддерживаемых этим Mapper.

Предупреждение

пространство имен аксессора Mapper.relationships является экземпляром OrderedProperties. Это объект, похожий на словарь, который включает небольшое количество именованных методов, таких как OrderedProperties.items() и OrderedProperties.values(). При динамическом доступе к атрибутам лучше использовать схему диктуемого доступа, например, mapper.relationships[somename], а не getattr(mapper.relationships, somename), чтобы избежать коллизии имен.

См.также

Mapper.attrs - пространство имен всех объектов MapperProperty.

attribute sqlalchemy.orm.Mapper.selectable¶

Конструкция FromClause, из которой этот Mapper выбирает по умолчанию.

Обычно это эквивалентно persist_selectable, если только не используется функция with_polymorphic, в этом случае возвращается полный «полиморфный» выбор.

attribute sqlalchemy.orm.Mapper.self_and_descendants¶

Коллекция, включающая данный картограф и все потомки картографа.

Это касается не только непосредственно наследующих отобразителей, но и всех наследующих отобразителей.

attribute sqlalchemy.orm.Mapper.single: bool¶

Представляет True, если этот Mapper является отображателем наследования одной таблицы.

Mapper.local_table будет None, если установлен этот флаг.

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

attribute sqlalchemy.orm.Mapper.synonyms¶

Возвращает пространство имен всех свойств Synonym, поддерживаемых данным Mapper.

См.также

Mapper.attrs - пространство имен всех объектов MapperProperty.

attribute sqlalchemy.orm.Mapper.tables: Sequence[TableClause]¶

Последовательность, содержащая коллекцию объектов Table или TableClause, о которых известно данному Mapper.

Если маппер отображен на Join или Alias, представляющий Select, здесь будут представлены отдельные объекты Table, составляющие полную конструкцию.

Это атрибут только для чтения, определяемый во время построения картографа. При непосредственном изменении поведение не определено.

attribute sqlalchemy.orm.Mapper.validators: util.immutabledict[str, Tuple[str, Dict[str, Any]]]¶

Неизменяемый словарь атрибутов, которые были украшены с помощью декоратора validates().

Словарь содержит имена строковых атрибутов в качестве ключей, сопоставленных с фактическим методом проверки.

attribute sqlalchemy.orm.Mapper.with_polymorphic_mappers¶

Список объектов Mapper, включенных в «полиморфный» запрос по умолчанию.