Асинхронный ввод/вывод (asyncio)¶
Поддержка Python asyncio. Включена поддержка использования Core и ORM с использованием диалектов, совместимых с asyncio.
Добавлено в версии 1.4.
Предупреждение
Пожалуйста, прочитайте Указания по установке платформы Asyncio (включая Apple M1) важные указания по установке для многих платформ, включая Apple M1 Architecture.
См.также
Поддержка асинхронного ввода-вывода в ядре и ORM - объявление о начале работы
Интеграция Asyncio - примеры скриптов, иллюстрирующие рабочие примеры использования Core и ORM в рамках расширения asyncio.
Указания по установке платформы Asyncio (включая Apple M1)¶
Расширение asyncio требует только Python 3. Оно также зависит от библиотеки greenlet. Эта зависимость устанавливается по умолчанию на распространенных машинных платформах, включая:
x86_64 aarch64 ppc64le amd64 win32
Для перечисленных выше платформ известно, что greenlet
поставляет предварительно собранные файлы wheel. Для других платформ greenlet не устанавливается по умолчанию; текущий листинг файлов для greenlet можно посмотреть по адресу Greenlet - Download Files. Обратите внимание, что не учтены многие архитектуры, включая Apple M1.
Чтобы установить SQLAlchemy и при этом обеспечить наличие зависимости greenlet
независимо от используемой платформы, можно установить [asyncio]
setuptools extra следующим образом, включив также инструкцию pip
по установке greenlet
:
pip install sqlalchemy[asyncio]
Обратите внимание, что установка greenlet
на платформах, не имеющих предварительно собранного файла wheel, означает, что greenlet
будет собираться из исходных текстов, что требует наличия библиотек разработки Python.
Синопсис - ядро¶
Для использования в Core функция create_async_engine()
создает экземпляр AsyncEngine
, который затем предлагает асинхронную версию традиционного API Engine
. Функция AsyncEngine
предоставляет AsyncConnection
через свои методы AsyncEngine.connect()
и AsyncEngine.begin()
, которые оба предоставляют асинхронные менеджеры контекста. Затем AsyncConnection
может вызывать операторы, используя либо метод AsyncConnection.execute()
для передачи буферизованного Result
, либо метод AsyncConnection.stream()
для передачи потокового серверного AsyncResult
:
import asyncio
from sqlalchemy import Column
from sqlalchemy import MetaData
from sqlalchemy import select
from sqlalchemy import String
from sqlalchemy import Table
from sqlalchemy.ext.asyncio import create_async_engine
meta = MetaData()
t1 = Table("t1", meta, Column("name", String(50), primary_key=True))
async def async_main() -> None:
engine = create_async_engine(
"postgresql+asyncpg://scott:tiger@localhost/test",
echo=True,
)
async with engine.begin() as conn:
await conn.run_sync(meta.create_all)
await conn.execute(
t1.insert(), [{"name": "some name 1"}, {"name": "some name 2"}]
)
async with engine.connect() as conn:
# select a Result, which will be delivered with buffered
# results
result = await conn.execute(select(t1).where(t1.c.name == "some name 1"))
print(result.fetchall())
# for AsyncEngine created in function scope, close and
# clean-up pooled connections
await engine.dispose()
asyncio.run(async_main())
Выше метод AsyncConnection.run_sync()
может быть использован для вызова специальных функций DDL, таких как MetaData.create_all()
, которые не содержат ожидающего хука.
Совет
Рекомендуется вызывать метод AsyncEngine.dispose()
с помощью await
при использовании объекта AsyncEngine
в области видимости, которая будет выходить из контекста и собираться в мусор, как это показано в функции async_main
в приведенном выше примере. Это гарантирует, что все соединения, открытые пулом соединений, будут правильно утилизированы в ожидающем контексте. В отличие от использования блокирующего ввода-вывода, SQLAlchemy не может правильно утилизировать эти соединения в методах типа __del__
или финализаторах weakref, поскольку нет возможности вызвать await
. Невыполнение явной утилизации движка при выходе его из области видимости может привести к выдаче предупреждений в стандартный вывод, напоминающих форму RuntimeError: Event loop is closed
при сборке мусора.
В AsyncConnection
также реализован «потоковый» API через метод AsyncConnection.stream()
, который возвращает объект AsyncResult
. Этот объект результата использует курсор на стороне сервера и предоставляет async/await API, такой как async iterator:
async with engine.connect() as conn:
async_result = await conn.stream(select(t1))
async for row in async_result:
print("row: %s" % (row,))
Синопсис - ORM¶
При использовании запросов 2.0 style класс AsyncSession
обеспечивает полную функциональность ORM. В режиме использования по умолчанию необходимо соблюдать особую осторожность, чтобы избежать lazy loading или другого доступа к атрибутам с истекшим сроком действия, связанным с ORM-отношениями и атрибутами столбцов; об этом подробно говорится в следующем разделе Предотвращение неявного ввода-вывода при использовании AsyncSession. В приведенном ниже примере показан полный пример, включающий конфигурацию маппера и сессии:
from __future__ import annotations
import asyncio
import datetime
from typing import List
from sqlalchemy import ForeignKey
from sqlalchemy import func
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncAttrs
from sqlalchemy.ext.asyncio import async_sessionmaker
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.orm import DeclarativeBase
from sqlalchemy.orm import Mapped
from sqlalchemy.orm import mapped_column
from sqlalchemy.orm import relationship
from sqlalchemy.orm import selectinload
class Base(AsyncAttrs, DeclarativeBase):
pass
class A(Base):
__tablename__ = "a"
id: Mapped[int] = mapped_column(primary_key=True)
data: Mapped[str]
create_date: Mapped[datetime.datetime] = mapped_column(server_default=func.now())
bs: Mapped[List[B]] = relationship()
class B(Base):
__tablename__ = "b"
id: Mapped[int] = mapped_column(primary_key=True)
a_id: Mapped[int] = mapped_column(ForeignKey("a.id"))
data: Mapped[str]
async def insert_objects(async_session: async_sessionmaker[AsyncSession]) -> None:
async with async_session() as session:
async with session.begin():
session.add_all(
[
A(bs=[B(), B()], data="a1"),
A(bs=[], data="a2"),
A(bs=[B(), B()], data="a3"),
]
)
async def select_and_update_objects(
async_session: async_sessionmaker[AsyncSession],
) -> None:
async with async_session() as session:
stmt = select(A).options(selectinload(A.bs))
result = await session.execute(stmt)
for a1 in result.scalars():
print(a1)
print(f"created at: {a1.create_date}")
for b1 in a1.bs:
print(b1)
result = await session.execute(select(A).order_by(A.id).limit(1))
a1 = result.scalars().one()
a1.data = "new data"
await session.commit()
# access attribute subsequent to commit; this is what
# expire_on_commit=False allows
print(a1.data)
# alternatively, AsyncAttrs may be used to access any attribute
# as an awaitable (new in 2.0.13)
for b1 in await a1.awaitable_attrs.bs:
print(b1)
async def async_main() -> None:
engine = create_async_engine(
"postgresql+asyncpg://scott:tiger@localhost/test",
echo=True,
)
# async_sessionmaker: a factory for new AsyncSession objects.
# expire_on_commit - don't expire objects after transaction commit
async_session = async_sessionmaker(engine, expire_on_commit=False)
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.create_all)
await insert_objects(async_session)
await select_and_update_objects(async_session)
# for AsyncEngine created in function scope, close and
# clean-up pooled connections
await engine.dispose()
asyncio.run(async_main())
В приведенном примере AsyncSession
инстанцируется с помощью дополнительного помощника async_sessionmaker
, который предоставляет фабрику для создания новых объектов AsyncSession
с фиксированным набором параметров, что в данном случае включает ассоциацию его с AsyncEngine
по определенному URL базы данных. Затем он передается в другие методы, где может быть использован в асинхронном менеджере контекста Python (т.е. в операторе async with:
) так, что автоматически закрывается в конце блока; это эквивалентно вызову метода AsyncSession.close()
.
Предотвращение неявного ввода-вывода при использовании AsyncSession¶
При использовании традиционного asyncio приложение должно избегать точек, в которых может произойти обращение к атрибуту IO-on-attribute. Ниже приведены приемы, которые могут быть использованы для этого, многие из них проиллюстрированы в предыдущем примере.
Атрибуты, которые являются отношениями ленивой загрузки, отложенными столбцами или выражениями, или к которым осуществляется доступ в сценариях истечения срока действия, могут воспользоваться преимуществами миксина
AsyncAttrs
. Этот миксин, добавленный к конкретному классу или, в более общем случае, к суперклассу DeclarativeBase
, предоставляет аксессорAsyncAttrs.awaitable_attrs
, который доставляет любой атрибут в виде ожидаемого:from __future__ import annotations from typing import List from sqlalchemy.ext.asyncio import AsyncAttrs from sqlalchemy.orm import DeclarativeBase from sqlalchemy.orm import Mapped from sqlalchemy.orm import relationship class Base(AsyncAttrs, DeclarativeBase): pass class A(Base): __tablename__ = "a" # ... rest of mapping ... bs: Mapped[List[B]] = relationship() class B(Base): __tablename__ = "b" # ... rest of mapping ...
Для доступа к коллекции
A.bs
на только что загруженных экземплярахA
, когда не используется eager loading, обычно используется lazy loading, который для достижения успеха обычно выполняет IO к базе данных, что в условиях asyncio будет невозможно, так как неявное IO не допускается. Чтобы получить доступ к этому атрибуту непосредственно в asyncio без предварительных операций загрузки, к атрибуту можно обратиться как к awaitable, указав префиксAsyncAttrs.awaitable_attrs
:a1 = (await session.scalars(select(A))).one() for b1 in await a1.awaitable_attrs.bs: print(b1)
Миксин
AsyncAttrs
обеспечивает лаконичный фасад над внутренним подходом, который также используется в методеAsyncSession.run_sync()
.Добавлено в версии 2.0.13.
См.также
Коллекции могут быть заменены на коллекции write only collection, которые никогда не будут выдавать IO неявно, с помощью функции Писать только отношения в SQLAlchemy 2.0. При использовании этой возможности коллекции никогда не читаются, а только запрашиваются с помощью явных вызовов SQL. Пример использования коллекций только для записи с помощью asyncio см. в разделе
async_orm_writeonly.py
Интеграция Asyncio.При использовании коллекций «только запись» поведение программы в отношении коллекций просто и легко предсказуемо. Однако недостатком является отсутствие встроенной системы одновременной загрузки множества таких коллекций, которую необходимо выполнять вручную. Поэтому многие из приведенных ниже пунктов посвящены конкретным приемам использования традиционных отношений с ленивой загрузкой в asyncio, что требует большей осторожности.
Если не использовать
AsyncAttrs
, то отношения можно объявить с помощьюlazy="raise"
, чтобы по умолчанию они не пытались выдать SQL. Для загрузки коллекций вместо этого следует использовать eager loading.Наиболее полезной стратегией ускоренной загрузки является стратегия ускоренной загрузки
selectinload()
, которая используется в предыдущем примере для ускоренной загрузки коллекцииA.bs
в области действия вызоваawait session.execute()
:stmt = select(A).options(selectinload(A.bs))
При конструировании новых объектов коллекции всегда присваивается пустая коллекция по умолчанию, например, список в приведенном выше примере:
A(bs=[], data="a2")
Это позволяет коллекции
.bs
на вышеуказанном объектеA
присутствовать и быть доступной для чтения, когда объектA
смывается; в противном случае, когда смываетсяA
,.bs
был бы выгружен и при обращении к нему возникла бы ошибка.Конфигурация
AsyncSession
выполняется с помощьюSession.expire_on_commit
, установленного в False, чтобы мы могли обращаться к атрибутам объекта после вызоваAsyncSession.commit()
, как в строке в конце, где мы обращаемся к атрибуту:# create AsyncSession with expire_on_commit=False async_session = AsyncSession(engine, expire_on_commit=False) # sessionmaker version async_session = async_sessionmaker(engine, expire_on_commit=False) async with async_session() as session: result = await session.execute(select(A).order_by(A.id)) a1 = result.scalars().first() # commit would normally expire all attributes await session.commit() # access attribute subsequent to commit; this is what # expire_on_commit=False allows print(a1.data)
Другие рекомендации включают:
От методов типа
AsyncSession.expire()
следует отказаться в пользуAsyncSession.refresh()
; если истечение срока действия абсолютно необходимо. Как правило, истечение не требуется, так как при использовании asyncio значениеSession.expire_on_commit
обычно должно быть установлено в значениеFalse
.Лениво загруженное отношение может быть загружено явно под asyncio с помощью
AsyncSession.refresh()
, если имя нужного атрибута передано явно вSession.refresh.attribute_names
, например:# assume a_obj is an A that has lazy loaded A.bs collection a_obj = await async_session.get(A, [1]) # force the collection to load by naming it in attribute_names await async_session.refresh(a_obj, ["bs"]) # collection is present print(f"bs collection: {a_obj.bs}")
Конечно, предпочтительнее использовать ускоренную загрузку, чтобы иметь уже настроенные коллекции без необходимости ленивой загрузки.
Добавлено в версии 2.0.4: Добавлена поддержка метода
AsyncSession.refresh()
и лежащего в его основе методаSession.refresh()
для принудительной загрузки лениво загружаемых отношений, если они явно названы в параметреSession.refresh.attribute_names
. В предыдущих версиях отношения молча пропускались, даже если они были названы в параметре.Избегайте использования опции
all
каскада, задокументированной в Каскады, в пользу явного перечисления желаемых свойств каскада. Опция каскадаall
подразумевает, в частности, настройку refresh-expire, которая означает, что методAsyncSession.refresh()
истечет срок действия атрибутов на связанных объектах, но не обязательно обновит эти связанные объекты, если вrelationship()
не настроена ускоренная загрузка, оставив их в истекшем состоянии.Для столбцов
deferred()
, если они вообще используются, должны применяться соответствующие опции загрузчика в дополнение к тем, которые были указаны выше для конструкцийrelationship()
. Подробнее об отложенной загрузке столбцов см. в разделе Ограничение загрузки столбцов с помощью функции Column Deferral.
Стратегия «динамического» загрузчика отношений, описанная в Динамические загрузчики отношений, по умолчанию не совместима с подходом asyncio. Она может быть использована напрямую только при вызове метода
AsyncSession.run_sync()
, описанного в Запуск синхронных методов и функций в asyncio, или при использовании его атрибута.statement
для получения обычного select:user = await session.get(User, 42) addresses = (await session.scalars(user.addresses.statement)).all() stmt = user.addresses.statement.where(Address.email_address.startswith("patrick")) addresses_filter = (await session.scalars(stmt)).all()
Техника write only, появившаяся в версии 2.0 SQLAlchemy, полностью совместима с asyncio и должна быть предпочтительнее.
См.также
«Динамические» загрузчики отношений вытеснены «только записью» - заметки о переходе на стиль 2.0
При использовании asyncio с базой данных, не поддерживающей RETURNING, например, MySQL 8, значения по умолчанию сервера, такие как сгенерированные временные метки, не будут доступны для вновь выгружаемых объектов, если не используется опция
Mapper.eager_defaults
. В SQLAlchemy 2.0 это поведение автоматически применяется к таким бэкендам, как PostgreSQL, SQLite и MariaDB, которые используют RETURNING для получения новых значений при INSERT строк.
Запуск синхронных методов и функций в asyncio¶
Deep Alchemy
Такой подход, по сути, является публичным раскрытием механизма, с помощью которого SQLAlchemy может предоставлять интерфейс asyncio в первую очередь. Несмотря на отсутствие технических проблем, в целом этот подход можно считать «спорным», поскольку он противоречит некоторым основным принципам модели программирования asyncio, которые заключаются в том, что любой программный оператор, который потенциально может привести к вызову ввода-вывода, **должен иметь вызов await
, чтобы в программе не было явно указано в каждой строке, в которой может произойти ввод-вывод. Данный подход не меняет этой общей идеи, за исключением того, что он позволяет освободить от этого правила серию синхронных инструкций ввода-вывода в рамках вызова функции, по сути, объединив их в один awaitable.
В качестве альтернативного средства интеграции традиционной «ленивой загрузки» SQLAlchemy в цикл событий asyncio предусмотрен опциональный метод AsyncSession.run_sync()
, который будет запускать любую функцию Python внутри гринлета, где традиционные концепции синхронного программирования будут переведены на использование await
, когда они достигнут драйвера базы данных. Гипотетический подход здесь заключается в том, что асинхронно-ориентированное приложение может упаковать методы, связанные с базой данных, в функции, которые вызываются с помощью AsyncSession.run_sync()
.
Если бы мы не использовали selectinload()
для коллекции A.bs
, то, изменяя приведенный выше пример, мы могли бы реализовать обработку этих обращений к атрибутам в отдельной функции:
import asyncio
from sqlalchemy import select
from sqlalchemy.ext.asyncio import AsyncSession, create_async_engine
def fetch_and_update_objects(session):
"""run traditional sync-style ORM code in a function that will be
invoked within an awaitable.
"""
# the session object here is a traditional ORM Session.
# all features are available here including legacy Query use.
stmt = select(A)
result = session.execute(stmt)
for a1 in result.scalars():
print(a1)
# lazy loads
for b1 in a1.bs:
print(b1)
# legacy Query use
a1 = session.query(A).order_by(A.id).first()
a1.data = "new data"
async def async_main():
engine = create_async_engine(
"postgresql+asyncpg://scott:tiger@localhost/test",
echo=True,
)
async with engine.begin() as conn:
await conn.run_sync(Base.metadata.drop_all)
await conn.run_sync(Base.metadata.create_all)
async with AsyncSession(engine) as session:
async with session.begin():
session.add_all(
[
A(bs=[B(), B()], data="a1"),
A(bs=[B()], data="a2"),
A(bs=[B(), B()], data="a3"),
]
)
await session.run_sync(fetch_and_update_objects)
await session.commit()
# for AsyncEngine created in function scope, close and
# clean-up pooled connections
await engine.dispose()
asyncio.run(async_main())
Приведенный выше подход к выполнению определенных функций в рамках «синхронизирующего» бегуна имеет некоторые параллели с приложением, запускающим приложение SQLAlchemy поверх библиотеки событийного программирования, такой как gevent
. Отличия заключаются в следующем:
В отличие от использования
gevent
, мы можем продолжать использовать стандартный цикл событий Python asyncio или любой пользовательский цикл событий, без необходимости интегрироваться в цикл событийgevent
.Никакого «обезьянничанья» не происходит. В приведенном примере используется реальный драйвер asyncio, а пул соединений SQLAlchemy также использует встроенную в Python функцию
asyncio.Queue
для пула соединений.Программа может свободно переключаться между кодом async/await и содержащимися в ней функциями, использующими код sync, практически без ущерба для производительности. Нет ни «исполнителя потока», ни дополнительных ожидающих или синхронизирующих устройств.
В качестве базовых сетевых драйверов также используются чисто питоновские концепции asyncio, никаких сторонних сетевых библиотек, как это делают
gevent
иeventlet
, не используется.
Использование событий с помощью расширения asyncio¶
SQLAlchemy event system не подвергается прямому воздействию со стороны расширения asyncio, то есть пока не существует «асинхронной» версии обработчика событий SQLAlchemy.
Однако, поскольку расширение asyncio окружает обычный синхронный API SQLAlchemy, обычные обработчики событий в «синхронном» стиле свободно доступны, как это было бы, если бы asyncio не использовалось.
Как будет показано ниже, в настоящее время существует две стратегии регистрации событий в asyncio-facing API:
События могут быть зарегистрированы на уровне экземпляра (например, конкретного экземпляра
AsyncEngine
) путем связывания события с атрибутомsync
, который ссылается на проксируемый объект. Например, чтобы зарегистрировать событиеPoolEvents.connect()
против экземпляраAsyncEngine
, используйте в качестве цели его атрибутAsyncEngine.sync_engine
. К целям относятся:Для регистрации события на уровне класса, направленного на все экземпляры одного типа (например, на все экземпляры
AsyncSession
), используйте соответствующий класс-стиль синхронизации. Например, чтобы зарегистрировать событиеSessionEvents.before_commit()
против классаAsyncSession
, используйте в качестве цели классSession
.Для регистрации на уровне
sessionmaker
объедините явныйsessionmaker
сasync_sessionmaker
, используяasync_sessionmaker.sync_session_class
, и свяжите события сsessionmaker
.
При работе в обработчике событий в контексте asyncio объекты, подобные Connection
, продолжают работать в привычном «синхронном» режиме, не требуя использования await
или async
; когда сообщения в конечном итоге поступают на адаптер базы данных asyncio, стиль вызова прозрачно адаптируется обратно к стилю вызова asyncio. Для событий, которым передается соединение уровня DBAPI, например PoolEvents.connect()
, объект представляет собой pep-249 совместимый объект «соединение», который будет адаптировать вызовы в стиле синхронизации к драйверу asyncio.
Примеры слушателей событий с Async Engines / Sessions / Sessionmakers¶
Ниже приведены примеры обработчиков событий в стиле sync, связанных с конструкциями async-facing API:
Основные события на AsyncEngine.
В данном примере мы обращаемся к атрибуту
AsyncEngine.sync_engine
вAsyncEngine
как к цели дляConnectionEvents
иPoolEvents
:import asyncio from sqlalchemy import event from sqlalchemy import text from sqlalchemy.engine import Engine from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine("postgresql+asyncpg://scott:tiger@localhost:5432/test") # connect event on instance of Engine @event.listens_for(engine.sync_engine, "connect") def my_on_connect(dbapi_con, connection_record): print("New DBAPI connection:", dbapi_con) cursor = dbapi_con.cursor() # sync style API use for adapted DBAPI connection / cursor cursor.execute("select 'execute from event'") print(cursor.fetchone()[0]) # before_execute event on all Engine instances @event.listens_for(Engine, "before_execute") def my_before_execute( conn, clauseelement, multiparams, params, execution_options, ): print("before execute!") async def go(): async with engine.connect() as conn: await conn.execute(text("select 1")) await engine.dispose() asyncio.run(go())
Выход:
New DBAPI connection: <AdaptedConnection <asyncpg.connection.Connection object at 0x7f33f9b16960>> execute from event before execute!
ORM Events on AsyncSession.
В данном примере мы обращаемся к
AsyncSession.sync_session
как к цели дляSessionEvents
:import asyncio from sqlalchemy import event from sqlalchemy import text from sqlalchemy.ext.asyncio import AsyncSession from sqlalchemy.ext.asyncio import create_async_engine from sqlalchemy.orm import Session engine = create_async_engine("postgresql+asyncpg://scott:tiger@localhost:5432/test") session = AsyncSession(engine) # before_commit event on instance of Session @event.listens_for(session.sync_session, "before_commit") def my_before_commit(session): print("before commit!") # sync style API use on Session connection = session.connection() # sync style API use on Connection result = connection.execute(text("select 'execute from event'")) print(result.first()) # after_commit event on all Session instances @event.listens_for(Session, "after_commit") def my_after_commit(session): print("after commit!") async def go(): await session.execute(text("select 1")) await session.commit() await session.close() await engine.dispose() asyncio.run(go())
Выход:
before commit! execute from event after commit!
ORM Events on async_sessionmaker.
Для данного случая мы создаем
sessionmaker
в качестве цели события, затем назначаем его наasync_sessionmaker
с помощью параметраasync_sessionmaker.sync_session_class
:import asyncio from sqlalchemy import event from sqlalchemy.ext.asyncio import async_sessionmaker from sqlalchemy.orm import sessionmaker sync_maker = sessionmaker() maker = async_sessionmaker(sync_session_class=sync_maker) @event.listens_for(sync_maker, "before_commit") def before_commit(session): print("before commit") async def main(): async_session = maker() await async_session.commit() asyncio.run(main())
Выход:
before commit
Использование методов драйвера только с ожиданием в пуле соединений и других событиях¶
Как уже говорилось выше, обработчики событий, например, ориентированные на обработчики событий PoolEvents
, получают синхронизированное соединение типа «DBAPI», которое представляет собой объект-обертку, предоставляемый диалектами SQLAlchemy asyncio для адаптации базового соединения asyncio «драйвера» к тому, которое может быть использовано внутренними средствами SQLAlchemy. Особый случай возникает, когда пользовательская реализация такого обработчика событий должна использовать конечное «драйверное» соединение напрямую, используя только методы awaitable на этом драйверном соединении. Одним из таких примеров является метод .set_type_codec()
, предоставляемый драйвером asyncpg.
Для реализации этого сценария в классе SQLAlchemy AdaptedConnection
предусмотрен метод AdaptedConnection.run_async()
, позволяющий вызывать ожидающую функцию в «синхронном» контексте обработчика событий или другого внутреннего модуля SQLAlchemy. Этот метод является прямым аналогом метода AsyncConnection.run_sync()
, позволяющего запускать метод в стиле sync в режиме async.
AdaptedConnection.run_async()
должна быть передана функция, которая будет принимать внутреннее соединение «драйвера» в качестве единственного аргумента и возвращать awaitable, который будет вызван методом AdaptedConnection.run_async()
. Саму функцию не обязательно объявлять как async
; вполне допустимо, чтобы она была Python lambda:
, поскольку возвращаемое значение awaitable будет вызвано после возврата:
from sqlalchemy import event
from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine(...)
@event.listens_for(engine.sync_engine, "connect")
def register_custom_types(dbapi_connection, *args):
dbapi_connection.run_async(
lambda connection: connection.set_type_codec(
"MyCustomType",
encoder,
decoder, # ...
)
)
Выше объект, передаваемый обработчику события register_custom_types
, является экземпляром AdaptedConnection
, который предоставляет DBAPI-подобный интерфейс к базовому асинхронному объекту соединения на уровне драйвера. Метод AdaptedConnection.run_async()
предоставляет доступ к ожидающей среде, в которой могут выполняться действия с базовым соединением на уровне драйвера.
Добавлено в версии 1.4.30.
Использование нескольких циклов событий asyncio¶
Приложение, использующее несколько циклов событий, например, в редком случае сочетания asyncio с многопоточностью, не должно использовать один и тот же AsyncEngine
с разными циклами событий при использовании стандартной реализации пула.
Если AsyncEngine
передается из одного цикла событий в другой, то перед его повторным использованием в новом цикле событий необходимо вызвать метод AsyncEngine.dispose()
. В противном случае может возникнуть ошибка RuntimeError
, подобная Task <Task pending ...> got Future attached to a different loop
.
Если один и тот же движок должен использоваться в разных циклах, то его следует настроить на отключение пула с помощью NullPool
, что не позволит движку использовать любое соединение более одного раза:
from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.pool import NullPool
engine = create_async_engine(
"postgresql+asyncpg://user:pass@host/dbname",
poolclass=NullPool,
)
Использование asyncio scoped session¶
Шаблон «scoped session», используемый в потоковой SQLAlchemy с объектом scoped_session
, доступен и в asyncio, используя адаптированную версию под названием async_scoped_session
.
Совет
В целом SQLAlchemy не рекомендует использовать паттерн «scoped» для новых разработок, поскольку он опирается на изменяемое глобальное состояние, которое также должно быть явно уничтожено по завершении работы внутри потока или задачи. В частности, при использовании asyncio, вероятно, лучше передавать AsyncSession
непосредственно в функции ожидания, которым это необходимо.
При использовании async_scoped_session
, поскольку в контексте asyncio не существует понятия «поток-локал», в конструкторе необходимо указать параметр «scopefunc». Приведенный ниже пример иллюстрирует использование для этой цели функции asyncio.current_task()
:
from asyncio import current_task
from sqlalchemy.ext.asyncio import (
async_scoped_session,
async_sessionmaker,
)
async_session_factory = async_sessionmaker(
some_async_engine,
expire_on_commit=False,
)
AsyncScopedSession = async_scoped_session(
async_session_factory,
scopefunc=current_task,
)
some_async_session = AsyncScopedSession()
Предупреждение
Функция «scopefunc», используемая async_scoped_session
, вызывается произвольное число раз в рамках задачи, по одному разу при каждом обращении к базовому AsyncSession
. Поэтому функция должна быть эдемпотентной и легковесной, и не должна пытаться создавать или мутировать какое-либо состояние, например, устанавливать обратные вызовы и т.д.
Предупреждение
Использование current_task()
для «ключа» в области видимости требует, чтобы метод async_scoped_session.remove()
вызывался из внешнего awaitable, чтобы обеспечить удаление ключа из реестра по завершении задачи, иначе хэндл задачи, а также AsyncSession
останутся в памяти, создавая, по сути, утечку памяти. Правильное использование async_scoped_session.remove()
показано в следующем примере.
async_scoped_session
включает поведение прокси, аналогичное поведению scoped_session
, что означает, что с ним можно обращаться как с AsyncSession
напрямую, помня о необходимости использования обычных ключевых слов await
, в том числе для метода async_scoped_session.remove()
:
async def some_function(some_async_session, some_object):
# use the AsyncSession directly
some_async_session.add(some_object)
# use the AsyncSession via the context-local proxy
await AsyncScopedSession.commit()
# "remove" the current proxied AsyncSession for the local context
await AsyncScopedSession.remove()
Добавлено в версии 1.4.19.
Использование инспектора для проверки объектов схемы¶
SQLAlchemy пока не предлагает asyncio-версию Inspector
(представленную в Мелкозернистое отражение с инспектором), однако существующий интерфейс может быть использован в контексте asyncio с помощью метода AsyncConnection.run_sync()
из AsyncConnection
:
import asyncio
from sqlalchemy import inspect
from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("postgresql+asyncpg://scott:tiger@localhost/test")
def use_inspector(conn):
inspector = inspect(conn)
# use the inspector
print(inspector.get_view_names())
# return any value to the caller
return inspector.get_table_names()
async def async_main():
async with engine.connect() as conn:
tables = await conn.run_sync(use_inspector)
asyncio.run(async_main())
Документация по API движка¶
Object Name | Description |
---|---|
async_engine_from_config(configuration[, prefix], **kwargs) |
Создайте новый экземпляр AsyncEngine, используя словарь конфигурации. |
Asyncio-прокси для |
|
Asyncio-прокси для |
|
Asyncio-прокси для |
|
create_async_engine(url, **kw) |
Создайте новый экземпляр асинхронного движка. |
create_async_pool_from_url(url, **kwargs) |
Создайте новый экземпляр асинхронного движка. |
- function sqlalchemy.ext.asyncio.create_async_engine(url: Union[str, URL], **kw: Any) AsyncEngine ¶
Создайте новый экземпляр асинхронного движка.
Аргументы, передаваемые в
create_async_engine()
, в основном идентичны аргументам, передаваемым в функциюcreate_engine()
. Указанный диалект должен быть asyncio-совместимым диалектом, например asyncpg.Добавлено в версии 1.4.
- Параметры:
async_creator – async-вызываемая функция, возвращающая asyncio-соединение на уровне драйвера. Если функция задана, то она не должна принимать никаких аргументов и возвращает новое asyncio-соединение от базового драйвера базы данных asyncio; соединение будет обернуто в соответствующие структуры для использования с
AsyncEngine
. Обратите внимание, что параметры, указанные в URL, здесь не применяются, и функция-создатель должна использовать свои собственные параметры соединения. Этот параметр является asyncio-эквивалентом параметраcreate_engine.creator
функцииcreate_engine()
. … versionadded:: 2.0.16
- function sqlalchemy.ext.asyncio.async_engine_from_config(configuration: Dict[str, Any], prefix: str = 'sqlalchemy.', **kwargs: Any) AsyncEngine ¶
Создайте новый экземпляр AsyncEngine, используя словарь конфигурации.
Эта функция аналогична функции
engine_from_config()
в SQLAlchemy Core, за исключением того, что запрашиваемый диалект должен быть asyncio-совместимым диалектом, например asyncpg. Сигнатура аргументов функции идентична сигнатуре аргументов функцииengine_from_config()
.Добавлено в версии 1.4.29.
- function sqlalchemy.ext.asyncio.create_async_pool_from_url(url: Union[str, URL], **kwargs: Any) Pool ¶
Создайте новый экземпляр асинхронного движка.
Аргументы, передаваемые в
create_async_pool_from_url()
, в основном идентичны аргументам, передаваемым в функциюcreate_pool_from_url()
. Указанный диалект должен быть asyncio-совместимым диалектом, например asyncpg.Добавлено в версии 2.0.10.
- class sqlalchemy.ext.asyncio.AsyncEngine¶
Asyncio-прокси для
Engine
.AsyncEngine
приобретается с помощью функцииcreate_async_engine()
:from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine("postgresql+asyncpg://user:pass@host/dbname")
Добавлено в версии 1.4.
Members
begin(), clear_compiled_cache(), connect(), dialect, dispose(), driver, echo, engine, execution_options(), get_execution_options(), name, pool, raw_connection(), sync_engine, update_execution_options(), url
Классическая подпись.
класс
sqlalchemy.ext.asyncio.AsyncEngine
(sqlalchemy.ext.asyncio.base.ProxyComparable
,sqlalchemy.ext.asyncio.AsyncConnectable
)-
method
sqlalchemy.ext.asyncio.AsyncEngine.
begin() AsyncIterator[AsyncConnection] ¶ Возвращает менеджер контекста, при вводе которого будет выдано сообщение
AsyncConnection
с установленнымAsyncTransaction
.Например:
async with async_engine.begin() as conn: await conn.execute( text("insert into table (x, y, z) values (1, 2, 3)") ) await conn.execute(text("my_special_procedure(5)"))
-
method
sqlalchemy.ext.asyncio.AsyncEngine.
clear_compiled_cache() None ¶ Очистить скомпилированный кэш, связанный с диалектом.
Проксирование класса
Engine
от имени классаAsyncEngine
.Это относится только к встроенному кэшу, который устанавливается через параметр
create_engine.query_cache_size
. Это не влияет на кэши словарей, которые были переданы через параметрConnection.execution_options.query_cache
.Добавлено в версии 1.4.
-
method
sqlalchemy.ext.asyncio.AsyncEngine.
connect() AsyncConnection ¶ Возвращает объект
AsyncConnection
.При вводе в качестве менеджера асинхронного контекста
AsyncConnection
будет получено соединение с базовой базой данных из пула соединений:async with async_engine.connect() as conn: result = await conn.execute(select(user_table))
Запуск
AsyncConnection
может быть осуществлен и вне контекстного менеджера путем вызова его методаAsyncConnection.start()
.
-
attribute
sqlalchemy.ext.asyncio.AsyncEngine.
dialect¶ Прокси для атрибута
Engine.dialect
от имени классаAsyncEngine
.
-
method
sqlalchemy.ext.asyncio.AsyncEngine.
async dispose(close: bool = True) None ¶ Утилизировать пул соединений, используемый данным
AsyncEngine
.- Параметры:
close – если оставить значение по умолчанию
True
, то это приведет к полному закрытию всех текущих проверенных соединений с базой данных. Соединения, которые все еще проверяются, не будут закрыты, однако они больше не будут связаны с этимEngine
, поэтому, когда они закрываются по отдельности, в конечном итогеPool
, с которым они связаны, будет собран мусор, и они будут полностью закрыты, если еще не были закрыты при регистрации. Если установлено значениеFalse
, то предыдущий пул соединений отменяется, и в остальном он никак не затрагивается.
См.также
-
attribute
sqlalchemy.ext.asyncio.AsyncEngine.
driver¶ Имя драйвера
Dialect
, используемого даннымEngine
.Проксирование класса
Engine
от имени классаAsyncEngine
.
-
attribute
sqlalchemy.ext.asyncio.AsyncEngine.
echo¶ Если
True
, включить вывод журнала для данного элемента.Проксирование класса
Engine
от имени классаAsyncEngine
.Это приводит к установке уровня протоколирования Python для пространства имен класса этого элемента и ссылки на объект. Значение boolean
True
указывает на то, что для регистратора будет установлен уровень регистрацииlogging.INFO
, в то время как строковое значениеdebug
установит уровень регистрацииlogging.DEBUG
.
-
attribute
sqlalchemy.ext.asyncio.AsyncEngine.
engine¶ Возвращает данный
Engine
.Проксирование класса
Engine
от имени классаAsyncEngine
.Используется для унаследованных схем, допускающих наличие объектов
Connection
/Engine
в пределах одной переменной.
-
method
sqlalchemy.ext.asyncio.AsyncEngine.
execution_options(**opt: Any) AsyncEngine ¶ Возвращает новый
AsyncEngine
, который будет предоставлять объектыAsyncConnection
с заданными параметрами выполнения.Проксируется из
Engine.execution_options()
. Подробности см. в этом методе.
-
method
sqlalchemy.ext.asyncio.AsyncEngine.
get_execution_options() _ExecuteOptions ¶ Получить опции, не относящиеся к языку SQL, которые будут действовать во время выполнения.
Проксирование класса
Engine
от имени классаAsyncEngine
.См.также
-
attribute
sqlalchemy.ext.asyncio.AsyncEngine.
name¶ Строковое имя
Dialect
, используемое даннымEngine
.Проксирование класса
Engine
от имени классаAsyncEngine
.
-
attribute
sqlalchemy.ext.asyncio.AsyncEngine.
pool¶ Прокси для атрибута
Engine.pool
от имени классаAsyncEngine
.
-
method
sqlalchemy.ext.asyncio.AsyncEngine.
async raw_connection() PoolProxiedConnection ¶ Возвращает «сырое» DBAPI-соединение из пула соединений.
-
attribute
sqlalchemy.ext.asyncio.AsyncEngine.
sync_engine: Engine¶ Ссылка на стиль синхронизации
Engine
, к которому данныйAsyncEngine
проксирует запросы.Этот экземпляр может быть использован в качестве цели события.
-
method
sqlalchemy.ext.asyncio.AsyncEngine.
update_execution_options(**opt: Any) None ¶ Обновить словарь execution_options по умолчанию для данного
Engine
.Проксирование класса
Engine
от имени классаAsyncEngine
.Заданные ключи/значения в **opt добавляются к опциям выполнения по умолчанию, которые будут использоваться для всех соединений. Начальное содержимое этого словаря может быть передано через параметр
execution_options
вcreate_engine()
.
-
attribute
sqlalchemy.ext.asyncio.AsyncEngine.
url¶ Прокси для атрибута
Engine.url
от имени классаAsyncEngine
.
-
method
- class sqlalchemy.ext.asyncio.AsyncConnection¶
Asyncio-прокси для
Connection
.AsyncConnection
приобретается с помощью методаAsyncEngine.connect()
изAsyncEngine
:from sqlalchemy.ext.asyncio import create_async_engine engine = create_async_engine("postgresql+asyncpg://user:pass@host/dbname") async with engine.connect() as conn: result = await conn.execute(select(table))
Добавлено в версии 1.4.
Members
begin(), begin_nested(), close(), closed, commit(), connection, default_isolation_level, dialect, exec_driver_sql(), execute(), execution_options(), get_nested_transaction(), get_raw_connection(), get_transaction(), in_nested_transaction(), in_transaction(), info, invalidate(), invalidated, rollback(), run_sync(), scalar(), scalars(), start(), stream(), stream_scalars(), sync_connection, sync_engine
Классическая подпись.
класс
sqlalchemy.ext.asyncio.AsyncConnection
(sqlalchemy.ext.asyncio.base.ProxyComparable
,sqlalchemy.ext.asyncio.base.StartableContext
,sqlalchemy.ext.asyncio.AsyncConnectable
)-
method
sqlalchemy.ext.asyncio.AsyncConnection.
begin() AsyncTransaction ¶ Начать транзакцию до того, как произойдет автозапуск.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
begin_nested() AsyncTransaction ¶ Начинает вложенную транзакцию и возвращает хэндл транзакции.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async close() None ¶ Закройте эту
AsyncConnection
.Это приводит к откату транзакции, если таковая уже существует.
-
attribute
sqlalchemy.ext.asyncio.AsyncConnection.
closed¶ Возвращает True, если данное соединение закрыто.
Проксирование класса
Connection
от имени классаAsyncConnection
.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async commit() None ¶ Зафиксировать транзакцию, находящуюся в данный момент в процессе выполнения.
Этот метод фиксирует текущую транзакцию, если она была начата. Если транзакция не была начата, то метод не имеет никакого эффекта, предполагая, что соединение находится в невалидированном состоянии.
Транзакция начинается на
Connection
автоматически при первом выполнении оператора или при вызове методаConnection.begin()
.
-
attribute
sqlalchemy.ext.asyncio.AsyncConnection.
connection¶ Не реализовано для async; вызывайте
AsyncConnection.get_raw_connection()
.
-
attribute
sqlalchemy.ext.asyncio.AsyncConnection.
default_isolation_level¶ Уровень изоляции времени начального соединения, связанный с используемым
Dialect
.Проксирование класса
Connection
от имени классаAsyncConnection
.Это значение не зависит от опций выполнения
Connection.execution_options.isolation_level
иEngine.execution_options.isolation_level
и определяетсяDialect
при создании первого соединения путем выполнения SQL-запроса к базе данных для текущего уровня изоляции до выдачи каких-либо дополнительных команд.Вызов этого аксессора не вызывает никаких новых SQL-запросов.
См.также
Connection.get_isolation_level()
- просмотр текущего фактического уровня изоляцииcreate_engine.isolation_level
- устанавливается на уровень изоляцииEngine
Connection.execution_options.isolation_level
- устанавливается на уровень изоляцииConnection
-
attribute
sqlalchemy.ext.asyncio.AsyncConnection.
dialect¶ Прокси для атрибута
Connection.dialect
от имени классаAsyncConnection
.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async exec_driver_sql(statement: str, parameters: Optional[_DBAPIAnyExecuteParams] = None, execution_options: Optional[CoreExecuteOptionsParameter] = None) CursorResult[Any] ¶ Выполняет SQL-строку на уровне драйвера и возвращает буферизованную строку
Result
.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async execute(statement: Executable, parameters: Optional[_CoreAnyExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None) CursorResult[Any] ¶ Выполняет конструкцию SQL-оператора и возвращает буферизованное значение
Result
.- Параметры:
object – Оператор, который должен быть выполнен. Это всегда объект, находящийся как в иерархии
ClauseElement
, так и в иерархииExecutable
, включая: *Select
*Insert
,Update
,Delete
*TextClause
иTextualSelect
*DDL
и объекты, наследующие отExecutableDDLElement
.parameters – параметры, которые будут связываться в операторе. Это может быть либо словарь имен и значений параметров, либо изменяемая последовательность (например, список) словарей. Если передается список словарей, то при выполнении оператора будет использован метод DBAPI
cursor.executemany()
. При передаче одного словаря будет использоваться метод DBAPIcursor.execute()
.execution_options – необязательный словарь опций выполнения, которые будут связаны с выполнением оператора. Этот словарь может содержать подмножество опций, принимаемых оператором
Connection.execution_options()
.
- Результат:
объект
Result
.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async execution_options(**opt: Any) AsyncConnection ¶ Установите для соединения параметры, не относящиеся к языку SQL, которые вступают в силу во время выполнения.
Возвращается объект
AsyncConnection
с добавленными новыми опциями.Более подробно об этом методе см. в разделе
Connection.execution_options()
.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
get_nested_transaction() Optional[AsyncTransaction] ¶ Возвращает
AsyncTransaction
, представляющий текущую вложенную (savepoint) транзакцию, если таковая имеется.При этом используется метод
Connection.get_nested_transaction()
базового синхронного соединения для получения текущегоTransaction
, который затем проксируется в новый объектAsyncTransaction
.Добавлено в версии 1.4.0b2.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async get_raw_connection() PoolProxiedConnection ¶ Возвращает пул соединений уровня DBAPI, используемый данным
AsyncConnection
.Это проксированное соединение пула соединений SQLAlchemy, которое затем имеет атрибут
_ConnectionFairy.driver_connection
, ссылающийся на реальное соединение с драйвером. Вместо него_ConnectionFairy.dbapi_connection
ссылается на экземплярAdaptedConnection
, который адаптирует соединение драйвера к протоколу DBAPI.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
get_transaction() Optional[AsyncTransaction] ¶ Возвращает
AsyncTransaction
, представляющий текущую транзакцию, если таковая имеется.При этом используется метод
Connection.get_transaction()
базового синхронного соединения для получения текущегоTransaction
, который затем проксируется в новый объектAsyncTransaction
.Добавлено в версии 1.4.0b2.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
in_nested_transaction() bool ¶ Возвращает True, если транзакция находится в процессе выполнения.
Добавлено в версии 1.4.0b2.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
in_transaction() bool ¶ Возвращает True, если транзакция находится в процессе выполнения.
-
attribute
sqlalchemy.ext.asyncio.AsyncConnection.
info¶ Возвращает
Connection.info
словарь , лежащий в основеConnection
.Этот словарь можно свободно записывать для определения состояния, ассоциируемого с подключением к базе данных.
Этот атрибут доступен только в том случае, если
AsyncConnection
в данный момент подключен. Если атрибутомAsyncConnection.closed
являетсяTrue
, то обращение к этому атрибуту приведет к появлениюResourceClosedError
.Добавлено в версии 1.4.0b2.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async invalidate(exception: Optional[BaseException] = None) None ¶ Аннулировать базовое соединение DBAPI, связанное с данным
Connection
.Более подробно об этом методе см. в методе
Connection.invalidate()
.
-
attribute
sqlalchemy.ext.asyncio.AsyncConnection.
invalidated¶ Возвращает True, если данное соединение было признано недействительным.
Проксирование класса
Connection
от имени классаAsyncConnection
.При этом не указывается, было ли соединение признано недействительным на уровне пула, однако
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async rollback() None ¶ Откатить транзакцию, находящуюся в процессе выполнения.
Этот метод откатывает текущую транзакцию, если она была начата. Если транзакция не была начата, то метод не имеет никакого эффекта. Если транзакция была начата и соединение находится в состоянии invalidated, то транзакция очищается с помощью этого метода.
Транзакция начинается на
Connection
автоматически при первом выполнении оператора или при вызове методаConnection.begin()
.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async run_sync(fn: Callable[[...], Any], *arg: Any, **kw: Any) Any ¶ Вызывает данный синхронный (т.е. не async) вызываемый модуль, передавая в качестве первого аргумента синхронный стиль
Connection
.Этот метод позволяет запускать традиционные синхронные функции SQLAlchemy в контексте приложения asyncio.
Например:
def do_something_with_core(conn: Connection, arg1: int, arg2: str) -> str: '''A synchronous function that does not require awaiting :param conn: a Core SQLAlchemy Connection, used synchronously :return: an optional return value is supported ''' conn.execute( some_table.insert().values(int_col=arg1, str_col=arg2) ) return "success" async def do_something_async(async_engine: AsyncEngine) -> None: '''an async function that uses awaiting''' async with async_engine.begin() as async_conn: # run do_something_with_core() with a sync-style # Connection, proxied into an awaitable return_code = await async_conn.run_sync(do_something_with_core, 5, "strval") print(return_code)
Этот метод поддерживает цикл событий asyncio вплоть до соединения с базой данных, запуская заданную вызываемую переменную в специально инструментированном гринлете.
Наиболее простым использованием
AsyncConnection.run_sync()
является вызов методов, таких какMetaData.create_all()
, с помощьюAsyncConnection
, который должен быть предоставленMetaData.create_all()
в качествеConnection
объекта:# run metadata.create_all(conn) with a sync-style Connection, # proxied into an awaitable with async_engine.begin() as conn: await conn.run_sync(metadata.create_all)
Примечание
Предоставленный callable вызывается inline в цикле событий asyncio и будет блокировать традиционные вызовы IO. IO в рамках этой вызываемой переменной должен вызывать только API базы данных SQLAlchemy asyncio, которые будут должным образом адаптированы к контексту greenlet.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async scalar(statement: Executable, parameters: Optional[_CoreSingleExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None) Any ¶ Выполняет конструкцию SQL-оператора и возвращает скалярный объект.
Этот метод является сокращением для вызова метода
Result.scalar()
после вызова методаConnection.execute()
. Параметры эквивалентны.- Результат:
скалярное значение Python, представляющее первый столбец первой возвращаемой строки.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async scalars(statement: Executable, parameters: Optional[_CoreAnyExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None) ScalarResult[Any] ¶ Выполняет конструкцию оператора SQL и возвращает скалярные объекты.
Этот метод является сокращением для вызова метода
Result.scalars()
после вызова методаConnection.execute()
. Параметры эквивалентны.- Результат:
объект
ScalarResult
.
Добавлено в версии 1.4.24.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
async start(is_ctxmanager: bool = False) AsyncConnection ¶ Запустите контекст этого объекта
AsyncConnection
вне использования блока Pythonwith:
.
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
stream(statement: Executable, parameters: Optional[_CoreAnyExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None) AsyncIterator[AsyncResult[Any]] ¶ Выполнить оператор и вернуть ожидаемый объект
AsyncResult
.Например:
result = await conn.stream(stmt): async for row in result: print(f"{row}")
Метод
AsyncConnection.stream()
поддерживает опциональное использование менеджера контекста по отношению к объектуAsyncResult
, как в:async with conn.stream(stmt) as result: async for row in result: print(f"{row}")
В приведенном шаблоне метод
AsyncResult.close()
вызывается безусловно, даже если итератор прерывается выбросом исключения. Однако использование контекстного менеджера остается необязательным, и функция может быть вызвана как в стилеasync with fn():
, так и в стилеawait fn()
.Добавлено в версии 2.0.0b3: добавлена поддержка контекстного менеджера
- Результат:
ожидаемый объект, который выдаст объект
AsyncResult
.
См.также
-
method
sqlalchemy.ext.asyncio.AsyncConnection.
stream_scalars(statement: Executable, parameters: Optional[_CoreSingleExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None) AsyncIterator[AsyncScalarResult[Any]] ¶ Выполнить оператор и вернуть ожидаемый объект
AsyncScalarResult
.Например:
result = await conn.stream_scalars(stmt) async for scalar in result: print(f"{scalar}")
Этот метод является сокращением для вызова метода
AsyncResult.scalars()
после вызова методаConnection.stream()
. Параметры эквивалентны.Метод
AsyncConnection.stream_scalars()
поддерживает опциональное использование менеджера контекста по отношению к объектуAsyncScalarResult
, как в:async with conn.stream_scalars(stmt) as result: async for scalar in result: print(f"{scalar}")
В приведенном шаблоне метод
AsyncScalarResult.close()
вызывается безусловно, даже если итератор прерывается выбросом исключения. Однако использование контекстного менеджера остается необязательным, и функция может быть вызвана как в стилеasync with fn():
, так и в стилеawait fn()
.Добавлено в версии 2.0.0b3: добавлена поддержка контекстного менеджера
- Результат:
ожидаемый объект, который выдаст объект
AsyncScalarResult
.
Добавлено в версии 1.4.24.
См.также
-
attribute
sqlalchemy.ext.asyncio.AsyncConnection.
sync_connection: Optional[Connection]¶ Ссылка на стиль синхронизации
Connection
, к которому данныйAsyncConnection
проксирует запросы.Этот экземпляр может быть использован в качестве цели события.
-
attribute
sqlalchemy.ext.asyncio.AsyncConnection.
sync_engine: Engine¶ Ссылка на стиль синхронизации
Engine
, с которым данныйAsyncConnection
связан через лежащий в его основеConnection
.Этот экземпляр может быть использован в качестве цели события.
-
method
- class sqlalchemy.ext.asyncio.AsyncTransaction¶
Asyncio-прокси для
Transaction
.Members
Классическая подпись.
класс
sqlalchemy.ext.asyncio.AsyncTransaction
(sqlalchemy.ext.asyncio.base.ProxyComparable
,sqlalchemy.ext.asyncio.base.StartableContext
)-
method
sqlalchemy.ext.asyncio.AsyncTransaction.
async close() None ¶ Закройте эту
AsyncTransaction
.Если данная транзакция является базовой транзакцией во вложении begin/commit, то транзакция откатывается назад(). В противном случае метод возвращается.
Он используется для отмены транзакции, не затрагивая область действия вложенной транзакции.
-
method
sqlalchemy.ext.asyncio.AsyncTransaction.
async commit() None ¶ Зафиксируйте это
AsyncTransaction
.
-
method
sqlalchemy.ext.asyncio.AsyncTransaction.
async rollback() None ¶ Откатитесь назад
AsyncTransaction
.
-
method
sqlalchemy.ext.asyncio.AsyncTransaction.
async start(is_ctxmanager: bool = False) AsyncTransaction ¶ Запустите контекст этого объекта
AsyncTransaction
вне использования блока Pythonwith:
.
-
method
Документация API по набору результатов¶
Объект AsyncResult
является асинхронно-адаптированной версией объекта Result
. Он возвращается только при использовании методов AsyncConnection.stream()
или AsyncSession.stream()
, которые возвращают объект результата, находящийся поверх активного курсора базы данных.
Object Name | Description |
---|---|
Обертка для |
|
Обертка asyncio вокруг объекта |
|
Обертка для |
|
|
- class sqlalchemy.ext.asyncio.AsyncResult¶
Обертка asyncio вокруг объекта
Result
.Параметр
AsyncResult
применяется только при выполнении операторов, использующих курсор на стороне сервера. Он возвращается только из методовAsyncConnection.stream()
иAsyncSession.stream()
.Примечание
Как и в случае с
Result
, этот объект используется для результатов ORM, возвращаемыхAsyncSession.execute()
, которые могут содержать экземпляры отображаемых объектов ORM по отдельности или в виде кортежей. Обратите внимание, что эти объекты результатов не дедуплицируют экземпляры или строки автоматически, как это происходит в случае с традиционным объектомQuery
. Для дедупликации экземпляров или строк в языке Python используйте метод-модификаторAsyncResult.unique()
.Добавлено в версии 1.4.
Members
all(), close(), closed, columns(), fetchall(), fetchmany(), fetchone(), first(), freeze(), keys(), mappings(), one(), one_or_none(), partitions(), scalar(), scalar_one(), scalar_one_or_none(), scalars(), t, tuples(), unique(), yield_per()
Классическая подпись.
класс
sqlalchemy.ext.asyncio.AsyncResult
(sqlalchemy.engine._WithKeys
,sqlalchemy.ext.asyncio.AsyncCommon
)-
method
sqlalchemy.ext.asyncio.AsyncResult.
async all() Sequence[Row[_TP]] ¶ Возвращает все строки в списке.
Закрывает набор результатов после вызова. Последующие вызовы будут возвращать пустой список.
- Результат:
список объектов
Row
.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async close() None ¶ наследуется от
AsyncCommon.close()
методаAsyncCommon
Закройте этот результат.
-
attribute
sqlalchemy.ext.asyncio.AsyncResult.
closed¶ наследуется от
AsyncCommon.closed
атрибутаAsyncCommon
проксирует атрибут .closed базового объекта result, если таковой имеется, иначе возникает ошибка
AttributeError
.Добавлено в версии 2.0.0b3.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
columns(*col_expressions: _KeyIndexType) Self ¶ Определите столбцы, которые должны быть возвращены в каждой строке.
Полное описание поведения см. в разделе
Result.columns()
в синхронном API SQLAlchemy.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async fetchall() Sequence[Row[_TP]] ¶ Синоним метода
AsyncResult.all()
.Добавлено в версии 2.0.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async fetchmany(size: Optional[int] = None) Sequence[Row[_TP]] ¶ Получение большого количества строк.
Когда все строки исчерпаны, возвращается пустой список.
Этот метод предусмотрен для обратной совместимости с SQLAlchemy 1.x.x.
Для получения строк в группах используйте метод
AsyncResult.partitions()
.- Результат:
список объектов
Row
.
См.также
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async fetchone() Optional[Row[_TP]] ¶ Получение одного ряда.
Если все строки исчерпаны, возвращается None.
Этот метод предусмотрен для обратной совместимости с SQLAlchemy 1.x.x.
Чтобы получить только первую строку результата, используйте метод
AsyncResult.first()
. Для итерации по всем строкам используйте непосредственно объектAsyncResult
.- Результат:
объект
Row
, если фильтры не применяются, илиNone
, если не осталось ни одной строки.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async first() Optional[Row[_TP]] ¶ Получить первый ряд или
None
, если ряд отсутствует.Закрывает набор результатов и отбрасывает оставшиеся строки.
Примечание
По умолчанию этот метод возвращает одну строку, например, кортеж. Чтобы вернуть ровно одно единственное скалярное значение, то есть первый столбец первой строки, используйте метод
AsyncResult.scalar()
или комбинируйтеAsyncResult.scalars()
иAsyncResult.first()
.Кроме того, в отличие от поведения традиционного метода ORM
Query.first()
, не применяется ограничение на SQL-запрос, который был вызван для создания этогоAsyncResult
; для драйвера DBAPI, который буферизирует результаты в памяти перед выдачей строк, все строки будут отправлены в процесс Python и все, кроме первой строки, будут отброшены.См.также
- Результат:
объект
Row
, или None, если строк не осталось.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async freeze() FrozenResult[_TP] ¶ Возвращает вызываемый объект, который при вызове будет создавать копии данного
AsyncResult
.Возвращаемый вызываемый объект является экземпляром
FrozenResult
.Этот метод используется для кэширования набора результатов. Метод должен быть вызван на результате, когда он не был поглощен, и вызов метода приведет к полному потреблению результата. Когда
FrozenResult
извлекается из кэша, его можно вызывать любое количество раз, и каждый раз он будет создавать новый объектResult
по сохраненному набору строк.См.также
Повторное выполнение заявлений - пример использования в ORM для реализации кэша наборов результатов.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
keys() RMKeyView ¶ наследуется от
sqlalchemy.engine._WithKeys.keys
методаsqlalchemy.engine._WithKeys
Возвращает итерируемое представление, которое выдает ключи строк, которые будут представлены каждым
Row
.Ключи могут представлять собой метки столбцов, возвращаемых оператором core, или имена классов orm, возвращаемых в результате выполнения операции orm.
Представление также может быть проверено на содержание ключей с помощью оператора Python
in
, который будет проверять как строковые ключи, представленные в представлении, так и альтернативные ключи, например, объекты столбцов.Изменено в версии 1.4: возвращается объект представления ключей, а не обычный список.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
mappings() AsyncMappingResult ¶ Примените фильтр отображений к возвращаемым строкам, вернув экземпляр
AsyncMappingResult
.При применении этого фильтра при выборке строк будут возвращаться объекты
RowMapping
, а неRow
.- Результат:
новый объект фильтрации
AsyncMappingResult
, ссылающийся на базовый объектResult
.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async one() Row[_TP] ¶ Вернуть ровно один ряд или выдать исключение.
Поднимает
NoResultFound
, если результат не возвращает ни одной строки, илиMultipleResultsFound
, если будет возвращено несколько строк.Примечание
По умолчанию этот метод возвращает одну строку, например, кортеж. Чтобы вернуть ровно одно единственное скалярное значение, то есть первый столбец первой строки, используйте метод
AsyncResult.scalar_one()
или комбинируйтеAsyncResult.scalars()
иAsyncResult.one()
.Добавлено в версии 1.4.
- Результат:
Первый
Row
.- повышает:
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async one_or_none() Optional[Row[_TP]] ¶ Возвращать не более одного результата или вызывать исключение.
Возвращает
None
, если результат не содержит строк. ВозвращаетMultipleResultsFound
, если возвращается несколько строк.Добавлено в версии 1.4.
- Результат:
Первая строка
Row
илиNone
, если строка отсутствует.- повышает:
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async partitions(size: Optional[int] = None) AsyncIterator[Sequence[Row[_TP]]] ¶ Итерация по подспискам строк заданного размера.
Возвращается асинхронный итератор:
async def scroll_results(connection): result = await connection.stream(select(users_table)) async for partition in result.partitions(100): print("list of rows: %s" % partition)
Полное описание поведения см. в разделе
Result.partitions()
в синхронном API SQLAlchemy.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async scalar() Any ¶ Получить первый столбец первой строки и закрыть набор результатов.
Возвращает
None
, если нет строк для выборки.Проверка на наличие дополнительных строк не производится.
После вызова этого метода объект будет полностью закрыт, например, будет вызван метод
CursorResult.close()
.- Результат:
скалярное значение Python, или
None
, если строк не осталось.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async scalar_one() Any ¶ Возвращает ровно один скалярный результат или вызывает исключение.
Это эквивалентно вызову
AsyncResult.scalars()
, а затемAsyncResult.one()
.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
async scalar_one_or_none() Optional[Any] ¶ Возвращает ровно один скалярный результат или
None
.Это эквивалентно вызову
AsyncResult.scalars()
, а затемAsyncResult.one_or_none()
.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
scalars(index: _KeyIndexType = 0) AsyncScalarResult[Any] ¶ Возвращает объект фильтрации
AsyncScalarResult
, который будет возвращать отдельные элементы, а не объектыRow
.Полное описание поведения см. в разделе
Result.scalars()
в синхронном API SQLAlchemy.- Параметры:
index – целое число или ключ строки, указывающий на столбец, который будет извлечен из каждой строки, по умолчанию
0
, указывающий на первый столбец.- Результат:
новый объект фильтрации
AsyncScalarResult
, ссылающийся на данный объектAsyncResult
.
-
attribute
sqlalchemy.ext.asyncio.AsyncResult.
t¶ Применить к возвращаемым строкам фильтр типизации «набранный кортеж».
Атрибут
AsyncResult.t
является синонимом вызова методаAsyncResult.tuples()
.Добавлено в версии 2.0.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
tuples() AsyncTupleResult[_TP] ¶ Применить к возвращаемым строкам фильтр типизации «набранный кортеж».
Этот метод возвращает тот же самый объект
AsyncResult
во время выполнения, однако аннотируется как возвращающий объектAsyncTupleResult
, что укажет средствам типизации PEP 484, что возвращаются простые типизированные экземплярыTuple
, а не строки. Это позволяет распаковывать кортежи и осуществлять__getitem__
доступ кRow
объектам с типизацией для тех случаев, когда вызываемый оператор сам содержал информацию о типизации.Добавлено в версии 2.0.
- Результат:
тип
AsyncTupleResult
при наборе текста.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
unique(strategy: Optional[_UniqueFilterType] = None) Self ¶ Применить уникальную фильтрацию к объектам, возвращаемым данным
AsyncResult
.Полное описание поведения см. в разделе
Result.unique()
в синхронном API SQLAlchemy.
-
method
sqlalchemy.ext.asyncio.AsyncResult.
yield_per(num: int) Self ¶ наследуется от
FilterResult.yield_per()
методаFilterResult
Настройте стратегию выборки строк на одновременную выборку
num
строк.Метод
FilterResult.yield_per()
является проходным для методаResult.yield_per()
. Указания по его использованию приведены в документации к этому методу.Добавлено в версии 1.4.40: - added
FilterResult.yield_per()
so that the method is available on all result set implementationsСм.также
Использование курсоров на стороне сервера (они же потоковые результаты) - описывает поведение Core для
Result.yield_per()
Получение больших наборов результатов с доходностью за - в Руководство по составлению запросов в ORM
-
method
- class sqlalchemy.ext.asyncio.AsyncScalarResult¶
Обертка для
AsyncResult
, которая возвращает скалярные, а неRow
значения.Объект
AsyncScalarResult
приобретается путем вызова методаAsyncResult.scalars()
.Полное описание поведения объекта
ScalarResult
в синхронном API SQLAlchemy см.Добавлено в версии 1.4.
Members
all(), close(), closed, fetchall(), fetchmany(), first(), one(), one_or_none(), partitions(), unique(), yield_per()
Классическая подпись.
класс
sqlalchemy.ext.asyncio.AsyncScalarResult
(sqlalchemy.ext.asyncio.AsyncCommon
)-
method
sqlalchemy.ext.asyncio.AsyncScalarResult.
async all() Sequence[_R] ¶ Возвращает все скалярные значения в списке.
Эквивалентно
AsyncResult.all()
за исключением того, что возвращаются скалярные значения, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncScalarResult.
async close() None ¶ наследуется от
AsyncCommon.close()
методаAsyncCommon
Закройте этот результат.
-
attribute
sqlalchemy.ext.asyncio.AsyncScalarResult.
closed¶ наследуется от
AsyncCommon.closed
атрибутаAsyncCommon
проксирует атрибут .closed базового объекта result, если таковой имеется, иначе возникает ошибка
AttributeError
.Добавлено в версии 2.0.0b3.
-
method
sqlalchemy.ext.asyncio.AsyncScalarResult.
async fetchall() Sequence[_R] ¶ Синоним метода
AsyncScalarResult.all()
.
-
method
sqlalchemy.ext.asyncio.AsyncScalarResult.
async fetchmany(size: Optional[int] = None) Sequence[_R] ¶ Получение большого количества объектов.
Эквивалентно
AsyncResult.fetchmany()
за исключением того, что возвращаются скалярные значения, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncScalarResult.
async first() Optional[_R] ¶ Получить первый объект или
None
, если объект отсутствует.Эквивалентно
AsyncResult.first()
за исключением того, что возвращаются скалярные значения, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncScalarResult.
async one() _R ¶ Вернуть ровно один объект или вызвать исключение.
Эквивалентно
AsyncResult.one()
за исключением того, что возвращаются скалярные значения, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncScalarResult.
async one_or_none() Optional[_R] ¶ Возвращать не более одного объекта или вызывать исключение.
Эквивалентно
AsyncResult.one_or_none()
за исключением того, что возвращаются скалярные значения, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncScalarResult.
async partitions(size: Optional[int] = None) AsyncIterator[Sequence[_R]] ¶ Итерация по вложенным спискам элементов заданного размера.
Эквивалентно
AsyncResult.partitions()
за исключением того, что возвращаются скалярные значения, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncScalarResult.
unique(strategy: Optional[_UniqueFilterType] = None) Self ¶ Применить уникальную фильтрацию к объектам, возвращаемым данным
AsyncScalarResult
.Подробности использования см. в разделе
AsyncResult.unique()
.
-
method
sqlalchemy.ext.asyncio.AsyncScalarResult.
yield_per(num: int) Self ¶ наследуется от
FilterResult.yield_per()
методаFilterResult
Настройте стратегию выборки строк на одновременную выборку
num
строк.Метод
FilterResult.yield_per()
является проходным для методаResult.yield_per()
. Указания по его использованию приведены в документации к этому методу.Добавлено в версии 1.4.40: - added
FilterResult.yield_per()
so that the method is available on all result set implementationsСм.также
Использование курсоров на стороне сервера (они же потоковые результаты) - описывает поведение Core для
Result.yield_per()
Получение больших наборов результатов с доходностью за - в Руководство по составлению запросов в ORM
-
method
- class sqlalchemy.ext.asyncio.AsyncMappingResult¶
Обертка для
AsyncResult
, которая возвращает значения словаря, а неRow
.Объект
AsyncMappingResult
приобретается путем вызова методаAsyncResult.mappings()
.Полное описание поведения объекта
MappingResult
в синхронном API SQLAlchemy см.Добавлено в версии 1.4.
Members
all(), close(), closed, columns(), fetchall(), fetchmany(), fetchone(), first(), keys(), one(), one_or_none(), partitions(), unique(), yield_per()
Классическая подпись.
класс
sqlalchemy.ext.asyncio.AsyncMappingResult
(sqlalchemy.engine._WithKeys
,sqlalchemy.ext.asyncio.AsyncCommon
)-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
async all() Sequence[RowMapping] ¶ Возвращает все строки в списке.
Эквивалентно
AsyncResult.all()
за исключением того, что возвращаются значенияRowMapping
, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
async close() None ¶ наследуется от
AsyncCommon.close()
методаAsyncCommon
Закройте этот результат.
-
attribute
sqlalchemy.ext.asyncio.AsyncMappingResult.
closed¶ наследуется от
AsyncCommon.closed
атрибутаAsyncCommon
проксирует атрибут .closed базового объекта result, если таковой имеется, иначе возникает ошибка
AttributeError
.Добавлено в версии 2.0.0b3.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
columns(*col_expressions: _KeyIndexType) Self ¶ Определите столбцы, которые должны быть возвращены в каждой строке.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
async fetchall() Sequence[RowMapping] ¶ Синоним метода
AsyncMappingResult.all()
.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
async fetchmany(size: Optional[int] = None) Sequence[RowMapping] ¶ Получение большого количества строк.
Эквивалентно
AsyncResult.fetchmany()
за исключением того, что возвращаются значенияRowMapping
, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
async fetchone() Optional[RowMapping] ¶ Получить один объект.
Эквивалентно
AsyncResult.fetchone()
за исключением того, что возвращаются значенияRowMapping
, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
async first() Optional[RowMapping] ¶ Получить первый объект или
None
, если объект отсутствует.Эквивалентно
AsyncResult.first()
за исключением того, что возвращаются значенияRowMapping
, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
keys() RMKeyView ¶ наследуется от
sqlalchemy.engine._WithKeys.keys
методаsqlalchemy.engine._WithKeys
Возвращает итерируемое представление, которое выдает ключи строк, которые будут представлены каждым
Row
.Ключи могут представлять собой метки столбцов, возвращаемых оператором core, или имена классов orm, возвращаемых в результате выполнения операции orm.
Представление также может быть проверено на содержание ключей с помощью оператора Python
in
, который будет проверять как строковые ключи, представленные в представлении, так и альтернативные ключи, например, объекты столбцов.Изменено в версии 1.4: возвращается объект представления ключей, а не обычный список.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
async one() RowMapping ¶ Вернуть ровно один объект или вызвать исключение.
Эквивалентно
AsyncResult.one()
за исключением того, что возвращаются значенияRowMapping
, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
async one_or_none() Optional[RowMapping] ¶ Возвращать не более одного объекта или вызывать исключение.
Эквивалентно
AsyncResult.one_or_none()
за исключением того, что возвращаются значенияRowMapping
, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
async partitions(size: Optional[int] = None) AsyncIterator[Sequence[RowMapping]] ¶ Итерация по вложенным спискам элементов заданного размера.
Эквивалентно
AsyncResult.partitions()
за исключением того, что возвращаются значенияRowMapping
, а не объектыRow
.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
unique(strategy: Optional[_UniqueFilterType] = None) Self ¶ Применить уникальную фильтрацию к объектам, возвращаемым данным
AsyncMappingResult
.Подробности использования см. в разделе
AsyncResult.unique()
.
-
method
sqlalchemy.ext.asyncio.AsyncMappingResult.
yield_per(num: int) Self ¶ наследуется от
FilterResult.yield_per()
методаFilterResult
Настройте стратегию выборки строк на одновременную выборку
num
строк.Метод
FilterResult.yield_per()
является проходным для методаResult.yield_per()
. Указания по его использованию приведены в документации к этому методу.Добавлено в версии 1.4.40: - added
FilterResult.yield_per()
so that the method is available on all result set implementationsСм.также
Использование курсоров на стороне сервера (они же потоковые результаты) - описывает поведение Core для
Result.yield_per()
Получение больших наборов результатов с доходностью за - в Руководство по составлению запросов в ORM
-
method
- class sqlalchemy.ext.asyncio.AsyncTupleResult¶
AsyncResult
, который типизирован как возвращающий обычные кортежи Python, а не строки.Поскольку
Row
уже во всех отношениях ведет себя как кортеж, этот класс является классом только для типизации, обычныйAsyncResult
по-прежнему используется во время выполнения программы.Классическая подпись.
класс
sqlalchemy.ext.asyncio.AsyncTupleResult
(sqlalchemy.ext.asyncio.AsyncCommon
,sqlalchemy.util.langhelpers.TypingOnly
)
Документация ORM Session API¶
Object Name | Description |
---|---|
async_object_session(instance) |
Возвращает |
Обеспечивает масштабируемое управление объектами |
|
async_session(session) |
Возвращает объект |
Конфигурируемая фабрика |
|
Класс Mixin, обеспечивающий ожидаемый доступ ко всем атрибутам. |
|
Asyncio-версия |
|
Обертка для объекта ORM |
- function sqlalchemy.ext.asyncio.async_object_session(instance: object) Optional[AsyncSession] ¶
Возвращает
AsyncSession
, к которому принадлежит данный экземпляр.Эта функция использует функцию sync-API
object_session
для полученияSession
, ссылающегося на данный экземпляр, а затем связывает его с исходнымAsyncSession
.Если
AsyncSession
был собран мусор, то возвращаемое значение будетNone
.Эта функциональность также доступна из аксессора
InstanceState.async_session
.- Параметры:
instance – экземпляр, сопоставленный с ORM
- Результат:
объект
AsyncSession
, илиNone
.
Добавлено в версии 1.4.18.
- function sqlalchemy.ext.asyncio.async_session(session: Session) Optional[AsyncSession] ¶
Возвращает объект
AsyncSession
, который проксирует данный объектSession
, если таковой имеется.- Параметры:
session – экземпляр
Session
.- Результат:
экземпляр
AsyncSession
илиNone
.
Добавлено в версии 1.4.18.
- class sqlalchemy.ext.asyncio.async_sessionmaker¶
Конфигурируемая фабрика
AsyncSession
.Фабрика
async_sessionmaker
работает так же, как и фабрикаsessionmaker
, генерируя при вызове новые объектыAsyncSession
, создавая их с учетом установленных здесь конфигурационных аргументов.например:
from sqlalchemy.ext.asyncio import create_async_engine from sqlalchemy.ext.asyncio import AsyncSession from sqlalchemy.ext.asyncio import async_sessionmaker async def run_some_sql(async_session: async_sessionmaker[AsyncSession]) -> None: async with async_session() as session: session.add(SomeObject(data="object")) session.add(SomeOtherObject(name="other object")) await session.commit() async def main() -> None: # an AsyncEngine, which the AsyncSession will use for connection # resources engine = create_async_engine('postgresql+asyncpg://scott:tiger@localhost/') # create a reusable factory for new AsyncSession instances async_session = async_sessionmaker(engine) await run_some_sql(async_session) await engine.dispose()
async_sessionmaker
полезен для того, чтобы различные части программы могли создавать новые объектыAsyncSession
с фиксированной конфигурацией, установленной заранее. Заметим, что объектыAsyncSession
могут также инстанцироваться непосредственно, если не используетсяasync_sessionmaker
.Добавлено в версии 2.0:
async_sessionmaker
предоставляет классsessionmaker
, предназначенный для работы с объектомAsyncSession
, включая поддержку типизации pep-484.См.также
Синопсис - ORM - показывает пример использования
sessionmaker
- общий обзорsessionmaker
архитектура
Открытие и закрытие сессии - вводный текст по созданию сессий с использованием
sessionmaker
.Members
Классическая подпись.
класс
sqlalchemy.ext.asyncio.async_sessionmaker
(typing.Generic
)-
method
sqlalchemy.ext.asyncio.async_sessionmaker.
__call__(**local_kw: Any) _AS ¶ Создать новый объект
AsyncSession
, используя конфигурацию, установленную в данномasync_sessionmaker
.В Python метод
__call__
вызывается у объекта при его «вызове» так же, как и у функции:AsyncSession = async_sessionmaker(async_engine, expire_on_commit=False) session = AsyncSession() # invokes sessionmaker.__call__()
-
method
sqlalchemy.ext.asyncio.async_sessionmaker.
__init__(bind: Optional[_AsyncSessionBind] = None, *, class_: Type[_AS] = <class 'sqlalchemy.ext.asyncio.session.AsyncSession'>, autoflush: bool = True, expire_on_commit: bool = True, info: Optional[_InfoType] = None, **kw: Any)¶ Построить новый
async_sessionmaker
.Все приведенные здесь аргументы, кроме
class_
, соответствуют аргументам, принимаемым непосредственноSession
. Более подробную информацию о параметрах см. в документальной строкеAsyncSession.__init__()
.
-
method
sqlalchemy.ext.asyncio.async_sessionmaker.
begin() _AsyncSessionContextManager[_AS] ¶ Создайте менеджер контекста, который одновременно предоставляет новый
AsyncSession
, а также транзакцию, которая фиксирует.например:
async def main(): Session = async_sessionmaker(some_engine) async with Session.begin() as session: session.add(some_object) # commits transaction, closes session
-
method
sqlalchemy.ext.asyncio.async_sessionmaker.
configure(**new_kw: Any) None ¶ (Пере)настройка аргументов для данного async_sessionmaker.
например:
AsyncSession = async_sessionmaker(some_engine) AsyncSession.configure(bind=create_async_engine('sqlite+aiosqlite://'))
- class sqlalchemy.ext.asyncio.async_scoped_session¶
Обеспечивает масштабируемое управление объектами
AsyncSession
.Подробности использования см. в разделе Использование asyncio scoped session.
Добавлено в версии 1.4.19.
Members
__call__(), __init__(), add(), add_all(), autoflush, begin(), begin_nested(), bind, close(), close_all(), commit(), configure(), connection(), delete(), deleted, dirty, execute(), expire(), expire_all(), expunge(), expunge_all(), flush(), get(), get_bind(), identity_key(), identity_map, info, invalidate(), is_active, is_modified(), merge(), new, no_autoflush, object_session(), refresh(), remove(), rollback(), scalar(), scalars(), session_factory, stream(), stream_scalars()
Классическая подпись.
класс
sqlalchemy.ext.asyncio.async_scoped_session
(typing.Generic
)-
method
sqlalchemy.ext.asyncio.async_scoped_session.
__call__(**kw: Any) _AS ¶ Возвращает текущий
AsyncSession
, создавая его с помощьюscoped_session.session_factory
, если он отсутствует.- Параметры:
**kw – Аргументы ключевого слова будут переданы вызываемому модулю
scoped_session.session_factory
, если не существует существующегоAsyncSession
. ЕслиAsyncSession
присутствует и аргументы ключевого слова были переданы, то будет вызванInvalidRequestError
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
__init__(session_factory: async_sessionmaker[_AS], scopefunc: Callable[[], Any])¶ Построить новый
async_scoped_session
.- Параметры:
session_factory – фабрика для создания новых экземпляров
AsyncSession
. Обычно, но не обязательно, это экземплярasync_sessionmaker
.scopefunc – функция, определяющая текущую область видимости. Здесь может быть полезна такая функция, как
asyncio.current_task
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
add(instance: object, _warn: bool = True) None ¶ Поместите объект в эту область
Session
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.Объекты, находящиеся в состоянии transient при передаче в метод
Session.add()
, будут переходить в состояние pending до следующего flush, после которого они перейдут в состояние persistent.Объекты, находящиеся в состоянии detached при передаче в метод
Session.add()
, перейдут в состояние persistent непосредственно.Если транзакция, используемая
Session
, откатывается, то объекты, которые были переходными на момент передачи их вSession.add()
, будут переведены обратно в состояние transient и больше не будут присутствовать в этомSession
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
add_all(instances: Iterable[object]) None ¶ Добавить заданную коллекцию экземпляров в данный
Session
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.Общее описание поведения приведено в документации для
Session.add()
.
-
attribute
sqlalchemy.ext.asyncio.async_scoped_session.
autoflush¶ Прокси для атрибута
Session.autoflush
от имени классаAsyncSession
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
begin() AsyncSessionTransaction ¶ Возвращает объект
AsyncSessionTransaction
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Лежащий в основе
Session
будет выполнять действие «begin» при вводе объектаAsyncSessionTransaction
:async with async_session.begin(): # .. ORM transaction is begun
Обратите внимание, что ввод-вывод данных из базы данных обычно не происходит в момент начала транзакции на уровне сеанса, поскольку транзакции в базе данных начинаются по требованию. Тем не менее, блок begin является асинхронным для того, чтобы можно было использовать крючок события
SessionEvents.after_transaction_create()
, который может выполнить ввод-вывод.Общее описание ORM begin приведено в разделе
Session.begin()
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
begin_nested() AsyncSessionTransaction ¶ Возвращает объект
AsyncSessionTransaction
, который начнет «вложенную» транзакцию, например, SAVEPOINT.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Поведение аналогично поведению
AsyncSession.begin()
.Общее описание ORM begin nested приведено в разделе
Session.begin_nested()
.
-
attribute
sqlalchemy.ext.asyncio.async_scoped_session.
bind¶ Прокси для атрибута
AsyncSession.bind
от имени классаasync_scoped_session
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async close() None ¶ Закрыть транзакционные ресурсы и объекты ORM, используемые данной
AsyncSession
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.При этом удаляются все объекты ORM, связанные с данным
AsyncSession
, завершается любая транзакция и releases все объектыAsyncConnection
, которые данныйAsyncSession
сам вычеркнул из связанных с нимAsyncEngine
объектов. Затем операция оставляетAsyncSession
в состоянии, в котором он может быть использован снова.Совет
Метод
AsyncSession.close()
не препятствует повторному использованию сессии. СамAsyncSession
не имеет состояния «закрыто»; это означает, чтоAsyncSession
просто освобождает все соединения с базой данных и объекты ORM.См.также
Закрытие - подробно о семантике
AsyncSession.close()
-
async classmethod
sqlalchemy.ext.asyncio.async_scoped_session.
close_all() None ¶ Закрыть все сеансы
AsyncSession
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async commit() None ¶ Зафиксировать текущую выполняющуюся транзакцию.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
configure(**kwargs: Any) None ¶ переконфигурировать
sessionmaker
, используемый даннымscoped_session
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async connection(**kw: Any) AsyncConnection ¶ Возвращает объект
AsyncConnection
, соответствующий транзакционному состоянию данного объектаSession
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Этот метод также может быть использован для установки параметров выполнения соединения с базой данных, используемого текущей транзакцией.
Добавлено в версии 1.4.24: Добавлены аргументы **kw, которые передаются в базовый метод
Session.connection()
.См.также
Session.connection()
- основная документация по «соединению»
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async delete(instance: object) None ¶ Пометить экземпляр как удаленный.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Операция удаления базы данных происходит при
flush()
.Поскольку эта операция может потребовать каскадирования по незагруженным связям, она является ожидаемой, чтобы обеспечить возможность выполнения этих запросов.
См.также
Session.delete()
- основная документация по удалению
-
attribute
sqlalchemy.ext.asyncio.async_scoped_session.
deleted¶ Множество всех экземпляров, помеченных как «удаленные» в пределах данного
Session
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.
-
attribute
sqlalchemy.ext.asyncio.async_scoped_session.
dirty¶ Множество всех постоянных экземпляров, считающихся грязными.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.Например:
some_mapped_object in session.dirty
Экземпляры считаются грязными, если они были изменены, но не удалены.
Обратите внимание, что этот расчет «грязных» атрибутов является «оптимистичным»; большинство операций по установке атрибутов или изменению коллекции пометят экземпляр как «грязный» и поместят его в этот набор, даже если чистого изменения значения атрибута не произошло. Во время промывки значение каждого атрибута сравнивается с его ранее сохраненным значением, и если чистого изменения нет, то операция SQL не выполняется (это более дорогая операция, поэтому она выполняется только во время промывки).
Чтобы проверить, есть ли у экземпляра actionable net изменения в его атрибутах, используйте метод
Session.is_modified()
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async execute(statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) Result[Any] ¶ Выполнить оператор и вернуть буферизованный объект
Result
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.См.также
Session.execute()
- основная документация по выполнению
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
expire(instance: object, attribute_names: Optional[Iterable[str]] = None) None ¶ Истечение срока действия атрибутов экземпляра.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.Помечает атрибуты экземпляра как устаревшие. При следующем обращении к атрибуту с истекшим сроком действия будет выдан запрос к текущему транзакционному контексту объекта
Session
, чтобы загрузить все атрибуты с истекшим сроком действия для данного экземпляра. Заметим, что в строго изолированной транзакции будут возвращены те же значения, которые были прочитаны ранее в этой же транзакции, независимо от изменений состояния базы данных вне этой транзакции.Для одновременного истечения срока действия всех объектов в
Session
используйтеSession.expire_all()
.Поведение объекта
Session
по умолчанию заключается в том, что при вызове методовSession.rollback()
илиSession.commit()
происходит удаление всего состояния, чтобы новое состояние могло быть загружено для новой транзакции. По этой причине вызовSession.expire()
имеет смысл только в том случае, если в текущей транзакции был выдан нестандартный SQL-оператор.- Параметры:
instance – Экземпляр, который необходимо обновить.
attribute_names – необязательный список строковых имен атрибутов, указывающих на подмножество атрибутов, срок действия которых должен быть истек.
См.также
Обновление / истечение срока действия - вводный материал
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
expire_all() None ¶ Истекает срок действия всех постоянных экземпляров в рамках данной сессии.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.При следующем обращении к атрибутам постоянного экземпляра будет выдан запрос с использованием текущего транзакционного контекста объекта
Session
, чтобы загрузить все истекшие атрибуты для данного экземпляра. Заметим, что в строго изолированной транзакции будут возвращены те же значения, которые были прочитаны ранее в этой же транзакции, независимо от изменений в состоянии базы данных вне этой транзакции.Чтобы исключить отдельные объекты и отдельные атрибуты этих объектов, используйте
Session.expire()
.Поведение объекта
Session
по умолчанию заключается в том, что при вызове методовSession.rollback()
илиSession.commit()
все состояние завершается, чтобы новое состояние могло быть загружено для новой транзакции. По этой причине вызовSession.expire_all()
обычно не требуется, если предположить, что транзакция изолирована.См.также
Обновление / истечение срока действия - вводный материал
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
expunge(instance: object) None ¶ Удалить экземпляр из данного
Session
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.При этом будут освобождены все внутренние ссылки на экземпляр. Каскадирование будет применяться в соответствии с правилом каскада expunge.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
expunge_all() None ¶ Удалить все экземпляры объектов из данного
Session
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.Это эквивалентно вызову
expunge(obj)
на всех объектах в данномSession
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async flush(objects: Optional[Sequence[Any]] = None) None ¶ Промыть все изменения объектов в базе данных.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.См.также
Session.flush()
- основная документация для flush
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async 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 = {}) Optional[_O] ¶ Возвращает экземпляр, основанный на заданном идентификаторе первичного ключа, или
None
, если он не найден.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.См.также
Session.get()
- основная документация для get
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
get_bind(mapper: Optional[_EntityBindKey[_O]] = None, clause: Optional[ClauseElement] = None, bind: Optional[_SessionBind] = None, **kw: Any) Union[Engine, Connection] ¶ Возвращает «привязку», к которой привязан синхронно проксируемый
Session
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.В отличие от метода
Session.get_bind()
, этот метод в настоящее время не используется даннымAsyncSession
каким-либо образом для разрешения движков для запросов.Примечание
Этот метод напрямую связан с методом
Session.get_bind()
, однако в настоящее время не может быть использован в качестве цели переопределения, в отличие от методаSession.get_bind()
. В приведенном ниже примере показано, как реализовать пользовательские схемыSession.get_bind()
, работающие сAsyncSession
иAsyncEngine
.Шаблон, представленный в Нестандартные вертикальные перегородки, иллюстрирует применение пользовательской схемы bind-lookup к
Session
, заданному набором объектовEngine
. Чтобы применить соответствующую реализациюSession.get_bind()
для использования с объектамиAsyncSession
иAsyncEngine
, продолжим подклассSession
и применим его кAsyncSession
с помощьюAsyncSession.sync_session_class
. Внутренний метод должен продолжать возвращать экземплярыEngine
, которые могут быть получены изAsyncEngine
с помощью атрибутаAsyncEngine.sync_engine
:# using example from "Custom Vertical Partitioning" import random from sqlalchemy.ext.asyncio import AsyncSession from sqlalchemy.ext.asyncio import create_async_engine from sqlalchemy.ext.asyncio import async_sessionmaker from sqlalchemy.orm import Session # construct async engines w/ async drivers engines = { 'leader':create_async_engine("sqlite+aiosqlite:///leader.db"), 'other':create_async_engine("sqlite+aiosqlite:///other.db"), 'follower1':create_async_engine("sqlite+aiosqlite:///follower1.db"), 'follower2':create_async_engine("sqlite+aiosqlite:///follower2.db"), } class RoutingSession(Session): def get_bind(self, mapper=None, clause=None, **kw): # within get_bind(), return sync engines if mapper and issubclass(mapper.class_, MyOtherClass): return engines['other'].sync_engine elif self._flushing or isinstance(clause, (Update, Delete)): return engines['leader'].sync_engine else: return engines[ random.choice(['follower1','follower2']) ].sync_engine # apply to AsyncSession using sync_session_class AsyncSessionMaker = async_sessionmaker( sync_session_class=RoutingSession )
Метод
Session.get_bind()
вызывается в неасинхронном, неявно неблокирующем контексте точно так же, как и крючки событий ORM и функции, вызываемые черезAsyncSession.run_sync()
, поэтому программы, которые хотят выполнять SQL-команды внутриSession.get_bind()
, могут продолжать делать это, используя код в стиле блокировки, который будет переведен в неявно асинхронный вызов в точке вызова IO на драйверах базы данных.
-
classmethod
sqlalchemy.ext.asyncio.async_scoped_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] ¶ Возвращает ключ идентификации.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.Это псевдоним
identity_key()
.
-
attribute
sqlalchemy.ext.asyncio.async_scoped_session.
identity_map¶ Прокси для атрибута
Session.identity_map
от имени классаAsyncSession
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.
-
attribute
sqlalchemy.ext.asyncio.async_scoped_session.
info¶ Модифицируемый пользователем словарь.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.Начальное значение этого словаря может быть заполнено с помощью аргумента
info
конструктораSession
, конструктораsessionmaker
или методов фабрики. Словарь здесь всегда локален для данногоSession
и может быть изменен независимо от всех другихSession
объектов.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async invalidate() None ¶ Закройте этот сеанс, используя аннулирование соединения.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Полное описание приведено в разделе
Session.invalidate()
.
-
attribute
sqlalchemy.ext.asyncio.async_scoped_session.
is_active¶ True, если данный
Session
не находится в состоянии «частичного отката».Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.Изменено в версии 1.4:
Session
больше не начинает новую транзакцию немедленно, поэтому при первом инстанцированииSession
этот атрибут будет равен False.Состояние «частичного отката» обычно указывает на то, что процесс промывки транзакции
Session
завершился неудачно, и для полного отката транзакции необходимо вызвать методSession.rollback()
.Если эта
Session
вообще не находится в транзакции, тоSession
будет автозапускаться при ее первом использовании, поэтому в этом случаеSession.is_active
вернет True.В противном случае, если эта
Session
находится внутри транзакции, и эта транзакция не была откачена,Session.is_active
также вернет True.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
is_modified(instance: object, include_collections: bool = True) bool ¶ Возвращает
True
, если данный экземпляр имеет локально измененные атрибуты.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.Этот метод извлекает историю для каждого инструментального атрибута экземпляра и выполняет сравнение текущего значения с его ранее зафиксированным значением, если таковое имеется.
По сути, это более дорогая и точная версия проверки наличия данного экземпляра в коллекции
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.ext.asyncio.async_scoped_session.
async merge(instance: _O, *, load: bool = True, options: Optional[Sequence[ORMOption]] = None) _O ¶ Скопировать состояние данного экземпляра в соответствующий экземпляр внутри данного
AsyncSession
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.См.также
Session.merge()
- основная документация по слиянию
-
attribute
sqlalchemy.ext.asyncio.async_scoped_session.
new¶ Множество всех экземпляров, помеченных как «новые» в пределах данного
Session
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.
-
attribute
sqlalchemy.ext.asyncio.async_scoped_session.
no_autoflush¶ Возвращает менеджер контекста, в котором отключена автопромывка.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.например:
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.ext.asyncio.async_scoped_session.
object_session(instance: object) Optional[Session] ¶ Возвращает
Session
, к которому принадлежит объект.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Проксирование класса
Session
от имени классаAsyncSession
.Это псевдоним
object_session()
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async refresh(instance: object, attribute_names: Optional[Iterable[str]] = None, with_for_update: ForUpdateParameter = None) None ¶ Истечение и обновление атрибутов для данного экземпляра.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.Будет выдан запрос к базе данных, и все атрибуты обновятся, получив текущее значение в базе данных.
Это асинхронная версия метода
Session.refresh()
. Полное описание всех опций приведено в этом методе.См.также
Session.refresh()
- основная документация по обновлению
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async remove() None ¶ Утилизация текущего
AsyncSession
, если он присутствует.В отличие от метода удаления scoped_session, этот метод будет использовать await для ожидания метода закрытия AsyncSession.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async rollback() None ¶ Откат текущей выполняемой транзакции.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async scalar(statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) Any ¶ Выполнить оператор и вернуть скалярный результат.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.См.также
Session.scalar()
- основная документация по скаляру
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async scalars(statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) ScalarResult[Any] ¶ Выполнение оператора и возврат скалярных результатов.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.- Результат:
объект
ScalarResult
Добавлено в версии 1.4.24: Добавлено
AsyncSession.scalars()
Добавлено в версии 1.4.26: Добавлено
async_scoped_session.scalars()
См.также
Session.scalars()
- основная документация по скалярамAsyncSession.stream_scalars()
- потоковая версия
-
attribute
sqlalchemy.ext.asyncio.async_scoped_session.
session_factory: async_sessionmaker[_AS]¶ Атрибут session_factory provided to __init__ хранится в этом атрибуте и может быть использован позднее. Это может быть полезно, когда требуется создать новый нескопированный
AsyncSession
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async stream(statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) AsyncResult[Any] ¶ Выполнить оператор и вернуть потоковый объект
AsyncResult
.Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.
-
method
sqlalchemy.ext.asyncio.async_scoped_session.
async stream_scalars(statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) AsyncScalarResult[Any] ¶ Выполнить оператор и вернуть поток скалярных результатов.
Проксирование класса
AsyncSession
от имени классаasync_scoped_session
.- Результат:
объект
AsyncScalarResult
Добавлено в версии 1.4.24.
См.также
Session.scalars()
- основная документация по скалярамAsyncSession.scalars()
- непотоковая версия
-
method
- class sqlalchemy.ext.asyncio.AsyncAttrs¶
Класс Mixin, обеспечивающий ожидаемый доступ ко всем атрибутам.
Например:
from __future__ import annotations from typing import List from sqlalchemy import ForeignKey from sqlalchemy import func from sqlalchemy.ext.asyncio import AsyncAttrs from sqlalchemy.orm import DeclarativeBase from sqlalchemy.orm import Mapped from sqlalchemy.orm import mapped_column from sqlalchemy.orm import relationship class Base(AsyncAttrs, DeclarativeBase): pass class A(Base): __tablename__ = "a" id: Mapped[int] = mapped_column(primary_key=True) data: Mapped[str] bs: Mapped[List[B]] = relationship() class B(Base): __tablename__ = "b" id: Mapped[int] = mapped_column(primary_key=True) a_id: Mapped[int] = mapped_column(ForeignKey("a.id")) data: Mapped[str]
В приведенном примере миксин
AsyncAttrs
применяется к декларативному классуBase
, где он вступает в силу для всех подклассов. Этот миксин добавляет во все классы один новый атрибутAsyncAttrs.awaitable_attrs
, который будет выдавать значение любого атрибута как awaitable. Это позволяет обращаться к атрибутам, которые могут быть подвержены ленивой загрузке или отложенной/неотложенной загрузке, таким образом, что IO все еще может быть испущен:a1 = (await async_session.scalars(select(A).where(A.id == 5))).one() # use the lazy loader on ``a1.bs`` via the ``.async_attrs`` # interface, so that it may be awaited for b1 in await a1.async_attrs.bs: print(b1)
AsyncAttrs.awaitable_attrs
выполняет обращение к атрибуту, что примерно эквивалентно использованию методаAsyncSession.run_sync()
, например:for b1 in await async_session.run_sync(lambda sess: a1.bs): print(b1)
Добавлено в версии 2.0.13.
Members
-
attribute
sqlalchemy.ext.asyncio.AsyncAttrs.
awaitable_attrs¶ предоставить пространство имен всех атрибутов данного объекта, обернутых как awaitables.
например:
a1 = (await async_session.scalars(select(A).where(A.id == 5))).one() some_attribute = await a1.async_attrs.some_deferred_attribute some_collection = await a1.async_attrs.some_collection
-
attribute
- class sqlalchemy.ext.asyncio.AsyncSession¶
Asyncio-версия
Session
.AsyncSession
является прокси для традиционного экземпляраSession
.Добавлено в версии 1.4.
Для использования
AsyncSession
с пользовательскими реализациямиSession
см. параметрAsyncSession.sync_session_class
.Members
sync_session_class, __init__(), add(), add_all(), autoflush, begin(), begin_nested(), close(), close_all(), commit(), connection(), delete(), deleted, dirty, execute(), expire(), expire_all(), expunge(), expunge_all(), flush(), get(), get_bind(), get_nested_transaction(), get_transaction(), identity_key(), identity_map, in_nested_transaction(), in_transaction(), info, invalidate(), is_active, is_modified(), merge(), new, no_autoflush, object_session(), refresh(), rollback(), run_sync(), scalar(), scalars(), stream(), stream_scalars(), sync_session
Классическая подпись.
класс
sqlalchemy.ext.asyncio.AsyncSession
(sqlalchemy.ext.asyncio.base.ReversibleProxy
)-
attribute
sqlalchemy.ext.asyncio.AsyncSession.
sync_session_class: Type[Session] = <class 'sqlalchemy.orm.session.Session'>¶ Класс или вызываемый модуль, который предоставляет базовый экземпляр
Session
для конкретногоAsyncSession
.На уровне класса этот атрибут является значением по умолчанию для параметра
AsyncSession.sync_session_class
. Пользовательские подклассыAsyncSession
могут переопределять его.На уровне экземпляра этот атрибут указывает на текущий класс или вызываемый модуль, который был использован для предоставления экземпляра
Session
для данного экземпляраAsyncSession
.Добавлено в версии 1.4.24.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
__init__(bind: Optional[_AsyncSessionBind] = None, *, binds: Optional[Dict[_SessionBindKey, _AsyncSessionBind]] = None, sync_session_class: Optional[Type[Session]] = None, **kw: Any)¶ Построить новый
AsyncSession
.Все параметры, кроме
sync_session_class
, передаются непосредственно вызываемому модулюsync_session_class
для инстанцирования новогоSession
. Документация по параметрам приведена в разделеSession.__init__()
.- Параметры:
sync_session_class – Подкласс
Session
или другой вызываемый объект, который будет использоваться для построения проксируемогоSession
. Этот параметр может быть использован для предоставления пользовательских подклассовSession
. По умолчанию используется атрибут уровня классаAsyncSession.sync_session_class
. … versionadded:: 1.4.24
-
method
sqlalchemy.ext.asyncio.AsyncSession.
add(instance: object, _warn: bool = True) None ¶ Поместите объект в эту область
Session
.Проксирование класса
Session
от имени классаAsyncSession
.Объекты, находящиеся в состоянии transient при передаче в метод
Session.add()
, будут переходить в состояние pending до следующего flush, после которого они перейдут в состояние persistent.Объекты, находящиеся в состоянии detached при передаче в метод
Session.add()
, перейдут в состояние persistent непосредственно.Если транзакция, используемая
Session
, откатывается, то объекты, которые были переходными на момент передачи их вSession.add()
, будут переведены обратно в состояние transient и больше не будут присутствовать в этомSession
.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
add_all(instances: Iterable[object]) None ¶ Добавить заданную коллекцию экземпляров в данный
Session
.Проксирование класса
Session
от имени классаAsyncSession
.Общее описание поведения приведено в документации для
Session.add()
.
-
attribute
sqlalchemy.ext.asyncio.AsyncSession.
autoflush¶ Прокси для атрибута
Session.autoflush
от имени классаAsyncSession
.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
begin() AsyncSessionTransaction ¶ Возвращает объект
AsyncSessionTransaction
.Лежащий в основе
Session
будет выполнять действие «begin» при вводе объектаAsyncSessionTransaction
:async with async_session.begin(): # .. ORM transaction is begun
Обратите внимание, что ввод-вывод данных из базы данных обычно не происходит в момент начала транзакции на уровне сеанса, поскольку транзакции в базе данных начинаются по требованию. Тем не менее, блок begin является асинхронным для того, чтобы можно было использовать крючок события
SessionEvents.after_transaction_create()
, который может выполнить ввод-вывод.Общее описание ORM begin приведено в разделе
Session.begin()
.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
begin_nested() AsyncSessionTransaction ¶ Возвращает объект
AsyncSessionTransaction
, который начнет «вложенную» транзакцию, например, SAVEPOINT.Поведение аналогично поведению
AsyncSession.begin()
.Общее описание ORM begin nested приведено в разделе
Session.begin_nested()
.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async close() None ¶ Закрыть транзакционные ресурсы и объекты ORM, используемые данной
AsyncSession
.При этом удаляются все объекты ORM, связанные с данным
AsyncSession
, завершается любая транзакция и releases все объектыAsyncConnection
, которые данныйAsyncSession
сам вычеркнул из связанных с нимAsyncEngine
объектов. Затем операция оставляетAsyncSession
в состоянии, в котором он может быть использован снова.Совет
Метод
AsyncSession.close()
не препятствует повторному использованию сессии. СамAsyncSession
не имеет состояния «закрыто»; это означает, чтоAsyncSession
просто освобождает все соединения с базой данных и объекты ORM.См.также
Закрытие - подробно о семантике
AsyncSession.close()
-
async classmethod
sqlalchemy.ext.asyncio.AsyncSession.
close_all() None ¶ Закрыть все сеансы
AsyncSession
.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async commit() None ¶ Зафиксировать текущую выполняющуюся транзакцию.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async connection(**kw: Any) AsyncConnection ¶ Возвращает объект
AsyncConnection
, соответствующий транзакционному состоянию данного объектаSession
.Этот метод также может быть использован для установки параметров выполнения соединения с базой данных, используемого текущей транзакцией.
Добавлено в версии 1.4.24: Добавлены аргументы **kw, которые передаются в базовый метод
Session.connection()
.См.также
Session.connection()
- основная документация по «соединению»
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async delete(instance: object) None ¶ Пометить экземпляр как удаленный.
Операция удаления базы данных происходит при
flush()
.Поскольку эта операция может потребовать каскадирования по незагруженным связям, она является ожидаемой, чтобы обеспечить возможность выполнения этих запросов.
См.также
Session.delete()
- основная документация по удалению
-
attribute
sqlalchemy.ext.asyncio.AsyncSession.
deleted¶ Множество всех экземпляров, помеченных как «удаленные» в пределах данного
Session
Проксирование класса
Session
от имени классаAsyncSession
.
-
attribute
sqlalchemy.ext.asyncio.AsyncSession.
dirty¶ Множество всех постоянных экземпляров, считающихся грязными.
Проксирование класса
Session
от имени классаAsyncSession
.Например:
some_mapped_object in session.dirty
Экземпляры считаются грязными, если они были изменены, но не удалены.
Обратите внимание, что этот расчет «грязных» атрибутов является «оптимистичным»; большинство операций по установке атрибутов или изменению коллекции пометят экземпляр как «грязный» и поместят его в этот набор, даже если чистого изменения значения атрибута не произошло. Во время промывки значение каждого атрибута сравнивается с его ранее сохраненным значением, и если чистого изменения нет, то операция SQL не выполняется (это более дорогая операция, поэтому она выполняется только во время промывки).
Чтобы проверить, есть ли у экземпляра actionable net изменения в его атрибутах, используйте метод
Session.is_modified()
.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async execute(statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) Result[Any] ¶ Выполнить оператор и вернуть буферизованный объект
Result
.См.также
Session.execute()
- основная документация по выполнению
-
method
sqlalchemy.ext.asyncio.AsyncSession.
expire(instance: object, attribute_names: Optional[Iterable[str]] = None) None ¶ Истечение срока действия атрибутов экземпляра.
Проксирование класса
Session
от имени классаAsyncSession
.Помечает атрибуты экземпляра как устаревшие. При следующем обращении к атрибуту с истекшим сроком действия будет выдан запрос к текущему транзакционному контексту объекта
Session
, чтобы загрузить все атрибуты с истекшим сроком действия для данного экземпляра. Заметим, что в строго изолированной транзакции будут возвращены те же значения, которые были прочитаны ранее в этой же транзакции, независимо от изменений состояния базы данных вне этой транзакции.Для одновременного истечения срока действия всех объектов в
Session
используйтеSession.expire_all()
.Поведение объекта
Session
по умолчанию заключается в том, что при вызове методовSession.rollback()
илиSession.commit()
происходит удаление всего состояния, чтобы новое состояние могло быть загружено для новой транзакции. По этой причине вызовSession.expire()
имеет смысл только в том случае, если в текущей транзакции был выдан нестандартный SQL-оператор.- Параметры:
instance – Экземпляр, который необходимо обновить.
attribute_names – необязательный список строковых имен атрибутов, указывающих на подмножество атрибутов, срок действия которых должен быть истек.
См.также
Обновление / истечение срока действия - вводный материал
-
method
sqlalchemy.ext.asyncio.AsyncSession.
expire_all() None ¶ Истекает срок действия всех постоянных экземпляров в рамках данной сессии.
Проксирование класса
Session
от имени классаAsyncSession
.При следующем обращении к атрибутам постоянного экземпляра будет выдан запрос с использованием текущего транзакционного контекста объекта
Session
, чтобы загрузить все истекшие атрибуты для данного экземпляра. Заметим, что в строго изолированной транзакции будут возвращены те же значения, которые были прочитаны ранее в этой же транзакции, независимо от изменений в состоянии базы данных вне этой транзакции.Чтобы исключить отдельные объекты и отдельные атрибуты этих объектов, используйте
Session.expire()
.Поведение объекта
Session
по умолчанию заключается в том, что при вызове методовSession.rollback()
илиSession.commit()
все состояние завершается, чтобы новое состояние могло быть загружено для новой транзакции. По этой причине вызовSession.expire_all()
обычно не требуется, если предположить, что транзакция изолирована.См.также
Обновление / истечение срока действия - вводный материал
-
method
sqlalchemy.ext.asyncio.AsyncSession.
expunge(instance: object) None ¶ Удалить экземпляр из данного
Session
.Проксирование класса
Session
от имени классаAsyncSession
.При этом будут освобождены все внутренние ссылки на экземпляр. Каскадирование будет применяться в соответствии с правилом каскада expunge.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
expunge_all() None ¶ Удалить все экземпляры объектов из данного
Session
.Проксирование класса
Session
от имени классаAsyncSession
.Это эквивалентно вызову
expunge(obj)
на всех объектах в данномSession
.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async flush(objects: Optional[Sequence[Any]] = None) None ¶ Промыть все изменения объектов в базе данных.
См.также
Session.flush()
- основная документация для flush
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async 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 = {}) Optional[_O] ¶ Возвращает экземпляр, основанный на заданном идентификаторе первичного ключа, или
None
, если он не найден.См.также
Session.get()
- основная документация для get
-
method
sqlalchemy.ext.asyncio.AsyncSession.
get_bind(mapper: Optional[_EntityBindKey[_O]] = None, clause: Optional[ClauseElement] = None, bind: Optional[_SessionBind] = None, **kw: Any) Union[Engine, Connection] ¶ Возвращает «привязку», к которой привязан синхронно проксируемый
Session
.В отличие от метода
Session.get_bind()
, этот метод в настоящее время не используется даннымAsyncSession
каким-либо образом для разрешения движков для запросов.Примечание
Этот метод напрямую связан с методом
Session.get_bind()
, однако в настоящее время не может быть использован в качестве цели переопределения, в отличие от методаSession.get_bind()
. В приведенном ниже примере показано, как реализовать пользовательские схемыSession.get_bind()
, работающие сAsyncSession
иAsyncEngine
.Шаблон, представленный в Нестандартные вертикальные перегородки, иллюстрирует применение пользовательской схемы bind-lookup к
Session
, заданному набором объектовEngine
. Чтобы применить соответствующую реализациюSession.get_bind()
для использования с объектамиAsyncSession
иAsyncEngine
, продолжим подклассSession
и применим его кAsyncSession
с помощьюAsyncSession.sync_session_class
. Внутренний метод должен продолжать возвращать экземплярыEngine
, которые могут быть получены изAsyncEngine
с помощью атрибутаAsyncEngine.sync_engine
:# using example from "Custom Vertical Partitioning" import random from sqlalchemy.ext.asyncio import AsyncSession from sqlalchemy.ext.asyncio import create_async_engine from sqlalchemy.ext.asyncio import async_sessionmaker from sqlalchemy.orm import Session # construct async engines w/ async drivers engines = { 'leader':create_async_engine("sqlite+aiosqlite:///leader.db"), 'other':create_async_engine("sqlite+aiosqlite:///other.db"), 'follower1':create_async_engine("sqlite+aiosqlite:///follower1.db"), 'follower2':create_async_engine("sqlite+aiosqlite:///follower2.db"), } class RoutingSession(Session): def get_bind(self, mapper=None, clause=None, **kw): # within get_bind(), return sync engines if mapper and issubclass(mapper.class_, MyOtherClass): return engines['other'].sync_engine elif self._flushing or isinstance(clause, (Update, Delete)): return engines['leader'].sync_engine else: return engines[ random.choice(['follower1','follower2']) ].sync_engine # apply to AsyncSession using sync_session_class AsyncSessionMaker = async_sessionmaker( sync_session_class=RoutingSession )
Метод
Session.get_bind()
вызывается в неасинхронном, неявно неблокирующем контексте точно так же, как и крючки событий ORM и функции, вызываемые черезAsyncSession.run_sync()
, поэтому программы, которые хотят выполнять SQL-команды внутриSession.get_bind()
, могут продолжать делать это, используя код в стиле блокировки, который будет переведен в неявно асинхронный вызов в точке вызова IO на драйверах базы данных.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
get_nested_transaction() Optional[AsyncSessionTransaction] ¶ Возвращает текущую выполняющуюся вложенную транзакцию, если таковая имеется.
- Результат:
объект
AsyncSessionTransaction
, илиNone
.
Добавлено в версии 1.4.18.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
get_transaction() Optional[AsyncSessionTransaction] ¶ Возвращает текущую выполняющуюся корневую транзакцию, если таковая имеется.
- Результат:
объект
AsyncSessionTransaction
, илиNone
.
Добавлено в версии 1.4.18.
-
classmethod
sqlalchemy.ext.asyncio.AsyncSession.
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] ¶ Возвращает ключ идентификации.
Проксирование класса
Session
от имени классаAsyncSession
.Это псевдоним
identity_key()
.
-
attribute
sqlalchemy.ext.asyncio.AsyncSession.
identity_map¶ Прокси для атрибута
Session.identity_map
от имени классаAsyncSession
.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
in_nested_transaction() bool ¶ Возвращает True, если данная
Session
начала вложенную транзакцию, например, SAVEPOINT.Проксирование класса
Session
от имени классаAsyncSession
.Добавлено в версии 1.4.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
in_transaction() bool ¶ Возвращает True, если данная
Session
начала транзакцию.Проксирование класса
Session
от имени классаAsyncSession
.Добавлено в версии 1.4.
См.также
-
attribute
sqlalchemy.ext.asyncio.AsyncSession.
info¶ Модифицируемый пользователем словарь.
Проксирование класса
Session
от имени классаAsyncSession
.Начальное значение этого словаря может быть заполнено с помощью аргумента
info
конструктораSession
, конструктораsessionmaker
или методов фабрики. Словарь здесь всегда локален для данногоSession
и может быть изменен независимо от всех другихSession
объектов.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async invalidate() None ¶ Закройте этот сеанс, используя аннулирование соединения.
Полное описание приведено в разделе
Session.invalidate()
.
-
attribute
sqlalchemy.ext.asyncio.AsyncSession.
is_active¶ True, если данный
Session
не находится в состоянии «частичного отката».Проксирование класса
Session
от имени классаAsyncSession
.Изменено в версии 1.4:
Session
больше не начинает новую транзакцию немедленно, поэтому при первом инстанцированииSession
этот атрибут будет равен False.Состояние «частичного отката» обычно указывает на то, что процесс промывки транзакции
Session
завершился неудачно, и для полного отката транзакции необходимо вызвать методSession.rollback()
.Если эта
Session
вообще не находится в транзакции, тоSession
будет автозапускаться при ее первом использовании, поэтому в этом случаеSession.is_active
вернет True.В противном случае, если эта
Session
находится внутри транзакции, и эта транзакция не была откачена,Session.is_active
также вернет True.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
is_modified(instance: object, include_collections: bool = True) bool ¶ Возвращает
True
, если данный экземпляр имеет локально измененные атрибуты.Проксирование класса
Session
от имени классаAsyncSession
.Этот метод извлекает историю для каждого инструментального атрибута экземпляра и выполняет сравнение текущего значения с его ранее зафиксированным значением, если таковое имеется.
По сути, это более дорогая и точная версия проверки наличия данного экземпляра в коллекции
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.ext.asyncio.AsyncSession.
async merge(instance: _O, *, load: bool = True, options: Optional[Sequence[ORMOption]] = None) _O ¶ Скопировать состояние данного экземпляра в соответствующий экземпляр внутри данного
AsyncSession
.См.также
Session.merge()
- основная документация по слиянию
-
attribute
sqlalchemy.ext.asyncio.AsyncSession.
new¶ Множество всех экземпляров, помеченных как «новые» в пределах данного
Session
.Проксирование класса
Session
от имени классаAsyncSession
.
-
attribute
sqlalchemy.ext.asyncio.AsyncSession.
no_autoflush¶ Возвращает менеджер контекста, в котором отключена автопромывка.
Проксирование класса
Session
от имени классаAsyncSession
.например:
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.ext.asyncio.AsyncSession.
object_session(instance: object) Optional[Session] ¶ Возвращает
Session
, к которому принадлежит объект.Проксирование класса
Session
от имени классаAsyncSession
.Это псевдоним
object_session()
.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async refresh(instance: object, attribute_names: Optional[Iterable[str]] = None, with_for_update: ForUpdateParameter = None) None ¶ Истечение и обновление атрибутов для данного экземпляра.
Будет выдан запрос к базе данных, и все атрибуты обновятся, получив текущее значение в базе данных.
Это асинхронная версия метода
Session.refresh()
. Полное описание всех опций приведено в этом методе.См.также
Session.refresh()
- основная документация по обновлению
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async rollback() None ¶ Откат текущей выполняемой транзакции.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async run_sync(fn: Callable[[...], Any], *arg: Any, **kw: Any) Any ¶ Вызывает данный синхронный (т.е. не async) вызываемый модуль, передавая в качестве первого аргумента синхронный стиль
Session
.Этот метод позволяет запускать традиционные синхронные функции SQLAlchemy в контексте приложения asyncio.
Например:
def some_business_method(session: Session, param: str) -> str: '''A synchronous function that does not require awaiting :param session: a SQLAlchemy Session, used synchronously :return: an optional return value is supported ''' session.add(MyObject(param=param)) session.flush() return "success" async def do_something_async(async_engine: AsyncEngine) -> None: '''an async function that uses awaiting''' with AsyncSession(async_engine) as async_session: # run some_business_method() with a sync-style # Session, proxied into an awaitable return_code = await async_session.run_sync(some_business_method, param="param1") print(return_code)
Этот метод поддерживает цикл событий asyncio вплоть до соединения с базой данных, запуская заданную вызываемую переменную в специально инструментированном гринлете.
Совет
Предоставленный callable вызывается inline в цикле событий asyncio и будет блокировать традиционные вызовы IO. IO в рамках этой вызываемой переменной должен вызывать только API базы данных SQLAlchemy asyncio, которые будут должным образом адаптированы к контексту greenlet.
См.также
AsyncAttrs
- миксин для сопоставленных классов ORM, который обеспечивает аналогичную возможность более лаконично на основе каждого атрибута
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async scalar(statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) Any ¶ Выполнить оператор и вернуть скалярный результат.
См.также
Session.scalar()
- основная документация по скаляру
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async scalars(statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) ScalarResult[Any] ¶ Выполнение оператора и возврат скалярных результатов.
- Результат:
объект
ScalarResult
Добавлено в версии 1.4.24: Добавлено
AsyncSession.scalars()
Добавлено в версии 1.4.26: Добавлено
async_scoped_session.scalars()
См.также
Session.scalars()
- основная документация по скалярамAsyncSession.stream_scalars()
- потоковая версия
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async stream(statement: Executable, params: Optional[_CoreAnyExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) AsyncResult[Any] ¶ Выполнить оператор и вернуть потоковый объект
AsyncResult
.
-
method
sqlalchemy.ext.asyncio.AsyncSession.
async stream_scalars(statement: Executable, params: Optional[_CoreSingleExecuteParams] = None, *, execution_options: OrmExecuteOptionsParameter = {}, bind_arguments: Optional[_BindArguments] = None, **kw: Any) AsyncScalarResult[Any] ¶ Выполнить оператор и вернуть поток скалярных результатов.
- Результат:
объект
AsyncScalarResult
Добавлено в версии 1.4.24.
См.также
Session.scalars()
- основная документация по скалярамAsyncSession.scalars()
- непотоковая версия
-
attribute
sqlalchemy.ext.asyncio.AsyncSession.
sync_session: Session¶ Ссылка на базовый
Session
, к которому данныйAsyncSession
проксирует запросы.Этот экземпляр может быть использован в качестве цели события.
-
attribute
- class sqlalchemy.ext.asyncio.AsyncSessionTransaction¶
Обертка для объекта ORM
SessionTransaction
.Этот объект предоставляется для того, чтобы можно было вернуть объект удержания транзакции для
AsyncSession.begin()
.Объект поддерживает как явные вызовы
AsyncSessionTransaction.commit()
иAsyncSessionTransaction.rollback()
, так и использование в качестве асинхронного менеджера контекста.Добавлено в версии 1.4.
Members
Классическая подпись.
класс
sqlalchemy.ext.asyncio.AsyncSessionTransaction
(sqlalchemy.ext.asyncio.base.ReversibleProxy
,sqlalchemy.ext.asyncio.base.StartableContext
)-
method
sqlalchemy.ext.asyncio.AsyncSessionTransaction.
async commit() None ¶ Зафиксируйте это
AsyncTransaction
.
-
method
sqlalchemy.ext.asyncio.AsyncSessionTransaction.
async rollback() None ¶ Откатитесь назад
AsyncTransaction
.
-
method