Added single

Author: technige

neo4j/v1/exceptions.py

@@ -23,8 +23,6 @@ class ProtocolError(Exception):
     """ Raised when an unexpected or unsupported protocol event occurs.
     """
 
-    pass
-
 
 class CypherError(Exception):
     """ Raised when the Cypher engine returns an error to the client.
@@ -38,3 +36,8 @@ def __init__(self, data):
         for key, value in data.items():
             if not key.startswith("_"):
                 setattr(self, key, value)
+
+
+class ResultError(Exception):
+    """ Raised when an error occurs while consuming a result.
+    """

neo4j/v1/session.py

@@ -33,7 +33,7 @@ class which can be used to obtain `Driver` instances that are used for
 from .compat import integer, string, urlparse
 from .connection import connect, Response, RUN, PULL_ALL
 from .constants import ENCRYPTED_DEFAULT, TRUST_DEFAULT, TRUST_SIGNED_CERTIFICATES
-from .exceptions import CypherError
+from .exceptions import CypherError, ResultError
 from .ssl_compat import SSL_AVAILABLE, SSLContext, PROTOCOL_SSLv23, OP_NO_SSLv2, CERT_REQUIRED
 from .types import hydrated
 
@@ -256,6 +256,18 @@ def consume(self):
             self.connection = None
         return self._summary
 
+    def single(self):
+        """ Return the next record, failing if none or more than one remain.
+        """
+        records = list(self)
+        num_records = len(records)
+        if num_records == 0:
+            raise ResultError("No records found in stream")
+        elif num_records != 1:
+            raise ResultError("Multiple records found in stream")
+        else:
+            return records[0]
+
 
 class ResultSummary(object):
     """ A summary of execution returned with a :class:`.StatementResult` object.

test/test_session.py

@@ -26,7 +26,7 @@
 from mock import patch
 
 from neo4j.v1.constants import TRUST_ON_FIRST_USE
-from neo4j.v1.exceptions import CypherError
+from neo4j.v1.exceptions import CypherError, ResultError
 from neo4j.v1.session import GraphDatabase, basic_auth, Record, SSL_AVAILABLE
 from neo4j.v1.types import Node, Relationship, Path
 
@@ -575,3 +575,27 @@ def test_can_consume_result_after_session_with_error(self):
         tx.commit()
         session.close()
         assert [record[0] for record in result] == [1, 2, 3]
+
+    def test_single_with_exactly_one_record(self):
+        session = self.driver.session()
+        result = session.run("UNWIND range(1, 1) AS n RETURN n")
+        record = result.single()
+        assert list(record.values()) == [1]
+
+    def test_single_with_no_records(self):
+        session = self.driver.session()
+        result = session.run("CREATE ()")
+        with self.assertRaises(ResultError):
+            _ = 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()
+
+    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