Асинхронный ввод/вывод (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(), которые не содержат ожидающего хука.

В 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().

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())

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

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

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

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

• События могут быть зарегистрированы на уровне экземпляра (например, конкретного экземпляра AsyncEngine) путем связывания события с атрибутом sync, который ссылается на проксируемый объект. Например, чтобы зарегистрировать событие PoolEvents.connect() против экземпляра AsyncEngine, используйте в качестве цели его атрибут AsyncEngine.sync_engine. К целям относятся:

  AsyncEngine.sync_engine

  AsyncConnection.sync_connection

  AsyncConnection.sync_engine

  AsyncSession.sync_session

• Для регистрации события на уровне класса, направленного на все экземпляры одного типа (например, на все экземпляры AsyncSession), используйте соответствующий класс-стиль синхронизации. Например, чтобы зарегистрировать событие SessionEvents.before_commit() против класса AsyncSession, используйте в качестве цели класс Session.

• Для регистрации на уровне sessionmaker объедините явный sessionmaker с async_sessionmaker, используя async_sessionmaker.sync_session_class, и свяжите события с sessionmaker.

При работе в обработчике событий в контексте asyncio объекты, подобные Connection, продолжают работать в привычном «синхронном» режиме, не требуя использования await или async; когда сообщения в конечном итоге поступают на адаптер базы данных asyncio, стиль вызова прозрачно адаптируется обратно к стилю вызова asyncio. Для событий, которым передается соединение уровня DBAPI, например PoolEvents.connect(), объект представляет собой pep-249 совместимый объект «соединение», который будет адаптировать вызовы в стиле синхронизации к драйверу asyncio.

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,  # ...
        )
    )

Использование нескольких циклов событий 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.

При использовании 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()

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()

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

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 движка¶

function sqlalchemy.ext.asyncio.create_async_engine(url: Union[str, URL], **kw: Any) → AsyncEngine¶

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

Аргументы, передаваемые в create_async_engine(), в основном идентичны аргументам, передаваемым в функцию create_engine(). Указанный диалект должен быть asyncio-совместимым диалектом, например asyncpg.

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

Параметры:

async_creator – async-вызываемая функция, возвращающая asyncio-соединение на уровне драйвера. Если функция задана, то она не должна принимать никаких аргументов и возвращает новое asyncio-соединение от базового драйвера базы данных asyncio; соединение будет обернуто в соответствующие структуры для использования с AsyncEngine. Обратите внимание, что параметры, указанные в URL, здесь не применяются, и функция-создатель должна использовать свои собственные параметры соединения. Этот параметр является asyncio-эквивалентом параметра create_engine.creator функции create_engine(). … versionadded:: 2.0.16

function sqlalchemy.ext.asyncio.async_engine_from_config(configuration: Dict[str, Any], prefix: str = 'sqlalchemy.', **kwargs: Any) → AsyncEngine¶

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

Эта функция аналогична функции engine_from_config() в SQLAlchemy Core, за исключением того, что запрашиваемый диалект должен быть asyncio-совместимым диалектом, например asyncpg. Сигнатура аргументов функции идентична сигнатуре аргументов функции engine_from_config().

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

function sqlalchemy.ext.asyncio.create_async_pool_from_url(url: Union[str, URL], **kwargs: Any) → Pool¶

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

Аргументы, передаваемые в create_async_pool_from_url(), в основном идентичны аргументам, передаваемым в функцию create_pool_from_url(). Указанный диалект должен быть asyncio-совместимым диалектом, например asyncpg.

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

class sqlalchemy.ext.asyncio.AsyncEngine¶

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

AsyncEngine приобретается с помощью функции create_async_engine():

from sqlalchemy.ext.asyncio import create_async_engine
engine = create_async_engine("postgresql+asyncpg://user:pass@host/dbname")

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

Members

begin(), clear_compiled_cache(), connect(), dialect, dispose(), driver, echo, engine, execution_options(), get_execution_options(), name, pool, raw_connection(), sync_engine, update_execution_options(), url

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

