Added peek

Author: technige

neo4j/v1/session.py

@@ -268,6 +268,20 @@ def single(self):
         else:
             return records[0]
 
+    def peek(self):
+        """ Return the next record without advancing the cursor. Fails
+        if no records remain.
+        """
+        if self._buffer:
+            values = self._buffer[0]
+            return Record(self.keys(), tuple(map(hydrated, values)))
+        while not self._buffer and not self._consumed:
+            self.connection.fetch()
+            if self._buffer:
+                values = self._buffer[0]
+                return Record(self.keys(), tuple(map(hydrated, values)))
+        raise ResultError("End of stream")
+
 
 class ResultSummary(object):
     """ A summary of execution returned with a :class:`.StatementResult` object.

test/test_session.py

@@ -586,16 +586,56 @@ def test_single_with_no_records(self):
         session = self.driver.session()
         result = session.run("CREATE ()")
         with self.assertRaises(ResultError):
-            _ = result.single()
+            result.single()
 
     def test_single_with_multiple_records(self):
         session = self.driver.session()
         result = session.run("UNWIND range(1, 3) AS n RETURN n")
         with self.assertRaises(ResultError):
-            _ = result.single()
+            result.single()
 
     def test_single_consumes_entire_result(self):
         session = self.driver.session()
         result = session.run("UNWIND range(1, 1) AS n RETURN n")
         _ = result.single()
         assert result._consumed
+
+    def test_peek_can_look_one_ahead(self):
+        session = self.driver.session()
+        result = session.run("UNWIND range(1, 3) AS n RETURN n")
+        record = result.peek()
+        assert list(record.values()) == [1]
+
+    def test_peek_fails_if_nothing_remains(self):
+        session = self.driver.session()
+        result = session.run("CREATE ()")
+        with self.assertRaises(ResultError):
+            result.peek()
+
+    def test_peek_does_not_advance_cursor(self):
+        session = self.driver.session()
+        result = session.run("UNWIND range(1, 3) AS n RETURN n")
+        result.peek()
+        assert [record[0] for record in result] == [1, 2, 3]
+
+    def test_peek_at_different_stages(self):
+        session = self.driver.session()
+        result = session.run("UNWIND range(0, 9) AS n RETURN n")
+        # Peek ahead to the first record
+        expected_next = 0
+        upcoming = result.peek()
+        assert upcoming[0] == expected_next
+        # Then look through all the other records
+        for expected, record in enumerate(result):
+            # Check this record is as expected
+            assert record[0] == expected
+            # Check the upcoming record is as expected...
+            if expected < 9:
+                # ...when one should follow
+                expected_next = expected + 1
+                upcoming = result.peek()
+                assert upcoming[0] == expected_next
+            else:
+                # ...when none should follow
+                with self.assertRaises(ResultError):
+                    result.peek()