Clean up API docs (#736)

 * remove year from copy-right
 * amend imports where missing
 * improve code readability
 * backport improved spatial type docs from 5.0
 * document `srid` values of spatial types

Author: robsdedude

docs/source/api.rst

@@ -270,8 +270,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: ``None``
@@ -484,9 +484,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::
@@ -501,9 +501,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``
@@ -536,9 +537,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: ``None``
@@ -676,9 +678,10 @@ Example:
         return record["node_id"]
 
     def set_person_name(tx, node_id, name):
-        result = tx.run("MATCH (a:Person) WHERE id(a) = $id SET a.name = $name", id=node_id, name=name)
-        info = result.consume()
-        # use the info for logging etc.
+        query = "MATCH (a:Person) WHERE id(a) = $id SET a.name = $name"
+        result = tx.run(query, id=node_id, name=name)
+        summary = result.consume()
+        # use the summary for logging etc.
 
 .. _managed-transactions-ref:
 
@@ -1091,9 +1094,9 @@ Point (WGS-84)     :class:`neo4j.spatial.WGS84Point`
 Point
 =====
 
-
 .. autoclass:: neo4j.spatial.Point
-   :members:
+    :show-inheritance:
+    :members:
 
 
 CartesianPoint
@@ -1102,31 +1105,43 @@ CartesianPoint
 .. autoclass:: neo4j.spatial.CartesianPoint
     :show-inheritance:
 
-    .. autoproperty:: srid
+    .. property:: x
+        :type: float
+
+        Same value as ``point[0]``.
+
+    .. property:: y
+        :type: float
 
-    .. autoproperty:: x
+        Same value as ``point[1]``.
 
-    .. autoproperty:: y
+    .. property:: z
+        :type: float
 
-    .. autoproperty:: z
+        Same value as ``point[2]``.
 
-    .. automethod:: count
+        Only available if the point is in 3D space.
 
-    .. automethod:: index
 
+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
@@ -1135,37 +1150,61 @@ WGS84Point
 .. autoclass:: neo4j.spatial.WGS84Point
     :show-inheritance:
 
-    .. autoproperty:: srid
+    .. property:: x
+        :type: float
+
+        Same value as ``point[0]``.
+
+    .. property:: y
+        :type: float
 
-    .. autoproperty:: x
+        Same value as ``point[1]``.
 
-    .. autoproperty:: y
+    .. property:: z
+        :type: float
 
-    .. autoproperty:: z
+        Same value as ``point[2]``.
 
-    .. autoproperty:: longitude
+        Only available if the point is in 3D space.
 
-    .. autoproperty:: latitude
+    .. property:: longitude
+        :type: float
 
-    .. autoproperty:: height
+        Alias for :attr:`.x`.
 
-    .. automethod:: count
+    .. property:: latitude
+        :type: float
 
-    .. automethod:: index
+        Alias for :attr:`.y`.
 
+    .. property:: height
+        :type: float
 
+        Alias for :attr:`.z`.
 
+        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
+
 
 
 *******************

docs/source/conf.py

@@ -56,7 +56,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

neo4j/spatial/__init__.py

@@ -50,6 +50,11 @@ class Point(tuple):
     there is no subclass defined for the required SRID.
     """
 
+    #: The SRID (spatial reference identifier) of the spatial data.
+    #: A number that identifies the coordinate system the spatial type is to be
+    #: interpreted in.
+    #:
+    #: :type: int
     srid = None
 
     def __new__(cls, iterable):

neo4j/work/result.py

@@ -262,11 +262,11 @@ def create_node_tx(tx, name):
                 result = tx.run("CREATE (n:ExampleNode { name: $name }) RETURN n", name=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::
 
@@ -277,12 +277,12 @@ def get_two_tx(tx):
                     if x > 1:
                         break
                     values.append(record.values())
-                info = result.consume()  # discard the remaining records if there are any
-                # use the info for logging etc.
-                return values, info
+                summary = result.consume()  # discard the remaining records if there are any
+                # 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
         """
@@ -322,7 +322,7 @@ 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
         """
         self._buffer(1)
         if self._record_buffer:

neo4j/work/simple.py

@@ -381,8 +381,9 @@ def get_two_tx(tx):
                     if x > 1:
                         break
                     values.append(record.values())
-                info = result.consume()  # discard the remaining records if there are any
-                # use the info for logging etc.
+                # discard the remaining records if there are any
+                summary = result.consume()
+                # use the summary for logging etc.
                 return values
 
             with driver.session() as session:
@@ -429,7 +430,7 @@ class Query:
     :param metadata: metadata attached to the query.
     :type metadata: dict
     :param timeout: seconds.
-    :type timeout: int
+    :type timeout: float or :const:`None`
     """
     def __init__(self, text, metadata=None, timeout=None):
         self.text = text
@@ -446,6 +447,8 @@ def unit_of_work(metadata=None, timeout=None):
 
     For example, a timeout may be applied::
 
+        from neo4j import unit_of_work
+
         @unit_of_work(timeout=100)
         def count_people_tx(tx):
             result = tx.run("MATCH (a:Person) RETURN count(a) AS persons")
@@ -465,7 +468,7 @@ def count_people_tx(tx):
         This functionality allows to limit query/transaction execution time.
         Specified timeout overrides the default timeout configured in the database using ``dbms.transaction.timeout`` setting.
         Value should not represent a duration of zero or negative duration.
-    :type timeout: int
+    :type timeout: float or :const:`None`
     """
 
     def wrapper(f):