Clean up API docs (#735)

 * remove year from copy-right
 * amend imports where missing
 * improve code readability
 * document `srid` values of spatial types
 * document `ResultConsumedError` can be raised from `Result.fetch`

Co-authored-by: Antonio Barcélos <antonio.barcelos@neo4j.com>

Author: robsdedude

docs/source/api.rst

@@ -275,8 +275,8 @@ For example:
            raise gaierror("Unexpected socket address %r" % socket_address)
 
    driver = GraphDatabase.driver("neo4j://example.com:9999",
-                auth=("neo4j", "password"),
-                resolver=custom_resolver)
+                                 auth=("neo4j", "password"),
+                                 resolver=custom_resolver)
 
 
 :Default: :const:`None`
@@ -541,9 +541,9 @@ Name of the database to query.
 
 
 .. py:attribute:: neo4j.DEFAULT_DATABASE
-   :noindex:
+    :noindex:
 
-   This will use the default database on the Neo4j instance.
+    This will use the default database on the Neo4j instance.
 
 
 .. Note::
@@ -558,9 +558,10 @@ Name of the database to query.
 
 .. code-block:: python
 
-   from neo4j import GraphDatabase
-   driver = GraphDatabase.driver(uri, auth=(user, password))
-   session = driver.session(database="system")
+    from neo4j import GraphDatabase
+
+    driver = GraphDatabase.driver(uri, auth=(user, password))
+    session = driver.session(database="system")
 
 
 :Default: ``neo4j.DEFAULT_DATABASE``
@@ -593,9 +594,10 @@ context of the impersonated user. For this, the user for which the
 
 .. code-block:: python
 
-   from neo4j import GraphDatabase
-   driver = GraphDatabase.driver(uri, auth=(user, password))
-   session = driver.session(impersonated_user="alice")
+    from neo4j import GraphDatabase
+
+    driver = GraphDatabase.driver(uri, auth=(user, password))
+    session = driver.session(impersonated_user="alice")
 
 
 :Default: :const:`None`
@@ -740,8 +742,8 @@ Example:
     def set_person_name(tx, node_id, name):
         query = "MATCH (a:Person) WHERE id(a) = $id SET a.name = $name"
         result = tx.run(query, id=node_id, name=name)
-        info = result.consume()
-        # use the info for logging etc.
+        summary = result.consume()
+        # use the summary for logging etc.
 
 .. _managed-transactions-ref:
 

docs/source/async_api.rst

@@ -446,8 +446,8 @@ Example:
     async def set_person_name(tx, node_id, name):
         query = "MATCH (a:Person) WHERE id(a) = $id SET a.name = $name"
         result = await tx.run(query, id=node_id, name=name)
-        info = await result.consume()
-        # use the info for logging etc.
+        summary = await result.consume()
+        # use the summary for logging etc.
 
 .. _async-managed-transactions-ref:
 

docs/source/conf.py

@@ -57,7 +57,7 @@
 
 # General information about the project.
 project = 'Neo4j Python Driver'
-copyright = '2002-2020 Neo4j, Inc.'
+copyright = 'Neo4j, Inc.'
 author = 'Neo4j, Inc.'
 
 # The version info for the project you're documenting, acts as replacement for

docs/source/types/spatial.rst

@@ -12,7 +12,7 @@ Point
 
 .. autoclass:: neo4j.spatial.Point
     :show-inheritance:
-    :members: srid
+    :members:
 
 
 CartesianPoint
@@ -21,9 +21,6 @@ CartesianPoint
 .. autoclass:: neo4j.spatial.CartesianPoint
     :show-inheritance:
 
-    .. property:: srid
-        :type: int
-
     .. property:: x
         :type: float
 
@@ -39,24 +36,28 @@ CartesianPoint
 
         Same value as ``point[2]``.
 
-        Only available if the point is in space.
+        Only available if the point is in 3D space.
 
 
 Examples
 --------
 
 .. code-block:: python
 
-    point=CartesianPoint((1.23, 4.56)
+    from neo4j.spatial import CartesianPoint
 
-    print(point.x, point.y)
+    point = CartesianPoint((1.23, 4.56)
+    print(point.x, point.y, point.srid)
+    # 1.23 4.56 7203
 
 
 .. code-block:: python
 
-    point=CartesianPoint((1.23, 4.56, 7.89)
+    from neo4j.spatial import CartesianPoint
 
-    print(point.x, point.y, point.z)
+    point = CartesianPoint((1.23, 4.56, 7.89)
+    print(point.x, point.y, point.z, point.srid)
+    # 1.23 4.56 7.8 9157
 
 
 WGS84Point
@@ -65,9 +66,6 @@ WGS84Point
 .. autoclass:: neo4j.spatial.WGS84Point
     :show-inheritance:
 
-    .. property:: srid
-        :type: int
-
     .. property:: x
         :type: float
 
@@ -83,7 +81,7 @@ WGS84Point
 
         Same value as ``point[2]``.
 
-        Only available if the point is in space.
+        Only available if the point is in 3D space.
 
     .. property:: longitude
         :type: float
@@ -100,19 +98,25 @@ WGS84Point
 
         Alias for :attr:`.z`.
 
-        Only available if the point is in space.
+        Only available if the point is in 3D space.
 
 
 Examples
 --------
 
 .. code-block:: python
 
-    point=WGS84Point((1.23, 4.56))
-    print(point.longitude, point.latitude)
+    from neo4j.spatial import WGS84Point
+
+    point = WGS84Point((1.23, 4.56))
+    print(point.longitude, point.latitude, point.srid)
+    # 1.23 4.56 4326
 
 
 .. code-block:: python
 
-    point=WGS84Point((1.23, 4.56, 7.89))
-    print(point.longitude, point.latitude, point.height)
+    from neo4j.spatial import WGS84Point
+
+    point = WGS84Point((1.23, 4.56, 7.89))
+    print(point.longitude, point.latitude, point.height, point.srid)
+    # 1.23 4.56 7.89 4979

neo4j/_async/work/result.py

@@ -207,7 +207,7 @@ def on_success(summary_metadata):
     async def __aiter__(self):
         """Iterator returning Records.
         :returns: Record, it is an immutable ordered collection of key-value pairs.
-        :rtype: :class:`neo4j.AsyncRecord`
+        :rtype: :class:`neo4j.Record`
         """
         while self._record_buffer or self._attached:
             if self._record_buffer:
@@ -316,17 +316,19 @@ async def consume(self):
 
         Example::
 
-            def create_node_tx(tx, name):
+            async def create_node_tx(tx, name):
                 result = await tx.run(
                     "CREATE (n:ExampleNode { name: $name }) RETURN n", name=name
                 )
                 record = await result.single()
                 value = record.value()
-                info = await result.consume()
-                return value, info
+                summary = await result.consume()
+                return value, summary
 
             async with driver.session() as session:
-                node_id, info = await session.write_transaction(create_node_tx, "example")
+                node_id, summary = await session.write_transaction(
+                    create_node_tx, "example"
+                )
 
         Example::
 
@@ -337,13 +339,16 @@ async def get_two_tx(tx):
                     if len(values) >= 2:
                         break
                     values.append(record.values())
+                # or shorter: values = [record.values()
+                #                       for record in await result.fetch(2)]
+
                 # discard the remaining records if there are any
-                info = await result.consume()
-                # use the info for logging etc.
-                return values, info
+                summary = await result.consume()
+                # use the summary for logging etc.
+                return values, summary
 
-            with driver.session() as session:
-                values, info = session.read_transaction(get_two_tx)
+            async with driver.session() as session:
+                values, summary = await session.read_transaction(get_two_tx)
 
         :returns: The :class:`neo4j.ResultSummary` for this result
 
@@ -424,7 +429,11 @@ async def fetch(self, n):
         :param n: the maximum number of records to fetch.
         :type n: int
 
-        :returns: list of :class:`neo4j.AsyncRecord`
+        :returns: list of :class:`neo4j.Record`
+
+        :raises ResultConsumedError: if the transaction from which this result
+            was obtained has been closed or the Result has been explicitly
+            consumed.
 
         .. versionadded:: 5.0
         """
@@ -438,7 +447,8 @@ async def peek(self):
         """Obtain the next record from this result without consuming it.
         This leaves the record in the buffer for further processing.
 
-        :returns: the next :class:`.Record` or :const:`None` if none remain
+        :returns: the next :class:`neo4j.Record` or :const:`None` if none
+            remain.
 
         :raises ResultConsumedError: if the transaction from which this result
             was obtained has been closed or the Result has been explicitly
@@ -474,7 +484,7 @@ async def graph(self):
     async def value(self, key=0, default=None):
         """Helper function that return the remainder of the result as a list of values.
 
-        See :class:`neo4j.AsyncRecord.value`
+        See :class:`neo4j.Record.value`
 
         :param key: field to return for each remaining record. Obtain a single value from the record by index or key.
         :param default: default value, used if the index of key is unavailable
@@ -494,7 +504,7 @@ async def value(self, key=0, default=None):
     async def values(self, *keys):
         """Helper function that return the remainder of the result as a list of values lists.
 
-        See :class:`neo4j.AsyncRecord.values`
+        See :class:`neo4j.Record.values`
 
         :param keys: fields to return for each remaining record. Optionally filtering to include only certain values by index or key.
 
@@ -513,7 +523,7 @@ async def values(self, *keys):
     async def data(self, *keys):
         """Helper function that return the remainder of the result as a list of dictionaries.
 
-        See :class:`neo4j.AsyncRecord.data`
+        See :class:`neo4j.Record.data`
 
         :param keys: fields to return for each remaining record. Optionally filtering to include only certain values by index or key.
 

neo4j/_async/work/session.py

@@ -468,9 +468,12 @@ async def get_two_tx(tx):
                     if len(values) >= 2:
                         break
                     values.append(record.values())
+                # or shorter: values = [record.values()
+                #                       for record in await result.fetch(2)]
+
                 # discard the remaining records if there are any
-                info = await result.consume()
-                # use the info for logging etc.
+                summary = await result.consume()
+                # use the summary for logging etc.
                 return values
 
             async with driver.session() as session:

neo4j/_conf.py

@@ -30,6 +30,8 @@ class TrustSystemCAs(TrustStore):
 
     For example::
 
+        import neo4j
+
         driver = neo4j.GraphDatabase.driver(
             url, auth=auth, trusted_certificates=neo4j.TrustSystemCAs()
         )
@@ -48,6 +50,8 @@ class TrustAll(TrustStore):
 
     For example::
 
+        import neo4j
+
         driver = neo4j.GraphDatabase.driver(
             url, auth=auth, trusted_certificates=neo4j.TrustAll()
         )
@@ -69,6 +73,8 @@ class TrustCustomCAs(TrustStore):
 
     For example::
 
+        import neo4j
+
         driver = neo4j.GraphDatabase.driver(
             url, auth=auth,
             trusted_certificates=neo4j.TrustCustomCAs(

neo4j/_sync/work/result.py

@@ -322,11 +322,13 @@ def create_node_tx(tx, name):
                 )
                 record = result.single()
                 value = record.value()
-                info = result.consume()
-                return value, info
+                summary = result.consume()
+                return value, summary
 
             with driver.session() as session:
-                node_id, info = session.write_transaction(create_node_tx, "example")
+                node_id, summary = session.write_transaction(
+                    create_node_tx, "example"
+                )
 
         Example::
 
@@ -337,13 +339,16 @@ def get_two_tx(tx):
                     if len(values) >= 2:
                         break
                     values.append(record.values())
+                # or shorter: values = [record.values()
+                #                       for record in result.fetch(2)]
+
                 # discard the remaining records if there are any
-                info = result.consume()
-                # use the info for logging etc.
-                return values, info
+                summary = result.consume()
+                # use the summary for logging etc.
+                return values, summary
 
             with driver.session() as session:
-                values, info = session.read_transaction(get_two_tx)
+                values, summary = session.read_transaction(get_two_tx)
 
         :returns: The :class:`neo4j.ResultSummary` for this result
 
@@ -426,6 +431,10 @@ def fetch(self, n):
 
         :returns: list of :class:`neo4j.Record`
 
+        :raises ResultConsumedError: if the transaction from which this result
+            was obtained has been closed or the Result has been explicitly
+            consumed.
+
         .. versionadded:: 5.0
         """
         self._buffer(n)
@@ -438,7 +447,8 @@ def peek(self):
         """Obtain the next record from this result without consuming it.
         This leaves the record in the buffer for further processing.
 
-        :returns: the next :class:`.Record` or :const:`None` if none remain
+        :returns: the next :class:`neo4j.Record` or :const:`None` if none
+            remain.
 
         :raises ResultConsumedError: if the transaction from which this result
             was obtained has been closed or the Result has been explicitly