diff options
Diffstat (limited to 'lib/sqlalchemy/engine/result.py')
| -rw-r--r-- | lib/sqlalchemy/engine/result.py | 322 |
1 files changed, 169 insertions, 153 deletions
diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py index 392cefa02..a63bad54e 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 |