класс sqlalchemy.ext.asyncio.AsyncEngine (sqlalchemy.ext.asyncio.base.ProxyComparable, sqlalchemy.ext.asyncio.AsyncConnectable)

method sqlalchemy.ext.asyncio.AsyncEngine.begin() → AsyncIterator[AsyncConnection]¶

Возвращает менеджер контекста, при вводе которого будет выдано сообщение AsyncConnection с установленным AsyncTransaction.

Например:

async with async_engine.begin() as conn:
    await conn.execute(
        text("insert into table (x, y, z) values (1, 2, 3)")
    )
    await conn.execute(text("my_special_procedure(5)"))

method sqlalchemy.ext.asyncio.AsyncEngine.clear_compiled_cache() → None¶

Очистить скомпилированный кэш, связанный с диалектом.

Проксирование класса Engine от имени класса AsyncEngine.

Это относится только к встроенному кэшу, который устанавливается через параметр create_engine.query_cache_size. Это не влияет на кэши словарей, которые были переданы через параметр Connection.execution_options.query_cache.

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

method sqlalchemy.ext.asyncio.AsyncEngine.connect() → AsyncConnection¶

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

При вводе в качестве менеджера асинхронного контекста AsyncConnection будет получено соединение с базовой базой данных из пула соединений:

async with async_engine.connect() as conn:
    result = await conn.execute(select(user_table))

Запуск AsyncConnection может быть осуществлен и вне контекстного менеджера путем вызова его метода AsyncConnection.start().

attribute sqlalchemy.ext.asyncio.AsyncEngine.dialect¶

Прокси для атрибута Engine.dialect от имени класса AsyncEngine.

method sqlalchemy.ext.asyncio.AsyncEngine.async dispose(close: bool = True) → None¶

Утилизировать пул соединений, используемый данным AsyncEngine.

Параметры:

close – если оставить значение по умолчанию True, то это приведет к полному закрытию всех текущих проверенных соединений с базой данных. Соединения, которые все еще проверяются, не будут закрыты, однако они больше не будут связаны с этим Engine, поэтому, когда они закрываются по отдельности, в конечном итоге Pool, с которым они связаны, будет собран мусор, и они будут полностью закрыты, если еще не были закрыты при регистрации. Если установлено значение False, то предыдущий пул соединений отменяется, и в остальном он никак не затрагивается.

См.также

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-соединение из пула соединений.

См.также

Работа с драйверами SQL и необработанными соединениями DBAPI

attribute sqlalchemy.ext.asyncio.AsyncEngine.sync_engine: Engine¶

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

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

См.также

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

method sqlalchemy.ext.asyncio.AsyncEngine.update_execution_options(**opt: Any) → None¶

Обновить словарь execution_options по умолчанию для данного Engine.

Проксирование класса Engine от имени класса AsyncEngine.

Заданные ключи/значения в **opt добавляются к опциям выполнения по умолчанию, которые будут использоваться для всех соединений. Начальное содержимое этого словаря может быть передано через параметр execution_options в create_engine().

См.также

Connection.execution_options()

Engine.execution_options()

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.

Members

begin(), begin_nested(), close(), closed, commit(), connection, default_isolation_level, dialect, exec_driver_sql(), execute(), execution_options(), get_nested_transaction(), get_raw_connection(), get_transaction(), in_nested_transaction(), in_transaction(), info, invalidate(), invalidated, rollback(), run_sync(), scalar(), scalars(), start(), stream(), stream_scalars(), sync_connection, sync_engine

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

класс sqlalchemy.ext.asyncio.AsyncConnection (sqlalchemy.ext.asyncio.base.ProxyComparable, sqlalchemy.ext.asyncio.base.StartableContext, sqlalchemy.ext.asyncio.AsyncConnectable)

method sqlalchemy.ext.asyncio.AsyncConnection.begin() → AsyncTransaction¶

Начать транзакцию до того, как произойдет автозапуск.

method sqlalchemy.ext.asyncio.AsyncConnection.begin_nested() → AsyncTransaction¶

Начинает вложенную транзакцию и возвращает хэндл транзакции.

method sqlalchemy.ext.asyncio.AsyncConnection.async close() → None¶

Закройте эту AsyncConnection.

Это приводит к откату транзакции, если таковая уже существует.

attribute sqlalchemy.ext.asyncio.AsyncConnection.closed¶

Возвращает True, если данное соединение закрыто.

Проксирование класса Connection от имени класса AsyncConnection.

method sqlalchemy.ext.asyncio.AsyncConnection.async commit() → None¶

Зафиксировать транзакцию, находящуюся в данный момент в процессе выполнения.

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

Транзакция начинается на Connection автоматически при первом выполнении оператора или при вызове метода Connection.begin().

attribute sqlalchemy.ext.asyncio.AsyncConnection.connection¶

Не реализовано для async; вызывайте AsyncConnection.get_raw_connection().

attribute sqlalchemy.ext.asyncio.AsyncConnection.default_isolation_level¶

Уровень изоляции времени начального соединения, связанный с используемым Dialect.

Проксирование класса Connection от имени класса AsyncConnection.

Это значение не зависит от опций выполнения Connection.execution_options.isolation_level и Engine.execution_options.isolation_level и определяется Dialect при создании первого соединения путем выполнения SQL-запроса к базе данных для текущего уровня изоляции до выдачи каких-либо дополнительных команд.

Вызов этого аксессора не вызывает никаких новых SQL-запросов.

См.также

Connection.get_isolation_level() - просмотр текущего фактического уровня изоляции

create_engine.isolation_level - устанавливается на уровень изоляции Engine

Connection.execution_options.isolation_level - устанавливается на уровень изоляции Connection

attribute sqlalchemy.ext.asyncio.AsyncConnection.dialect¶

Прокси для атрибута Connection.dialect от имени класса AsyncConnection.

method sqlalchemy.ext.asyncio.AsyncConnection.async exec_driver_sql(statement: str, parameters: Optional[_DBAPIAnyExecuteParams] = None, execution_options: Optional[CoreExecuteOptionsParameter] = None) → CursorResult[Any]¶

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

method sqlalchemy.ext.asyncio.AsyncConnection.async execute(statement: Executable, parameters: Optional[_CoreAnyExecuteParams] = None, *, execution_options: Optional[CoreExecuteOptionsParameter] = None) → CursorResult[Any]¶

Выполняет конструкцию SQL-оператора и возвращает буферизованное значение Result.

Параметры:

• object – Оператор, который должен быть выполнен. Это всегда объект, находящийся как в иерархии ClauseElement, так и в иерархии Executable, включая: * Select * Insert, Update, Delete * TextClause и TextualSelect * DDL и объекты, наследующие от ExecutableDDLElement.

• parameters – параметры, которые будут связываться в операторе. Это может быть либо словарь имен и значений параметров, либо изменяемая последовательность (например, список) словарей. Если передается список словарей, то при выполнении оператора будет использован метод DBAPI cursor.executemany(). При передаче одного словаря будет использоваться метод 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.

См.также

AsyncSession.run_sync()

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

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.

См.также

AsyncConnection.stream_scalars()

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

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

См.также

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

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

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

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

См.также

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

class sqlalchemy.ext.asyncio.AsyncTransaction¶

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

Members

close(), commit(), rollback(), start()

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

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

class sqlalchemy.ext.asyncio.AsyncResult¶

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

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

Примечание

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

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

Members

all(), close(), closed, columns(), fetchall(), fetchmany(), fetchone(), first(), freeze(), keys(), mappings(), one(), one_or_none(), partitions(), scalar(), scalar_one(), scalar_one_or_none(), scalars(), t, tuples(), unique(), yield_per()

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

