From: Federico Caselli Date: Thu, 8 Dec 2022 18:34:49 +0000 (+0100) Subject: Better syncronize async result docs with plain ones. X-Git-Tag: rel_2_0_0rc1~41^2 X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=30e42a8d302ac7885e4d2f8547038ab66480346a;p=thirdparty%2Fsqlalchemy%2Fsqlalchemy.git Better syncronize async result docs with plain ones. Removed non-functional method ``merge`` from :class:`_asyncio.AsyncResult`. This method was non-functional and non-testes since the first introduction of asyncio in SQLAlchemy. Fixes: #7158 Fixes: #8952 Change-Id: Ibc3d17be8a8b7cab9bf2074f0408f74b4c4b161d --- diff --git a/.gitignore b/.gitignore index 91846d1f7c..13b40c819a 100644 --- a/.gitignore +++ b/.gitignore @@ -39,3 +39,4 @@ test/test_schema.db /.pytest_cache /db_idents.txt .DS_Store +.vs diff --git a/doc/build/changelog/unreleased_14/8952.rst b/doc/build/changelog/unreleased_14/8952.rst new file mode 100644 index 0000000000..32a36e84a8 --- /dev/null +++ b/doc/build/changelog/unreleased_14/8952.rst @@ -0,0 +1,8 @@ +.. change:: + :tags: bug, asyncio + :tickets: 8952 + :versions: 2.0.0b5 + + Removed non-functional method ``merge`` from :class:`_asyncio.AsyncResult`. + This method was non-functional and non-testes since the first introduction + of asyncio in SQLAlchemy. diff --git a/doc/build/core/connections.rst b/doc/build/core/connections.rst index a39c452f61..4d97f82bcf 100644 --- a/doc/build/core/connections.rst +++ b/doc/build/core/connections.rst @@ -2304,7 +2304,7 @@ Connection / Engine API :inherited-members: -Result Set API +Result Set API --------------- .. autoclass:: ChunkedIteratorResult @@ -2345,3 +2345,4 @@ Result Set API .. autoclass:: RowMapping :members: +.. autoclass:: TupleResult diff --git a/doc/build/orm/extensions/asyncio.rst b/doc/build/orm/extensions/asyncio.rst index 102c65056e..f3bf6dda3e 100644 --- a/doc/build/orm/extensions/asyncio.rst +++ b/doc/build/orm/extensions/asyncio.rst @@ -939,12 +939,17 @@ cursor. .. autoclass:: AsyncResult :members: + :inherited-members: .. autoclass:: AsyncScalarResult :members: + :inherited-members: .. autoclass:: AsyncMappingResult :members: + :inherited-members: + +.. autoclass:: AsyncTupleResult ORM Session API Documentation ----------------------------- diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py index 392cefa020..a63bad54e6 100644 --- a/lib/sqlalchemy/engine/result.py +++ b/lib/sqlalchemy/engine/result.py @@ -869,7 +869,7 @@ class _WithKeys: # used mainly to share documentation on the keys method. def keys(self) -> RMKeyView: """Return an iterable view which yields the string keys that would - be represented by each :class:`.Row`. + be represented by each :class:`_engine.Row`. The keys can represent the labels of the columns returned by a core statement or the names of the orm classes returned by an orm @@ -893,20 +893,21 @@ SelfResult = TypeVar("SelfResult", bound="Result[Any]") class Result(_WithKeys, ResultInternal[Row[_TP]]): """Represent a set of database results. - .. versionadded:: 1.4 The :class:`.Result` object provides a completely - updated usage model and calling facade for SQLAlchemy Core and - SQLAlchemy ORM. In Core, it forms the basis of the - :class:`.CursorResult` object which replaces the previous - :class:`.ResultProxy` interface. When using the ORM, a higher level - object called :class:`.ChunkedIteratorResult` is normally used. + .. versionadded:: 1.4 The :class:`_engine.Result` object provides a + completely updated usage model and calling facade for SQLAlchemy + Core and SQLAlchemy ORM. In Core, it forms the basis of the + :class:`_engine.CursorResult` object which replaces the previous + :class:`_engine.ResultProxy` interface. When using the ORM, a + higher level object called :class:`_engine.ChunkedIteratorResult` + is normally used. .. note:: In SQLAlchemy 1.4 and above, this object is used for ORM results returned by :meth:`_orm.Session.execute`, which can yield instances of ORM mapped objects either individually or within - tuple-like rows. Note that the :class:`_result.Result` object does not + tuple-like rows. Note that the :class:`_engine.Result` object does 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:`_result.Result.unique` modifier + instances or rows, use the :meth:`_engine.Result.unique` modifier method. .. seealso:: @@ -935,7 +936,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): self.close() def close(self) -> None: - """close this :class:`_result.Result`. + """close this :class:`_engine.Result`. The behavior of this method is implementation specific, and is not implemented by default. The method should generally end @@ -944,7 +945,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): :class:`.ResourceClosedError`. .. versionadded:: 1.4.27 - ``.close()`` was previously not generally - available for all :class:`_result.Result` classes, instead only + available for all :class:`_engine.Result` classes, instead only being available on the :class:`_engine.CursorResult` returned for Core statement executions. As most other result objects, namely the ones used by the ORM, are proxying a :class:`_engine.CursorResult` @@ -962,7 +963,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): @property def closed(self) -> bool: - """return True if this :class:`.Result` reports .closed + """return ``True`` if this :class:`_engine.Result` reports .closed .. versionadded:: 1.4.43 @@ -1076,13 +1077,15 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): a given statement construct. .. versionchanged:: 2.0 Due to a bug in 1.4, the - :meth:`.Result.columns` method had an incorrect behavior where - calling upon the method with just one index would cause the - :class:`.Result` object to yield scalar values rather than - :class:`.Row` objects. In version 2.0, this behavior has been - corrected such that calling upon :meth:`.Result.columns` with - a single index will produce a :class:`.Result` object that continues - to yield :class:`.Row` objects, which include only a single column. + :meth:`_engine.Result.columns` method had an incorrect behavior + where calling upon the method with just one index would cause the + :class:`_engine.Result` object to yield scalar values rather than + :class:`_engine.Row` objects. In version 2.0, this behavior + has been corrected such that calling upon + :meth:`_engine.Result.columns` with a single index will + produce a :class:`_engine.Result` object that continues + to yield :class:`_engine.Row` objects, which include + only a single column. E.g.:: @@ -1128,7 +1131,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): ... def scalars(self, index: _KeyIndexType = 0) -> ScalarResult[Any]: - """Return a :class:`_result.ScalarResult` filtering object which + """Return a :class:`_engine.ScalarResult` filtering object which will return single elements rather than :class:`_row.Row` objects. E.g.:: @@ -1137,17 +1140,17 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): >>> result.scalars().all() [1, 2, 3] - When results are fetched from the :class:`_result.ScalarResult` + When results are fetched from the :class:`_engine.ScalarResult` filtering object, the single column-row that would be returned by the - :class:`_result.Result` is instead returned as the column's value. + :class:`_engine.Result` is instead returned as the column's value. .. versionadded:: 1.4 :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:`_result.ScalarResult` filtering object referring - to this :class:`_result.Result` object. + :return: a new :class:`_engine.ScalarResult` filtering object referring + to this :class:`_engine.Result` object. """ return ScalarResult(self, index) @@ -1156,7 +1159,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): self, key: _KeyIndexType, raiseerr: bool = True ) -> Optional[Callable[[Row[Any]], Any]]: """return a callable that will retrieve the given key from a - :class:`.Row`. + :class:`_engine.Row`. """ if self._source_supports_scalars: @@ -1167,7 +1170,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): def _tuple_getter(self, keys: Sequence[_KeyIndexType]) -> _TupleGetterType: """return a callable that will retrieve the given keys from a - :class:`.Row`. + :class:`_engine.Row`. """ if self._source_supports_scalars: @@ -1178,15 +1181,16 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): def mappings(self) -> MappingResult: """Apply a mappings filter to returned rows, returning an instance of - :class:`_result.MappingResult`. + :class:`_engine.MappingResult`. When this filter is applied, fetching rows will return - :class:`.RowMapping` objects instead of :class:`.Row` objects. + :class:`_engine.RowMapping` objects instead of :class:`_engine.Row` + objects. .. versionadded:: 1.4 - :return: a new :class:`_result.MappingResult` filtering object - referring to this :class:`_result.Result` object. + :return: a new :class:`_engine.MappingResult` filtering object + referring to this :class:`_engine.Result` object. """ @@ -1196,8 +1200,8 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): def t(self) -> TupleResult[_TP]: """Apply a "typed tuple" typing filter to returned rows. - The :attr:`.Result.t` attribute is a synonym for calling the - :meth:`.Result.tuples` method. + The :attr:`_engine.Result.t` attribute is a synonym for + calling the :meth:`_engine.Result.tuples` method. .. versionadded:: 2.0 @@ -1207,23 +1211,24 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): def tuples(self) -> TupleResult[_TP]: """Apply a "typed tuple" typing filter to returned rows. - This method returns the same :class:`.Result` object at runtime, - however annotates as returning a :class:`.TupleResult` object + This method returns the same :class:`_engine.Result` object + at runtime, + however annotates as returning a :class:`_engine.TupleResult` 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:`.Row` objects - to by typed, for those cases where the statement invoked itself - included typing information. + 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.TupleResult` type at typing time. + :return: the :class:`_engine.TupleResult` type at typing time. .. seealso:: - :attr:`.Result.t` - shorter synonym + :attr:`_engine.Result.t` - shorter synonym - :attr:`.Row.t` - :class:`.Row` version + :attr:`_engine.Row.t` - :class:`_engine.Row` version """ @@ -1232,7 +1237,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): def _raw_row_iterator(self) -> Iterator[_RowData]: """Return a safe iterator that yields raw row data. - This is used by the :meth:`._engine.Result.merge` method + This is used by the :meth:`_engine.Result.merge` method to merge multiple compatible results together. """ @@ -1291,7 +1296,6 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): :ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel` - """ getter = self._manyrow_getter @@ -1320,8 +1324,8 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): :meth:`_engine.Result.first` method. To iterate through all rows, iterate the :class:`_engine.Result` object directly. - :return: a :class:`.Row` object if no filters are applied, or None - if no rows remain. + :return: a :class:`_engine.Row` object if no filters are applied, + or ``None`` if no rows remain. """ row = self._onerow_getter(self) @@ -1338,10 +1342,14 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): This method is provided for backwards compatibility with SQLAlchemy 1.x.x. - To fetch rows in groups, use the :meth:`._result.Result.partitions` + To fetch rows in groups, use the :meth:`_engine.Result.partitions` method. - :return: a list of :class:`.Row` objects. + :return: a list of :class:`_engine.Row` objects. + + .. seealso:: + + :meth:`_engine.Result.partitions` """ @@ -1355,25 +1363,28 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): .. versionadded:: 1.4 - :return: a list of :class:`.Row` objects. + :return: a list of :class:`_engine.Row` objects. """ return self._allrows() def first(self) -> Optional[Row[_TP]]: - """Fetch the first row or None if no row is present. + """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:`.Result.scalar` method, - or combine :meth:`.Result.scalars` and :meth:`.Result.first`. + column of the first row, use the + :meth:`_engine.Result.scalar` method, + or combine :meth:`_engine.Result.scalars` and + :meth:`_engine.Result.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:`_engine.Result`; + SQL query which was invoked to produce this + :class:`_engine.Result`; 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. @@ -1382,14 +1393,14 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): :ref:`migration_20_unify_select` - :return: a :class:`.Row` object, or None + :return: a :class:`_engine.Row` object, or None if no rows remain. .. seealso:: - :meth:`_result.Result.scalar` + :meth:`_engine.Result.scalar` - :meth:`_result.Result.one` + :meth:`_engine.Result.one` """ @@ -1406,15 +1417,16 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): .. versionadded:: 1.4 - :return: The first :class:`.Row` or None if no row is available. + :return: The first :class:`_engine.Row` or ``None`` if no row + is available. :raises: :class:`.MultipleResultsFound` .. seealso:: - :meth:`_result.Result.first` + :meth:`_engine.Result.first` - :meth:`_result.Result.one` + :meth:`_engine.Result.one` """ return self._only_one_row( @@ -1432,14 +1444,14 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): def scalar_one(self) -> Any: """Return exactly one scalar result or raise an exception. - This is equivalent to calling :meth:`.Result.scalars` and then - :meth:`.Result.one`. + This is equivalent to calling :meth:`_engine.Result.scalars` and + then :meth:`_engine.Result.one`. .. seealso:: - :meth:`.Result.one` + :meth:`_engine.Result.one` - :meth:`.Result.scalars` + :meth:`_engine.Result.scalars` """ return self._only_one_row( @@ -1455,16 +1467,16 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): ... def scalar_one_or_none(self) -> Optional[Any]: - """Return exactly one or no scalar result. + """Return exactly one scalar result or ``None``. - This is equivalent to calling :meth:`.Result.scalars` and then - :meth:`.Result.one_or_none`. + This is equivalent to calling :meth:`_engine.Result.scalars` and + then :meth:`_engine.Result.one_or_none`. .. seealso:: - :meth:`.Result.one_or_none` + :meth:`_engine.Result.one_or_none` - :meth:`.Result.scalars` + :meth:`_engine.Result.scalars` """ return self._only_one_row( @@ -1480,22 +1492,24 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): .. 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:`.Result.scalar_one` method, - or combine :meth:`.Result.scalars` and :meth:`.Result.one`. + column of the first row, use the + :meth:`_engine.Result.scalar_one` method, or combine + :meth:`_engine.Result.scalars` and + :meth:`_engine.Result.one`. .. versionadded:: 1.4 - :return: The first :class:`.Row`. + :return: The first :class:`_engine.Row`. :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound` .. seealso:: - :meth:`_result.Result.first` + :meth:`_engine.Result.first` - :meth:`_result.Result.one_or_none` + :meth:`_engine.Result.one_or_none` - :meth:`_result.Result.scalar_one` + :meth:`_engine.Result.scalar_one` """ return self._only_one_row( @@ -1513,7 +1527,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): def scalar(self) -> Any: """Fetch the first column of the first row, and close the result set. - Returns None if there are no rows to fetch. + Returns ``None`` if there are no rows to fetch. No validation is performed to test if additional rows remain. @@ -1521,7 +1535,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): e.g. the :meth:`_engine.CursorResult.close` method will have been called. - :return: a Python scalar value , or None if no rows remain. + :return: a Python scalar value, or ``None`` if no rows remain. """ return self._only_one_row( @@ -1530,7 +1544,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): def freeze(self) -> FrozenResult[_TP]: """Return a callable object that will produce copies of this - :class:`.Result` when invoked. + :class:`_engine.Result` when invoked. The callable object returned is an instance of :class:`_engine.FrozenResult`. @@ -1552,7 +1566,7 @@ class Result(_WithKeys, ResultInternal[Row[_TP]]): return FrozenResult(self) def merge(self, *others: Result[Any]) -> MergedResult[_TP]: - """Merge this :class:`.Result` with other compatible result + """Merge this :class:`_engine.Result` with other compatible result objects. The object returned is an instance of :class:`_engine.MergedResult`, @@ -1573,11 +1587,11 @@ SelfFilterResult = TypeVar("SelfFilterResult", bound="FilterResult[Any]") class FilterResult(ResultInternal[_R]): """A wrapper for a :class:`_engine.Result` that returns objects other than - :class:`_result.Row` objects, such as dictionaries or scalar objects. + :class:`_engine.Row` objects, such as dictionaries or scalar objects. - :class:`.FilterResult` is the common base for additional result - APIs including :class:`.MappingResult`, :class:`.ScalarResult` - and :class:`.AsyncResult`. + :class:`_engine.FilterResult` is the common base for additional result + APIs including :class:`_engine.MappingResult`, + :class:`_engine.ScalarResult` and :class:`_engine.AsyncResult`. """ @@ -1630,7 +1644,8 @@ class FilterResult(ResultInternal[_R]): @property def closed(self) -> bool: - """return True if the underlying :class:`.Result` reports .closed + """Return ``True`` if the underlying :class:`_engine.Result` reports + closed .. versionadded:: 1.4.43 @@ -1638,7 +1653,7 @@ class FilterResult(ResultInternal[_R]): return self._real_result.closed def close(self) -> None: - """Close this :class:`.FilterResult`. + """Close this :class:`_engine.FilterResult`. .. versionadded:: 1.4.43 @@ -1670,16 +1685,16 @@ SelfScalarResult = TypeVar("SelfScalarResult", bound="ScalarResult[Any]") class ScalarResult(FilterResult[_R]): - """A wrapper for a :class:`_result.Result` that returns scalar values + """A wrapper for a :class:`_engine.Result` that returns scalar values rather than :class:`_row.Row` values. - The :class:`_result.ScalarResult` object is acquired by calling the - :meth:`_result.Result.scalars` method. + The :class:`_engine.ScalarResult` object is acquired by calling the + :meth:`_engine.Result.scalars` method. - A special limitation of :class:`_result.ScalarResult` is that it has + A special limitation of :class:`_engine.ScalarResult` is that it has no ``fetchone()`` method; since the semantics of ``fetchone()`` are that the ``None`` value indicates no more results, this is not compatible - with :class:`_result.ScalarResult` since there is no way to distinguish + with :class:`_engine.ScalarResult` since there is no way to distinguish between ``None`` as a row value versus ``None`` as an indicator. Use ``next(result)`` to receive values individually. @@ -1718,8 +1733,8 @@ class ScalarResult(FilterResult[_R]): def partitions(self, size: Optional[int] = None) -> Iterator[Sequence[_R]]: """Iterate through sub-lists of elements of the size given. - Equivalent to :meth:`_result.Result.partitions` except that - scalar values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.partitions` except that + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1741,8 +1756,8 @@ class ScalarResult(FilterResult[_R]): def fetchmany(self, size: Optional[int] = None) -> Sequence[_R]: """Fetch many objects. - Equivalent to :meth:`_result.Result.fetchmany` except that - scalar values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.fetchmany` except that + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1751,8 +1766,8 @@ class ScalarResult(FilterResult[_R]): def all(self) -> Sequence[_R]: """Return all scalar values in a list. - Equivalent to :meth:`_result.Result.all` except that - scalar values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.all` except that + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1765,10 +1780,10 @@ class ScalarResult(FilterResult[_R]): return self._next_impl() def first(self) -> Optional[_R]: - """Fetch the first object or None if no object is present. + """Fetch the first object or ``None`` if no object is present. - Equivalent to :meth:`_result.Result.first` except that - scalar values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.first` except that + scalar values, rather than :class:`_engine.Row` objects, are returned. @@ -1780,8 +1795,8 @@ class ScalarResult(FilterResult[_R]): def one_or_none(self) -> Optional[_R]: """Return at most one object or raise an exception. - Equivalent to :meth:`_result.Result.one_or_none` except that - scalar values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.one_or_none` except that + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1792,8 +1807,8 @@ class ScalarResult(FilterResult[_R]): def one(self) -> _R: """Return exactly one object or raise an exception. - Equivalent to :meth:`_result.Result.one` except that - scalar values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.one` except that + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1806,12 +1821,12 @@ SelfTupleResult = TypeVar("SelfTupleResult", bound="TupleResult[Any]") class TupleResult(FilterResult[_R], util.TypingOnly): - """a :class:`.Result` that's typed as returning plain Python tuples - instead of rows. + """A :class:`_engine.Result` that's typed as returning plain + Python tuples instead of rows. - Since :class:`.Row` acts like a tuple in every way already, - this class is a typing only class, regular :class:`.Result` is still - used at runtime. + Since :class:`_engine.Row` acts like a tuple in every way already, + this class is a typing only class, regular :class:`_engine.Result` is + still used at runtime. """ @@ -1824,8 +1839,8 @@ class TupleResult(FilterResult[_R], util.TypingOnly): ) -> Iterator[Sequence[_R]]: """Iterate through sub-lists of elements of the size given. - Equivalent to :meth:`_result.Result.partitions` except that - tuple values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.partitions` except that + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1834,8 +1849,8 @@ class TupleResult(FilterResult[_R], util.TypingOnly): def fetchone(self) -> Optional[_R]: """Fetch one tuple. - Equivalent to :meth:`_result.Result.fetchone` except that - tuple values, rather than :class:`_result.Row` + Equivalent to :meth:`_engine.Result.fetchone` except that + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1848,8 +1863,8 @@ class TupleResult(FilterResult[_R], util.TypingOnly): def fetchmany(self, size: Optional[int] = None) -> Sequence[_R]: """Fetch many objects. - Equivalent to :meth:`_result.Result.fetchmany` except that - tuple values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.fetchmany` except that + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1858,8 +1873,8 @@ class TupleResult(FilterResult[_R], util.TypingOnly): def all(self) -> Sequence[_R]: # noqa: A001 """Return all scalar values in a list. - Equivalent to :meth:`_result.Result.all` except that - tuple values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.all` except that + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1872,10 +1887,10 @@ class TupleResult(FilterResult[_R], util.TypingOnly): ... def first(self) -> Optional[_R]: - """Fetch the first object or None if no object is present. + """Fetch the first object or ``None`` if no object is present. - Equivalent to :meth:`_result.Result.first` except that - tuple values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.first` except that + tuple values, rather than :class:`_engine.Row` objects, are returned. @@ -1885,8 +1900,8 @@ class TupleResult(FilterResult[_R], util.TypingOnly): def one_or_none(self) -> Optional[_R]: """Return at most one object or raise an exception. - Equivalent to :meth:`_result.Result.one_or_none` except that - tuple values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.one_or_none` except that + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1895,8 +1910,8 @@ class TupleResult(FilterResult[_R], util.TypingOnly): def one(self) -> _R: """Return exactly one object or raise an exception. - Equivalent to :meth:`_result.Result.one` except that - tuple values, rather than :class:`_result.Row` objects, + Equivalent to :meth:`_engine.Result.one` except that + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -1913,14 +1928,14 @@ class TupleResult(FilterResult[_R], util.TypingOnly): def scalar_one(self) -> Any: """Return exactly one scalar result or raise an exception. - This is equivalent to calling :meth:`.Result.scalars` and then - :meth:`.Result.one`. + This is equivalent to calling :meth:`_engine.Result.scalars` + and then :meth:`_engine.Result.one`. .. seealso:: - :meth:`.Result.one` + :meth:`_engine.Result.one` - :meth:`.Result.scalars` + :meth:`_engine.Result.scalars` """ ... @@ -1936,14 +1951,14 @@ class TupleResult(FilterResult[_R], util.TypingOnly): def scalar_one_or_none(self) -> Optional[Any]: """Return exactly one or no scalar result. - This is equivalent to calling :meth:`.Result.scalars` and then - :meth:`.Result.one_or_none`. + This is equivalent to calling :meth:`_engine.Result.scalars` + and then :meth:`_engine.Result.one_or_none`. .. seealso:: - :meth:`.Result.one_or_none` + :meth:`_engine.Result.one_or_none` - :meth:`.Result.scalars` + :meth:`_engine.Result.scalars` """ ... @@ -1960,7 +1975,7 @@ class TupleResult(FilterResult[_R], util.TypingOnly): """Fetch the first column of the first row, and close the result set. - Returns None if there are no rows to fetch. + Returns ``None`` if there are no rows to fetch. No validation is performed to test if additional rows remain. @@ -1968,7 +1983,7 @@ class TupleResult(FilterResult[_R], util.TypingOnly): e.g. the :meth:`_engine.CursorResult.close` method will have been called. - :return: a Python scalar value , or None if no rows remain. + :return: a Python scalar value , or ``None`` if no rows remain. """ ... @@ -2022,8 +2037,8 @@ class MappingResult(_WithKeys, FilterResult[RowMapping]): ) -> Iterator[Sequence[RowMapping]]: """Iterate through sub-lists of elements of the size given. - Equivalent to :meth:`_result.Result.partitions` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + Equivalent to :meth:`_engine.Result.partitions` except that + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -2045,8 +2060,8 @@ class MappingResult(_WithKeys, FilterResult[RowMapping]): def fetchone(self) -> Optional[RowMapping]: """Fetch one object. - Equivalent to :meth:`_result.Result.fetchone` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + Equivalent to :meth:`_engine.Result.fetchone` except that + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -2060,8 +2075,8 @@ class MappingResult(_WithKeys, FilterResult[RowMapping]): def fetchmany(self, size: Optional[int] = None) -> Sequence[RowMapping]: """Fetch many objects. - Equivalent to :meth:`_result.Result.fetchmany` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + Equivalent to :meth:`_engine.Result.fetchmany` except that + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -2071,8 +2086,8 @@ class MappingResult(_WithKeys, FilterResult[RowMapping]): def all(self) -> Sequence[RowMapping]: """Return all scalar values in a list. - Equivalent to :meth:`_result.Result.all` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + Equivalent to :meth:`_engine.Result.all` except that + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -2086,10 +2101,10 @@ class MappingResult(_WithKeys, FilterResult[RowMapping]): return self._next_impl() def first(self) -> Optional[RowMapping]: - """Fetch the first object or None if no object is present. + """Fetch the first object or ``None`` if no object is present. - Equivalent to :meth:`_result.Result.first` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + Equivalent to :meth:`_engine.Result.first` except that + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. @@ -2101,8 +2116,8 @@ class MappingResult(_WithKeys, FilterResult[RowMapping]): def one_or_none(self) -> Optional[RowMapping]: """Return at most one object or raise an exception. - Equivalent to :meth:`_result.Result.one_or_none` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + Equivalent to :meth:`_engine.Result.one_or_none` except that + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -2113,8 +2128,8 @@ class MappingResult(_WithKeys, FilterResult[RowMapping]): def one(self) -> RowMapping: """Return exactly one object or raise an exception. - Equivalent to :meth:`_result.Result.one` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + Equivalent to :meth:`_engine.Result.one` except that + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -2124,15 +2139,15 @@ class MappingResult(_WithKeys, FilterResult[RowMapping]): class FrozenResult(Generic[_TP]): - """Represents a :class:`.Result` object in a "frozen" state suitable + """Represents a :class:`_engine.Result` object in a "frozen" state suitable for caching. The :class:`_engine.FrozenResult` object is returned from the :meth:`_engine.Result.freeze` method of any :class:`_engine.Result` object. - A new iterable :class:`.Result` object is generated from a fixed - set of data each time the :class:`.FrozenResult` is invoked as + A new iterable :class:`_engine.Result` object is generated from a fixed + set of data each time the :class:`_engine.FrozenResult` is invoked as a callable:: @@ -2204,8 +2219,8 @@ class FrozenResult(Generic[_TP]): class IteratorResult(Result[_TP]): - """A :class:`.Result` that gets data from a Python iterator of - :class:`.Row` objects or similar row-like data. + """A :class:`_engine.Result` that gets data from a Python iterator of + :class:`_engine.Row` objects or similar row-like data. .. versionadded:: 1.4 @@ -2228,7 +2243,8 @@ class IteratorResult(Result[_TP]): @property def closed(self) -> bool: - """return True if this :class:`.IteratorResult` has been closed + """Return ``True`` if this :class:`_engine.IteratorResult` has + been closed .. versionadded:: 1.4.43 @@ -2295,8 +2311,8 @@ SelfChunkedIteratorResult = TypeVar( class ChunkedIteratorResult(IteratorResult[_TP]): - """An :class:`.IteratorResult` that works from an iterator-producing - callable. + """An :class:`_engine.IteratorResult` that works from an + iterator-producing callable. The given ``chunks`` argument is a function that is given a number of rows to return in each chunk, or ``None`` for all rows. The function should diff --git a/lib/sqlalchemy/ext/asyncio/__init__.py b/lib/sqlalchemy/ext/asyncio/__init__.py index dfe89a154e..6b0c7f3a7b 100644 --- a/lib/sqlalchemy/ext/asyncio/__init__.py +++ b/lib/sqlalchemy/ext/asyncio/__init__.py @@ -13,6 +13,7 @@ from .engine import create_async_engine as create_async_engine from .result import AsyncMappingResult as AsyncMappingResult from .result import AsyncResult as AsyncResult from .result import AsyncScalarResult as AsyncScalarResult +from .result import AsyncTupleResult as AsyncTupleResult from .scoping import async_scoped_session as async_scoped_session from .session import async_object_session as async_object_session from .session import async_session as async_session diff --git a/lib/sqlalchemy/ext/asyncio/result.py b/lib/sqlalchemy/ext/asyncio/result.py index 41ead5ee20..0704ef117a 100644 --- a/lib/sqlalchemy/ext/asyncio/result.py +++ b/lib/sqlalchemy/ext/asyncio/result.py @@ -21,9 +21,9 @@ from ... import util from ...engine import Result from ...engine.result import _NO_ROW from ...engine.result import _R +from ...engine.result import _WithKeys from ...engine.result import FilterResult from ...engine.result import FrozenResult -from ...engine.result import MergedResult from ...engine.result import ResultMetaData from ...engine.row import Row from ...engine.row import RowMapping @@ -35,7 +35,6 @@ if TYPE_CHECKING: from ...engine import CursorResult from ...engine.result import _KeyIndexType from ...engine.result import _UniqueFilterType - from ...engine.result import RMKeyView _T = TypeVar("_T", bound=Any) _TP = TypeVar("_TP", bound=Tuple[Any, ...]) @@ -66,7 +65,7 @@ class AsyncCommon(FilterResult[_R]): SelfAsyncResult = TypeVar("SelfAsyncResult", bound="AsyncResult[Any]") -class AsyncResult(AsyncCommon[Row[_TP]]): +class AsyncResult(_WithKeys, AsyncCommon[Row[_TP]]): """An asyncio wrapper around a :class:`_result.Result` object. The :class:`_asyncio.AsyncResult` only applies to statement executions that @@ -105,22 +104,12 @@ class AsyncResult(AsyncCommon[Row[_TP]]): "_row_getter", real_result.__dict__["_row_getter"] ) - @property - def closed(self) -> bool: - """proxies the .closed attribute of the underlying result object, - if any, else raises ``AttributeError``. - - .. versionadded:: 2.0.0b3 - - """ - return self._real_result.closed # type: ignore - @property def t(self) -> AsyncTupleResult[_TP]: """Apply a "typed tuple" typing filter to returned rows. - The :attr:`.AsyncResult.t` attribute is a synonym for calling the - :meth:`.AsyncResult.tuples` method. + The :attr:`_asyncio.AsyncResult.t` attribute is a synonym for + calling the :meth:`_asyncio.AsyncResult.tuples` method. .. versionadded:: 2.0 @@ -130,13 +119,14 @@ class AsyncResult(AsyncCommon[Row[_TP]]): def tuples(self) -> AsyncTupleResult[_TP]: """Apply a "typed tuple" typing filter to returned rows. - This method returns the same :class:`.AsyncResult` object at runtime, - however annotates as returning a :class:`.AsyncTupleResult` object - that will indicate to :pep:`484` typing tools that plain typed + 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:`.Row` objects - to by typed, for those cases where the statement invoked itself - included typing information. + 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 @@ -144,21 +134,14 @@ class AsyncResult(AsyncCommon[Row[_TP]]): .. seealso:: - :attr:`.AsyncResult.t` - shorter synonym + :attr:`_asyncio.AsyncResult.t` - shorter synonym - :attr:`.Row.t` - :class:`.Row` version + :attr:`_engine.Row.t` - :class:`_engine.Row` version """ return self # type: ignore - def keys(self) -> RMKeyView: - """Return the :meth:`_engine.Result.keys` collection from the - underlying :class:`_engine.Result`. - - """ - return self._metadata.keys - @_generative def unique( self: SelfAsyncResult, strategy: Optional[_UniqueFilterType] = None @@ -169,7 +152,6 @@ class AsyncResult(AsyncCommon[Row[_TP]]): Refer to :meth:`_engine.Result.unique` in the synchronous SQLAlchemy API for a complete behavioral description. - """ self._unique_filter_state = (set(), strategy) return self @@ -182,7 +164,6 @@ class AsyncResult(AsyncCommon[Row[_TP]]): Refer to :meth:`_engine.Result.columns` in the synchronous SQLAlchemy API for a complete behavioral description. - """ return self._column_slices(col_expressions) @@ -199,9 +180,8 @@ class AsyncResult(AsyncCommon[Row[_TP]]): async for partition in result.partitions(100): print("list of rows: %s" % partition) - .. seealso:: - - :meth:`_engine.Result.partitions` + Refer to :meth:`_engine.Result.partitions` in the synchronous + SQLAlchemy API for a complete behavioral description. """ @@ -215,7 +195,7 @@ class AsyncResult(AsyncCommon[Row[_TP]]): break async def fetchall(self) -> Sequence[Row[_TP]]: - """A synonym for the :meth:`.AsyncResult.all` method. + """A synonym for the :meth:`_asyncio.AsyncResult.all` method. .. versionadded:: 2.0 @@ -232,11 +212,11 @@ class AsyncResult(AsyncCommon[Row[_TP]]): SQLAlchemy 1.x.x. To fetch the first row of a result only, use the - :meth:`_engine.Result.first` method. To iterate through all - rows, iterate the :class:`_engine.Result` object directly. + :meth:`_asyncio.AsyncResult.first` method. To iterate through all + rows, iterate the :class:`_asyncio.AsyncResult` object directly. - :return: a :class:`.Row` object if no filters are applied, or None - if no rows remain. + :return: a :class:`_engine.Row` object if no filters are applied, + or ``None`` if no rows remain. """ row = await greenlet_spawn(self._onerow_getter, self) @@ -258,7 +238,7 @@ class AsyncResult(AsyncCommon[Row[_TP]]): To fetch rows in groups, use the :meth:`._asyncio.AsyncResult.partitions` method. - :return: a list of :class:`.Row` objects. + :return: a list of :class:`_engine.Row` objects. .. seealso:: @@ -274,7 +254,7 @@ class AsyncResult(AsyncCommon[Row[_TP]]): Closes the result set after invocation. Subsequent invocations will return an empty list. - :return: a list of :class:`.Row` objects. + :return: a list of :class:`_engine.Row` objects. """ @@ -291,17 +271,30 @@ class AsyncResult(AsyncCommon[Row[_TP]]): return row async def first(self) -> Optional[Row[_TP]]: - """Fetch the first row or None if no row is present. + """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, + .. 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`. - :return: a :class:`.Row` object, or None + 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:: @@ -322,7 +315,8 @@ class AsyncResult(AsyncCommon[Row[_TP]]): .. versionadded:: 1.4 - :return: The first :class:`.Row` or None if no row is available. + :return: The first :class:`_engine.Row` or ``None`` if no row + is available. :raises: :class:`.MultipleResultsFound` @@ -369,7 +363,7 @@ class AsyncResult(AsyncCommon[Row[_TP]]): ... async def scalar_one_or_none(self) -> Optional[Any]: - """Return exactly one or no scalar result. + """Return exactly one scalar result or ``None``. This is equivalent to calling :meth:`_asyncio.AsyncResult.scalars` and then :meth:`_asyncio.AsyncResult.one_or_none`. @@ -399,7 +393,7 @@ class AsyncResult(AsyncCommon[Row[_TP]]): .. versionadded:: 1.4 - :return: The first :class:`.Row`. + :return: The first :class:`_engine.Row`. :raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound` @@ -425,7 +419,7 @@ class AsyncResult(AsyncCommon[Row[_TP]]): async def scalar(self) -> Any: """Fetch the first column of the first row, and close the result set. - Returns None if there are no rows to fetch. + Returns ``None`` if there are no rows to fetch. No validation is performed to test if additional rows remain. @@ -433,7 +427,7 @@ class AsyncResult(AsyncCommon[Row[_TP]]): e.g. the :meth:`_engine.CursorResult.close` method will have been called. - :return: a Python scalar value , or None if no rows remain. + :return: a Python scalar value, or ``None`` if no rows remain. """ return await greenlet_spawn(self._only_one_row, False, False, True) @@ -461,25 +455,6 @@ class AsyncResult(AsyncCommon[Row[_TP]]): return await greenlet_spawn(FrozenResult, self) - def merge(self, *others: AsyncResult[_TP]) -> MergedResult[_TP]: - """Merge this :class:`_asyncio.AsyncResult` with other compatible - result objects. - - The object returned is an instance of :class:`_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. - - """ - return MergedResult( - self._metadata, - (self._real_result,) + tuple(o._real_result for o in others), - ) - @overload def scalars( self: AsyncResult[Tuple[_T]], index: Literal[0] @@ -515,10 +490,8 @@ class AsyncResult(AsyncCommon[Row[_TP]]): :class:`_asyncio.AsyncMappingResult`. When this filter is applied, fetching rows will return - :class:`.RowMapping` objects instead of :class:`.Row` objects. - - Refer to :meth:`_result.Result.mappings` in the synchronous - SQLAlchemy API for a complete behavioral description. + :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. @@ -582,7 +555,7 @@ class AsyncScalarResult(AsyncCommon[_R]): """Iterate through sub-lists of elements of the size given. Equivalent to :meth:`_asyncio.AsyncResult.partitions` except that - scalar values, rather than :class:`_result.Row` objects, + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -605,7 +578,7 @@ class AsyncScalarResult(AsyncCommon[_R]): """Fetch many objects. Equivalent to :meth:`_asyncio.AsyncResult.fetchmany` except that - scalar values, rather than :class:`_result.Row` objects, + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -615,7 +588,7 @@ class AsyncScalarResult(AsyncCommon[_R]): """Return all scalar values in a list. Equivalent to :meth:`_asyncio.AsyncResult.all` except that - scalar values, rather than :class:`_result.Row` objects, + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -632,10 +605,10 @@ class AsyncScalarResult(AsyncCommon[_R]): return row async def first(self) -> Optional[_R]: - """Fetch the first object or None if no object is present. + """Fetch the first object or ``None`` if no object is present. Equivalent to :meth:`_asyncio.AsyncResult.first` except that - scalar values, rather than :class:`_result.Row` objects, + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -645,7 +618,7 @@ class AsyncScalarResult(AsyncCommon[_R]): """Return at most one object or raise an exception. Equivalent to :meth:`_asyncio.AsyncResult.one_or_none` except that - scalar values, rather than :class:`_result.Row` objects, + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -655,7 +628,7 @@ class AsyncScalarResult(AsyncCommon[_R]): """Return exactly one object or raise an exception. Equivalent to :meth:`_asyncio.AsyncResult.one` except that - scalar values, rather than :class:`_result.Row` objects, + scalar values, rather than :class:`_engine.Row` objects, are returned. """ @@ -667,7 +640,7 @@ SelfAsyncMappingResult = TypeVar( ) -class AsyncMappingResult(AsyncCommon[RowMapping]): +class AsyncMappingResult(_WithKeys, AsyncCommon[RowMapping]): """A wrapper for a :class:`_asyncio.AsyncResult` that returns dictionary values rather than :class:`_engine.Row` values. @@ -694,21 +667,6 @@ class AsyncMappingResult(AsyncCommon[RowMapping]): if result._source_supports_scalars: self._metadata = self._metadata._reduce([0]) - def keys(self) -> RMKeyView: - """Return an iterable view which yields the string keys that would - be represented by each :class:`.Row`. - - The view also can be tested for key containment using the Python - ``in`` operator, which will test both for the string keys represented - in the view, as well as for alternate keys such as column objects. - - .. versionchanged:: 1.4 a key view object is returned rather than a - plain list. - - - """ - return self._metadata.keys - def unique( self: SelfAsyncMappingResult, strategy: Optional[_UniqueFilterType] = None, @@ -731,11 +689,10 @@ class AsyncMappingResult(AsyncCommon[RowMapping]): async def partitions( self, size: Optional[int] = None ) -> AsyncIterator[Sequence[RowMapping]]: - """Iterate through sub-lists of elements of the size given. Equivalent to :meth:`_asyncio.AsyncResult.partitions` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -758,7 +715,7 @@ class AsyncMappingResult(AsyncCommon[RowMapping]): """Fetch one object. Equivalent to :meth:`_asyncio.AsyncResult.fetchone` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -775,7 +732,7 @@ class AsyncMappingResult(AsyncCommon[RowMapping]): """Fetch many rows. Equivalent to :meth:`_asyncio.AsyncResult.fetchmany` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -786,7 +743,7 @@ class AsyncMappingResult(AsyncCommon[RowMapping]): """Return all rows in a list. Equivalent to :meth:`_asyncio.AsyncResult.all` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -804,13 +761,12 @@ class AsyncMappingResult(AsyncCommon[RowMapping]): return row async def first(self) -> Optional[RowMapping]: - """Fetch the first object or None if no object is present. + """Fetch the first object or ``None`` if no object is present. Equivalent to :meth:`_asyncio.AsyncResult.first` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. - """ return await greenlet_spawn(self._only_one_row, False, False, False) @@ -818,7 +774,7 @@ class AsyncMappingResult(AsyncCommon[RowMapping]): """Return at most one object or raise an exception. Equivalent to :meth:`_asyncio.AsyncResult.one_or_none` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -828,7 +784,7 @@ class AsyncMappingResult(AsyncCommon[RowMapping]): """Return exactly one object or raise an exception. Equivalent to :meth:`_asyncio.AsyncResult.one` except that - :class:`_result.RowMapping` values, rather than :class:`_result.Row` + :class:`_engine.RowMapping` values, rather than :class:`_engine.Row` objects, are returned. """ @@ -841,11 +797,11 @@ SelfAsyncTupleResult = TypeVar( class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): - """a :class:`.AsyncResult` that's typed as returning plain Python tuples - instead of rows. + """A :class:`_asyncio.AsyncResult` that's typed as returning plain + Python tuples instead of rows. - Since :class:`.Row` acts like a tuple in every way already, - this class is a typing only class, regular :class:`.AsyncResult` is + Since :class:`_engine.Row` acts like a tuple in every way already, + this class is a typing only class, regular :class:`_asyncio.AsyncResult` is still used at runtime. """ @@ -860,7 +816,7 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): """Iterate through sub-lists of elements of the size given. Equivalent to :meth:`_result.Result.partitions` except that - tuple values, rather than :class:`_result.Row` objects, + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -870,7 +826,7 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): """Fetch one tuple. Equivalent to :meth:`_result.Result.fetchone` except that - tuple values, rather than :class:`_result.Row` + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -884,7 +840,7 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): """Fetch many objects. Equivalent to :meth:`_result.Result.fetchmany` except that - tuple values, rather than :class:`_result.Row` objects, + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -894,7 +850,7 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): """Return all scalar values in a list. Equivalent to :meth:`_result.Result.all` except that - tuple values, rather than :class:`_result.Row` objects, + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -907,10 +863,10 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): ... async def first(self) -> Optional[_R]: - """Fetch the first object or None if no object is present. + """Fetch the first object or ``None`` if no object is present. Equivalent to :meth:`_result.Result.first` except that - tuple values, rather than :class:`_result.Row` objects, + tuple values, rather than :class:`_engine.Row` objects, are returned. @@ -921,7 +877,7 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): """Return at most one object or raise an exception. Equivalent to :meth:`_result.Result.one_or_none` except that - tuple values, rather than :class:`_result.Row` objects, + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -931,7 +887,7 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): """Return exactly one object or raise an exception. Equivalent to :meth:`_result.Result.one` except that - tuple values, rather than :class:`_result.Row` objects, + tuple values, rather than :class:`_engine.Row` objects, are returned. """ @@ -948,14 +904,14 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): async def scalar_one(self) -> Any: """Return exactly one scalar result or raise an exception. - This is equivalent to calling :meth:`.Result.scalars` and then - :meth:`.Result.one`. + This is equivalent to calling :meth:`_engine.Result.scalars` + and then :meth:`_engine.Result.one`. .. seealso:: - :meth:`.Result.one` + :meth:`_engine.Result.one` - :meth:`.Result.scalars` + :meth:`_engine.Result.scalars` """ ... @@ -973,14 +929,14 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): async def scalar_one_or_none(self) -> Optional[Any]: """Return exactly one or no scalar result. - This is equivalent to calling :meth:`.Result.scalars` and then - :meth:`.Result.one_or_none`. + This is equivalent to calling :meth:`_engine.Result.scalars` + and then :meth:`_engine.Result.one_or_none`. .. seealso:: - :meth:`.Result.one_or_none` + :meth:`_engine.Result.one_or_none` - :meth:`.Result.scalars` + :meth:`_engine.Result.scalars` """ ... @@ -997,7 +953,7 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): """Fetch the first column of the first row, and close the result set. - Returns None if there are no rows to fetch. + Returns ``None`` if there are no rows to fetch. No validation is performed to test if additional rows remain. @@ -1005,7 +961,7 @@ class AsyncTupleResult(AsyncCommon[_R], util.TypingOnly): e.g. the :meth:`_engine.CursorResult.close` method will have been called. - :return: a Python scalar value , or None if no rows remain. + :return: a Python scalar value , or ``None`` if no rows remain. """ ...