4.0 exception hierarchy (#350)

* Changed CypherError to Neo4jError

* Removed unused error.

* Neo4jAvailabilityError renamed to BoltNeo4jAvailabilityError

* Removed NotALeader and use NotALeaderError

* Removed ForbiddenOnReadOnlyDatabase

Using ForbiddenOnReadOnlyDatabaseError instead

* Divided Driver API Errors and Connector API Errors

The Driver API Errors can be found in exceptions.py
The Connector API Errors can be found in errors.py

* Added DriverError Group

SessionExpired(DriverError)
TransactionError(DriverError)
ServiceUnavailable(DriverError)

* SecurityError is replaced by BoltSecurityError

Driver API ClientErrors does not inherit SecurityError and SecurityError
is removed from the Driver API Errors.

* IncompleteCommitError is replaced with BoltIncompleteCommitError

* ProtocolError is replaced with BoltProtocolError

* Removed BoltNeo4jAvailabilityError

Added ServiceUnavailable errors that replace BoltNeo4jAvailabilityError
errors.

from neo4j.exceptions import (
    RoutingServiceUnavailable,
    ReadServiceUnavailable,
    WriteServiceUnavailable,
)

* Added docs info about internal driver errors

It's important to leave a note in here as a catch-all.
If users see an internal error, in particular a protocol error, they should open an issue.

* Renamed errors.py to _exceptions.py

The BoltError are internal errors that the user should never experience.

* Changed NotALeaderError to NotALeader

To align with the naming of the status code

Neo.ClientError.Cluster.NotALeader

* Renamed DatabaseUnavailableError to DatabaseUnavailable

This is to align with the naming of status code:

Neo.TransientError.General.DatabaseUnavailable

* Renamed ForbiddenOnReadOnlyDatabaseError to ForbiddenOnReadOnlyDatabase

This is to align with the status code:

Neo.ClientError.General.ForbiddenOnReadOnlyDatabase

Author: martin-neotech

docs/source/errors.rst

@@ -11,20 +11,16 @@ Connectivity errors
     Raised when a database server or service is not available.
     This may be due to incorrect configuration or could indicate a runtime failure of a database service that the driver is unable to route around.
 
-.. class:: neo4j.exceptions.SecurityError
 
-    Raised when a security issue occurs, generally around TLS or authentication.
-
-
-Cypher execution errors
+Neo4j execution errors
 =======================
 
-.. class:: neo4j.exceptions.CypherError
+.. class:: neo4j.exceptions.Neo4jError
 
     Raised when the Cypher engine returns an error to the client.
-    There are many possible types of Cypher error, each identified by a unique `status code <https://neo4j.com/docs/developer-manual/current/reference/status-codes/>`_.
+    There are many possible types of Cypher error, each identified by a unique `status code <https://neo4j.com/docs/status-codes/current/>`_.
 
-    The three classifications of status code are supported by the three subclasses of :class:`.CypherError`, listed below:
+    The three classifications of status code are supported by the three subclasses of :class:`.Neo4jError`, listed below:
 
 .. autoclass:: neo4j.exceptions.ClientError
 
@@ -33,11 +29,18 @@ Cypher execution errors
 .. autoclass:: neo4j.exceptions.TransientError
 
 
-Low-level errors
-================
+Internal Driver Errors
+=======================
+
+If users see an internal error, in particular a protocol error (BoltError*), they should open an issue on github.
+
+https://github.com/neo4j/neo4j-python-driver/issues
+
+Please provide details about your running environment,
 
-.. class:: neo4j.exceptions.ProtocolError
+Operating System:
+Python Version:
+Python Driver Version:
+Neo4j Version:
 
-    Raised when an unexpected or unsupported protocol event occurs.
-    This error generally indicates a fault with the driver or server software.
-    If you receive this error, please raise a GitHub issue or a support ticket.
+the code block with a description that produced the error and the error message.

neo4j/errors.py neo4j/_exceptions.pyneo4j/errors.py renamed to neo4j/_exceptions.py

@@ -168,53 +168,14 @@ def transaction(self):
             return None
 
 
-class ClientError(BoltFailure):
+class BoltIncompleteCommitError(BoltError):
+    """ Raised when a disconnection occurs while still waiting for a commit
+    response. For non-idempotent write transactions, this leaves the data
+    in an unknown state with regard to whether the transaction completed
+    successfully or not.
     """
-    """
-
-    transient = False
-
-
-class NotALeader(ClientError):
-    """
-    """
-
-    code = "Neo.ClientError.Cluster.NotALeader"
 
 
-class ForbiddenOnReadOnlyDatabase(ClientError):
-    """
-    """
-
-    code = "Neo.ClientError.General.ForbiddenOnReadOnlyDatabase"
-
-
-class DatabaseError(BoltFailure):
-    """
-    """
-
-    transient = False
-
-
-class TransientError(BoltFailure):
-    """
-    """
-
-    transient = True
-
-
-class Neo4jError(Exception):
-    """ Base class for all Neo4j service exceptions.
-    """
-
-
-class Neo4jAvailabilityError(Neo4jError):
-    """ Raised when a Neo4j service is partially or completely
-    unavailable.
-    """
-
-
-class Neo4jCompatibilityError(Neo4jError):
-    """ Raised when expected functionality is not supported or
-    available.
-    """
+class BoltProtocolError(BoltError):
+    """ Raised when an unexpected or unsupported protocol event occurs.
+    """

neo4j/aio/__init__.py

@@ -62,13 +62,17 @@
 from neo4j.addressing import Address
 from neo4j.aio._collections import WaitingList
 from neo4j.aio._mixins import Addressable, Breakable
-from neo4j.errors import (
+from neo4j._exceptions import (
     BoltError,
     BoltConnectionError,
     BoltSecurityError,
     BoltConnectionBroken,
     BoltHandshakeError,
-    Neo4jAvailabilityError,
+)
+from neo4j.exceptions import (
+    RoutingServiceUnavailable,
+    ReadServiceUnavailable,
+    WriteServiceUnavailable,
 )
 from neo4j.api import Version
 from neo4j.conf import PoolConfig
@@ -398,7 +402,7 @@ async def get_routing_table(self, context=None):
         :return: a new RoutingTable instance or None if the given router is
                  currently unable to provide routing information
         :raise ServiceUnavailable: if no writers are available
-        :raise ProtocolError: if the routing information received is unusable
+        :raise BoltProtocolError: if the routing information received is unusable
         """
 
 
@@ -817,7 +821,7 @@ async def _get_routing_table(self):
 
         # None of the routers have been successful, so just fail
         log.error("Unable to retrieve routing information")
-        raise Neo4jAvailabilityError("Unable to retrieve routing information")
+        raise RoutingServiceUnavailable("Unable to retrieve routing information")
 
     async def _ensure_routing_table_is_fresh(self, readonly=False):
         """ Update the routing table if stale.
@@ -855,8 +859,10 @@ async def _select_pool(self, readonly=False):
         for pool in pools:
             pools_by_usage.setdefault(pool.in_use, []).append(pool)
         if not pools_by_usage:
-            raise Neo4jAvailabilityError("No {} service currently "
-                                         "available".format("read" if readonly else "write"))
+            if readonly:
+                raise ReadServiceUnavailable("No read service currently available")
+            else:
+                raise WriteServiceUnavailable("No write service currently available")
         return choice(pools_by_usage[min(pools_by_usage)])
 
     async def acquire(self, *, readonly=False, force_reset=False):
@@ -878,10 +884,7 @@ async def acquire(self, *, readonly=False, force_reset=False):
                     # readonly, then intercept NotALeader and
                     # ForbiddenOnReadOnlyDatabase errors to
                     # invalidate the routing table.
-                    from neo4j.errors import (
-                        NotALeader,
-                        ForbiddenOnReadOnlyDatabase,
-                    )
+                    from neo4j.exceptions import ForbiddenOnReadOnlyDatabaseError, NotALeaderError
 
                     def handler(failure):
                         """ Invalidate the routing table before raising the failure.
@@ -890,8 +893,8 @@ def handler(failure):
                         self._routing_table.ttl = 0
                         raise failure
 
-                    cx.set_failure_handler(NotALeader, handler)
-                    cx.set_failure_handler(ForbiddenOnReadOnlyDatabase, handler)
+                    cx.set_failure_handler(NotALeaderError, handler)
+                    cx.set_failure_handler(ForbiddenOnReadOnlyDatabaseError, handler)
                 return cx
 
     async def release(self, connection, *, force_reset=False):
@@ -905,12 +908,9 @@ async def release(self, connection, *, force_reset=False):
                 pass
             else:
                 # Unhook any custom error handling and exit.
-                from neo4j.errors import (
-                    NotALeader,
-                    ForbiddenOnReadOnlyDatabase,
-                )
-                connection.del_failure_handler(NotALeader)
-                connection.del_failure_handler(ForbiddenOnReadOnlyDatabase)
+                from neo4j.exceptions import ForbiddenOnReadOnlyDatabaseError, NotALeaderError
+                connection.del_failure_handler(NotALeaderError)
+                connection.del_failure_handler(ForbiddenOnReadOnlyDatabaseError)
                 break
         else:
             raise ValueError("Connection does not belong to this pool")

neo4j/aio/_bolt3.py

@@ -28,14 +28,15 @@
 from neo4j.aio._mixins import Addressable
 from neo4j.api import Bookmark, Version
 from neo4j.data import Record
-from neo4j.errors import (
+from neo4j._exceptions import (
     BoltError,
     BoltFailure,
     BoltConnectionBroken,
     BoltConnectionClosed,
     BoltTransactionError,
     BoltRoutingError,
 )
+from neo4j.exceptions import Neo4jError
 from neo4j.packstream import PackStream, Structure
 from neo4j.routing import RoutingTable
 
@@ -612,7 +613,9 @@ def fail(self, failure):
             # TODO: fix "requires two params, only one was given" error
             handler(failure)
         else:
-            raise failure
+            # TODO: fix correct error logic after error and exception refactoring
+            # raise failure  # This is a BoltFailure
+            raise Neo4jError.hydrate(message=str(failure), code=failure.code)
 
     def get_failure_handler(self, cls):
         return self._failure_handlers.get(cls)