Results docs updates

Author: technige

docs/source/results.rst

@@ -9,12 +9,95 @@ Each result consists of header metadata, zero or more :class:`.Record` objects a
 Results also contain a buffer that automatically stores unconsumed records when results are consumed out of order.
 A :class:`.BoltStatementResult` is attached to an active connection, through a :class:`.Session`, until all its content has been buffered or consumed.
 
-.. autoclass:: neo4j.BoltStatementResult
-   :inherited-members:
-   :members:
+.. class:: neo4j.BoltStatementResult
 
-.. autoclass:: neo4j.Record
-   :members:
+    .. describe:: iter(result)
+
+    .. autoattribute:: session
+
+    .. automethod:: attached
+
+    .. automethod:: detach
+
+    .. automethod:: keys
+
+    .. automethod:: records
+
+    .. automethod:: summary
+
+    .. automethod:: consume
+
+    .. automethod:: single
+
+    .. automethod:: peek
+
+    .. automethod:: graph
+
+    .. automethod:: value
+
+    .. automethod:: values
+
+    .. automethod:: data
+
+
+.. class:: neo4j.Record
+
+    A :class:`.Record` is an immutable ordered collection of key-value
+    pairs. It is generally closer to a :py:class:`namedtuple` than to a
+    :py:class:`OrderedDict` inasmuch as iteration of the collection will
+    yield values rather than keys.
+
+    .. describe:: Record(iterable)
+
+        Create a new record based on an dictionary-like iterable.
+        This can be a dictionary itself, or may be a sequence of key-value pairs, each represented by a tuple.
+
+    .. describe:: record == other
+
+        Compare a record for equality with another value.
+        The `other` value may be any `Sequence` or `Mapping`, or both.
+        If comparing with a `Sequence`, the values are compared in order.
+        If comparing with a `Mapping`, the values are compared based on their keys.
+        If comparing with a value that exhibits both traits, both comparisons must be true for the values to be considered equal.
+
+    .. describe:: record != other
+
+        Compare a record for inequality with another value.
+        See above for comparison rules.
+
+    .. describe:: hash(record)
+
+        Create a hash for this record.
+        This will raise a :exc:`TypeError` if any values within the record are unhashable.
+
+    .. describe:: record[index]
+
+        Obtain a value from the record by index.
+        This will raise an :exc:`IndexError` if the specified index is out of range.
+
+    .. describe:: record[i:j]
+
+        Derive a sub-record based on a start and end index.
+        All keys and values within those bounds will be copied across in the same order as in the original record.
+
+    .. describe:: record[key]
+
+        Obtain a value from the record by key.
+        This will raise a :exc:`KeyError` if the specified key does not exist.
+
+    .. automethod:: get(key, default=None)
+
+    .. automethod:: value(key=0, default=None)
+
+    .. automethod:: index(key)
+
+    .. automethod:: keys
+
+    .. automethod:: values
+
+    .. automethod:: items
+
+    .. automethod:: data
 
 
 Summary Details

neo4j/__init__.py

@@ -73,7 +73,7 @@
 from warnings import warn
 
 
-from .compat import perf_counter, urlparse, xstr, Mapping
+from .compat import perf_counter, urlparse, xstr, Sequence, Mapping
 from .config import *
 from .meta import version as __version__
 
@@ -889,13 +889,13 @@ def __iter__(self):
 
     @property
     def session(self):
+        """ The :class:`.Session` to which this result is attached, if any.
+        """
         return self._session
 
     def attached(self):
         """ Indicator for whether or not this result is still attached to
-        a :class:`.Session`.
-
-        :returns: :const:`True` if still attached, :const:`False` otherwise
+        an open :class:`.Session`.
         """
         return self._session and not self._session.closed()
 
@@ -1250,7 +1250,22 @@ def __repr__(self):
                             " ".join("%s=%r" % (field, self[i]) for i, field in enumerate(self.__keys)))
 
     def __eq__(self, other):
-        return dict(self) == dict(other)
+        """ In order to be flexible regarding comparison, the equality rules
+        for a record permit comparison with any other Sequence or Mapping.
+
+        :param other:
+        :return:
+        """
+        compare_as_sequence = isinstance(other, Sequence)
+        compare_as_mapping = isinstance(other, Mapping)
+        if compare_as_sequence and compare_as_mapping:
+            return list(self) == list(other) and dict(self) == dict(other)
+        elif compare_as_sequence:
+            return list(self) == list(other)
+        elif compare_as_mapping:
+            return dict(self) == dict(other)
+        else:
+            return False
 
     def __ne__(self, other):
         return not self.__eq__(other)
@@ -1276,6 +1291,13 @@ def __getslice__(self, start, stop):
         return self.__class__(zip(keys, values))
 
     def get(self, key, default=None):
+        """ Obtain a value from the record by key, returning a default
+        value if the key does not exist.
+
+        :param key:
+        :param default:
+        :return:
+        """
         try:
             index = self.__keys.index(ustr(key))
         except ValueError:
@@ -1287,6 +1309,9 @@ def get(self, key, default=None):
 
     def index(self, key):
         """ Return the index of the given item.
+
+        :param key:
+        :return:
         """
         if isinstance(key, integer):
             if 0 <= key < len(self.__keys):

neo4j/compat/__init__.py

@@ -124,9 +124,9 @@ def perf_counter():
 # Using or importing the ABCs from 'collections' instead of from
 # 'collections.abc' is deprecated, and in 3.8 it will stop working
 try:
-    from collections.abc import Mapping
+    from collections.abc import Sequence, Mapping
 except ImportError:
-    from collections import Mapping
+    from collections import Sequence, Mapping
 
 
 # The location of urlparse varies between Python 2 and 3

test/integration/test_result.py

@@ -272,14 +272,14 @@ def test_single_consumes_entire_result_if_one_record(self):
         session = self.driver.session()
         result = session.run("UNWIND range(1, 1) AS n RETURN n")
         _ = result.single()
-        assert not result.attached()
+        assert not result.session
 
     def test_single_consumes_entire_result_if_multiple_records(self):
         session = self.driver.session()
         result = session.run("UNWIND range(1, 3) AS n RETURN n")
         with pytest.warns(UserWarning):
             _ = result.single()
-        assert not result.attached()
+        assert not result.session
 
     def test_single_value(self):
         with self.driver.session() as session: