Improve ResultProxy/Row documentation before the API change

We'd like to merge Ieb9085e9bcff564359095b754da9ae0af55679f0,
however the documentation in that change should be based off
of more comprehensive documentation than what we have already.

Add the notion of "row" to the tutorial and document all
methods.   This will also be backported at least to 1.3
in terms of RowProxy.

Change-Id: I2173aecc86cf15c5a7c473b8f471639ee9082f84

1 files changed, 75 insertions, 38 deletions

diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index c2f976aa0..13738cb46 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -129,9 +129,12 @@ except ImportError:
 class Row(BaseRow, collections_abc.Sequence):
     """Represent a single result row.
 
+    The :class:`.Row` object is retrieved from a database result, from the
+    :class:`.ResultProxy` object using methods like
+    :meth:`.ResultProxy.fetchall`.
+
     The :class:`.Row` object seeks to act mostly like a Python named
-    tuple, but also provides for mapping-oriented access via the
-    :attr:`.Row._mapping` attribute.
+    tuple, but also provides some Python dictionary behaviors at the same time.
 
     .. seealso::
 
@@ -189,7 +192,22 @@ class Row(BaseRow, collections_abc.Sequence):
         return repr(sql_util._repr_row(self))
 
     def has_key(self, key):
-        """Return True if this Row contains the given key."""
+        """Return True if this :class:`.Row` contains the given key.
+
+        Through the SQLAlchemy 1.x series, the ``__contains__()`` method
+        of :class:`.Row` also links to :meth:`.Row.has_key`, in that
+        an expression such as ::
+
+            "some_col" in row
+
+        Will return True if the row contains a column named ``"some_col"``,
+        in the way that a Python mapping works.
+
+        However, it is planned that the 2.0 series of SQLAlchemy will reverse
+        this behavior so that ``__contains__()`` will refer to a value being
+        present in the row, in the way that a Python tuple works.
+
+        """
 
         return self._parent._has_key(key)
 
@@ -197,23 +215,52 @@ class Row(BaseRow, collections_abc.Sequence):
         return self._get_by_key_impl(key)
 
     def items(self):
-        """Return a list of tuples, each tuple containing a key/value pair."""
-        # TODO: no coverage here
+        """Return a list of tuples, each tuple containing a key/value pair.
+
+        This method is analogous to the Python dictionary ``.items()`` method,
+        except that it returns a list, not an iterator.
+
+        """
+
         return [(key, self[key]) for key in self.keys()]
 
     def keys(self):
-        """Return the list of keys as strings represented by this Row."""
+        """Return the list of keys as strings represented by this
+        :class:`.Row`.
+
+        This method is analogous to the Python dictionary ``.keys()`` method,
+        except that it returns a list, not an iterator.
+
+        """
 
         return [k for k in self._parent.keys if k is not None]
 
     def iterkeys(self):
+        """Return a an iterator against the :meth:`.Row.keys` method.
+
+        This method is analogous to the Python-2-only dictionary
+        ``.iterkeys()`` method.
+
+        """
         return iter(self._parent.keys)
 
     def itervalues(self):
+        """Return a an iterator against the :meth:`.Row.values` method.
+
+        This method is analogous to the Python-2-only dictionary
+        ``.itervalues()`` method.
+
+        """
         return iter(self)
 
     def values(self):
-        """Return the values represented by this Row as a list."""
+        """Return the values represented by this :class:`.Row` as a list.
+
+        This method is analogous to the Python dictionary ``.values()`` method,
+        except that it returns a list, not an iterator.
+
+        """
+
         return self._values_impl()
 
 
@@ -827,23 +874,16 @@ class ResultMetaData(object):
 
 
 class ResultProxy(object):
-    """Wraps a DB-API cursor object to provide easier access to row columns.
-
-    Individual columns may be accessed by their integer position,
-    case-insensitive column name, or by ``schema.Column``
-    object. e.g.::
-
-      row = fetchone()
-
-      col1 = row[0]    # access via integer position
+    """A facade around a DBAPI cursor object.
 
-      col2 = row['col2']   # access via name
+    Returns database rows via the :class:`.Row` class, which provides
+    additional API features and behaviors on top of the raw data returned
+    by the DBAPI.
 
-      col3 = row[mytable.c.mycol] # access via Column object.
+    .. seealso::
 
-    ``ResultProxy`` also handles post-processing of result column
-    data using ``TypeEngine`` objects, which are referenced from
-    the originating SQL statement that produced this result set.
+        :ref:`coretutorial_selecting` - introductory material for accessing
+        :class:`.ResultProxy` and :class:`.Row` objects.
 
     """
 
