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

5 files changed, 80 insertions, 16 deletions

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):