Documentation Adding error handling doc (#266)

Author: leszekhanusz

docs/advanced/error_handling.rst

@@ -0,0 +1,73 @@
+Error Handing
+=============
+
+Local errors
+------------
+
+If gql detects locally that something does not correspond to the GraphQL specification,
+then gql may raise a **GraphQLError** from graphql-core.
+
+This may happen for example:
+
+- if your query is not valid
+- if your query does not correspond to your schema
+- if the result received from the backend does not correspond to the schema
+  if :code:`parse_results` is set to True
+
+Transport errors
+----------------
+
+If an error happens with the transport, then gql may raise a
+:class:`TransportError <gql.transport.exceptions.TransportError>`
+
+Here are the possible Transport Errors:
+
+- :class:`TransportProtocolError <gql.transport.exceptions.TransportProtocolError>`:
+  Should never happen if the backend is a correctly configured GraphQL server.
+  It means that the answer received from the server does not correspond
+  to the transport protocol.
+
+- :class:`TransportServerError <gql.transport.exceptions.TransportServerError>`:
+  There was an error communicating with the server. If this error is received,
+  then the connection with the server will be closed. This may happen if the server
+  returned a 404 http header for example.
+  The http error code is available in the exception :code:`code` attribute.
+
+- :class:`TransportQueryError <gql.transport.exceptions.TransportQueryError>`:
+  There was a specific error returned from the server for your query.
+  The message you receive in this error has been created by the backend, not gql!
+  In that case, the connection to the server is still available and you are
+  free to try to send other queries using the same connection.
+  The message of the exception contains the first error returned by the backend.
+  All the errors messages are available in the exception :code:`errors` attribute.
+
+- :class:`TransportClosed <gql.transport.exceptions.TransportClosed>`:
+  This exception is generated when the client is trying to use the transport
+  while the transport was previously closed.
+
+- :class:`TransportAlreadyConnected <gql.transport.exceptions.TransportAlreadyConnected>`:
+  Exception generated when the client is trying to connect to the transport
+  while the transport is already connected.
+
+HTTP
+^^^^
+
+For HTTP transports, we should get a json response which contain
+:code:`data` or :code:`errors` fields.
+If that is not the case, then the returned error depends whether the http return code
+is below 400 or not.
+
+- json response:
+    - with data or errors keys:
+        - no errors key -> no exception
+        - errors key -> raise **TransportQueryError**
+    - no data or errors keys:
+        - http code < 400:
+          raise **TransportProtocolError**
+        - http code >= 400:
+          raise **TransportServerError**
+- not a json response:
+    - http code < 400:
+      raise **TransportProtocolError**
+    - http code >= 400:
+      raise **TransportServerError**

docs/advanced/index.rst

@@ -6,5 +6,6 @@ Advanced
 
    async_advanced_usage
    logging
+   error_handling
    local_schema
    dsl_module

docs/modules/gql.rst

@@ -20,5 +20,6 @@ Sub-Packages
 
    client
    transport
+   transport_exceptions
    dsl
    utilities

docs/modules/transport_exceptions.rst

@@ -0,0 +1,7 @@
+gql.transport.exceptions
+========================
+
+.. currentmodule:: gql.transport.exceptions
+
+.. automodule:: gql.transport.exceptions
+    :member-order: bysource

gql/transport/exceptions.py

@@ -2,6 +2,8 @@
 
 
 class TransportError(Exception):
+    """Base class for all the Transport exceptions"""
+
     pass
 
 
@@ -18,7 +20,9 @@ class TransportServerError(TransportError):
     This exception will close the transport connection.
     """
 
-    def __init__(self, message=None, code=None):
+    code: Optional[int]
+
+    def __init__(self, message: str, code: Optional[int] = None):
         super(TransportServerError, self).__init__(message)
         self.code = code
 
@@ -29,6 +33,11 @@ class TransportQueryError(Exception):
     This exception should not close the transport connection.
     """
 
+    query_id: Optional[int]
+    errors: Optional[List[Any]]
+    data: Optional[Any]
+    extensions: Optional[Any]
+
     def __init__(
         self,
         msg: str,