API сессии¶

Session и sessionmaker()¶

Object Name	Description
ORMExecuteState	Представляет собой вызов метода `Session.execute()`, переданный в крючок события `SessionEvents.do_orm_execute()`.
Session	Управляет операциями персистентности для объектов, отображенных в ORM.
sessionmaker	Конфигурируемая фабрика `Session`.
SessionTransaction	Транзакция уровня `Session`.
SessionTransactionOrigin	указывает на происхождение `SessionTransaction`.

class sqlalchemy.orm.sessionmaker¶

Конфигурируемая фабрика Session.

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

например:

from sqlalchemy import create_engine
from sqlalchemy.orm import sessionmaker

# an Engine, which the Session will use for connection
# resources
engine = create_engine('postgresql+psycopg2://scott:tiger@localhost/')

Session = sessionmaker(engine)

with Session() as session:
    session.add(some_object)
    session.add(some_other_object)
    session.commit()

Использование менеджера контекста необязательно; в противном случае возвращаемый объект Session может быть закрыт явно с помощью метода Session.close(). Использование блока try:/finally: необязательно, однако оно гарантирует, что закрытие произойдет даже при наличии ошибок базы данных:

session = Session()
try:
    session.add(some_object)
    session.add(some_other_object)
    session.commit()
finally:
    session.close()

sessionmaker действует как фабрика для объектов Session так же, как Engine действует как фабрика для объектов Connection. Таким образом, он также включает метод sessionmaker.begin(), который предоставляет контекстный менеджер, который начинает и фиксирует транзакцию, а также закрывает Session после завершения, откатывая транзакцию, если возникают какие-либо ошибки:

Session = sessionmaker(engine)

with Session.begin() as session:
    session.add(some_object)
    session.add(some_other_object)
# commits transaction, closes session

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

При вызове sessionmaker для создания Session в метод также могут быть переданы аргументы ключевых слов; эти аргументы будут переопределять глобально настроенные параметры. Ниже мы используем sessionmaker, связанный с определенным Engine, для создания Session, который вместо этого связан с определенным Connection, полученным от этого двигателя:

Session = sessionmaker(engine)

# bind an individual session to a connection

with engine.connect() as connection:
    with Session(bind=connection) as session:
        # work with session

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

# application starts, sessionmaker does not have
# an engine bound yet
Session = sessionmaker()

# ... later, when an engine URL is read from a configuration
# file or other events allow the engine to be created
engine = create_engine('sqlite:///foo.db')
Session.configure(bind=engine)

sess = Session()
# work with session

См.также

Открытие и закрытие сессии - вводный текст по созданию сессий с использованием sessionmaker.

Members

__call__(), __init__(), begin(), close_all(), configure(), identity_key(), object_session()

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

класс sqlalchemy.orm.sessionmaker (sqlalchemy.orm.session._SessionClassMethods, typing.Generic)

method sqlalchemy.orm.sessionmaker.__call__(**local_kw: Any) → _S¶

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

В Python метод __call__ вызывается на объекте, когда его «вызывают» так же, как и функцию:

Session = sessionmaker(some_engine)
session = Session()  # invokes sessionmaker.__call__()

method sqlalchemy.orm.sessionmaker.__init__(bind: Optional[_SessionBind] = None, *, class_: Type[_S] = <class 'sqlalchemy.orm.session.Session'>, autoflush: bool = True, expire_on_commit: bool = True, info: Optional[_InfoType] = None, **kw: Any)¶

Создайте новый sessionmaker.

Все аргументы здесь, кроме class_, соответствуют аргументам, принимаемым Session напрямую. Более подробную информацию о параметрах см. в строке документации Session.__init__().

Параметры:

bind – Engine или другой Connectable, с которым будут связаны вновь создаваемые Session объекты.
class_ – класс, который следует использовать для создания новых объектов Session. По умолчанию используется Session.
autoflush – Настройка автосмыва для вновь созданных объектов Session. … см. также:: Промывка - дополнительная информация об автозамывке
expire_on_commit=True – параметр Session.expire_on_commit, используемый для вновь создаваемых объектов Session.
info – необязательный словарь информации, которая будет доступна через Session.info. Обратите внимание, что этот словарь обновляется, а не заменяется, когда параметр info указан для конкретной операции построения Session.
**kw – все остальные аргументы ключевых слов передаются в конструктор вновь создаваемых объектов Session.

method sqlalchemy.orm.sessionmaker.begin() → AbstractContextManager[_S]¶

Создайте менеджер контекста, который одновременно предоставляет новый Session, а также транзакцию, которая фиксирует.

например:

Session = sessionmaker(some_engine)

with Session.begin() as session:
    session.add(some_object)

# commits transaction, closes session

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

classmethod sqlalchemy.orm.sessionmaker.close_all() → None¶: наследуется от sqlalchemy.orm.session._SessionClassMethods.close_all метода sqlalchemy.orm.session._SessionClassMethods

Закройте все сессии в памяти.

Не рекомендуется, начиная с версии 1.3: Метод Session.close_all() является устаревшим и будет удален в одном из будущих выпусков. Пожалуйста, обратитесь к close_all_sessions().

method sqlalchemy.orm.sessionmaker.configure(**new_kw: Any) → None¶

(Пере)настройка аргументов для этого создателя сеанса.

например:

Session = sessionmaker()

Session.configure(bind=create_engine('sqlite://'))

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

наследуется от sqlalchemy.orm.session._SessionClassMethods.identity_key метода sqlalchemy.orm.session._SessionClassMethods

Возвращает ключ идентификации.

Это псевдоним identity_key().

classmethod sqlalchemy.orm.sessionmaker.object_session(instance: object) → Optional[Session]¶

наследуется от sqlalchemy.orm.session._SessionClassMethods.object_session метода sqlalchemy.orm.session._SessionClassMethods

Возвращает Session, к которому принадлежит объект.

Это псевдоним object_session().

class sqlalchemy.orm.ORMExecuteState¶

Представляет собой вызов метода Session.execute(), переданный в крючок события SessionEvents.do_orm_execute().

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

См.также

Выполнение событий - документация верхнего уровня о том, как использовать SessionEvents.do_orm_execute()

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

класс sqlalchemy.orm.ORMExecuteState (sqlalchemy.util.langhelpers.MemoizedSlots)

method sqlalchemy.orm.ORMExecuteState.__init__(session: Session, statement: Executable, parameters: Optional[_CoreAnyExecuteParams], execution_options: _ExecuteOptions, bind_arguments: _BindArguments, compile_state_cls: Optional[Type[ORMCompileState]], events_todo: List[_InstanceLevelDispatch[Session]])¶

Создайте новый ORMExecuteState.

этот объект строится внутри.

attribute sqlalchemy.orm.ORMExecuteState.all_mappers¶

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

Под «верхним уровнем» мы подразумеваем те Mapper объекты, которые будут представлены в строках набора результатов для запроса select(), или для запроса update() или delete(), маппер, который является основным объектом UPDATE или DELETE.

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

См.также

ORMExecuteState.bind_mapper

attribute sqlalchemy.orm.ORMExecuteState.bind_arguments: _BindArguments¶

Словарь, переданный в качестве словаря Session.execute.bind_arguments.

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

attribute sqlalchemy.orm.ORMExecuteState.bind_mapper¶

Возвращает Mapper, который является основным «связующим» отображателем.

Для объекта ORMExecuteState, вызывающего оператор ORM, то есть атрибутом ORMExecuteState.is_orm_statement является True, этот атрибут возвращает Mapper, который считается «основным» отобразителем оператора. Термин «bind mapper» относится к тому факту, что объект Session может быть «связан» с несколькими объектами Engine, ключами которых являются сопоставленные классы, а «bind mapper» определяет, какой из этих объектов Engine будет выбран.

Для оператора, который вызывается для одного сопоставленного класса, ORMExecuteState.bind_mapper является надежным способом получения этого сопоставителя.

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

См.также

ORMExecuteState.all_mappers

attribute sqlalchemy.orm.ORMExecuteState.execution_options: _ExecuteOptions¶

Полный словарь текущих вариантов исполнения.

Это объединение опций уровня оператора с локально передаваемыми опциями выполнения.

См.также

ORMExecuteState.local_execution_options

Executable.execution_options()

Варианты выполнения ORM

method sqlalchemy.orm.ORMExecuteState.invoke_statement(statement: Optional[Executable] = None, params: Optional[_CoreAnyExecuteParams] = None, execution_options: Optional[OrmExecuteOptionsParameter] = None, bind_arguments: Optional[_BindArguments] = None) → Result[Any]¶

Выполнить оператор, представленный этим ORMExecuteState, без повторного вызова событий, которые уже произошли.

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

Когда объект Result возвращается фактической функцией-обработчиком внутри SessionEvents.do_orm_execute() и передается в вызывающий метод Session.execute(), остаток метода Session.execute() вытесняется, и объект Result немедленно возвращается вызывающему методу Session.execute().

Параметры:

statement – необязательный оператор, который будет вызван вместо оператора, представленного в данный момент ORMExecuteState.statement.
params – необязательный словарь параметров или список параметров, которые будут объединены в существующий ORMExecuteState.parameters данного ORMExecuteState. … versionchanged:: 2.0 список словарей параметров принимается для многих исполнений.
execution_options – необязательный словарь опций выполнения будет объединен с существующим ORMExecuteState.execution_options этого ORMExecuteState.
bind_arguments – необязательный словарь bind_arguments, который будет объединен с текущим ORMExecuteState.bind_arguments данного ORMExecuteState.

