sqlalchemy.ext.asyncio.result.AsyncResult

class documentation

class AsyncResult(AsyncCommon):

An asyncio wrapper around a _result.Result object.

The _asyncio.AsyncResult only applies to statement executions that use a server-side cursor. It is returned only from the _asyncio.AsyncConnection.stream and _asyncio.AsyncSession.stream methods.

Note

As is the case with _engine.Result, this object is used for ORM results returned by _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 _orm.Query object. For in-Python de-duplication of instances or rows, use the _asyncio.AsyncResult.unique modifier method.

New in version 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	`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 `_asyncio.AsyncResult` when invoked.
Method	`keys`	Return the `_engine.Result.keys` collection from the underlying `_engine.Result`.
Method	`mappings`	Apply a mappings filter to returned rows, returning an instance of `_asyncio.AsyncMappingResult`.
Method	`merge`	Merge this `_asyncio.AsyncResult` with other compatible result objects.
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 or no scalar result.
Method	`scalars`	Return an `_asyncio.AsyncScalarResult` filtering object which will return single elements rather than `_row.Row` objects.
Method	`unique`	Apply unique filtering to the objects returned by this `_asyncio.AsyncResult`.
Instance Variable	`_metadata`	Undocumented
Instance Variable	`_real_result`	Undocumented
Instance Variable	`_unique_filter_state`	Undocumented

Inherited from AsyncCommon:

Async Method close Close this result.

Inherited from FilterResult (via AsyncCommon):

Method	`_fetchall_impl`	Undocumented
Method	`_fetchiter_impl`	Undocumented
Method	`_fetchmany_impl`	Undocumented
Method	`_fetchone_impl`	Undocumented
Method	`_soft_close`	Undocumented
Class Variable	`_post_creational_filter`	Undocumented
Property	`_attributes`	Undocumented

Inherited from ResultInternal (via 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
Instance Variable	`_generate_rows`	Undocumented

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

Method _generate Undocumented

def __aiter__(self):

Undocumented

async def __anext__(self):

Undocumented

def __init__(self, real_result):

Undocumented

async def all(self):

Return all rows in a list.

Closes the result set after invocation. Subsequent invocations will return an empty list.

Returns
a list of `.Row` objects.

def columns(self, *col_expressions):

Establish the columns that should be returned in each row.

Refer to _engine.Result.columns in the synchronous SQLAlchemy API for a complete behavioral description.

async def fetchmany(self, size=None):

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 ._asyncio.AsyncResult.partitions method.

See Also

_asyncio.AsyncResult.partitions

Returns
a list of `.Row` objects.

async def fetchone(self):

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 _engine.Result.first method. To iterate through all rows, iterate the _engine.Result object directly.

Returns
a `.Row` object if no filters are applied, or None if no rows remain.

async def first(self):

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 _asyncio.AsyncResult.scalar method, or combine _asyncio.AsyncResult.scalars and _asyncio.AsyncResult.first.

See Also

_asyncio.AsyncResult.scalar

_asyncio.AsyncResult.one

Returns
a `.Row` object, or None if no rows remain.

async def freeze(self):

Return a callable object that will produce copies of this _asyncio.AsyncResult when invoked.

The callable object returned is an instance of _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 _engine.FrozenResult is retrieved from a cache, it can be called any number of times where it will produce a new _engine.Result object each time against its stored set of rows.

See Also

:ref:`do_orm_execute_re_executing` - example usage within the ORM to implement a result-set cache.

def keys(self):

Return the _engine.Result.keys collection from the underlying _engine.Result.

def mappings(self):

Apply a mappings filter to returned rows, returning an instance of _asyncio.AsyncMappingResult.

When this filter is applied, fetching rows will return .RowMapping objects instead of .Row objects.

Refer to _result.Result.mappings in the synchronous SQLAlchemy API for a complete behavioral description.

Returns
a new `_asyncio.AsyncMappingResult` filtering object referring to the underlying `_result.Result` object.

def merge(self, *others):

Merge this _asyncio.AsyncResult with other compatible result objects.

The object returned is an instance of _engine.MergedResult, which will be composed of iterators from the given result objects.

The new result will use the metadata from this result object. The subsequent result objects must be against an identical set of result / cursor metadata, otherwise the behavior is undefined.

async def one(self):

Return exactly one row or raise an exception.

Raises .NoResultFound if the result returns no rows, or .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 _asyncio.AsyncResult.scalar_one method, or combine _asyncio.AsyncResult.scalars and _asyncio.AsyncResult.one.

New in version 1.4.

See Also

_asyncio.AsyncResult.first

_asyncio.AsyncResult.one_or_none

_asyncio.AsyncResult.scalar_one

Returns
The first `.Row`.
Raises
`Unknown exception`	`.MultipleResultsFound`, `.NoResultFound`

async def one_or_none(self):

Return at most one result or raise an exception.

Returns None if the result has no rows. Raises .MultipleResultsFound if multiple rows are returned.

New in version 1.4.

See Also

_asyncio.AsyncResult.first

_asyncio.AsyncResult.one

Returns
The first `.Row` or None if no row is available.
Raises
`Unknown exception`	`.MultipleResultsFound`

async def partitions(self, size=None):

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)

See Also

_engine.Result.partitions

async def scalar(self):

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 _engine.CursorResult.close method will have been called.

Returns
a Python scalar value , or None if no rows remain.

async def scalar_one(self):

Return exactly one scalar result or raise an exception.

This is equivalent to calling _asyncio.AsyncResult.scalars and then _asyncio.AsyncResult.one.

See Also

_asyncio.AsyncResult.one

_asyncio.AsyncResult.scalars

async def scalar_one_or_none(self):

Return exactly one or no scalar result.

This is equivalent to calling _asyncio.AsyncResult.scalars and then _asyncio.AsyncResult.one_or_none.

See Also

_asyncio.AsyncResult.one_or_none

_asyncio.AsyncResult.scalars

def scalars(self, index=0):

Return an _asyncio.AsyncScalarResult filtering object which will return single elements rather than _row.Row objects.

Refer to _result.Result.scalars in the synchronous SQLAlchemy API for a complete behavioral description.

Parameters
index	integer or row key indicating the column to be fetched from each row, defaults to `0` indicating the first column.
Returns
a new `_asyncio.AsyncScalarResult` filtering object referring to this `_asyncio.AsyncResult` object.

def unique(self, strategy=None):

Apply unique filtering to the objects returned by this _asyncio.AsyncResult.

Refer to _engine.Result.unique in the synchronous SQLAlchemy API for a complete behavioral description.

_metadata =

Undocumented

_real_result =

overrides sqlalchemy.engine.result.ResultInternal._real_result

Undocumented

_unique_filter_state =

overrides sqlalchemy.engine.result.ResultInternal._unique_filter_state

Undocumented