sqlalchemy.ext.asyncio.result.AsyncResult

class documentation

class AsyncResult(_WithKeys, AsyncCommon[Row[_TP]]): (source)

View In Hierarchy

An asyncio wrapper around a :class:`_result.Result` object. The :class:`_asyncio.AsyncResult` only applies to statement executions that use a server-side cursor. It is returned only from the :meth:`_asyncio.AsyncConnection.stream` and :meth:`_asyncio.AsyncSession.stream` methods. .. note:: As is the case with :class:`_engine.Result`, this object is used for ORM results returned by :meth:`_asyncio.AsyncSession.execute`, which can yield instances of ORM mapped objects either individually or within tuple-like rows. Note that these result objects do not deduplicate instances or rows automatically as is the case with the legacy :class:`_orm.Query` object. For in-Python de-duplication of instances or rows, use the :meth:`_asyncio.AsyncResult.unique` modifier method. .. versionadded:: 1.4

Method __aiter__ Undocumented
Async Method __anext__ Undocumented
Method __init__ Undocumented
Async Method all Return all rows in a list.
Method columns Establish the columns that should be returned in each row.
Async Method fetchall A synonym for the :meth:`_asyncio.AsyncResult.all` method.
Async Method fetchmany Fetch many rows.
Async Method fetchone Fetch one row.
Async Method first Fetch the first row or ``None`` if no row is present.
Async Method freeze Return a callable object that will produce copies of this :class:`_asyncio.AsyncResult` when invoked.
Method mappings Apply a mappings filter to returned rows, returning an instance of :class:`_asyncio.AsyncMappingResult`.
Async Method one Return exactly one row or raise an exception.
Async Method one_or_none Return at most one result or raise an exception.
Async Method partitions Iterate through sub-lists of rows of the size given.
Async Method scalar Fetch the first column of the first row, and close the result set.
Async Method scalar_one Return exactly one scalar result or raise an exception.
Async Method scalar_one_or_none Return exactly one scalar result or ``None``.
Method scalars Return an :class:`_asyncio.AsyncScalarResult` filtering object which will return single elements rather than :class:`_row.Row` objects.
Method tuples Apply a "typed tuple" typing filter to returned rows.
Method unique Apply unique filtering to the objects returned by this :class:`_asyncio.AsyncResult`.
Class Variable __slots__ Undocumented
Property t Apply a "typed tuple" typing filter to returned rows.
Instance Variable _metadata Undocumented
Instance Variable _post_creational_filter Undocumented
Instance Variable _real_result Undocumented
Instance Variable _unique_filter_state Undocumented

Inherited from _WithKeys:

Method keys Return an iterable view which yields the string keys that would be represented by each :class:`_engine.Row`.

Inherited from AsyncCommon (via _WithKeys):

Async Method close Close this result.
Property closed proxies the .closed attribute of the underlying result object, if any, else raises ``AttributeError``.

Inherited from FilterResult (via _WithKeys, AsyncCommon):

Method __enter__ Undocumented
Method __exit__ Undocumented
Method yield_per Configure the row-fetching strategy to fetch ``num`` rows at a time.
Method _fetchall_impl Undocumented
Method _fetchiter_impl Undocumented
Method _fetchmany_impl Undocumented
Method _fetchone_impl Undocumented
Method _soft_close Undocumented
Property _attributes Undocumented
Property _soft_closed Undocumented

Inherited from ResultInternal (via _WithKeys, AsyncCommon, FilterResult):

Method _allrows Undocumented
Method _column_slices Undocumented
Method _iter_impl Undocumented
Method _iterator_getter Undocumented
Method _manyrow_getter Undocumented
Method _next_impl Undocumented
Method _onerow_getter Undocumented
Method _only_one_row Undocumented
Method _raw_all_rows Undocumented
Method _row_getter Undocumented
Method _unique_strategy Undocumented
Class Variable _is_cursor Undocumented
Class Variable _row_logging_fn Undocumented
Class Variable _source_supports_scalars Undocumented
Instance Variable _generate_rows Undocumented

Inherited from InPlaceGenerative (via _WithKeys, AsyncCommon, FilterResult, ResultInternal):

Method _generate Undocumented
def __aiter__(self) -> AsyncResult[_TP]: (source)

Undocumented

async def __anext__(self) -> Row[_TP]: (source)

Undocumented

def __init__(self, real_result: Result[_TP]): (source)

Undocumented

async def all(self) -> Sequence[Row[_TP]]: (source)

Return all rows in a list. Closes the result set after invocation. Subsequent invocations will return an empty list. :return: a list of :class:`_engine.Row` objects.

def columns(self, *col_expressions: _KeyIndexType) -> Self: (source)

Establish the columns that should be returned in each row. Refer to :meth:`_engine.Result.columns` in the synchronous SQLAlchemy API for a complete behavioral description.

async def fetchall(self) -> Sequence[Row[_TP]]: (source)

A synonym for the :meth:`_asyncio.AsyncResult.all` method. .. versionadded:: 2.0

async def fetchmany(self, size: Optional[int] = None) -> Sequence[Row[_TP]]: (source)

Fetch many rows. When all rows are exhausted, returns an empty list. This method is provided for backwards compatibility with SQLAlchemy 1.x.x. To fetch rows in groups, use the :meth:`._asyncio.AsyncResult.partitions` method. :return: a list of :class:`_engine.Row` objects. .. seealso:: :meth:`_asyncio.AsyncResult.partitions`

async def fetchone(self) -> Optional[Row[_TP]]: (source)

Fetch one row. When all rows are exhausted, returns None. This method is provided for backwards compatibility with SQLAlchemy 1.x.x. To fetch the first row of a result only, use the :meth:`_asyncio.AsyncResult.first` method. To iterate through all rows, iterate the :class:`_asyncio.AsyncResult` object directly. :return: a :class:`_engine.Row` object if no filters are applied, or ``None`` if no rows remain.

async def first(self) -> Optional[Row[_TP]]: (source)

Fetch the first row or ``None`` if no row is present. Closes the result set and discards remaining rows. .. note:: This method returns one **row**, e.g. tuple, by default. To return exactly one single scalar value, that is, the first column of the first row, use the :meth:`_asyncio.AsyncResult.scalar` method, or combine :meth:`_asyncio.AsyncResult.scalars` and :meth:`_asyncio.AsyncResult.first`. Additionally, in contrast to the behavior of the legacy ORM :meth:`_orm.Query.first` method, **no limit is applied** to the SQL query which was invoked to produce this :class:`_asyncio.AsyncResult`; for a DBAPI driver that buffers results in memory before yielding rows, all rows will be sent to the Python process and all but the first row will be discarded. .. seealso:: :ref:`migration_20_unify_select` :return: a :class:`_engine.Row` object, or None if no rows remain. .. seealso:: :meth:`_asyncio.AsyncResult.scalar` :meth:`_asyncio.AsyncResult.one`

async def freeze(self) -> FrozenResult[_TP]: (source)

Return a callable object that will produce copies of this :class:`_asyncio.AsyncResult` when invoked. The callable object returned is an instance of :class:`_engine.FrozenResult`. This is used for result set caching. The method must be called on the result when it has been unconsumed, and calling the method will consume the result fully. When the :class:`_engine.FrozenResult` is retrieved from a cache, it can be called any number of times where it will produce a new :class:`_engine.Result` object each time against its stored set of rows. .. seealso:: :ref:`do_orm_execute_re_executing` - example usage within the ORM to implement a result-set cache.

def mappings(self) -> AsyncMappingResult: (source)

Apply a mappings filter to returned rows, returning an instance of :class:`_asyncio.AsyncMappingResult`. When this filter is applied, fetching rows will return :class:`_engine.RowMapping` objects instead of :class:`_engine.Row` objects. :return: a new :class:`_asyncio.AsyncMappingResult` filtering object referring to the underlying :class:`_result.Result` object.

async def one(self) -> Row[_TP]: (source)

Return exactly one row or raise an exception. Raises :class:`.NoResultFound` if the result returns no rows, or :class:`.MultipleResultsFound` if multiple rows would be returned. .. note:: This method returns one **row**, e.g. tuple, by default. To return exactly one single scalar value, that is, the first column of the first row, use the :meth:`_asyncio.AsyncResult.scalar_one` method, or combine :meth:`_asyncio.AsyncResult.scalars` and :meth:`_asyncio.AsyncResult.one`. .. versionadded:: 1.4 :return: The first :class:`_engine.Row`. :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound` .. seealso:: :meth:`_asyncio.AsyncResult.first` :meth:`_asyncio.AsyncResult.one_or_none` :meth:`_asyncio.AsyncResult.scalar_one`

async def one_or_none(self) -> Optional[Row[_TP]]: (source)

Return at most one result or raise an exception. Returns ``None`` if the result has no rows. Raises :class:`.MultipleResultsFound` if multiple rows are returned. .. versionadded:: 1.4 :return: The first :class:`_engine.Row` or ``None`` if no row is available. :raises: :class:`.MultipleResultsFound` .. seealso:: :meth:`_asyncio.AsyncResult.first` :meth:`_asyncio.AsyncResult.one`

async def partitions(self, size: Optional[int] = None) -> AsyncIterator[Sequence[Row[_TP]]]: (source)

Iterate through sub-lists of rows of the size given. An async iterator is returned:: 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) Refer to :meth:`_engine.Result.partitions` in the synchronous SQLAlchemy API for a complete behavioral description.

@overload
async def scalar(self: AsyncResult[Tuple[_T]]) -> Optional[_T]:
@overload
async def scalar(self) -> Any:
(source)

Fetch the first column of the first row, and close the result set. Returns ``None`` if there are no rows to fetch. No validation is performed to test if additional rows remain. After calling this method, the object is fully closed, e.g. the :meth:`_engine.CursorResult.close` method will have been called. :return: a Python scalar value, or ``None`` if no rows remain.

@overload
async def scalar_one(self: AsyncResult[Tuple[_T]]) -> _T:
@overload
async def scalar_one(self) -> Any:
(source)

Return exactly one scalar result or raise an exception. This is equivalent to calling :meth:`_asyncio.AsyncResult.scalars` and then :meth:`_asyncio.AsyncResult.one`. .. seealso:: :meth:`_asyncio.AsyncResult.one` :meth:`_asyncio.AsyncResult.scalars`

@overload
async def scalar_one_or_none(self: AsyncResult[Tuple[_T]]) -> Optional[_T]:
@overload
async def scalar_one_or_none(self) -> Optional[Any]:
(source)

Return exactly one scalar result or ``None``. This is equivalent to calling :meth:`_asyncio.AsyncResult.scalars` and then :meth:`_asyncio.AsyncResult.one_or_none`. .. seealso:: :meth:`_asyncio.AsyncResult.one_or_none` :meth:`_asyncio.AsyncResult.scalars`

@overload
def scalars(self: AsyncResult[Tuple[_T]], index: Literal[0]) -> AsyncScalarResult[_T]:
@overload
def scalars(self: AsyncResult[Tuple[_T]]) -> AsyncScalarResult[_T]:
@overload
def scalars(self, index: _KeyIndexType = 0) -> AsyncScalarResult[Any]:
(source)

Return an :class:`_asyncio.AsyncScalarResult` filtering object which will return single elements rather than :class:`_row.Row` objects. Refer to :meth:`_result.Result.scalars` in the synchronous SQLAlchemy API for a complete behavioral description. :param index: integer or row key indicating the column to be fetched from each row, defaults to ``0`` indicating the first column. :return: a new :class:`_asyncio.AsyncScalarResult` filtering object referring to this :class:`_asyncio.AsyncResult` object.

def tuples(self) -> AsyncTupleResult[_TP]: (source)

Apply a "typed tuple" typing filter to returned rows. This method returns the same :class:`_asyncio.AsyncResult` object at runtime, however annotates as returning a :class:`_asyncio.AsyncTupleResult` object that will indicate to :pep:`484` typing tools that plain typed ``Tuple`` instances are returned rather than rows. This allows tuple unpacking and ``__getitem__`` access of :class:`_engine.Row` objects to by typed, for those cases where the statement invoked itself included typing information. .. versionadded:: 2.0 :return: the :class:`_result.AsyncTupleResult` type at typing time. .. seealso:: :attr:`_asyncio.AsyncResult.t` - shorter synonym :attr:`_engine.Row.t` - :class:`_engine.Row` version

@_generative
def unique(self, strategy: Optional[_UniqueFilterType] = None) -> Self: (source)

Apply unique filtering to the objects returned by this :class:`_asyncio.AsyncResult`. Refer to :meth:`_engine.Result.unique` in the synchronous SQLAlchemy API for a complete behavioral description.

__slots__: tuple = (source)
overrides sqlalchemy.engine.result._WithKeys.__slots__

Undocumented

@property
t: AsyncTupleResult[_TP] = (source)

Apply a "typed tuple" typing filter to returned rows. The :attr:`_asyncio.AsyncResult.t` attribute is a synonym for calling the :meth:`_asyncio.AsyncResult.tuples` method. .. versionadded:: 2.0

_metadata = (source)
overrides sqlalchemy.engine.result._WithKeys._metadata

Undocumented

_post_creational_filter = (source)
overrides sqlalchemy.engine.result.FilterResult._post_creational_filter

Undocumented

_real_result = (source)
overrides sqlalchemy.ext.asyncio.result.AsyncCommon._real_result

Undocumented

_unique_filter_state = (source)
overrides sqlalchemy.engine.result.ResultInternal._unique_filter_state

Undocumented