Merge pull request #44 from neo4j/1.0-consume

1.0 consume

Author: pontusmelke

examples/test_examples.py

@@ -98,7 +98,7 @@ def test_statement(self):
         # tag::statement[]
         result = session.run("CREATE (person:Person {name: {name}})", {"name": "Arthur"})
         # end::statement[]
-        result.discard()
+        result.consume()
         session.close()
 
     def test_statement_without_parameters(self):
@@ -107,7 +107,7 @@ def test_statement_without_parameters(self):
         # tag::statement-without-parameters[]
         result = session.run("CREATE (person:Person {name: 'Arthur'})")
         # end::statement-without-parameters[]
-        result.discard()
+        result.consume()
         session.close()
 
     def test_result_traversal(self):
@@ -181,9 +181,9 @@ def test_result_summary_query_profile(self):
         # tag::result-summary-query-profile[]
         result = session.run("PROFILE MATCH (p:Person {name: {name}}) "
                              "RETURN id(p)", {"name": "Arthur"})
-        list(result)  # skip the records to get to the summary
-        print(result.summary.statement_type)
-        print(result.summary.profile)
+        summary = result.consume()
+        print(summary.statement_type)
+        print(summary.profile)
         # end::result-summary-query-profile[]
         session.close()
 
@@ -192,8 +192,8 @@ def test_result_summary_notifications(self):
         session = driver.session()
         # tag::result-summary-notifications[]
         result = session.run("EXPLAIN MATCH (king), (queen) RETURN king, queen")
-        list(result)  # skip the records to get to the summary
-        for notification in result.summary.notifications:
+        summary = result.consume()
+        for notification in summary.notifications:
             print(notification)
         # end::result-summary-notifications[]
         session.close()

neo4j/v1/session.py

@@ -158,10 +158,6 @@ class StatementResult(object):
     #: Dictionary of parameters passed with the statement.
     parameters = None
 
-    #: The result summary (only available after the result has
-    #: been fully consumed)
-    summary = None
-
     def __init__(self, connection, run_response, pull_all_response):
         super(StatementResult, self).__init__()
 
@@ -176,6 +172,10 @@ def __init__(self, connection, run_response, pull_all_response):
         # the result is used immediately, this buffer will be ignored.
         self._buffer = deque()
 
+        # The result summary (populated after the records have been
+        # fully consumed).
+        self._summary = None
+
         # Flag to indicate whether the entire stream has been consumed
         # from the network (but not necessarily yielded).
         self._consumed = False
@@ -190,7 +190,7 @@ def on_record(values):
 
         def on_footer(metadata):
             # Called on receipt of the result footer.
-            self.summary = ResultSummary(self.statement, self.parameters, **metadata)
+            self._summary = ResultSummary(self.statement, self.parameters, **metadata)
             self._consumed = True
 
         def on_failure(metadata):
@@ -215,8 +215,9 @@ def __next__(self):
         elif self._consumed:
             raise StopIteration()
         else:
+            fetch = self.connection.fetch
             while not self._buffer and not self._consumed:
-                self.connection.fetch()
+                fetch()
             return self.__next__()
 
     def keys(self):
@@ -227,15 +228,16 @@ def keys(self):
             self.connection.fetch()
         return self._keys
 
-    def discard(self):
-        """ Consume the remainder of this result and detach the connection
-        from this result.
+    def consume(self):
+        """ Consume the remainder of this result and return the
+        summary.
         """
         if self.connection and not self.connection.closed:
             fetch = self.connection.fetch
             while not self._consumed:
                 fetch()
             self.connection = None
+        return self._summary
 
 
 class ResultSummary(object):
@@ -270,7 +272,7 @@ def __init__(self, statement, parameters, **metadata):
         self.statement = statement
         self.parameters = parameters
         self.statement_type = metadata.get("type")
-        self.counters = Counters(metadata.get("stats", {}))
+        self.counters = SummaryCounters(metadata.get("stats", {}))
         if "plan" in metadata:
             self.plan = make_plan(metadata["plan"])
         if "profile" in metadata:
@@ -285,13 +287,10 @@ def __init__(self, statement, parameters, **metadata):
                                                    notification["description"], notification["severity"], position))
 
 
-class Counters(object):
+class SummaryCounters(object):
     """ Set of statistics from a Cypher statement execution.
     """
 
-    #:
-    contains_updates = False
-
     #:
     nodes_created = 0
 
@@ -333,6 +332,14 @@ def __init__(self, statistics):
     def __repr__(self):
         return repr(vars(self))
 
+    @property
+    def contains_updates(self):
+        return self.nodes_created or self.nodes_deleted or \
+               self.relationships_created or self.relationships_deleted or \
+               self.properties_set or self.labels_added or self.labels_removed or \
+               self.indexes_added or self.indexes_removed or \
+               self.constraints_added or self.constraints_removed
+
 
 #: A plan describes how the database will execute your statement.
 #:
@@ -473,7 +480,7 @@ def close(self):
         """ Recycle this session through the driver it came from.
         """
         if self.last_result:
-            self.last_result.discard()
+            self.last_result.consume()
         self.driver.recycle(self)
 
     def begin_transaction(self):

neokit

@@ -156,12 +156,12 @@ def test_can_run_simple_statement_with_params(self):
     def test_fails_on_bad_syntax(self):
         session = GraphDatabase.driver("bolt://localhost", auth=auth_token).session()
         with self.assertRaises(CypherError):
-            session.run("X").discard()
+            session.run("X").consume()
 
     def test_fails_on_missing_parameter(self):
         session = GraphDatabase.driver("bolt://localhost", auth=auth_token).session()
         with self.assertRaises(CypherError):
-            session.run("RETURN {x}").discard()
+            session.run("RETURN {x}").consume()
 
     def test_can_run_simple_statement_from_bytes_string(self):
         session = GraphDatabase.driver("bolt://localhost", auth=auth_token).session()
@@ -227,7 +227,7 @@ def test_can_return_path(self):
     def test_can_handle_cypher_error(self):
         with GraphDatabase.driver("bolt://localhost", auth=auth_token).session() as session:
             with self.assertRaises(CypherError):
-                session.run("X").discard()
+                session.run("X").consume()
 
     def test_keys_are_available_before_and_after_stream(self):
         with GraphDatabase.driver("bolt://localhost", auth=auth_token).session() as session:
@@ -248,30 +248,24 @@ class SummaryTestCase(ServerTestCase):
     def test_can_obtain_summary_after_consuming_result(self):
         with GraphDatabase.driver("bolt://localhost", auth=auth_token).session() as session:
             result = session.run("CREATE (n) RETURN n")
-            list(result)
-            summary = result.summary
+            summary = result.consume()
             assert summary.statement == "CREATE (n) RETURN n"
             assert summary.parameters == {}
             assert summary.statement_type == "rw"
             assert summary.counters.nodes_created == 1
 
-    def test_cannot_obtain_summary_without_consuming_result(self):
-        with GraphDatabase.driver("bolt://localhost", auth=auth_token).session() as session:
-            result = session.run("CREATE (n) RETURN n")
-            assert result.summary is None
-
     def test_no_plan_info(self):
         with GraphDatabase.driver("bolt://localhost", auth=auth_token).session() as session:
             result = session.run("CREATE (n) RETURN n")
-            list(result)  # consume the result
-            assert result.summary.plan is None
-            assert result.summary.profile is None
+            summary = result.consume()
+            assert summary.plan is None
+            assert summary.profile is None
 
     def test_can_obtain_plan_info(self):
         with GraphDatabase.driver("bolt://localhost", auth=auth_token).session() as session:
             result = session.run("EXPLAIN CREATE (n) RETURN n")
-            list(result)  # consume the result
-            plan = result.summary.plan
+            summary = result.consume()
+            plan = summary.plan
             assert plan.operator_type == "ProduceResults"
             assert plan.identifiers == ["n"]
             assert plan.arguments == {"planner": "COST", "EstimatedRows": 1.0, "version": "CYPHER 3.0",
@@ -282,8 +276,8 @@ def test_can_obtain_plan_info(self):
     def test_can_obtain_profile_info(self):
         with GraphDatabase.driver("bolt://localhost", auth=auth_token).session() as session:
             result = session.run("PROFILE CREATE (n) RETURN n")
-            list(result)  # consume the result
-            profile = result.summary.profile
+            summary = result.consume()
+            profile = summary.profile
             assert profile.db_hits == 0
             assert profile.rows == 1
             assert profile.operator_type == "ProduceResults"
@@ -296,19 +290,19 @@ def test_can_obtain_profile_info(self):
     def test_no_notification_info(self):
         with GraphDatabase.driver("bolt://localhost", auth=auth_token).session() as session:
             result = session.run("CREATE (n) RETURN n")
-            list(result)  # consume the result
-            notifications = result.summary.notifications
+            summary = result.consume()
+            notifications = summary.notifications
             assert notifications == []
 
     def test_can_obtain_notification_info(self):
         with GraphDatabase.driver("bolt://localhost", auth=auth_token).session() as session:
             result = session.run("EXPLAIN MATCH (n), (m) RETURN n, m")
-            list(result)  # consume the result
-            notifications = result.summary.notifications
+            summary = result.consume()
+            notifications = summary.notifications
 
             assert len(notifications) == 1
             notification = notifications[0]
-            assert notification.code == "Neo.ClientNotification.Statement.CartesianProduct"
+            assert notification.code == "Neo.ClientNotification.Statement.CartesianProductWarning"
             assert notification.title == "This query builds a cartesian product between " \
                                          "disconnected patterns."
             assert notification.severity == "WARNING"
@@ -333,7 +327,7 @@ class ResetTestCase(ServerTestCase):
     def test_automatic_reset_after_failure(self):
         with GraphDatabase.driver("bolt://localhost", auth=auth_token).session() as session:
             try:
-                session.run("X").discard()
+                session.run("X").consume()
             except CypherError:
                 result = session.run("RETURN 1")
                 record = next(result)
@@ -347,7 +341,7 @@ def test_defunct(self):
             assert not session.connection.defunct
             with patch.object(ChunkChannel, "chunk_reader", side_effect=ProtocolError()):
                 with self.assertRaises(ProtocolError):
-                    session.run("RETURN 1").discard()
+                    session.run("RETURN 1").consume()
             assert session.connection.defunct
             assert session.connection.closed