@@ -912,7 +952,9 @@ class ResultProxy(object):
                 )
 
     def keys(self):
-        """Return the current set of string keys for rows."""
+        """Return the list of string keys that would represented by each
+        :class:`.Row`."""
+
         if self._metadata:
             return self._metadata.keys
         else:
@@ -1085,8 +1127,6 @@ class ResultProxy(object):
 
             :ref:`connections_toplevel`
 
-            :meth:`.ResultProxy._soft_close`
-
         """
 
         if not self.closed:
@@ -1104,7 +1144,10 @@ class ResultProxy(object):
                 yield row
 
     def __next__(self):
-        """Implement the next() protocol.
+        """Implement the Python next() protocol.
+
+        This method, mirrored as both ``.next()`` and  ``.__next__()``, is part
+        of Python's API for producing iterator-like behavior.
 
         .. versionadded:: 1.2
 
@@ -1358,9 +1401,7 @@ class ResultProxy(object):
         an empty list.   After the :meth:`.ResultProxy.close` method is
         called, the method will raise :class:`.ResourceClosedError`.
 
-        .. versionchanged:: 1.0.0 - Added "soft close" behavior which
-           allows the result to be used in an "exhausted" state prior to
-           calling the :meth:`.ResultProxy.close` method.
+        :return: a list of :class:`.Row` objects
 
         """
 
@@ -1386,9 +1427,7 @@ class ResultProxy(object):
         an empty list.   After the :meth:`.ResultProxy.close` method is
         called, the method will raise :class:`.ResourceClosedError`.
 
-        .. versionchanged:: 1.0.0 - Added "soft close" behavior which
-           allows the result to be used in an "exhausted" state prior to
-           calling the :meth:`.ResultProxy.close` method.
+        :return: a list of :class:`.Row` objects
 
         """
 
@@ -1414,9 +1453,7 @@ class ResultProxy(object):
         After the :meth:`.ResultProxy.close` method is
         called, the method will raise :class:`.ResourceClosedError`.
 
-        .. versionchanged:: 1.0.0 - Added "soft close" behavior which
-           allows the result to be used in an "exhausted" state prior to
-           calling the :meth:`.ResultProxy.close` method.
+        :return: a :class:`.Row` object, or None if no rows remain
 
         """
         try:
@@ -1434,11 +1471,11 @@ class ResultProxy(object):
     def first(self):
         """Fetch the first row and then close the result set unconditionally.
 
-        Returns None if no row is present.
-
         After calling this method, the object is fully closed,
         e.g. the :meth:`.ResultProxy.close` method will have been called.
 
+        :return: a :class:`.Row` object, or None if no rows remain
+
         """
         if self._metadata is None:
             return self._non_result(None)
@@ -1461,11 +1498,11 @@ class ResultProxy(object):
     def scalar(self):
         """Fetch the first column of the first row, and close the result set.
 
-        Returns None if no row is present.
-
         After calling this method, the object is fully closed,
         e.g. the :meth:`.ResultProxy.close` method will have been called.
 
+        :return: a Python scalar value , or None if no rows remain
+
         """
         row = self.first()
         if row is not None: