Refactor RequestsHttpTransport Class (#63)

Also improve test coverage and doc strings.

Author: KingDarBoja

README.md

@@ -34,11 +34,14 @@ The example below shows how you can execute queries against a local schema.
 ```python
 from gql import gql, Client
 
-client = Client(schema=schema)
+from .someSchema import SampleSchema
+
+
+client = Client(schema=SampleSchema)
 query = gql('''
-{
-  hello
-}
+    {
+      hello
+    }
 ''')
 
 client.execute(query)
@@ -50,12 +53,69 @@ If you want to add additional headers when executing the query, you can specify
 from gql import Client
 from gql.transport.requests import RequestsHTTPTransport
 
+from .someSchema import SampleSchema
+
 client = Client(transport=RequestsHTTPTransport(
-     url='/graphql', headers={'Authorization': 'token'}), schema=schema)
+     url='/graphql', headers={'Authorization': 'token'}), schema=SampleSchema)
+```
+
+To execute against a graphQL API. (We get the schema by using introspection).
+
+```python
+from gql import gql, Client
+from gql.transport.requests import RequestsHTTPTransport
+
+sample_transport=RequestsHTTPTransport(
+    url='https://countries.trevorblades.com/',
+    use_json=True,
+    headers={
+        "Content-type": "application/json",
+    },
+    verify=False
+)
+
+client = Client(
+    retries=3,
+    transport=sample_transport,
+    fetch_schema_from_transport=True,
+)
+
+query = gql('''
+    query getContinents {
+      continents {
+        code
+        name
+      }
+    }
+''')
+
+client.execute(query)
 ```
 
+If you have a local schema stored as a `schema.graphql` file, you can do:
+
+```python
+from graphql import build_ast_schema, parse
+from gql import gql, Client
+
+with open('path/to/schema.graphql') as source:
+    document = parse(source.read())
+
+schema = build_ast_schema(document)
+
+client = Client(schema=schema)
+query = gql('''
+    {
+      hello
+    }
+''')
+
+client.execute(query)
+```
+
+
 ## Contributing
-See [CONTRIBUTING.md](contributing.md)
+See [CONTRIBUTING.md](CONTRIBUTING.md)
 
 ## License
 

gql/transport/__init__.py

@@ -0,0 +1,20 @@
+import abc
+from typing import Union
+
+import six
+from graphql.execution import ExecutionResult
+from graphql.language.ast import Node, Document
+from promise import Promise
+
+
+@six.add_metaclass(abc.ABCMeta)
+class Transport:
+    @abc.abstractmethod
+    def execute(self, document):
+        # type: (Union[Node, Document]) -> Union[ExecutionResult, Promise[ExecutionResult]]
+        """Execute the provided document AST for either a remote or local GraphQL Schema.
+
+        :param document: GraphQL query as AST Node or Document object.
+        :return: Either ExecutionResult or a Promise that resolves to ExecutionResult object.
+        """
+        raise NotImplementedError("Any Transport subclass must implement execute method")

gql/transport/http.py

@@ -1,12 +1,34 @@
-from graphql.execution import execute
+from typing import Union, Any
 
+from graphql import GraphQLSchema
+from graphql.execution import execute, ExecutionResult
+from graphql.language.ast import Document
+from promise import Promise
 
-class LocalSchemaTransport(object):
+from gql.transport import Transport
 
-    def __init__(self, schema):
+
+class LocalSchemaTransport(Transport):
+    """A transport for executing GraphQL queries against a local schema."""
+    def __init__(
+        self,  # type: LocalSchemaTransport
+        schema  # type: GraphQLSchema
+    ):
+        """Initialize the transport with the given local schema.
+
+        :param schema: Local schema as GraphQLSchema object
+        """
         self.schema = schema
 
     def execute(self, document, *args, **kwargs):
+        # type: (Document, Any, Any) -> Union[ExecutionResult, Promise[ExecutionResult]]
+        """Execute the given document against the configured local schema.
+
+        :param document: GraphQL query as AST Node object.
+        :param args: Positional options for execute method from graphql-core library.
+        :param kwargs: Keyword options passed to execute method from graphql-core library.
+        :return: Either ExecutionResult or a Promise that resolves to ExecutionResult object.
+        """
         return execute(
             self.schema,
             document,

gql/transport/local_schema.py

@@ -1,26 +1,70 @@
 from __future__ import absolute_import
 
+from typing import Any, Dict, Union
+
 import requests
 from graphql.execution import ExecutionResult
+from graphql.language.ast import Node
 from graphql.language.printer import print_ast
+from requests.auth import AuthBase
+from requests.cookies import RequestsCookieJar
 
-from .http import HTTPTransport
+from gql.transport import Transport
 
 
-class RequestsHTTPTransport(HTTPTransport):
-    def __init__(self, url, auth=None, use_json=False, timeout=None, **kwargs):
-        """
-        :param url: The GraphQL URL
-        :param auth: Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth
-        :param use_json: Send request body as JSON instead of form-urlencoded
-        :param timeout: Specifies a default timeout for requests (Default: None)
+class RequestsHTTPTransport(Transport):
+    """Transport to execute GraphQL queries on remote servers.
+
+    The transport uses the requests library to send HTTP POST requests.
+    """
+    def __init__(
+        self,  # type: RequestsHTTPTransport
+        url,  # type: str
+        headers=None,  # type: Dict[str, Any]
+        cookies=None,  # type: Union[Dict[str, Any], RequestsCookieJar]
+        auth=None,  # type: AuthBase
+        use_json=False,  # type: bool
+        timeout=None,  # type: int
+        verify=True,  # type: bool
+        **kwargs  # type: Any
+    ):
+        """Initialize the transport with the given request parameters.
+
+        :param url: The GraphQL server URL.
+        :param headers: Dictionary of HTTP Headers to send with the :class:`Request` (Default: None).
+        :param cookies: Dict or CookieJar object to send with the :class:`Request` (Default: None).
+        :param auth: Auth tuple or callable to enable Basic/Digest/Custom HTTP Auth (Default: None).
+        :param use_json: Send request body as JSON instead of form-urlencoded (Default: False).
+        :param timeout: Specifies a default timeout for requests (Default: None).
+        :param verify: Either a boolean, in which case it controls whether we verify
+            the server's TLS certificate, or a string, in which case it must be a path
+            to a CA bundle to use. (Default: True).
+        :param kwargs: Optional arguments that ``request`` takes. These can be seen at the :requests_: source code
+            or the official :docs_:
+
+        .. _requests: https://github.com/psf/requests/blob/master/requests/api.py
+        .. _docs: https://requests.readthedocs.io/en/master/
         """
-        super(RequestsHTTPTransport, self).__init__(url, **kwargs)
+        self.url = url
+        self.headers = headers
+        self.cookies = cookies
         self.auth = auth
-        self.default_timeout = timeout
         self.use_json = use_json
+        self.default_timeout = timeout
+        self.verify = verify
+        self.kwargs = kwargs
 
     def execute(self, document, variable_values=None, timeout=None):
+        # type: (Node, dict, int) -> ExecutionResult
+        """Execute the provided document AST against the configured remote server.
+        This uses the requests library to perform a HTTP POST request to the remote server.
+
+        :param document: GraphQL query as AST Node object.
+        :param variable_values: Dictionary of input parameters (Default: None).
+        :param timeout: Specifies a default timeout for requests (Default: None).
+        :return: The result of execution. `data` is the result of executing the query, `errors` is null if no errors
+            occurred, and is a non-empty array if an error occurred.
+        """
         query_str = print_ast(document)
         payload = {
             'query': query_str,
@@ -33,9 +77,13 @@ def execute(self, document, variable_values=None, timeout=None):
             'auth': self.auth,
             'cookies': self.cookies,
             'timeout': timeout or self.default_timeout,
+            'verify': self.verify,
             data_key: payload
         }
 
+        # Pass kwargs to requests post method
+        post_args.update(self.kwargs)
+
         response = requests.post(self.url, **post_args)
         try:
             result = response.json()

gql/transport/requests.py

@@ -0,0 +1,15 @@
+type User {
+    id: ID!
+    username: String
+    firstName: String
+    lastName: String
+    fullName: String
+}
+
+type Query {
+    user(id: ID!): User
+}
+
+schema {
+    query: Query
+}

tests/fixtures/graphql/sample.graphql

@@ -14,17 +14,17 @@ def ds():
 
 
 def test_invalid_field_on_type_query(ds):
-    with pytest.raises(KeyError) as excInfo:
+    with pytest.raises(KeyError) as exc_info:
         ds.Query.extras.select(
             ds.Character.name
         )
-    assert "Field extras does not exist in type Query." in str(excInfo.value)
+    assert "Field extras does not exist in type Query." in str(exc_info.value)
 
 
 def test_incompatible_query_field(ds):
-    with pytest.raises(Exception) as excInfo:
+    with pytest.raises(Exception) as exc_info:
         ds.query('hero')
-    assert "Received incompatible query field" in str(excInfo.value)
+    assert "Received incompatible query field" in str(exc_info.value)
 
 
 def test_hero_name_query(ds):

tests/starwars/test_dsl.py

@@ -343,12 +343,12 @@ def test_check_type_of_luke(client):
 
 def test_parse_error(client):
     result = None
-    with pytest.raises(Exception) as excinfo:
+    with pytest.raises(Exception) as exc_info:
         query = gql('''
             qeury
         ''')
         result = client.execute(query)
-    error = excinfo.value
+    error = exc_info.value
     formatted_error = format_error(error)
     assert formatted_error['locations'] == [{'column': 13, 'line': 2}]
     assert 'Syntax Error GraphQL request (2:13) Unexpected Name "qeury"' in formatted_error['message']

tests/starwars/test_query.py

@@ -77,9 +77,9 @@ def validation_errors(client, query):
 
 
 def test_incompatible_request_gql(client):
-    with pytest.raises(Exception) as excInfo:
+    with pytest.raises(Exception) as exc_info:
         gql(123)
-    assert "Received incompatible request" in str(excInfo.value)
+    assert "Received incompatible request" in str(exc_info.value)
 
 
 def test_nested_query_with_fragment(client):