Improve some documentations

Change-Id: Ibcb0da3166b94aa58fa92d544c3e5cf75844546e

2 files changed, 34 insertions, 33 deletions

diff --git a/lib/sqlalchemy/engine/result.py b/lib/sqlalchemy/engine/result.py
index 8b9b413c4..cb452ac73 100644
--- a/lib/sqlalchemy/engine/result.py
+++ b/lib/sqlalchemy/engine/result.py
@@ -677,7 +677,30 @@ class ResultInternal(InPlaceGenerative):
         return uniques, strategy
 
 
-class Result(ResultInternal):
+class _WithKeys(object):
+    # used mainly to share documentation on the keys method.
+    # py2k does not allow overriding the __doc__ attribute.
+    def keys(self):
+        """Return an iterable view which yields the string keys that would
+        be represented by each :class:`.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
+        execution.
+
+        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
+
+
+class Result(_WithKeys, ResultInternal):
     """Represent a set of database results.
 
     .. versionadded:: 1.4  The :class:`.Result` object provides a completely
@@ -705,21 +728,6 @@ class Result(ResultInternal):
     def _soft_close(self, hard=False):
         raise NotImplementedError()
 
-    def keys(self):
-        """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
-
     @_generative
     def yield_per(self, num):
         """Configure the row-fetching strategy to fetch num rows at a time.
@@ -949,7 +957,7 @@ class Result(ResultInternal):
         :paramref:`.Connection.execution_options.stream_results` execution
         option is used indicating that the driver should not pre-buffer
         results, if possible.   Not all drivers support this option and
-        the option is silently ignored for those who do.
+        the option is silently ignored for those who do not.
 
         .. versionadded:: 1.4
 
@@ -1361,7 +1369,7 @@ class ScalarResult(FilterResult):
         return self._only_one_row(True, True, False)
 
 
-class MappingResult(FilterResult):
+class MappingResult(_WithKeys, FilterResult):
     """A wrapper for a :class:`_engine.Result` that returns dictionary values
     rather than :class:`_engine.Row` values.
 
@@ -1381,21 +1389,6 @@ class MappingResult(FilterResult):
         if result._source_supports_scalars:
             self._metadata = self._metadata._reduce([0])
 
-    def keys(self):
-        """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, strategy=None):
         # type: () -> MappingResult
         """Apply unique filtering to the objects returned by this
diff --git a/lib/sqlalchemy/engine/row.py b/lib/sqlalchemy/engine/row.py
index fe6831e30..288f08e29 100644
--- a/lib/sqlalchemy/engine/row.py
+++ b/lib/sqlalchemy/engine/row.py
@@ -276,6 +276,10 @@ class Row(BaseRow, collections_abc.Sequence):
         """Return the list of keys as strings represented by this
         :class:`.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
+        execution.
+
         This method is analogous to the Python dictionary ``.keys()`` method,
         except that it returns a list, not an iterator.
 
@@ -293,6 +297,10 @@ class Row(BaseRow, collections_abc.Sequence):
         """Return a tuple of string keys as represented by this
         :class:`.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
+        execution.
+
         This attribute is analogous to the Python named tuple ``._fields``
         attribute.