класс sqlalchemy.ext.asyncio.AsyncResult (sqlalchemy.engine._WithKeys, sqlalchemy.ext.asyncio.AsyncCommon)

method sqlalchemy.ext.asyncio.AsyncResult.async all() → Sequence[Row[_TP]]¶

Возвращает все строки в списке.

Закрывает набор результатов после вызова. Последующие вызовы будут возвращать пустой список.

Результат:

список объектов Row.

method sqlalchemy.ext.asyncio.AsyncResult.async close() → None¶

наследуется от AsyncCommon.close() метода AsyncCommon

Закройте этот результат.

attribute sqlalchemy.ext.asyncio.AsyncResult.closed¶

наследуется от AsyncCommon.closed атрибута AsyncCommon

проксирует атрибут .closed базового объекта result, если таковой имеется, иначе возникает ошибка AttributeError.

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

method sqlalchemy.ext.asyncio.AsyncResult.columns(*col_expressions: _KeyIndexType) → Self¶

Определите столбцы, которые должны быть возвращены в каждой строке.

Полное описание поведения см. в разделе Result.columns() в синхронном API SQLAlchemy.

method sqlalchemy.ext.asyncio.AsyncResult.async fetchall() → Sequence[Row[_TP]]¶

Синоним метода AsyncResult.all().

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

method sqlalchemy.ext.asyncio.AsyncResult.async fetchmany(size: Optional[int] = None) → Sequence[Row[_TP]]¶

Получение большого количества строк.

Когда все строки исчерпаны, возвращается пустой список.

Этот метод предусмотрен для обратной совместимости с SQLAlchemy 1.x.x.

Для получения строк в группах используйте метод AsyncResult.partitions().

Результат:

список объектов Row.

См.также

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 и все, кроме первой строки, будут отброшены.

См.также

ORM Query Unified with Core Select

Результат:

объект Row, или None, если строк не осталось.

См.также

AsyncResult.scalar()

AsyncResult.one()

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

См.также

AsyncResult.first()

AsyncResult.one_or_none()

AsyncResult.scalar_one()

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

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

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

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

Результат:

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

повышает:

MultipleResultsFound

См.также

AsyncResult.first()

AsyncResult.one()

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().

См.также

AsyncResult.one()

AsyncResult.scalars()

method sqlalchemy.ext.asyncio.AsyncResult.async scalar_one_or_none() → Optional[Any]¶

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

Это эквивалентно вызову AsyncResult.scalars(), а затем AsyncResult.one_or_none().

См.также

AsyncResult.one_or_none()

AsyncResult.scalars()

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

См.также

Использование курсоров на стороне сервера (они же потоковые результаты) - описывает поведение Core для Result.yield_per()

Получение больших наборов результатов с доходностью за - в Руководство по составлению запросов в ORM

class sqlalchemy.ext.asyncio.AsyncScalarResult¶

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

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

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

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

Members

all(), close(), closed, fetchall(), fetchmany(), first(), one(), one_or_none(), partitions(), unique(), yield_per()

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

класс sqlalchemy.ext.asyncio.AsyncScalarResult (sqlalchemy.ext.asyncio.AsyncCommon)

method sqlalchemy.ext.asyncio.AsyncScalarResult.async all() → Sequence[_R]¶

Возвращает все скалярные значения в списке.

Эквивалентно AsyncResult.all() за исключением того, что возвращаются скалярные значения, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async close() → None¶

наследуется от AsyncCommon.close() метода AsyncCommon

Закройте этот результат.

attribute sqlalchemy.ext.asyncio.AsyncScalarResult.closed¶

наследуется от AsyncCommon.closed атрибута AsyncCommon

проксирует атрибут .closed базового объекта result, если таковой имеется, иначе возникает ошибка AttributeError.

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

method sqlalchemy.ext.asyncio.AsyncScalarResult.async fetchall() → Sequence[_R]¶

Синоним метода AsyncScalarResult.all().

