Асинхронный ввод/вывод (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. Этот миксин, добавленный к конкретному классу или, в более общем случае, к суперклассу Declarative Base, предоставляет аксессор 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.

    См.также

    AsyncAttrs

  • Коллекции могут быть заменены на коллекции 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 и должна быть предпочтительнее.

  • При использовании 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. Отличия заключаются в следующем:

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

  2. Никакого «обезьянничанья» не происходит. В приведенном примере используется реальный драйвер asyncio, а пул соединений SQLAlchemy также использует встроенную в Python функцию asyncio.Queue для пула соединений.

  3. Программа может свободно переключаться между кодом async/await и содержащимися в ней функциями, использующими код sync, практически без ущерба для производительности. Нет ни «исполнителя потока», ни дополнительных ожидающих или синхронизирующих устройств.

  4. В качестве базовых сетевых драйверов также используются чисто питоновские концепции asyncio, никаких сторонних сетевых библиотек, как это делают gevent и eventlet, не используется.

Использование событий с помощью расширения asyncio

SQLAlchemy event system не подвергается прямому воздействию со стороны расширения asyncio, то есть пока не существует «асинхронной» версии обработчика событий SQLAlchemy.

Однако, поскольку расширение asyncio окружает обычный синхронный API SQLAlchemy, обычные обработчики событий в «синхронном» стиле свободно доступны, как это было бы, если бы asyncio не использовалось.

Как будет показано ниже, в настоящее время существует две стратегии регистрации событий в asyncio-facing API:

При работе в обработчике событий в контексте 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, используя словарь конфигурации.

AsyncConnection

Asyncio-прокси для Connection.

AsyncEngine

Asyncio-прокси для Engine.

AsyncTransaction

Asyncio-прокси для Transaction.

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.

Классическая подпись.

класс 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, то предыдущий пул соединений отменяется, и в остальном он никак не затрагивается.

См.также

Engine.dispose()

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.

См.также

Engine.execution_options()

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.

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.

Классическая подпись.

класс 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(). При передаче одного словаря будет использоваться метод DBAPI cursor.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 вне использования блока Python with:.

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.

См.также

AsyncConnection.stream()

attribute sqlalchemy.ext.asyncio.AsyncConnection.sync_connection: Optional[Connection]

Ссылка на стиль синхронизации Connection, к которому данный AsyncConnection проксирует запросы.

Этот экземпляр может быть использован в качестве цели события.

attribute sqlalchemy.ext.asyncio.AsyncConnection.sync_engine: Engine

Ссылка на стиль синхронизации Engine, с которым данный AsyncConnection связан через лежащий в его основе Connection.

Этот экземпляр может быть использован в качестве цели события.

class sqlalchemy.ext.asyncio.AsyncTransaction

Asyncio-прокси для Transaction.

Классическая подпись.

класс 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 вне использования блока Python with:.

Документация API по набору результатов

Объект AsyncResult является асинхронно-адаптированной версией объекта Result. Он возвращается только при использовании методов AsyncConnection.stream() или AsyncSession.stream(), которые возвращают объект результата, находящийся поверх активного курсора базы данных.

Object Name Description

AsyncMappingResult

Обертка для AsyncResult, которая возвращает значения словаря, а не Row.

AsyncResult

Обертка asyncio вокруг объекта Result.

AsyncScalarResult

Обертка для AsyncResult, которая возвращает скалярные, а не Row значения.

AsyncTupleResult

AsyncResult, который типизирован как возвращающий обычные кортежи Python, а не строки.

class sqlalchemy.ext.asyncio.AsyncResult

Обертка asyncio вокруг объекта Result.

Параметр AsyncResult применяется только при выполнении операторов, использующих курсор на стороне сервера. Он возвращается только из методов AsyncConnection.stream() и AsyncSession.stream().

Примечание

Как и в случае с Result, этот объект используется для результатов ORM, возвращаемых AsyncSession.execute(), которые могут содержать экземпляры отображаемых объектов ORM по отдельности или в виде кортежей. Обратите внимание, что эти объекты результатов не дедуплицируют экземпляры или строки автоматически, как это происходит в случае с традиционным объектом Query. Для дедупликации экземпляров или строк в языке Python используйте метод-модификатор AsyncResult.unique().

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

Классическая подпись.

класс 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.

См.также

AsyncResult.partitions()

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.

повышает:

MultipleResultsFound, NoResultFound

method sqlalchemy.ext.asyncio.AsyncResult.async one_or_none() Optional[Row[_TP]]

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

Возвращает None, если результат не содержит строк. Возвращает MultipleResultsFound, если возвращается несколько строк.

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

Результат:

Первая строка Row или None, если строка отсутствует.

повышает:

MultipleResultsFound

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 при наборе текста.

См.также

AsyncResult.t - более короткий синоним

Row.t - Row версия

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

class sqlalchemy.ext.asyncio.AsyncScalarResult

Обертка для AsyncResult, которая возвращает скалярные, а не Row значения.

Объект AsyncScalarResult приобретается путем вызова метода AsyncResult.scalars().

Полное описание поведения объекта ScalarResult в синхронном API SQLAlchemy см.

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

Классическая подпись.

класс 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

class sqlalchemy.ext.asyncio.AsyncMappingResult

Обертка для AsyncResult, которая возвращает значения словаря, а не Row.

Объект AsyncMappingResult приобретается путем вызова метода AsyncResult.mappings().

Полное описание поведения объекта MappingResult в синхронном API SQLAlchemy см.

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

Классическая подпись.

класс 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

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)

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

async_scoped_session

Обеспечивает масштабируемое управление объектами AsyncSession.

async_session(session)

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

async_sessionmaker

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

AsyncAttrs

Класс Mixin, обеспечивающий ожидаемый доступ ко всем атрибутам.

AsyncSession

Asyncio-версия Session.

AsyncSessionTransaction

Обертка для объекта ORM SessionTransaction.

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.

Классическая подпись.

класс 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.

Классическая подпись.

класс 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.

См. sessionmaker.configure().

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() - непотоковая версия

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

awaitable_attrs

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
class sqlalchemy.ext.asyncio.AsyncSession

Asyncio-версия Session.

AsyncSession является прокси для традиционного экземпляра Session.

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

Для использования AsyncSession с пользовательскими реализациями Session см. параметр AsyncSession.sync_session_class.

Классическая подпись.

класс 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.

См.также

Session.is_active

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, который обеспечивает аналогичную возможность более лаконично на основе каждого атрибута

AsyncConnection.run_sync()

Запуск синхронных методов и функций в asyncio

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 проксирует запросы.

Этот экземпляр может быть использован в качестве цели события.

class sqlalchemy.ext.asyncio.AsyncSessionTransaction

Обертка для объекта ORM SessionTransaction.

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

Объект поддерживает как явные вызовы AsyncSessionTransaction.commit() и AsyncSessionTransaction.rollback(), так и использование в качестве асинхронного менеджера контекста.

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

Members

commit(), rollback()

Классическая подпись.

класс 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.

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