# 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
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::
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
: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`
@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
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.::
...
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.::
>>> 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)
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:
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:
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.
"""
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
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
"""
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.
"""
:ref:`orm_queryguide_yield_per` - in the :ref:`queryguide_toplevel`
-
"""
getter = self._manyrow_getter
: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)
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`
"""
.. 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.
: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`
"""
.. 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(
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(
...
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(
.. 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(
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.
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(
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`.
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`,
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`.
"""
@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
return self._real_result.closed
def close(self) -> None:
- """Close this :class:`.FilterResult`.
+ """Close this :class:`_engine.FilterResult`.
.. versionadded:: 1.4.43
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.
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.
"""
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.
"""
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.
"""
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.
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.
"""
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.
"""
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.
"""
) -> 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.
"""
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.
"""
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.
"""
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.
"""
...
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.
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.
"""
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.
"""
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`
"""
...
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`
"""
...
"""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.
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.
"""
...
) -> 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.
"""
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.
"""
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.
"""
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.
"""
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.
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.
"""
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.
"""
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::
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
@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
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
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
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, ...])
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
"_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
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
.. 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
Refer to :meth:`_engine.Result.unique` in the synchronous
SQLAlchemy API for a complete behavioral description.
-
"""
self._unique_filter_state = (set(), strategy)
return self
Refer to :meth:`_engine.Result.columns` in the synchronous
SQLAlchemy API for a complete behavioral description.
-
"""
return self._column_slices(col_expressions)
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.
"""
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
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)
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::
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.
"""
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::
.. 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`
...
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`.
.. versionadded:: 1.4
- :return: The first :class:`.Row`.
+ :return: The first :class:`_engine.Row`.
:raises: :class:`.MultipleResultsFound`, :class:`.NoResultFound`
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.
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)
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]
: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.
"""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.
"""
"""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.
"""
"""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.
"""
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.
"""
"""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.
"""
"""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.
"""
)
-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.
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,
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.
"""
"""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.
"""
"""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.
"""
"""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.
"""
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)
"""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.
"""
"""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.
"""
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.
"""
"""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.
"""
"""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.
"""
"""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.
"""
"""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.
"""
...
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.
"""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.
"""
"""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.
"""
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`
"""
...
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`
"""
...
"""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.
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.
"""
...
projects / thirdparty / sqlalchemy / sqlalchemy.git / commitdiff