method sqlalchemy.ext.asyncio.AsyncScalarResult.async fetchmany(size: Optional[int] = None) → Sequence[_R]¶

Получение большого количества объектов.

Эквивалентно AsyncResult.fetchmany() за исключением того, что возвращаются скалярные значения, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async first() → Optional[_R]¶

Получить первый объект или None, если объект отсутствует.

Эквивалентно AsyncResult.first() за исключением того, что возвращаются скалярные значения, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async one() → _R¶

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

Эквивалентно AsyncResult.one() за исключением того, что возвращаются скалярные значения, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async one_or_none() → Optional[_R]¶

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

Эквивалентно AsyncResult.one_or_none() за исключением того, что возвращаются скалярные значения, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncScalarResult.async partitions(size: Optional[int] = None) → AsyncIterator[Sequence[_R]]¶

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

Эквивалентно AsyncResult.partitions() за исключением того, что возвращаются скалярные значения, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncScalarResult.unique(strategy: Optional[_UniqueFilterType] = None) → Self¶

Применить уникальную фильтрацию к объектам, возвращаемым данным AsyncScalarResult.

Подробности использования см. в разделе AsyncResult.unique().

method sqlalchemy.ext.asyncio.AsyncScalarResult.yield_per(num: int) → Self¶

наследуется от FilterResult.yield_per() метода FilterResult

Настройте стратегию выборки строк на одновременную выборку num строк.

Метод FilterResult.yield_per() является проходным для метода Result.yield_per(). Указания по его использованию приведены в документации к этому методу.

Добавлено в версии 1.4.40: - added FilterResult.yield_per() so that the method is available on all result set implementations

См.также

Использование курсоров на стороне сервера (они же потоковые результаты) - описывает поведение Core для Result.yield_per()

Получение больших наборов результатов с доходностью за - в Руководство по составлению запросов в ORM

class sqlalchemy.ext.asyncio.AsyncMappingResult¶

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

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

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

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

Members

all(), close(), closed, columns(), fetchall(), fetchmany(), fetchone(), first(), keys(), one(), one_or_none(), partitions(), unique(), yield_per()

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

класс sqlalchemy.ext.asyncio.AsyncMappingResult (sqlalchemy.engine._WithKeys, sqlalchemy.ext.asyncio.AsyncCommon)

method sqlalchemy.ext.asyncio.AsyncMappingResult.async all() → Sequence[RowMapping]¶

Возвращает все строки в списке.

Эквивалентно AsyncResult.all() за исключением того, что возвращаются значения RowMapping, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async close() → None¶

наследуется от AsyncCommon.close() метода AsyncCommon

Закройте этот результат.

attribute sqlalchemy.ext.asyncio.AsyncMappingResult.closed¶

наследуется от AsyncCommon.closed атрибута AsyncCommon

проксирует атрибут .closed базового объекта result, если таковой имеется, иначе возникает ошибка AttributeError.

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

method sqlalchemy.ext.asyncio.AsyncMappingResult.columns(*col_expressions: _KeyIndexType) → Self¶

Определите столбцы, которые должны быть возвращены в каждой строке.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async fetchall() → Sequence[RowMapping]¶

Синоним метода AsyncMappingResult.all().

method sqlalchemy.ext.asyncio.AsyncMappingResult.async fetchmany(size: Optional[int] = None) → Sequence[RowMapping]¶

Получение большого количества строк.

Эквивалентно AsyncResult.fetchmany() за исключением того, что возвращаются значения RowMapping, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async fetchone() → Optional[RowMapping]¶

Получить один объект.

Эквивалентно AsyncResult.fetchone() за исключением того, что возвращаются значения RowMapping, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async first() → Optional[RowMapping]¶

Получить первый объект или None, если объект отсутствует.

Эквивалентно AsyncResult.first() за исключением того, что возвращаются значения RowMapping, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncMappingResult.keys() → RMKeyView¶

наследуется от sqlalchemy.engine._WithKeys.keys метода sqlalchemy.engine._WithKeys

