Государственное управление¶

Краткое введение в состояния объектов¶

Полезно знать состояния, в которых может находиться экземпляр в течение сессии:

• Transient - экземпляр, который не находится в сессии и не сохраняется в базе данных; т.е. он не имеет идентификатора базы данных. Единственная связь такого объекта с ORM заключается в том, что его класс имеет Mapper, связанный с ним.

• Pending - когда вы Session.add() переходящий экземпляр, он становится ожидающим. На самом деле он еще не был сброшен в базу данных, но будет сброшен при следующем сбросе.

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

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

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

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

>>> from sqlalchemy import inspect
>>> insp = inspect(my_object)
>>> insp.persistent
True

Атрибуты сессии¶

Сам Session действует в некотором роде как коллекция, подобная множеству. Доступ ко всем присутствующим элементам можно получить с помощью интерфейса итератора:

for obj in session:
    print(obj)

А наличие можно проверить, используя обычную семантику «содержит»:

if obj in session:
    print("Object is present")

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

# pending objects recently added to the Session
session.new

# persistent objects which currently have changes detected
# (this collection is now created on the fly each time the property is called)
session.dirty

# persistent objects that have been marked as deleted via session.delete(obj)
session.deleted

# dictionary of all persistent objects, keyed on their
# identity key
session.identity_map

(Документация: Session.new, Session.dirty, Session.deleted, Session.identity_map).

Поведение при обращении к сеансам¶

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

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

Также возможен подход, основанный на событиях. Простой рецепт, обеспечивающий поведение «сильной ссылки» для всех объектов, пока они остаются в состоянии persistent, выглядит следующим образом:

from sqlalchemy import event


def strong_reference_session(session):
    @event.listens_for(session, "pending_to_persistent")
    @event.listens_for(session, "deleted_to_persistent")
    @event.listens_for(session, "detached_to_persistent")
    @event.listens_for(session, "loaded_as_persistent")
    def strong_ref_object(sess, instance):
        if "refs" not in sess.info:
            sess.info["refs"] = refs = set()
        else:
            refs = sess.info["refs"]

        refs.add(instance)

    @event.listens_for(session, "persistent_to_detached")
    @event.listens_for(session, "persistent_to_deleted")
    @event.listens_for(session, "persistent_to_transient")
    def deref_object(sess, instance):
        sess.info["refs"].discard(instance)

Выше мы перехватили крючки событий SessionEvents.pending_to_persistent(), SessionEvents.detached_to_persistent(), SessionEvents.deleted_to_persistent() и SessionEvents.loaded_as_persistent(), чтобы перехватывать объекты, когда они входят в переход persistent, и крючки SessionEvents.persistent_to_detached() и SessionEvents.persistent_to_deleted(), чтобы перехватывать объекты, когда они выходят из постоянного состояния.

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

from sqlalchemy.orm import Session

my_session = Session()
strong_reference_session(my_session)

Он также может быть вызван для любого sessionmaker:

from sqlalchemy.orm import sessionmaker

maker = sessionmaker()
strong_reference_session(maker)

Объединение¶

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

merged_object = session.merge(existing_object)

Когда ему дается экземпляр, он выполняет следующие действия:

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

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

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

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

• Операция каскадируется на связанные объекты и коллекции, на что указывает каскад merge (см. Каскады).

• Возвращается новый экземпляр.

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

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

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

  В случае использования кэширования обычно используется флаг load=False, чтобы снять накладные расходы на согласование состояния объекта с базой данных. Существует также «объемная» версия Session.merge() под названием Query.merge_result(), которая была разработана для работы с расширенными кэшем объектами Query - см. раздел Кэширование Dogpile.

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

  В случае использования «передачи между потоками/процессами» приложение может захотеть использовать флаг load=False, чтобы избежать накладных расходов и избыточных SQL-запросов при передаче данных.

class User(Base):
    __tablename__ = "user"

    id = mapped_column(Integer, primary_key=True)
    name = mapped_column(String(50), nullable=False)
    addresses = relationship("Address", backref="user")


class Address(Base):
    __tablename__ = "address"

    id = mapped_column(Integer, primary_key=True)
    email_address = mapped_column(String(50), nullable=False)
    user_id = mapped_column(Integer, ForeignKey("user.id"), nullable=False)

>>> u1 = User(name="ed", addresses=[Address(email_address="ed@ed.com")])
>>> session.add(u1)
>>> session.commit()

>>> existing_a1 = u1.addresses[0]
>>> a1 = Address(id=existing_a1.id)

>>> a1.user = u1
>>> a1 = session.merge(a1)
>>> session.commit()
sqlalchemy.orm.exc.FlushError: New instance <Address at 0x1298f50>
with identity key (<class '__main__.Address'>, (1,)) conflicts with
persistent instance <Address at 0x12a25d0>

>>> a1 = Address()
>>> a1.user = u1
>>> a1 in session
True
>>> existing_a1 in session
True
>>> a1 is existing_a1
False

>>> a1 = Address(id=existing_a1.id, user_id=u1.id)
>>> a1.user = None
>>> a1 = session.merge(a1)
>>> session.commit()
sqlalchemy.exc.IntegrityError: (IntegrityError) address.user_id
may not be NULL

>>> a1 = Address(id=existing_a1, user_id=user.id)
>>> assert a1 not in session
>>> a1 = session.merge(a1)

>>> a1 = Address(id=existing_a1, user_id=user.id)
>>> a1.user
>>> a1.__dict__
{'_sa_instance_state': <sqlalchemy.orm.state.InstanceState object at 0x1298d10>,
    'user_id': 1,
    'id': 1,
    'user': None}
>>> # we don't want user=None merged, remove it
>>> del a1.user
>>> a1 = session.merge(a1)
>>> # success
>>> session.commit()

Expunging¶

Expunge удаляет объект из сессии, отправляя постоянные экземпляры в состояние detached, а отложенные экземпляры - в состояние transient:

session.expunge(obj1)

Чтобы удалить все элементы, вызовите Session.expunge_all() (ранее этот метод был известен как clear()).

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

Expiring означает, что хранящиеся в базе данных данные, содержащиеся в серии атрибутов объекта, стираются таким образом, что при следующем обращении к этим атрибутам будет выдан SQL-запрос, который обновит эти данные из базы данных.

Когда мы говорим об истечении срока действия данных, мы обычно имеем в виду объект, находящийся в состоянии persistent. Например, если мы загрузим объект следующим образом:

user = session.scalars(select(User).filter_by(name="user1").limit(1)).first()

Приведенный выше объект User является постоянным и имеет ряд атрибутов; если бы мы заглянули внутрь его __dict__, то увидели бы, что состояние загружено:

>>> user.__dict__
{
  'id': 1, 'name': u'user1',
  '_sa_instance_state': <...>,
}

где id и name относятся к этим столбцам в базе данных. _sa_instance_state - это значение, не относящееся к базе данных, используемое SQLAlchemy внутренне (оно ссылается на InstanceState для экземпляра. Хотя это не имеет прямого отношения к данному разделу, если мы хотим получить доступ к нему, мы должны использовать функцию inspect() для доступа к нему).

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

>>> session.expire(user)
>>> user.__dict__
{'_sa_instance_state': <...>}

Мы видим, что в то время как внутреннее «состояние» все еще сохраняется, значения, соответствующие столбцам id и name, исчезли. Если бы мы обратились к одному из этих столбцов и наблюдали за SQL, мы бы увидели следующее:

>>> print(user.name)
{execsql}SELECT user.id AS user_id, user.name AS user_name
FROM user
WHERE user.id = ?
(1,)
{stop}user1

Выше, при обращении к истекшему атрибуту user.name, ORM инициировал lazy load для получения последнего состояния из базы данных, выдав SELECT для строки пользователя, к которой относится этот пользователь. После этого __dict__ снова заполняется:

>>> user.__dict__
{
  'id': 1, 'name': u'user1',
  '_sa_instance_state': <...>,
}

Другим ключевым поведением как Session.expire(), так и Session.refresh() является то, что все изменения объекта, не прошедшие очистку, отбрасываются. То есть, если мы изменим атрибут нашего User:

>>> user.name = "user2"

но затем мы вызываем Session.expire() без предварительного вызова Session.flush(), наше ожидающее значение 'user2' отбрасывается:

>>> session.expire(user)
>>> user.name
'user1'

Метод Session.expire() может быть использован для пометки как «истекший» всех ORM-сопоставленных атрибутов для экземпляра:

# expire all ORM-mapped attributes on obj1
session.expire(obj1)

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

# expire only attributes obj1.attr1, obj1.attr2
session.expire(obj1, ["attr1", "attr2"])

Метод Session.expire_all() позволяет нам по существу вызывать Session.expire() на всех объектах, содержащихся внутри Session одновременно:

session.expire_all()

Метод Session.refresh() имеет аналогичный интерфейс, но вместо истечения срока действия он выдает немедленный SELECT для строки объекта сразу:

# reload all attributes on obj1
session.refresh(obj1)

Session.refresh() также принимает список строковых имен атрибутов, но, в отличие от Session.expire(), ожидает, что хотя бы одно имя будет именем атрибута, отображенного на столбец:

# reload obj1.attr1, obj1.attr2
session.refresh(obj1, ["attr1", "attr2"])

stmt = (
    select(User)
    .execution_options(populate_existing=True)
    .where((User.name.in_(["a", "b", "c"])))
)
for user in session.execute(stmt).scalars():
    print(user)  # will be refreshed for those columns that came back from the query