From f247bb20007190ae7aa89929c02c03317b1e6876 Mon Sep 17 00:00:00 2001 From: Mike Bayer Date: Sun, 26 Apr 2020 10:59:34 -0400 Subject: Documentation updates for ResultProxy -> Result This is based off of I8091919d45421e3f53029b8660427f844fee0228 and includes all documentation-only changes as a separate merge, once the parent is merged. Change-Id: I711adea23df0f9f0b1fe7c76210bd2de6d31842d --- lib/sqlalchemy/engine/__init__.py | 4 +++ lib/sqlalchemy/engine/base.py | 20 ++++++------ lib/sqlalchemy/engine/events.py | 4 +-- lib/sqlalchemy/engine/interfaces.py | 4 +-- lib/sqlalchemy/engine/result.py | 64 +++++++++++++++++++++++++++++++++++-- 5 files changed, 80 insertions(+), 16 deletions(-) (limited to 'lib/sqlalchemy/engine') diff --git a/lib/sqlalchemy/engine/__init__.py b/lib/sqlalchemy/engine/__init__.py index 8419cf920..39bf28545 100644 --- a/lib/sqlalchemy/engine/__init__.py +++ b/lib/sqlalchemy/engine/__init__.py @@ -40,6 +40,10 @@ from .interfaces import ExceptionContext # noqa from .interfaces import ExecutionContext # noqa from .interfaces import TypeCompiler # noqa from .mock import create_mock_engine +from .result import ChunkedIteratorResult # noqa +from .result import FrozenResult # noqa +from .result import IteratorResult # noqa +from .result import MergedResult # noqa from .result import Result # noqa from .result import result_tuple # noqa from .row import BaseRow # noqa diff --git a/lib/sqlalchemy/engine/base.py b/lib/sqlalchemy/engine/base.py index 09e700b5c..a2066de4a 100644 --- a/lib/sqlalchemy/engine/base.py +++ b/lib/sqlalchemy/engine/base.py @@ -977,7 +977,7 @@ class Connection(Connectable): def execute(self, object_, *multiparams, **params): r"""Executes a SQL statement construct and returns a - :class:`_engine.ResultProxy`. + :class:`_engine.CursorResult`. :param object: The statement to be executed. May be one of: @@ -1319,7 +1319,7 @@ class Connection(Connectable): self, statement, parameters=None, execution_options=None ): r"""Executes a SQL statement construct and returns a - :class:`_engine.ResultProxy`. + :class:`_engine.CursorResult`. :param statement: The statement str to be executed. Bound parameters must use the underlying DBAPI's paramstyle, such as "qmark", @@ -1380,7 +1380,7 @@ class Connection(Connectable): *args ): """Create an :class:`.ExecutionContext` and execute, returning - a :class:`_engine.ResultProxy`.""" + a :class:`_engine.CursorResult`.""" if execution_options: dialect.set_exec_execution_options(self, execution_options) @@ -1516,12 +1516,12 @@ class Connection(Connectable): assert not self._is_future assert not context._is_future_result - # ResultProxy already exhausted rows / has no rows. + # CursorResult already exhausted rows / has no rows. # close us now if result._soft_closed: self.close() else: - # ResultProxy will close this Connection when no more + # CursorResult will close this Connection when no more # rows to fetch. result._autoclose_connection = True except BaseException as e: @@ -2350,10 +2350,10 @@ class Engine(Connectable, log.Identified): that the :class:`_engine.Connection` will be closed when the operation is complete. When set to ``True``, it indicates the :class:`_engine.Connection` is in "single use" mode, where the - :class:`_engine.ResultProxy` returned by the first call to + :class:`_engine.CursorResult` returned by the first call to :meth:`_engine.Connection.execute` will close the :class:`_engine.Connection` when - that :class:`_engine.ResultProxy` has exhausted all result rows. + that :class:`_engine.CursorResult` has exhausted all result rows. .. seealso:: @@ -2465,16 +2465,16 @@ class Engine(Connectable, log.Identified): ) def execute(self, statement, *multiparams, **params): """Executes the given construct and returns a - :class:`_engine.ResultProxy`. + :class:`_engine.CursorResult`. The arguments are the same as those used by :meth:`_engine.Connection.execute`. Here, a :class:`_engine.Connection` is acquired using the :meth:`_engine.Engine.connect` method, and the statement executed - with that connection. The returned :class:`_engine.ResultProxy` + with that connection. The returned :class:`_engine.CursorResult` is flagged - such that when the :class:`_engine.ResultProxy` is exhausted and its + such that when the :class:`_engine.CursorResult` is exhausted and its underlying cursor is closed, the :class:`_engine.Connection` created here will also be closed, which allows its associated DBAPI connection diff --git a/lib/sqlalchemy/engine/events.py b/lib/sqlalchemy/engine/events.py index 2ab707b8a..af271c56c 100644 --- a/lib/sqlalchemy/engine/events.py +++ b/lib/sqlalchemy/engine/events.py @@ -243,7 +243,7 @@ class ConnectionEvents(event.Events): .. versionadded: 1.4 - :param result: :class:`_engine.ResultProxy` generated by the execution + :param result: :class:`_engine.CursorResult` generated by the execution . """ @@ -298,7 +298,7 @@ class ConnectionEvents(event.Events): :param conn: :class:`_engine.Connection` object :param cursor: DBAPI cursor object. Will have results pending if the statement was a SELECT, but these should not be consumed - as they will be needed by the :class:`_engine.ResultProxy`. + as they will be needed by the :class:`_engine.CursorResult`. :param statement: string SQL statement, as passed to the DBAPI :param parameters: Dictionary, tuple, or list of parameters being passed to the ``execute()`` or ``executemany()`` method of the diff --git a/lib/sqlalchemy/engine/interfaces.py b/lib/sqlalchemy/engine/interfaces.py index e07877475..49d9af966 100644 --- a/lib/sqlalchemy/engine/interfaces.py +++ b/lib/sqlalchemy/engine/interfaces.py @@ -1250,7 +1250,7 @@ class ExecutionContext(object): """Return the DBAPI ``cursor.rowcount`` value, or in some cases an interpreted value. - See :attr:`_engine.ResultProxy.rowcount` for details on this. + See :attr:`_engine.CursorResult.rowcount` for details on this. """ @@ -1298,7 +1298,7 @@ class Connectable(object): def execute(self, object_, *multiparams, **params): """Executes the given construct and returns a """ - """:class:`_engine.ResultProxy`.""" + """:class:`_engine.CursorResult`.""" raise NotImplementedError() def scalar(self, object_, *multiparams, **params): diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py index a3a9cc489..fe0abf0bb 100644 --- a/lib/sqlalchemy/engine/result.py +++ b/lib/sqlalchemy/engine/result.py @@ -585,9 +585,15 @@ class Result(InPlaceGenerative): """Return a callable object that will produce copies of this :class:`.Result` when invoked. + The callable object returned is an instance of + :class:`_engine.FrozenResult`. + This is used for result set caching. The method must be called on the result when it has been unconsumed, and calling the method - will consume the result fully. + will consume the result fully. When the :class:`_engine.FrozenResult` + is retrieved from a cache, it can be called any number of times where + it will produce a new :class:`_engine.Result` object each time + against its stored set of rows. """ return FrozenResult(self) @@ -596,7 +602,7 @@ class Result(InPlaceGenerative): """Merge this :class:`.Result` with other compatible result objects. - The object returned is an instance of :class:`.MergedResult`, + The object returned is an instance of :class:`_engine.MergedResult`, which will be composed of iterators from the given result objects. @@ -1009,6 +1015,30 @@ class Result(InPlaceGenerative): class FrozenResult(object): + """Represents a :class:`.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 generatged from a fixed + set of data each time the :class:`.FrozenResult` is invoked as + a callable:: + + + result = connection.execute(query) + + frozen = result.freeze() + + r1 = frozen() + r2 = frozen() + # ... etc + + .. versionadded:: 1.4 + + """ + def __init__(self, result): self.metadata = result._metadata._for_freeze() self._post_creational_filter = result._post_creational_filter @@ -1030,6 +1060,13 @@ class FrozenResult(object): class IteratorResult(Result): + """A :class:`.Result` that gets data from a Python iterator of + :class:`.Row` objects. + + .. versionadded:: 1.4 + + """ + def __init__(self, cursor_metadata, iterator): self._metadata = cursor_metadata self.iterator = iterator @@ -1061,6 +1098,20 @@ class IteratorResult(Result): class ChunkedIteratorResult(IteratorResult): + """An :class:`.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 + then return an un-consumed iterator of lists, each list of the requested + size. + + The function can be called at any time again, in which case it should + continue from the same result set but adjust the chunk size as given. + + .. versionadded:: 1.4 + + """ + def __init__(self, cursor_metadata, chunks): self._metadata = cursor_metadata self.chunks = chunks @@ -1074,6 +1125,15 @@ class ChunkedIteratorResult(IteratorResult): class MergedResult(IteratorResult): + """A :class:`_engine.Result` that is merged from any number of + :class:`_engine.Result` objects. + + Returned by the :meth:`_engine.Result.merge` method. + + .. versionadded:: 1.4 + + """ + closed = False def __init__(self, cursor_metadata, results): -- cgit v1.2.1