Возвращает итерируемое представление, которое выдает ключи строк, которые будут представлены каждым Row.

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

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

Изменено в версии 1.4: возвращается объект представления ключей, а не обычный список.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async one() → RowMapping¶

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

Эквивалентно AsyncResult.one() за исключением того, что возвращаются значения RowMapping, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async one_or_none() → Optional[RowMapping]¶

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

Эквивалентно AsyncResult.one_or_none() за исключением того, что возвращаются значения RowMapping, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncMappingResult.async partitions(size: Optional[int] = None) → AsyncIterator[Sequence[RowMapping]]¶

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

Эквивалентно AsyncResult.partitions() за исключением того, что возвращаются значения RowMapping, а не объекты Row.

method sqlalchemy.ext.asyncio.AsyncMappingResult.unique(strategy: Optional[_UniqueFilterType] = None) → Self¶

Применить уникальную фильтрацию к объектам, возвращаемым данным AsyncMappingResult.

Подробности использования см. в разделе AsyncResult.unique().

method sqlalchemy.ext.asyncio.AsyncMappingResult.yield_per(num: int) → Self¶

наследуется от FilterResult.yield_per() метода FilterResult

Настройте стратегию выборки строк на одновременную выборку num строк.

Метод FilterResult.yield_per() является проходным для метода Result.yield_per(). Указания по его использованию приведены в документации к этому методу.

Добавлено в версии 1.4.40: - added FilterResult.yield_per() so that the method is available on all result set implementations

См.также

Использование курсоров на стороне сервера (они же потоковые результаты) - описывает поведение Core для Result.yield_per()

Получение больших наборов результатов с доходностью за - в Руководство по составлению запросов в ORM

class sqlalchemy.ext.asyncio.AsyncTupleResult¶

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

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

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

класс sqlalchemy.ext.asyncio.AsyncTupleResult (sqlalchemy.ext.asyncio.AsyncCommon, sqlalchemy.util.langhelpers.TypingOnly)

Документация ORM Session API¶

function sqlalchemy.ext.asyncio.async_object_session(instance: object) → Optional[AsyncSession]¶

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

Эта функция использует функцию sync-API object_session для получения Session, ссылающегося на данный экземпляр, а затем связывает его с исходным AsyncSession.

Если AsyncSession был собран мусор, то возвращаемое значение будет None.

Эта функциональность также доступна из аксессора InstanceState.async_session.

Параметры:

instance – экземпляр, сопоставленный с ORM

Результат:

объект AsyncSession, или None.

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

function sqlalchemy.ext.asyncio.async_session(session: Session) → Optional[AsyncSession]¶

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

Параметры:

session – экземпляр Session.

Результат:

экземпляр AsyncSession или None.

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

class sqlalchemy.ext.asyncio.async_sessionmaker¶

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

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

например:

from sqlalchemy.ext.asyncio import create_async_engine
from sqlalchemy.ext.asyncio import AsyncSession
from sqlalchemy.ext.asyncio import async_sessionmaker

async def run_some_sql(async_session: async_sessionmaker[AsyncSession]) -> None:
    async with async_session() as session:
        session.add(SomeObject(data="object"))
        session.add(SomeOtherObject(name="other object"))
        await session.commit()

async def main() -> None:
    # an AsyncEngine, which the AsyncSession will use for connection
    # resources
    engine = create_async_engine('postgresql+asyncpg://scott:tiger@localhost/')

    # create a reusable factory for new AsyncSession instances
    async_session = async_sessionmaker(engine)

    await run_some_sql(async_session)

    await engine.dispose()

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

Добавлено в версии 2.0: async_sessionmaker предоставляет класс sessionmaker, предназначенный для работы с объектом AsyncSession, включая поддержку типизации pep-484.

См.также

Синопсис - ORM - показывает пример использования

sessionmaker - общий обзор

sessionmaker архитектура

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

Members

__call__(), __init__(), begin(), configure()

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

класс 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://'))