Результат:

объект Result с результатами на уровне ORM.

См.также

Повторное выполнение заявлений - справочная информация и примеры по правильному использованию ORMExecuteState.invoke_statement().

attribute sqlalchemy.orm.ORMExecuteState.is_column_load¶

Возвращает True, если операция обновляет атрибуты, ориентированные на столбцы, на существующем объекте ORM.

Это происходит во время таких операций, как Session.refresh(), а также при загрузке атрибута, отложенного по команде defer(), или при загрузке атрибута, срок действия которого истек либо непосредственно по команде Session.expire(), либо через операцию фиксации.

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

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

См.также

ORMExecuteState.is_relationship_load

attribute sqlalchemy.orm.ORMExecuteState.is_delete¶: return True, если это операция DELETE.

attribute sqlalchemy.orm.ORMExecuteState.is_executemany¶: return True, если параметры представляют собой многоэлементный список словарей с более чем одним словарем.

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

attribute sqlalchemy.orm.ORMExecuteState.is_insert¶: возвращает True, если это операция INSERT.

attribute sqlalchemy.orm.ORMExecuteState.is_orm_statement¶

return True, если операция является оператором ORM.

Это указывает на то, что вызываемый select(), insert(), update() или delete() содержит сущности ORM в качестве субъектов. Для оператора, который не содержит сущностей ORM и вместо этого ссылается только на метаданные Table, он вызывается как оператор Core SQL, и никакой автоматизации на уровне ORM не происходит.

attribute sqlalchemy.orm.ORMExecuteState.is_relationship_load¶

Возвращает True, если эта загрузка загружает объекты от имени отношения.

Это означает, что действующий загрузчик является либо LazyLoader, SelectInLoader, SubqueryLoader или подобным, и весь оператор SELECT, который выдается, выполняется от имени загрузки отношения.

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

См.также

ORMExecuteState.is_column_load

attribute sqlalchemy.orm.ORMExecuteState.is_select¶: return True, если это операция SELECT.

attribute sqlalchemy.orm.ORMExecuteState.is_update¶: return True, если это операция UPDATE.

attribute sqlalchemy.orm.ORMExecuteState.lazy_loaded_from¶

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

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

attribute sqlalchemy.orm.ORMExecuteState.load_options¶: Возвращает параметры load_options, которые будут использоваться для данного выполнения.

attribute sqlalchemy.orm.ORMExecuteState.loader_strategy_path¶

Возвращает PathRegistry для текущего пути загрузки.

Этот объект представляет «путь» в запросе вдоль связей при загрузке определенного объекта или коллекции.

attribute sqlalchemy.orm.ORMExecuteState.local_execution_options: _ExecuteOptions¶

Словарное представление опций выполнения, переданных методу Session.execute().

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

См.также

ORMExecuteState.execution_options

attribute sqlalchemy.orm.ORMExecuteState.parameters: Optional[_CoreAnyExecuteParams]¶: Словарь параметров, которые были переданы в Session.execute().

attribute sqlalchemy.orm.ORMExecuteState.session: Session¶: Используемый Session.

attribute sqlalchemy.orm.ORMExecuteState.statement: Executable¶

Вызываемый оператор SQL.

Для ORM-выбора, который был бы получен из Query, это экземпляр select, который был сгенерирован из ORM-запроса.

attribute sqlalchemy.orm.ORMExecuteState.update_delete_options¶: Возвращает параметры update_delete_options, которые будут использоваться для данного выполнения.

method sqlalchemy.orm.ORMExecuteState.update_execution_options(**opts: Any) → None¶: Обновите локальные параметры выполнения новыми значениями.

attribute sqlalchemy.orm.ORMExecuteState.user_defined_options¶: Последовательность UserDefinedOptions, которая была связана с вызываемым оператором.

class sqlalchemy.orm.Session¶

Управляет операциями персистентности для объектов, отображенных в ORM.

Парадигма использования сессии описана в Использование сеанса.

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

класс sqlalchemy.orm.Session (sqlalchemy.orm.session._SessionClassMethods, sqlalchemy.event.registry.EventTarget)

method sqlalchemy.orm.Session.__init__(bind: Optional[_SessionBind] = None, *, autoflush: bool = True, future: Literal[True] = True, expire_on_commit: bool = True, autobegin: bool = True, twophase: bool = False, binds: Optional[Dict[_SessionBindKey, _SessionBind]] = None, enable_baked_queries: bool = True, info: Optional[_InfoType] = None, query_cls: Optional[Type[Query[Any]]] = None, autocommit: Literal[False] = False, join_transaction_mode: JoinTransactionMode = 'conditional_savepoint')¶

Создайте новую сессию.

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

Параметры:

autoflush – При True все операции запроса будут выполнять Session.flush() вызов этого Session перед продолжением. Это удобная функция, позволяющая избежать повторного вызова Session.flush() для получения результатов запросов к базе данных. … см. также:: Промывка - дополнительная информация об автозапуске
autobegin – Автоматически запускать транзакции (т.е. эквивалентно вызову Session.begin()), когда доступ к базе данных запрашивается операцией. По умолчанию установлено значение True. Установите значение False, чтобы предотвратить Session от неявного начала транзакций после построения, а также после вызова любого из методов Session.rollback(), Session.commit() или Session.close(). … версия добавлена:: 2.0 .. seealso:: Отключение автозапуска для предотвращения неявных транзакций
bind – Необязательный Engine или Connection, к которому должен быть привязан этот Session. Если он указан, все SQL-операции, выполняемые этой сессией, будут выполняться через этот подключаемый элемент.
binds – Словарь, в котором может быть указано любое количество объектов Engine или Connection в качестве источника связности для операций SQL на основе каждого объекта. Ключи словаря состоят из любой серии сопоставленных классов, произвольных классов Python, которые являются основой для сопоставленных классов, Table объектов и Mapper объектов. Значениями словаря являются экземпляры объектов Engine или реже Connection. Операции, которые выполняются относительно определенного сопоставленного класса, будут обращаться к этому словарю для поиска ближайшего подходящего объекта, чтобы определить, какой Engine следует использовать для конкретной операции SQL. Полная эвристика для разрешения описана в Session.get_bind(). Использование выглядит следующим образом:: Session = sessionmaker(binds={ SomeMappedClass: create_engine(„postgresql+psycopg2://engine1“), SomeDeclarativeBase: create_engine(„postgresql+psycopg2: //engine2“), some_mapper: create_engine(„postgresql+psycopg2://engine3“), some_table: create_engine(„postgresql+psycopg2://engine4“), }) . . см. также:: Стратегии разделения (например, несколько бэкэндов баз данных на сессию) Session.bind_mapper() Session.bind_table() Session.get_bind()
class_ – Укажите альтернативный класс, отличный от sqlalchemy.orm.session.Session, который должен использоваться возвращаемым классом. Это единственный аргумент, который является локальным для функции sessionmaker, и не передается непосредственно в конструктор для Session.
enable_baked_queries – legacy; по умолчанию True. Параметр, используемый расширением sqlalchemy.ext.baked для определения того, следует ли кэшировать «запеченные запросы», как обычно работает это расширение. При значении False кэширование, используемое этим конкретным расширением, отключено. … versionchanged:: 1.4 Расширение sqlalchemy.ext.baked является устаревшим и не используется ни одним из внутренних компонентов SQLAlchemy. Поэтому этот флаг влияет только на те приложения, которые явно используют это расширение в своем собственном коде.
expire_on_commit – По умолчанию установлено значение True. При True все экземпляры будут полностью уничтожены после каждого commit(), так что все обращения к атрибутам/объектам после завершенной транзакции будут загружаться из самого последнего состояния базы данных. … см. также:: Совершение
future – Исправлено; этот флаг всегда равен True. … см. также:: SQLAlchemy 2.0 - руководство по миграции
info – необязательный словарь произвольных данных, которые должны быть связаны с этим Session. Доступен через атрибут Session.info. Обратите внимание, что словарь копируется во время построения, так что изменения в словаре для каждого Session будут локальными для этого Session.
query_cls – Класс, который должен использоваться для создания новых объектов Query, возвращаемых методом Session.query(). По умолчанию используется Query.
twophase – При True все транзакции будут запускаться как «двухфазная» транзакция, т.е. с использованием «двухфазной» семантики используемой базы данных вместе с XID. Во время транзакции commit(), после того как flush() будет выдан для всех подключенных баз данных, будет вызван метод TwoPhaseTransaction.prepare() на TwoPhaseTransaction каждой базы данных. Это позволяет каждой базе данных откатить всю транзакцию, прежде чем каждая транзакция будет зафиксирована.
autocommit – ключевое слово «autocommit» присутствует для обратной совместимости, но должно оставаться в значении по умолчанию False.
join_transaction_mode – Описывает транзакционное поведение, которое следует предпринять, если данное соединение является Connection, которое уже начало транзакцию вне области действия данного Session; другими словами, метод Connection.in_transaction() возвращает True. Следующие поведения вступают в силу только тогда, когда Session фактически использует данное соединение; то есть фактически вызываются такие методы, как Session.execute(), Session.connection() и т.д: * "conditional_savepoint" - по умолчанию. Если данное Connection начато в рамках транзакции, но не имеет SAVEPOINT, то используется "rollback_only". Если Connection дополнительно находится внутри SAVEPOINT, другими словами, метод Connection.in_nested_transaction() возвращает True, то используется "create_savepoint". Поведение "conditional_savepoint" пытается использовать точки сохранения для того, чтобы сохранить состояние существующей транзакции неизменным, но только если уже есть точка сохранения в процессе выполнения; в противном случае не предполагается, что используемый бэкенд имеет адекватную поддержку SAVEPOINT, так как доступность этой функции варьируется. "conditional_savepoint" также стремится установить приблизительную обратную совместимость с предыдущим поведением Session для приложений, которые не устанавливают определенный режим. Рекомендуется использовать одну из явных настроек. * "create_savepoint" - Session будет использовать Connection.begin_nested() во всех случаях для создания собственной транзакции. Эта транзакция по своей природе проходит «поверх» любой существующей транзакции, открытой на данном Connection; если базовая база данных и используемый драйвер имеют полную, не нарушенную поддержку SAVEPOINT, внешняя транзакция останется незатронутой в течение всего времени жизни Session. Режим "create_savepoint" наиболее полезен для интеграции Session в набор тестов, где внешняя инициированная транзакция должна оставаться незатронутой; однако он зависит от надлежащей поддержки SAVEPOINT базовым драйвером и базой данных. … совет:: При использовании SQLite драйвер SQLite, включенный в Python 3.11, не во всех случаях корректно обрабатывает SAVEPOINT без обходных путей. Смотрите раздел Сериализуемая изоляция / Точки сохранения / Транзакционный DDL для получения подробной информации о текущих обходных путях. * "control_fully" - Session возьмет под контроль данную транзакцию как свою собственную; Session.commit() вызовет .commit() на транзакции, Session.rollback() вызовет .rollback() на транзакции, Session.close() вызовет .rollback на транзакции. … совет:: Этот режим использования эквивалентен тому, как SQLAlchemy 1.4 будет обрабатывать Connection, переданный с существующим SAVEPOINT (т.е. Connection.begin_nested()); Session будет полностью контролировать существующий SAVEPOINT. * "rollback_only" - Session возьмет под контроль данную транзакцию только для вызовов .rollback(); вызовы .commit() не будут распространяться на данную транзакцию. Вызовы .close() не будут иметь никакого эффекта на данную транзакцию. … совет:: Этот режим использования эквивалентен тому, как SQLAlchemy 1.4 будет обрабатывать Connection, переданный с существующей обычной транзакцией базы данных (т.е. Connection.begin()); Session будет распространять Session.rollback() вызовы Session.commit() на базовую Session.close() транзакцию,

method sqlalchemy.orm.Session.add(instance: object, _warn: bool = True) → None¶

Поместите объект в этот Session.

Объекты, находящиеся в состоянии transient при передаче в метод Session.add(), перейдут в состояние pending до следующей промывки, после которой они перейдут в состояние persistent.

Объекты, которые находятся в состоянии detached при передаче в метод Session.add(), перейдут в состояние persistent напрямую.

Если транзакция, используемая Session, откатывается, объекты, которые были переходными, когда они были переданы в Session.add(), будут переведены обратно в состояние transient и больше не будут присутствовать в этом Session.

См.также

Session.add_all()

Добавление новых или существующих элементов - на Основы использования сеанса

method sqlalchemy.orm.Session.add_all(instances: Iterable[object]) → None¶

Добавляет заданную коллекцию экземпляров к данному Session.

Общее описание поведения см. в документации для Session.add().

См.также

Session.add()

Добавление новых или существующих элементов - на Основы использования сеанса

method sqlalchemy.orm.Session.begin(nested: bool = False) → SessionTransaction¶

Начать транзакцию или вложенную транзакцию на этом Session, если она еще не начата.

Объект Session имеет поведение autobegin, поэтому обычно нет необходимости в явном вызове метода Session.begin(). Однако его можно использовать для того, чтобы контролировать область, в которой начинается транзакционное состояние.

При использовании для начала самой внешней транзакции возникает ошибка, если эта Session уже находится внутри транзакции.

Параметры:: nested – если True, начинает транзакцию SAVEPOINT и эквивалентна вызову Session.begin_nested(). Документацию по транзакциям SAVEPOINT смотрите в разделе Использование SAVEPOINT.
Результат:: объект SessionTransaction. Обратите внимание, что SessionTransaction действует как менеджер контекста Python, позволяя использовать Session.begin() в блоке «with». Смотрите пример Явное начало.

См.также

Автозапуск

Управление транзакциями

Session.begin_nested()

method sqlalchemy.orm.Session.begin_nested() → SessionTransaction¶

Начните «вложенную» транзакцию на этой сессии, например, SAVEPOINT.

Для правильной работы этого метода целевая база данных (базы данных) и соответствующие драйверы должны поддерживать SQL SAVEPOINT.

Документацию по транзакциям SAVEPOINT см. в разделе Использование SAVEPOINT.

Результат:: объект SessionTransaction. Обратите внимание, что SessionTransaction действует как менеджер контекста, позволяя использовать Session.begin_nested() в блоке «with». Пример использования см. в Использование SAVEPOINT.

См.также

Использование SAVEPOINT

Сериализуемая изоляция / Точки сохранения / Транзакционный DDL - специальные обходные пути, необходимые для работы драйвера SQLite, чтобы SAVEPOINT работал правильно.

method sqlalchemy.orm.Session.bind_mapper(mapper: _EntityBindKey[_O], bind: _SessionBind) → None¶

Ассоциируйте Mapper или произвольный класс Python с «привязкой», например, Engine или Connection.

Данная сущность добавляется в поиск, используемый методом Session.get_bind().

Параметры:

mapper – объект Mapper, или экземпляр сопоставленного класса, или любой класс Python, который является основой набора сопоставленных классов.
bind – объект Engine или Connection.

См.также

Стратегии разделения (например, несколько бэкэндов баз данных на сессию)

Session.binds

Session.bind_table()

method sqlalchemy.orm.Session.bind_table(table: TableClause, bind: Union[Engine, Connection]) → None¶

Соедините Table с «привязкой», например, Engine или Connection.

Заданный Table добавляется в поиск, используемый методом Session.get_bind().

Параметры:

table – объект Table, который обычно является целью отображения ORM, или присутствует внутри selectable, который отображается.
bind – объект Engine или Connection.

См.также

Стратегии разделения (например, несколько бэкэндов баз данных на сессию)

Session.binds

Session.bind_mapper()

method sqlalchemy.orm.Session.bulk_insert_mappings(mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]], return_defaults: bool = False, render_nulls: bool = False) → None¶

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

Legacy Feature

Этот метод является унаследованной функцией, начиная с версии 2.0 серии SQLAlchemy. О современных массовых INSERT и UPDATE см. разделы ORM Bulk INSERT Statements и ORM Bulk UPDATE по первичному ключу. API версии 2.0 разделяет детали реализации с этим методом и добавляет новые возможности.

Параметры:

mapper – сопоставленный класс или реальный объект Mapper, представляющий единственный вид объекта, представленный в списке сопоставления.
mappings – последовательность словарей, каждый из которых содержит состояние вставляемой строки отображения в терминах имен атрибутов отображаемого класса. Если отображение ссылается на несколько таблиц, например, отображение с объединенным наследованием, каждый словарь должен содержать все ключи, которые должны быть заполнены во всех таблицах.
return_defaults – при значении True процесс INSERT будет изменен таким образом, чтобы обеспечить получение вновь созданных значений первичного ключа. Этот параметр обычно используется для того, чтобы обеспечить массовую вставку сопоставлений Joined Table Inheritance. … Примечание:: для бэкендов, не поддерживающих RETURNING, параметр Session.bulk_insert_mappings.return_defaults может значительно снизить производительность, поскольку операторы INSERT больше не могут быть объединены в пакет. Смотрите Поведение «Вставка многих значений» для операторов INSERT для получения информации о том, какие бэкенды затронуты.
render_nulls – Если значение None равно True, то в оператор INSERT будет включено значение NULL, а не столбец будет опущен в INSERT. Это позволяет всем вводимым строкам иметь одинаковый набор столбцов, что позволяет передавать полный набор строк в DBAPI. Обычно каждый набор столбцов, содержащий другую комбинацию значений NULL, чем предыдущий ряд, должен опускать другую серию столбцов из оператора INSERT, что означает, что он должен быть выдан как отдельный оператор. Передача этого флага гарантирует, что весь набор строк можно объединить в один пакет; однако ценой этого является то, что серверные настройки по умолчанию, которые вызываются опущенным столбцом, будут пропущены, поэтому следует позаботиться о том, чтобы в них не было необходимости. … предупреждение:: Когда этот флаг установлен, значения SQL по умолчанию на стороне сервера не будут вызываться для тех столбцов, которые вставлены как NULL; значение NULL будет отправлено явно. Необходимо позаботиться о том, чтобы для операции в целом не требовалось вызывать серверные функции по умолчанию.

См.также

Операции INSERT, UPDATE и DELETE с поддержкой ORM

Session.bulk_save_objects()

Session.bulk_update_mappings()

method sqlalchemy.orm.Session.bulk_save_objects(objects: Iterable[object], return_defaults: bool = False, update_changed_only: bool = True, preserve_order: bool = True) → None¶

Выполните массовое сохранение заданного списка объектов.

Legacy Feature

Для общего INSERT и UPDATE существующих объектов, отображаемых ORM, предпочитайте стандартные паттерны управления данными unit of work, представленные в Унифицированный учебник по SQLAlchemy в Манипулирование данными с помощью ORM. SQLAlchemy 2.0 теперь использует Поведение «Вставка многих значений» для операторов INSERT с современными диалектами, что решает предыдущие проблемы медлительности массового INSERT.

Параметры:

objects – последовательность сопоставленных экземпляров объектов. Сопоставленные объекты сохраняются как есть и не ассоциируются с Session впоследствии. Для каждого объекта, будет ли он отправлен как INSERT или UPDATE, зависит от тех же правил, которые используются Session в традиционной операции; если у объекта установлен атрибут InstanceState.key, то предполагается, что объект «отсоединен» и в результате будет UPDATE. В противном случае используется INSERT. В случае UPDATE утверждения группируются на основе того, какие атрибуты изменились, и, следовательно, должны быть предметом каждого предложения SET. Если update_changed_only имеет значение False, то все атрибуты, присутствующие в каждом объекте, применяются к оператору UPDATE, что может помочь в группировке операторов в более крупный executemany(), а также уменьшит накладные расходы на проверку истории атрибутов.
return_defaults – при значении True строки, в которых отсутствуют значения, генерирующие значения по умолчанию, а именно целочисленные первичные ключи по умолчанию и последовательности, будут вставляться по одному, чтобы значение первичного ключа было доступно. В частности, это позволит корректно вставлять объединенное наследование и другие многотабличные отображения без необходимости предоставлять значения первичного ключа заранее; однако Session.bulk_save_objects.return_defaults значительно снижает прирост производительности метода в целом. Настоятельно рекомендуется использовать стандартный подход Session.add_all().
update_changed_only – При значении True операторы UPDATE отображаются на основе тех атрибутов в каждом состоянии, которые зарегистрировали изменения. При значении False все присутствующие атрибуты отображаются в предложение SET, за исключением атрибутов первичного ключа.
preserve_order – когда True, порядок вставок и обновлений точно соответствует порядку, в котором заданы объекты. Когда False, общие типы объектов группируются по вставкам и обновлениям, чтобы обеспечить больше возможностей для пакетной обработки.

См.также

Операции INSERT, UPDATE и DELETE с поддержкой ORM

Session.bulk_insert_mappings()

Session.bulk_update_mappings()

method sqlalchemy.orm.Session.bulk_update_mappings(mapper: Mapper[Any], mappings: Iterable[Dict[str, Any]]) → None¶

Выполните массовое обновление заданного списка картографических словарей.

Legacy Feature

Параметры:

mapper – сопоставленный класс или реальный объект Mapper, представляющий единственный вид объекта, представленный в списке сопоставления.
mappings – последовательность словарей, каждый из которых содержит состояние сопоставленной строки, подлежащей обновлению, в терминах имен атрибутов сопоставленного класса. Если отображение относится к нескольким таблицам, например, отображение с объединенным наследованием, каждый словарь может содержать ключи, соответствующие всем таблицам. Все ключи, которые присутствуют и не являются частью первичного ключа, применяются к пункту SET оператора UPDATE; значения первичного ключа, которые требуются, применяются к пункту WHERE.

См.также

Операции INSERT, UPDATE и DELETE с поддержкой ORM

Session.bulk_insert_mappings()

Session.bulk_save_objects()

method sqlalchemy.orm.Session.close() → None¶

Закройте транзакционные ресурсы и объекты ORM, используемые этой Session.

Это удаляет все объекты ORM, связанные с данным Session, завершает любую выполняющуюся транзакцию и releases любые Connection объекты, которые данный Session сам выписал из связанных Engine объектов. Операция оставляет Session в состоянии, в котором он может быть использован снова.

Совет

Метод Session.close() не препятствует повторному использованию сессии. Сам Session на самом деле не имеет отдельного состояния «закрыто»; это просто означает, что Session освободит все соединения с базой данных и объекты ORM.

Изменено в версии 1.4: Метод Session.close() не создает сразу новый объект SessionTransaction; вместо этого новый SessionTransaction создается только в том случае, если Session снова используется для операции с базой данных.

См.также

Закрытие - подробно о семантике Session.close()

classmethod sqlalchemy.orm.Session.close_all() → None¶: наследуется от sqlalchemy.orm.session._SessionClassMethods.close_all метода sqlalchemy.orm.session._SessionClassMethods

Закройте все сессии в памяти.

Не рекомендуется, начиная с версии 1.3: Метод Session.close_all() является устаревшим и будет удален в одном из будущих выпусков. Пожалуйста, обратитесь к close_all_sessions().

method sqlalchemy.orm.Session.commit() → None¶

Очистка ожидающих изменений и фиксация текущей транзакции.

Когда операция COMMIT завершена, все объекты полностью expired, стирается их внутреннее содержимое, которое будет автоматически загружено заново при следующем обращении к объектам. В промежуточный момент эти объекты находятся в просроченном состоянии и не будут функционировать, если к ним detached из Session. Кроме того, эта операция повторной загрузки не поддерживается при использовании асинхронно-ориентированных API. Параметр Session.expire_on_commit может быть использован для отключения этого поведения.

Если для Session не существует транзакции, указывающей на то, что с момента предыдущего вызова Session.commit() для этого Session не было вызвано никаких операций, метод начнет и зафиксирует только внутреннюю «логическую» транзакцию, которая обычно не влияет на базу данных, если только не были обнаружены ожидающие изменения флеша, но все равно вызовет обработчики событий и правила истечения срока действия объектов.

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

См.также

Совершение

Управление транзакциями

Предотвращение неявного ввода-вывода при использовании AsyncSession

method sqlalchemy.orm.Session.connection(bind_arguments: Optional[_BindArguments] = None, execution_options: Optional[_ExecuteOptions] = None) → Connection¶

Возвращает объект Connection, соответствующий транзакционному состоянию этого объекта Session.

Возвращается либо Connection, соответствующий текущей транзакции, либо, если транзакция не выполняется, начинается новая и возвращается Connection (обратите внимание, что транзакционное состояние не устанавливается с DBAPI до тех пор, пока не будет выдан первый SQL-оператор).

Неоднозначность в многосвязных или несвязанных объектах Session может быть разрешена с помощью любого из необязательных аргументов ключевого слова. В конечном итоге для разрешения используется метод get_bind().

Параметры:

bind_arguments – словарь аргументов связывания. Может включать «mapper», «bind», «clause», другие пользовательские аргументы, которые передаются в Session.get_bind().
execution_options – словарь параметров выполнения, которые будут переданы в Connection.execution_options(), только при первом получении соединения. Если соединение уже присутствует в Session, выдается предупреждение и аргументы игнорируются. … см. также:: Настройка уровней изоляции транзакций / DBAPI AUTOCOMMIT

method sqlalchemy.orm.Session.delete(instance: object) → None¶

Пометить экземпляр как удаленный.

При передаче предполагается, что объект находится в состоянии persistent или detached; после вызова метода объект будет находиться в состоянии persistent до следующей процедуры flush. В течение этого времени объект также будет членом коллекции Session.deleted.

Когда произойдет следующий flush, объект перейдет в состояние deleted, указывающее на то, что для его строки в текущей транзакции был выпущен оператор DELETE. Когда транзакция успешно зафиксирована, удаленный объект переходит в состояние detached и больше не присутствует в этом Session.

См.также

Удаление - на Основы использования сеанса

attribute sqlalchemy.orm.Session.deleted¶: Набор всех экземпляров, помеченных как «удаленные» в пределах данного Session.

attribute sqlalchemy.orm.Session.dirty¶

Множество всех постоянных экземпляров, которые считаются грязными.

Например:

some_mapped_object in session.dirty

Экземпляры считаются грязными, если они были изменены, но не удалены.

Обратите внимание, что этот «грязный» расчет является «оптимистичным»; большинство операций по установке атрибутов или изменению коллекции пометит экземпляр как «грязный» и поместит его в этот набор, даже если нет чистого изменения значения атрибута. Во время промывки значение каждого атрибута сравнивается с его ранее сохраненным значением, и если чистого изменения нет, операция SQL не выполняется (это более дорогая операция, поэтому она выполняется только во время промывки).

Чтобы проверить, есть ли у экземпляра действующие чистые изменения его атрибутов, используйте метод Session.is_modified().

method sqlalchemy.orm.Session.enable_relationship_loading(obj: object) → None¶

Связывает объект с этим Session для загрузки связанного объекта.

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

enable_relationship_loading() существует для специальных случаев использования и не рекомендуется для общего использования.

Доступ к атрибутам, сопоставленным с relationship(), будет пытаться загрузить значение из базы данных, используя этот Session в качестве источника связи. Значения будут загружаться на основе значений внешнего и первичного ключей, имеющихся у данного объекта - если они отсутствуют, то эти связи будут недоступны.

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

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

Метод Session.enable_relationship_loading() аналогичен флагу load_on_pending в relationship(). В отличие от этого флага, Session.enable_relationship_loading() позволяет объекту оставаться переходным, сохраняя возможность загружать связанные элементы.

Чтобы сделать переходный объект, связанный с Session через Session.enable_relationship_loading() отложенным, добавьте его к Session с помощью Session.add() обычным способом. Если объект вместо этого представляет существующую личность в базе данных, его следует объединить с помощью Session.merge().

Session.enable_relationship_loading() не улучшает поведение при обычном использовании ORM - объектные ссылки должны быть построены на уровне объекта, а не на уровне внешнего ключа, чтобы они присутствовали обычным образом до выполнения flush(). Этот метод не предназначен для общего использования.

См.также

relationship.load_on_pending - этот флаг разрешает загрузку «многие-к-одному» для элементов, которые находятся в ожидании.

make_transient_to_detached() - позволяет добавить объект в Session без использования SQL, который затем будет раскрывать атрибуты при доступе.

method sqlalchemy.orm.Session.execute(statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, _parent_execute_state: Optional[Any] = None, _add_event: Optional[Any] = None) → Result[Any]¶

Выполнение конструкции выражения SQL.

Возвращает объект Result, представляющий результаты выполнения оператора.

Например:

from sqlalchemy import select
result = session.execute(
    select(User).where(User.id == 5)
)

API-контракт Session.execute() аналогичен контракту Connection.execute(), 2.0 style версии Connection.

Изменено в версии 1.4: метод Session.execute() теперь является основной точкой выполнения операторов ORM при использовании 2.0 style ORM.

Параметры:

statement – Исполняемый оператор (т.е. выражение Executable, например select()).
params – Необязательный словарь или список словарей, содержащих значения связанных параметров. Если словарь один, то происходит выполнение одной строки; если список словарей, то будет вызван «executemany». Ключи в каждом словаре должны соответствовать именам параметров, присутствующих в операторе.
execution_options – необязательный словарь опций выполнения, которые будут связаны с выполнением оператора. Этот словарь может предоставлять подмножество опций, которые принимаются Connection.execution_options(), а также может предоставлять дополнительные опции, понятные только в контексте ORM. … seealso:: Варианты выполнения ORM - специфические для ORM параметры выполнения
bind_arguments – словарь дополнительных аргументов для определения привязки. Может включать «mapper», «bind» или другие пользовательские аргументы. Содержимое этого словаря передается в метод Session.get_bind().

Результат:

объект Result.

method sqlalchemy.orm.Session.expire(instance: object, attribute_names: Optional[Iterable[str]] = None) → None¶

Истечение срока действия атрибутов экземпляра.

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

Чтобы одновременно исключить все объекты в Session, используйте Session.expire_all().

Поведение объекта Session по умолчанию заключается в том, что при вызове методов Session.rollback() или Session.commit() все состояние истекает, так что новое состояние может быть загружено для новой транзакции. По этой причине вызов метода Session.expire() имеет смысл только в том случае, если в текущей транзакции был выдан нестандартный SQL-запрос.

Параметры:

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

См.также

Обновление / истечение срока действия - вводный материал

Session.expire()

Session.refresh()

Query.populate_existing()

method sqlalchemy.orm.Session.expire_all() → None¶

Истечение срока действия всех постоянных экземпляров в рамках этой сессии.

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

Чтобы исключить отдельные объекты и отдельные атрибуты этих объектов, используйте Session.expire().

Поведение объекта Session по умолчанию заключается в том, что при вызове методов Session.rollback() или Session.commit() все состояние истекает, чтобы новое состояние могло быть загружено для новой транзакции. По этой причине вызов Session.expire_all() обычно не требуется, если транзакция изолирована.

См.также

Обновление / истечение срока действия - вводный материал

Session.expire()

Session.refresh()

Query.populate_existing()

method sqlalchemy.orm.Session.expunge(instance: object) → None¶

Удалите instance из этого Session.

Это освободит все внутренние ссылки на экземпляр. Каскадирование будет применяться в соответствии с правилом каскада expunge.

method sqlalchemy.orm.Session.expunge_all() → None¶

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

Это эквивалентно вызову expunge(obj) на всех объектах в этом Session.

method sqlalchemy.orm.Session.flush(objects: Optional[Sequence[Any]] = None) → None¶

Сбросьте все изменения объекта в базу данных.

Записывает все ожидающие создания, удаления и модификации объектов в базу данных в виде INSERTs, DELETEs, UPDATEs и т.д. Операции автоматически упорядочиваются решателем зависимостей единицы работы сессии.

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

Параметры:: objects – Необязательно; ограничивает операцию flush только элементами, которые находятся в данной коллекции. Эта функция предназначена для очень узкого круга случаев, когда конкретные объекты могут быть обработаны до того, как произойдет полная операция flush(). Она не предназначена для общего использования.

method sqlalchemy.orm.Session.get(entity: _EntityBindKey[_O], ident: _PKIdentityArgument, *, options: Optional[Sequence[ORMOption]] = None, populate_existing: bool = False, with_for_update: ForUpdateParameter = None, identity_token: Optional[Any] = None, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None) → Optional[_O]¶

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

Например:

my_user = session.get(User, 5)

some_object = session.get(VersionedFoo, (5, 10))

some_object = session.get(
    VersionedFoo,
    {"id": 5, "version_id": 10}
)

Добавлено в версии 1.4: Добавлен метод Session.get(), который перенесен из устаревшего метода Query.get().

Session.get() является особенным, так как предоставляет прямой доступ к карте идентификации Session. Если заданный идентификатор первичного ключа присутствует в локальной карте идентификации, объект возвращается непосредственно из этой коллекции и никакого SQL не выдается, если только объект не был помечен как полностью истекший. Если объект не присутствует, выполняется SELECT для поиска объекта.

Session.get() также выполнит проверку, если объект присутствует в карте идентификации и помечен как просроченный - будет выдан SELECT, чтобы обновить объект, а также убедиться, что строка все еще присутствует. Если нет, то выдается сообщение ObjectDeletedError.

Параметры:

entity – сопоставленный класс или Mapper, указывающий на тип загружаемой сущности.
ident – Скаляр, кортеж или словарь, представляющий первичный ключ. Для составного (например, с несколькими столбцами) первичного ключа следует передавать кортеж или словарь. Для первичного ключа, состоящего из одного столбца, обычно наиболее удобна скалярная форма вызова. Если первичным ключом строки является значение «5», вызов выглядит так:: my_object = session.get(SomeClass, 5) Форма кортежа содержит значения первичного ключа обычно в том порядке, в котором они соответствуют столбцам первичного ключа сопоставленного объекта Table, или, если используется параметр конфигурации Mapper.primary_key, в порядке, используемом для этого параметра. Например, если первичный ключ строки представлен целыми цифрами «5, 10», вызов будет выглядеть так:: my_object = session.get(SomeClass, (5, 10)) Словарная форма должна включать в качестве ключей имена сопоставленных атрибутов, соответствующих каждому элементу первичного ключа. Если сопоставленный класс имеет атрибуты id, version_id в качестве атрибутов, которые хранят значение первичного ключа объекта, вызов будет выглядеть так:: my_object = session.get(SomeClass, {«id»: 5, «version_id»: 10})
options – необязательная последовательность опций загрузчика, которые будут применены к запросу, если он выдан.
populate_existing – заставляет метод безусловно выдать SQL-запрос и обновить объект новыми загруженными данными, независимо от того, существует ли уже объект.
with_for_update – необязательное булево True, указывающее, что должен использоваться FOR UPDATE, или может быть словарем, содержащим флаги для указания более конкретного набора флагов FOR UPDATE для SELECT; флаги должны соответствовать параметрам Query.with_for_update(). Заменяет параметр Session.refresh.lockmode.
execution_options – необязательный словарь опций выполнения, которые будут ассоциированы с выполнением запроса, если он будет выдан. Этот словарь может содержать подмножество опций, принимаемых Connection.execution_options(), а также может содержать дополнительные опции, понятные только в контексте ORM. … версия добавлена:: 1.4.29 .. seealso:: Варианты выполнения ORM - специфические для ORM параметры выполнения
bind_arguments – словарь дополнительных аргументов для определения привязки. Может включать «mapper», «bind» или другие пользовательские аргументы. Содержимое этого словаря передается в метод Session.get_bind(). … добавлена версия: 2.0.0rc1

Результат:

Экземпляр объекта, или None.

method sqlalchemy.orm.Session.get_bind(mapper: Optional[_EntityBindKey[_O]] = None, *, clause: Optional[ClauseElement] = None, bind: Optional[_SessionBind] = None, _sa_skip_events: Optional[bool] = None, _sa_skip_for_implicit_returning: bool = False, **kw: Any) → Union[Engine, Connection]¶

Возвращает «привязку», к которой привязан данный Session.

Связка» обычно является экземпляром Engine, за исключением случаев, когда Session был явно связан непосредственно с Connection.

Для многократно связанного или несвязанного Session аргументы mapper или clause используются для определения соответствующего связывания для возврата.

Обратите внимание, что аргумент «mapper» обычно присутствует, когда Session.get_bind() вызывается через операцию ORM, такую как Session.query(), каждая отдельная операция INSERT/UPDATE/DELETE в рамках Session.flush(), вызов и т.д.

Порядок разрешения следующий:

если задан mapper и присутствует Session.binds, найти привязку, основываясь сначала на используемом mapper, затем на используемом mapped class, затем на любых базовых классах, присутствующих в __mro__ отображаемого класса, от более специфических суперклассов к более общим.
если пункт задан и присутствует Session.binds, найти привязку на основе объектов Table, найденных в данном пункте, присутствующих в Session.binds.
если Session.binds присутствует, верните его.
если дано предложение, попытаться вернуть привязку, связанную с MetaData, в конечном итоге связанную с предложением.
если задан mapper, попытаться вернуть привязку, связанную с MetaData, в конечном итоге ассоциированную с Table или другим selectable, с которым сопоставлен mapper.
Связка не найдена, выдается сообщение UnboundExecutionError.

Обратите внимание, что метод Session.get_bind() может быть переопределен в определяемом пользователем подклассе Session для обеспечения любой схемы разрешения привязки. Смотрите пример в Нестандартные вертикальные перегородки.

Параметры:

mapper – Необязательный сопоставленный класс или соответствующий экземпляр Mapper. Привязка может быть получена из Mapper, во-первых, путем обращения к карте «привязок», связанной с этим Session, и, во-вторых, путем обращения к MetaData, связанной с Table, к которому привязывается Mapper для привязки.
clause – ClauseElement (т.е. select(), text() и т.д.). Если аргумент mapper отсутствует или не смог создать связывание, то в данной конструкции выражения будет произведен поиск связанного элемента, обычно Table, связанного со связанным MetaData.

См.также

Стратегии разделения (например, несколько бэкэндов баз данных на сессию)

Session.binds

Session.bind_mapper()

Session.bind_table()

method sqlalchemy.orm.Session.get_nested_transaction() → Optional[SessionTransaction]¶: Возвращает текущую выполняющуюся вложенную транзакцию, если таковая имеется.

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

method sqlalchemy.orm.Session.get_transaction() → Optional[SessionTransaction]¶: Возвращает текущую выполняющуюся корневую транзакцию, если таковая имеется.

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

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

наследуется от sqlalchemy.orm.session._SessionClassMethods.identity_key метода sqlalchemy.orm.session._SessionClassMethods

Возвращает ключ идентификации.

Это псевдоним identity_key().

attribute sqlalchemy.orm.Session.identity_map: IdentityMap¶

Отображение идентификаторов объектов на сами объекты.

Итерация через Session.identity_map.values() обеспечивает доступ к полному набору постоянных объектов (т.е. тех, которые имеют идентификатор строки), находящихся в данный момент в сессии.

См.также

identity_key() - вспомогательная функция для получения ключей, используемых в данном словаре.

method sqlalchemy.orm.Session.in_nested_transaction() → bool¶: Возвращает True, если эта Session начала вложенную транзакцию, например, SAVEPOINT.

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

method sqlalchemy.orm.Session.in_transaction() → bool¶: Возвращает True, если данная Session начала транзакцию.

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

См.также

Session.is_active

attribute sqlalchemy.orm.Session.info¶

Модифицируемый пользователем словарь.

Начальное значение этого словаря может быть заполнено с помощью аргумента info конструктора Session, конструктора sessionmaker или методов фабрики. Данный словарь всегда локален для данного Session и может быть изменен независимо от всех других Session объектов.

method sqlalchemy.orm.Session.invalidate() → None¶

Закройте эту сессию, используя аннулирование соединения.

Это вариант Session.close(), который дополнительно гарантирует, что метод Connection.invalidate() будет вызван на каждом объекте Connection, который в данный момент используется для транзакции (обычно существует только одно соединение, если Session не используется с несколькими движками).

Это может быть вызвано, когда известно, что база данных находится в состоянии, когда соединения больше не безопасны для использования.

Ниже показан сценарий использования gevent, при котором могут возникать исключения Timeout, означающие, что базовое соединение должно быть отброшено:

import gevent

try:
    sess = Session()
    sess.add(User())
    sess.commit()
except gevent.Timeout:
    sess.invalidate()
    raise
except:
    sess.rollback()
    raise

Метод дополнительно делает все то, что делает Session.close(), включая удаление всех объектов ORM.

attribute sqlalchemy.orm.Session.is_active¶

True, если данный Session не находится в состоянии «частичного отката».

Изменено в версии 1.4: Session больше не начинает новую транзакцию немедленно, поэтому при первом создании Session этот атрибут будет иметь значение False.

Состояние «частичный откат» обычно указывает на то, что процесс промывки Session завершился неудачно, и для полного отката транзакции необходимо вызвать метод Session.rollback().

Если эта Session вообще не находится в транзакции, Session будет автозапускаться при ее первом использовании, поэтому в этом случае Session.is_active вернет True.

В противном случае, если эта Session находится внутри транзакции, и эта транзакция не была откачена внутренне, Session.is_active также вернет True.

См.также

«Транзакция этого сеанса была откачена из-за предыдущего исключения во время промывки.» (или аналогично)

Session.in_transaction()

method sqlalchemy.orm.Session.is_modified(instance: object, include_collections: bool = True) → bool¶

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

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

По сути, это более дорогая и точная версия проверки наличия данного экземпляра в коллекции Session.dirty; выполняется полная проверка на чистый «грязный» статус каждого атрибута.

Например:

return session.is_modified(someobject)

У этого метода есть несколько предостережений:

Экземпляры, находящиеся в коллекции Session.dirty, могут сообщить False при проверке этим методом. Это связано с тем, что объект мог получить события изменения через мутацию атрибутов, в результате чего он оказался в Session.dirty, но в конечном итоге его состояние осталось тем же, что и при загрузке из базы данных, поэтому чистых изменений здесь нет.
Скалярные атрибуты могут не записать ранее установленное значение, когда было применено новое значение, если атрибут не был загружен или был просрочен на момент получения нового значения - в этих случаях предполагается, что атрибут изменился, даже если в конечном итоге нет чистого изменения относительно его значения в базе данных. SQLAlchemy в большинстве случаев не нуждается в «старом» значении, когда происходит событие set, поэтому он пропускает затраты на вызов SQL, если старое значение не присутствует, исходя из предположения, что UPDATE скалярного значения обычно необходим, а в тех немногих случаях, когда это не так, в среднем дешевле, чем выдача защитного SELECT.

Старое» значение извлекается безусловно при установке, только если в контейнере атрибута установлен флаг active_history, равный True. Этот флаг обычно устанавливается для атрибутов первичного ключа и скалярных ссылок на объекты, которые не являются простыми «многие к одному». Чтобы установить этот флаг для любого произвольного сопоставленного столбца, используйте аргумент active_history с column_property().

Параметры:

instance – сопоставленный экземпляр, который должен быть проверен на наличие предстоящих изменений.
include_collections – Указывает, следует ли включать в операцию многозначные коллекции. Установка этого значения в False позволяет определить только свойства, основанные на локальных столбцах (т.е. скалярные столбцы или внешние ключи типа «многие к одному»), которые приведут к UPDATE для данного экземпляра при промывке.

method sqlalchemy.orm.Session.merge(instance: _O, *, load: bool = True, options: Optional[Sequence[ORMOption]] = None) → _O¶

Скопировать состояние данного экземпляра в соответствующий экземпляр внутри данного Session.

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

Эта операция каскадируется на ассоциированные экземпляры, если ассоциация отображена с помощью cascade="merge".

Подробное обсуждение слияния см. в Объединение.

Параметры:

instance – Экземпляр, подлежащий объединению.
load – Булево, при значении False merge() переходит в режим «высокой производительности», что заставляет его отказаться от эмиссии событий истории, а также от всех обращений к базе данных. Этот флаг используется в таких случаях, как передача графов объектов в Session из кэша второго уровня или передача только что загруженных объектов в Session, принадлежащий рабочему потоку или процессу, без повторного запроса к базе данных. В случае использования load=False добавляется оговорка, что данный объект должен находиться в «чистом» состоянии, то есть не иметь ожидающих изменений, подлежащих смыву - даже если входящий объект отделен от какого-либо Session. Это делается для того, чтобы при операции слияния, когда локальные атрибуты заполняются и каскадируются на связанные объекты и коллекции, значения могли быть «впечатаны» в целевой объект как есть, без генерации каких-либо событий истории или атрибутов, и без необходимости согласования входящих данных с существующими связанными объектами или коллекциями, которые могут быть не загружены. Результирующие объекты из load=False всегда получаются «чистыми», поэтому вполне уместно, что и передаваемые объекты должны быть «чистыми», иначе это говорит о неправильном использовании метода.
options – необязательная последовательность опций загрузчика, которая будет применена к методу Session.get() при загрузке операцией слияния существующей версии объекта из базы данных. … versionadded:: 1.4.24

См.также

make_transient_to_detached() - предусматривает альтернативное средство «слияния» отдельного объекта в Session.

attribute sqlalchemy.orm.Session.new¶: Набор всех экземпляров, помеченных как «новые» в пределах данного Session.

attribute sqlalchemy.orm.Session.no_autoflush¶

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

например:

with session.no_autoflush:

    some_object = SomeClass()
    session.add(some_object)
    # won't autoflush
    some_object.related_thing = session.query(SomeRelated).first()

Операции, выполняемые внутри блока with:, не будут подвержены смыву при обращении к запросу. Это полезно при инициализации серии объектов, включающих существующие запросы к базе данных, когда незавершенный объект еще не должен быть смыт.

classmethod sqlalchemy.orm.Session.object_session(instance: object) → Optional[Session]¶

наследуется от sqlalchemy.orm.session._SessionClassMethods.object_session метода sqlalchemy.orm.session._SessionClassMethods

Возвращает Session, к которому принадлежит объект.

Это псевдоним object_session().

method sqlalchemy.orm.Session.prepare() → None¶

Подготовить текущую транзакцию к двухфазной фиксации.

Если транзакция не выполняется, то этот метод вызывает ошибку InvalidRequestError.

Могут быть подготовлены только корневые транзакции двухфазных сессий. Если текущая транзакция таковой не является, то выдается сообщение InvalidRequestError.

method sqlalchemy.orm.Session.query(*entities: _ColumnsClauseArgument[Any], **kwargs: Any) → Query[Any]¶

Возвращает новый объект Query, соответствующий данному Session.

Отметим, что объект Query является наследием SQLAlchemy 2.0; конструкция select() теперь используется для построения ORM-запросов.

См.также

Унифицированный учебник по SQLAlchemy

Руководство по составлению запросов в ORM

Legacy Query API - унаследованный документ по API

method sqlalchemy.orm.Session.refresh(instance: object, attribute_names: Optional[Iterable[str]] = None, with_for_update: ForUpdateParameter = None) → None¶

Истечение срока действия и обновление атрибутов для данного экземпляра.

Выбранные атрибуты сначала будут просрочены, как и при использовании Session.expire(); затем в базу данных будет отправлен оператор SELECT для обновления атрибутов, ориентированных на столбцы, текущим значением, доступным в текущей транзакции.

Атрибуты, ориентированные на relationship(), также будут немедленно загружены, если они уже были загружены в объект с нетерпением, с использованием той же стратегии нетерпеливой загрузки, с которой они были загружены первоначально.

Добавлено в версии 1.4: - the Session.refresh() method can also refresh eagerly loaded attributes.

Атрибуты, ориентированные на relationship(), которые обычно загружаются с использованием стратегии select (или «ленивой») загрузки, также будут загружаться если они явно названы в коллекции attribute_names, выдавая оператор SELECT для атрибута с использованием стратегии immediate. Если отношения с «ленивой загрузкой» не поименованы в Session.refresh.attribute_names, то они остаются «лениво загруженными» атрибутами и неявно не обновляются.

Изменено в версии 2.0.4: Метод Session.refresh() теперь будет обновлять лениво загруженные relationship() ориентированные атрибуты на те, которые явно названы в коллекции Session.refresh.attribute_names.

Совет

Хотя метод Session.refresh() способен обновлять атрибуты, ориентированные как на столбцы, так и на отношения, его основной задачей является обновление локальных атрибутов, ориентированных на столбцы, на одном экземпляре. Для более широких возможностей обновления, включая возможность обновления атрибутов сразу для многих объектов при явном контроле над стратегиями загрузчика отношений, используйте функцию populate existing.

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

Параметры:

attribute_names – опционально. Итерабельная коллекция строковых имен атрибутов, указывающих на подмножество атрибутов, которые необходимо обновить.
with_for_update – необязательное булево True, указывающее, что должен использоваться FOR UPDATE, или может быть словарем, содержащим флаги для указания более конкретного набора флагов FOR UPDATE для SELECT; флаги должны соответствовать параметрам Query.with_for_update(). Заменяет параметр Session.refresh.lockmode.

См.также

Обновление / истечение срока действия - вводный материал

Session.expire()

Session.expire_all()

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

method sqlalchemy.orm.Session.rollback() → None¶

Откат текущей выполняемой транзакции.

Если транзакция не проводится, этот метод является сквозным.

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

См.также

Откат

Управление транзакциями

method sqlalchemy.orm.Session.scalar(statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) → Any¶

Выполнить оператор и вернуть скалярный результат.

Использование и параметры такие же, как у Session.execute(); возвращаемый результат - скалярное значение Python.

method sqlalchemy.orm.Session.scalars(statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) → ScalarResult[Any]¶

Выполнить оператор и вернуть результаты в виде скаляров.

Использование и параметры те же, что и у Session.execute(); возвращаемый результат - объект фильтрации ScalarResult, который будет возвращать отдельные элементы, а не объекты Row.

Результат:: объект ScalarResult

Добавлено в версии 1.4.24: Добавлено Session.scalars()

Добавлено в версии 1.4.26: Добавлено scoped_session.scalars()

См.также

Выбор сущностей ORM - противопоставляет поведение Session.execute() поведению Session.scalars()

class sqlalchemy.orm.SessionTransaction¶

Транзакция уровня Session.

SessionTransaction образуется из методов Session.begin() и Session.begin_nested(). Это в основном внутренний объект, который в современном использовании обеспечивает контекстный менеджер для сеансовых транзакций.

Документация по взаимодействию с SessionTransaction находится по адресу: Управление транзакциями.

Изменено в версии 1.4: Упрощены скопинг и методы API для работы с объектом SessionTransaction напрямую.

См.также

Управление транзакциями

Session.begin()

Session.begin_nested()

Session.rollback()

Session.commit()

Session.in_transaction()

Session.in_nested_transaction()

Session.get_transaction()

Session.get_nested_transaction()

Members

nested, origin, parent

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

класс sqlalchemy.orm.SessionTransaction (sqlalchemy.orm.state_changes._StateChange, sqlalchemy.engine.util.TransactionalContext)

attribute sqlalchemy.orm.SessionTransaction.nested: bool = False¶

Указывает, является ли данная транзакция вложенной, или SAVEPOINT, транзакцией.

Если SessionTransaction.nested имеет значение True, то ожидается, что SessionTransaction.parent также будет присутствовать, связываясь с вложенным SessionTransaction.

См.также

SessionTransaction.origin

attribute sqlalchemy.orm.SessionTransaction.origin: SessionTransactionOrigin¶

Происхождение этого SessionTransaction.

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

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

attribute sqlalchemy.orm.SessionTransaction.parent¶

Родитель SessionTransaction данного SessionTransaction.

Если этот атрибут равен None, то это означает, что данная SessionTransaction находится на вершине стека и соответствует реальному блоку «COMMIT»/»ROLLBACK». Если не``None``, то это либо «субтранзакция» (внутренний объект-маркер, используемый процессом flush), либо «вложенная» / SAVEPOINT транзакция. Если атрибут SessionTransaction.nested равен True, то это SAVEPOINT, а если False, то это субтранзакция.

class sqlalchemy.orm.SessionTransactionOrigin¶

указывает на происхождение SessionTransaction.

Это перечисление присутствует в атрибуте SessionTransaction.origin любого объекта SessionTransaction.

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

Members

AUTOBEGIN, BEGIN, BEGIN_NESTED, SUBTRANSACTION

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

класс sqlalchemy.orm.SessionTransactionOrigin (enum.Enum)

attribute sqlalchemy.orm.SessionTransactionOrigin.AUTOBEGIN = 0¶: транзакции были начаты автобегином

attribute sqlalchemy.orm.SessionTransactionOrigin.BEGIN = 1¶: транзакция была запущена вызовом Session.begin()

attribute sqlalchemy.orm.SessionTransactionOrigin.BEGIN_NESTED = 2¶: транзакция была начата Session.begin_nested().

attribute sqlalchemy.orm.SessionTransactionOrigin.SUBTRANSACTION = 3¶: транзакция является внутренней «субтранзакцией»

Утилиты сессии¶

Object Name	Description
close_all_sessions()	Закрыть все сессии в памяти.
make_transient(instance)	Измените состояние данного экземпляра так, чтобы оно было transient.
make_transient_to_detached(instance)	Сделать заданный переходный экземпляр detached.
object_session(instance)	Возвращает `Session`, к которому принадлежит данный экземпляр.
was_deleted(object_)	Возвращает True, если заданный объект был удален в рамках session flush.

function sqlalchemy.orm.close_all_sessions() → None¶

Закрыть все сессии в памяти.

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

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

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

function sqlalchemy.orm.make_transient(instance: object) → None¶

Измените состояние данного экземпляра так, чтобы оно было transient.

Примечание

make_transient() - это специальная функция, предназначенная только для расширенных случаев использования.

Предполагается, что данный отображаемый экземпляр находится в состоянии persistent или detached. Функция удалит его связь с любым Session, а также его InstanceState.identity. В результате объект будет вести себя так, как будто он только что создан, за исключением сохранения всех значений атрибутов/коллекций, которые были загружены на момент вызова. Флаг InstanceState.deleted также сбрасывается, если этот объект был удален в результате использования Session.delete().

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

make_transient() не открывает или иным образом нетерпеливо загружает ORM-атрибуты, которые не загружены на момент вызова функции. К ним относятся атрибуты, которые:

истекали через Session.expire()
истекали как естественный эффект фиксации сеансовой транзакции, например, Session.commit()
обычно lazy loaded, но в данный момент не загружены
являются «отложенными» (см. Ограничение загрузки столбцов с помощью функции Column Deferral) и еще не загружены
не присутствовали в запросе, загрузившем этот объект, как это часто бывает при наследовании объединенных таблиц и в других сценариях.

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

См.также

make_transient_to_detached()

function sqlalchemy.orm.make_transient_to_detached(instance: object) → None¶

Сделать заданный переходный экземпляр detached.

Примечание

make_transient_to_detached() - это специальная функция, предназначенная только для расширенных случаев использования.

Вся история атрибутов данного экземпляра будет сброшена, как если бы экземпляр был только что загружен из запроса. Отсутствующие атрибуты будут помечены как просроченные. Атрибуты первичного ключа объекта, которые являются обязательными, будут превращены в «ключ» экземпляра.

Затем объект может быть добавлен в сессию или объединен, возможно, с флагом load=False, и тогда он будет выглядеть так, как будто он был загружен таким образом, не выдавая SQL.

Это специальная функция, которая отличается от обычного вызова Session.merge() тем, что заданное постоянное состояние может быть получено без каких-либо вызовов SQL.

См.также

make_transient()

Session.enable_relationship_loading()

function sqlalchemy.orm.object_session(instance: object) → Optional[Session]¶

Возвращает Session, к которому принадлежит данный экземпляр.

По сути, это то же самое, что и аксессор InstanceState.session. Подробности см. в этом атрибуте.

function sqlalchemy.orm.util.was_deleted(object_: object) → bool¶

Возвращает True, если заданный объект был удален в рамках session flush.

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

См.также

InstanceState.was_deleted

Утилиты управления атрибутами и состояниями¶

Эти функции предоставляются SQLAlchemy attribute instrumentation API, чтобы обеспечить детальный интерфейс для работы с экземплярами, значениями атрибутов и историей. Некоторые из них полезны при построении функций-слушателей событий, например, описанных в События ОРМ.

Object Name	Description
del_attribute(instance, key)	Удаление значения атрибута, вызывающее события истории.
flag_dirty(instance)	Пометить экземпляр как «грязный» без указания какого-либо конкретного атрибута.
flag_modified(instance, key)	Пометить атрибут экземпляра как «измененный».
get_attribute(instance, key)	Получить значение атрибута, отменив все необходимые вызовы.
get_history(obj, key[, passive])	Возвращает запись `History` для заданного объекта и ключа атрибута.
History	Трехкортеж из добавленных, неизмененных и удаленных значений, представляющий изменения, произошедшие с инструментированным атрибутом.
init_collection(obj, key)	Инициализирует атрибут коллекции и возвращает адаптер коллекции.
instance_state	Возвращает `InstanceState` для заданного отображаемого объекта.
is_instrumented(instance, key)	Возвращает True, если заданный атрибут для данного экземпляра инструментирован пакетом attributes.
object_state(instance)	Если задан объект, то возвращается `InstanceState`, связанный с этим объектом.
set_attribute(instance, key, value[, initiator])	Устанавливает значение атрибута, вызывая события истории.
set_committed_value(instance, key, value)	Установить значение атрибута, не имеющего событий в истории.

function sqlalchemy.orm.util.object_state(instance: _T) → InstanceState[_T]¶

Если задан объект, то возвращается InstanceState, связанный с этим объектом.

Возникает sqlalchemy.orm.exc.UnmappedInstanceError, если отображение не настроено.

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

inspect(instance)

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

function sqlalchemy.orm.attributes.del_attribute(instance: object, key: str) → None¶

Удаление значения атрибута, вызывающее события истории.

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

function sqlalchemy.orm.attributes.get_attribute(instance: object, key: str) → Any¶

Получить значение атрибута, отменив все необходимые вызовы.

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

function sqlalchemy.orm.attributes.get_history(obj: object, key: str, passive: PassiveFlag = symbol('PASSIVE_OFF')) → History¶

Возвращает запись History для заданного объекта и ключа атрибута.

Это история pre-flush для данного атрибута, которая сбрасывается каждый раз, когда Session сбрасывает изменения в текущую транзакцию базы данных.

Примечание

Предпочтительнее использовать аксессоры AttributeState.history и AttributeState.load_history() для получения атрибутов экземпляра History.

Параметры:

obj – объект, класс которого инструментирован пакетом attributes.
key – строковое имя атрибута.
passive – указывает на поведение при загрузке атрибута, если значение еще не присутствует. Это атрибут bitflag, который по умолчанию имеет символ PASSIVE_OFF, указывающий на то, что все необходимые SQL должны быть выданы.

См.также

AttributeState.history

AttributeState.load_history() - получение истории с помощью вызываемых элементов загрузчика, если значение не присутствует локально.

function sqlalchemy.orm.attributes.init_collection(obj: object, key: str) → CollectionAdapter¶

Инициализирует атрибут коллекции и возвращает адаптер коллекции.

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

collection_adapter = init_collection(someobject, 'elements')
for elem in values:
    collection_adapter.append_without_event(elem)

Более простой способ выполнения описанных выше действий приведен в разделе set_committed_value().

Параметры:

obj – отображаемый объект
key – строковое имя атрибута, в котором находится коллекция.

function sqlalchemy.orm.attributes.flag_modified(instance: object, key: str) → None¶

Пометить атрибут экземпляра как «измененный».

Это устанавливает флаг „modified“ для экземпляра и устанавливает безусловное событие изменения для заданного атрибута. В атрибуте должно присутствовать значение, в противном случае выдается сообщение InvalidRequestError.

Чтобы пометить объект «грязным» без ссылки на какой-либо конкретный атрибут, чтобы он рассматривался в рамках flush, используйте вызов flag_dirty().

См.также

flag_dirty()

function sqlalchemy.orm.attributes.flag_dirty(instance: object) → None¶

Пометить экземпляр как «грязный» без указания какого-либо конкретного атрибута.

Это специальная операция, которая позволит объекту пройти через процесс flush для перехвата такими событиями, как SessionEvents.before_flush(). Обратите внимание, что для объекта, не имеющего изменений, даже если он был помечен грязным с помощью этого метода, в процессе flush не будет выдан SQL. Однако обработчик SessionEvents.before_flush() сможет увидеть объект в коллекции Session.dirty и может установить в нем изменения, которые затем будут включены в выдаваемый SQL.

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

См.также

flag_modified()

function sqlalchemy.orm.attributes.instance_state()¶

Возвращает InstanceState для заданного отображаемого объекта.

Эта функция является внутренней версией object_state(). Здесь предпочтительнее использовать функцию object_state() и/или inspect(), поскольку каждая из них выдает информативное исключение, если данный объект не сопоставлен.

function sqlalchemy.orm.instrumentation.is_instrumented(instance, key)¶

Возвращает True, если заданный атрибут для данного экземпляра инструментирован пакетом attributes.

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

function sqlalchemy.orm.attributes.set_attribute(instance: object, key: str, value: Any, initiator: Optional[AttributeEventToken] = None) → None¶

Устанавливает значение атрибута, вызывая события истории.

Параметры:

instance – объект, который будет изменен
key – строковое имя атрибута
value – значение для присвоения
initiator – экземпляр Event, который был бы передан от предыдущего слушателя событий. Этот аргумент используется, когда функция set_attribute() используется внутри существующей функции прослушивания событий, в которую передается объект Event; этот объект может быть использован для отслеживания начала цепочки событий. … versionadded:: 1.2.3

function sqlalchemy.orm.attributes.set_committed_value(instance, key, value)¶

Установить значение атрибута, не имеющего событий в истории.

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

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

class sqlalchemy.orm.attributes.History¶

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

Самый простой способ получить объект History для определенного атрибута объекта - использовать функцию inspect():

from sqlalchemy import inspect

hist = inspect(myobject).attrs.myattribute.history

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

added - коллекция элементов, добавляемых к атрибуту (первый элемент кортежа).
unchanged - коллекция элементов, не изменившихся по атрибуту (второй элемент кортежа).
deleted - коллекция элементов, которые были удалены из атрибута (третий элемент кортежа).

Members

added, deleted, empty(), has_changes(), non_added(), non_deleted(), sum(), unchanged

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

класс sqlalchemy.orm.History (builtins.tuple)

attribute sqlalchemy.orm.attributes.History.added: Union[Tuple[()], List[Any]]¶: Псевдоним для номера поля 0

attribute sqlalchemy.orm.attributes.History.deleted: Union[Tuple[()], List[Any]]¶: Псевдоним для поля номер 2

method sqlalchemy.orm.attributes.History.empty() → bool¶: Возвращает True, если данная History не имеет изменений и существующего, неизменного состояния.

method sqlalchemy.orm.attributes.History.has_changes() → bool¶: Возвращает True, если в данном History произошли изменения.

method sqlalchemy.orm.attributes.History.non_added() → Sequence[Any]¶: Возвращает коллекцию неизмененных + удаленных.

method sqlalchemy.orm.attributes.History.non_deleted() → Sequence[Any]¶: Возвращает коллекцию добавленных + неизмененных.

method sqlalchemy.orm.attributes.History.sum() → Sequence[Any]¶: Возвращает коллекцию добавленных + неизмененных + удаленных.

attribute sqlalchemy.orm.attributes.History.unchanged: Union[Tuple[()], List[Any]]¶: Псевдоним для поля номер 1

Отслеживание запросов, изменений объектов и сессий с помощью событий

События и внутренние компоненты

Вернуться на верх

API сессии¶

Session и sessionmaker()¶

Утилиты сессии¶

Утилиты управления атрибутами и состояниями¶

SQLAlchemy 2.0

Содержание

Дополнительно

Вы здесь: