4.1 api documentation update about result iterator (#456)

* added ref links to filter warnings

* updated examples for the api documentation

* added a example to session.run with a READ_ACCESS

Author: martin-neotech

docs/source/api.rst

@@ -167,7 +167,7 @@ Specify whether TCP keep-alive should be enabled.
 :Type: ``bool``
 :Default: ``True``
 
-**This is experimental.**
+**This is experimental.** (See :ref:`filter-warnings-ref`)
 
 
 .. _max-connection-lifetime-ref:
@@ -516,12 +516,31 @@ Auto-commit transactions are the simplest form of transaction, available via :py
 These are easy to use but support only one statement per transaction and are not automatically retried on failure.
 Auto-commit transactions are also the only way to run ``PERIODIC COMMIT`` statements, since this Cypher clause manages its own transactions internally.
 
+Example:
+
 .. code-block:: python
 
+    import neo4j
+
     def create_person(driver, name):
-        with driver.session() as session:
-            return session.run("CREATE (a:Person {name:$name}) "
-                               "RETURN id(a)", name=name).single().value()
+        with driver.session(default_access_mode=neo4j.WRITE_ACCESS) as session:
+            result = session.run("CREATE (a:Person { name: $name }) RETURN id(a) AS node_id", name=name)
+            record = result.single()
+            return record["node_id"]
+
+Example:
+
+.. code-block:: python
+
+    import neo4j
+
+    def get_numbers(driver):
+        numbers = []
+        with driver.session(default_access_mode=neo4j.READ_ACCESS) as session:
+            result = session.run("UNWIND [1, 2, 3] AS x RETURN x")
+            for record in result:
+                numbers.append(record["x"])
+        return numbers
 
 
 .. _explicit-transactions-ref:
@@ -551,23 +570,30 @@ or can be explicitly controlled through the :py:meth:`neo4j.Transaction.commit`,
 
 Explicit transactions are most useful for applications that need to distribute Cypher execution across multiple functions for the same transaction.
 
+Example:
+
 .. code-block:: python
 
+    import neo4j
+
     def create_person(driver, name):
-        with driver.session() as session:
+        with driver.session(default_access_mode=neo4j.WRITE_ACCESS) as session:
             tx = session.begin_transaction()
             node_id = create_person_node(tx)
             set_person_name(tx, node_id, name)
             tx.commit()
+            tx.close()
 
     def create_person_node(tx):
-        return tx.run("CREATE (a:Person)"
-                      "RETURN id(a)", name=name).single().value()
+        name = "default_name"
+        result = tx.run("CREATE (a:Person { name: $name }) RETURN id(a) AS node_id", name=name)
+        record = result.single()
+        return record["node_id"]
 
     def set_person_name(tx, node_id, name):
-        tx.run("MATCH (a:Person) WHERE id(a) = $id "
-               "SET a.name = $name", id=node_id, name=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.
 
 .. _managed-transactions-ref:
 
@@ -583,15 +609,18 @@ This function is called one or more times, within a configurable time limit, unt
 Results should be fully consumed within the function and only aggregate or status values should be returned.
 Returning a live result object would prevent the driver from correctly managing connections and would break retry guarantees.
 
+Example:
 
 .. code-block:: python
 
-    def create_person(tx, name):
-        return tx.run("CREATE (a:Person {name:$name}) "
-                      "RETURN id(a)", name=name).single().value()
+    def create_person(driver, name)
+        with driver.session() as session:
+            node_id = session.write_transaction(create_person_tx, name)
 
-    with driver.session() as session:
-        node_id = session.write_transaction(create_person, "Alice")
+    def create_person_tx(tx, name):
+        result = tx.run("CREATE (a:Person { name: $name }) RETURN id(a) AS node_id", name=name)
+        record = result.single()
+        return record["node_id"]
 
 To exert more control over how a transaction function is carried out, the :func:`neo4j.unit_of_work` decorator can be used.
 
@@ -631,7 +660,7 @@ A :class:`neo4j.Result` is attached to an active connection, through a :class:`n
 
     .. automethod:: graph
 
-       **This is experimental.**
+       **This is experimental.** (See :ref:`filter-warnings-ref`)
 
     .. automethod:: value
 
@@ -656,7 +685,7 @@ Graph
 
     .. automethod:: relationship_type
 
-**This is experimental.**
+**This is experimental.** (See :ref:`filter-warnings-ref`)
 
 
 ******
@@ -1248,6 +1277,8 @@ The Python Driver uses the :class:`neo4j.ExperimentalWarning` class to warn abou
 .. autoclass:: neo4j.ExperimentalWarning
 
 
+.. _filter-warnings-ref:
+
 Filter Warnings
 ===============
 

docs/source/transactions.rst

@@ -66,7 +66,7 @@ Auto-commit transactions are also the only way to run ``PERIODIC COMMIT`` statem
 
     def create_person(driver, name):
         with driver.session() as session:
-            return session.run("CREATE (a:Person {name:$name}) "
+            return session.run("CREATE (a:Person { name: $name }) "
                                "RETURN id(a)", name=name).single().value()
 
 Explicit Transactions
@@ -119,7 +119,7 @@ Returning a live result object would prevent the driver from correctly managing
 .. code-block:: python
 
     def create_person(tx, name):
-        return tx.run("CREATE (a:Person {name:$name}) "
+        return tx.run("CREATE (a:Person { name: $name }) "
                       "RETURN id(a)", name=name).single().value()
 
     with driver.session() as session:

neo4j/work/result.py

@@ -232,7 +232,35 @@ def keys(self):
         return self._keys
 
     def consume(self):
-        """Consume the remainder of this result and return a ResultSummary.
+        """Consume the remainder of this result and return a :class:`neo4j.ResultSummary`.
+
+        Example::
+
+            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
+
+            with driver.session() as session:
+                node_id, info = session.write_transaction(create_node_tx, "example")
+
+        Example::
+
+            def get_two_tx(tx):
+                result = tx.run("UNWIND [1,2,3,4] AS x RETURN x")
+                values = []
+                for ix, record in enumerate(result):
+                    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
+
+            with driver.session() as session:
+                values, info = session.read_transaction(get_two_tx)
 
         :returns: The :class:`neo4j.ResultSummary` for this result
         """

neo4j/work/simple.py

@@ -59,7 +59,7 @@ class Session(Workspace):
     context. For example::
 
         with driver.session() as session:
-            result = session.run("MATCH (a:Person) RETURN a.name")
+            result = session.run("MATCH (n:Person) RETURN n.name AS name")
             # do something with the result...
 
     :param pool: connection pool instance
@@ -344,12 +344,31 @@ def read_transaction(self, transaction_function, *args, **kwargs):
 
         Example::
 
-            def do_cypher(tx, cypher):
+            def do_cypher_tx(tx, cypher):
                 result = tx.run(cypher)
-                result.consume()
-                return 1
+                values = []
+                for record in result:
+                    values.append(record.values())
+                return values
 
-            value = session.read_transaction(do_cypher, "RETURN 1")
+            with driver.session() as session:
+                values = session.read_transaction(do_cypher_tx, "RETURN 1 AS x")
+
+        Example::
+
+            def get_two_tx(tx):
+                result = tx.run("UNWIND [1,2,3,4] AS x RETURN x")
+                values = []
+                for ix, record in enumerate(result):
+                    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
+
+            with driver.session() as session:
+                values = session.read_transaction(get_two_tx)
 
         :param transaction_function: a function that takes a transaction as an argument and does work with the transaction. `tx_function(tx, \*args, \*\*kwargs)`
         :param args: arguments for the `transaction_function`
@@ -367,12 +386,14 @@ def write_transaction(self, transaction_function, *args, **kwargs):
 
         Example::
 
-            def do_cypher(tx, cypher):
-                result = tx.run(cypher)
-                result.consume()
-                return 1
+            def create_node_tx(tx, name):
+                result = tx.run("CREATE (n:NodeExample { name: $name }) RETURN id(n) AS node_id", name=name)
+                record = result.single()
+                return record["node_id"]
+
+            with driver.session() as session:
+                node_id = session.write_transaction(create_node_tx, "example")
 
-            value = session.write_transaction(do_cypher, "RETURN 1")
 
         :param transaction_function: a function that takes a transaction as an argument and does work with the transaction. `tx_function(tx, \*args, \*\*kwargs)`
         :param args: key word arguments for the `transaction_function`
@@ -408,8 +429,10 @@ def unit_of_work(metadata=None, timeout=None):
     For example, a timeout may be applied::
 
         @unit_of_work(timeout=100)
-        def count_people(tx):
-            return tx.run("MATCH (a:Person) RETURN count(a)").single().value()
+        def count_people_tx(tx):
+            result = tx.run("MATCH (a:Person) RETURN count(a) AS persons")
+            record = result.single()
+            return record["persons"]
 
     :param metadata:
         a dictionary with metadata.

neo4j/work/transaction.py

@@ -82,10 +82,10 @@ def run(self, query, parameters=None, **kwparameters):
         arguments, or as a mixture of both. For example, the `run`
         queries below are all equivalent::
 
-            >>> query = "CREATE (a:Person {name:{name}, age:{age}})"
-            >>> tx.run(query, {"name": "Alice", "age": 33})
-            >>> tx.run(query, {"name": "Alice"}, age=33)
-            >>> tx.run(query, name="Alice", age=33)
+            >>> query = "CREATE (a:Person { name: $name, age: $age })"
+            >>> result = tx.run(query, {"name": "Alice", "age": 33})
+            >>> result = tx.run(query, {"name": "Alice"}, age=33)
+            >>> result = tx.run(query, name="Alice", age=33)
 
         Parameter values can be of any type supported by the Neo4j type
         system. In Python, this includes :class:`bool`, :class:`int`,