Optional dependencies for transports (#158)

* Disallow importing transports directly from gql

Author: leszekhanusz

.github/workflows/tests.yml

@@ -35,6 +35,26 @@ jobs:
         env:
           TOXENV: ${{ matrix.toxenv }}
 
+  single_extra:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        dependency: ["aiohttp", "requests", "websockets"]
+
+    steps:
+      - uses: actions/checkout@v2
+      - name: Set up Python 3.8
+        uses: actions/setup-python@v2
+        with:
+          python-version: 3.8
+      - name: Install dependencies with only ${{ matrix.dependency }} extra dependency
+        run: |
+          python -m pip install --upgrade pip
+          pip install .[${{ matrix.dependency }},test_no_transport]
+      - name: Test with --${{ matrix.dependency }}-only
+        run: pytest tests --${{ matrix.dependency }}-only
+
   coverage:
     runs-on: ubuntu-latest
 

Makefile

@@ -1,5 +1,7 @@
 .PHONY: clean tests docs
 
+SRC_PYTHON := gql tests scripts/gql-cli docs/code_examples
+
 dev-setup:
 	python pip install -e ".[test]"
 
@@ -9,11 +11,20 @@ tests:
 all_tests:
 	pytest tests --cov=gql --cov-report=term-missing --run-online -vv
 
+tests_aiohttp:
+	pytest tests --aiohttp-only
+
+tests_requests:
+	pytest tests --requests-only
+
+tests_websockets:
+	pytest tests --websockets-only
+
 check:
-	isort --recursive gql tests scripts/gql-cli
-	black gql tests scripts/gql-cli
-	flake8 gql tests scripts/gql-cli
-	mypy gql tests scripts/gql-cli
+	isort --recursive $(SRC_PYTHON)
+	black $(SRC_PYTHON)
+	flake8 $(SRC_PYTHON)
+	mypy $(SRC_PYTHON)
 	check-manifest
 
 docs:

README.md

@@ -45,7 +45,9 @@ The main features of GQL are:
 
 > **WARNING**: Please note that the following documentation describes the current version which is currently only available as a pre-release and needs to be installed with
 
-    $ pip install --pre gql
+    $ pip install --pre gql[all]
+
+> **NOTE**: See also [the documentation](https://gql.readthedocs.io/en/latest/intro.html#less-dependencies) to install GQL with less extra dependencies
 
 ## Usage
 

docs/async/async_usage.rst

@@ -17,7 +17,7 @@ Example:
 IPython
 -------
 
-.. Attention::
+.. warning::
 
     On some Python environments, like :emphasis:`Jupyter` or :emphasis:`Spyder`,
     which are using :emphasis:`IPython`,

docs/code_examples/aiohttp_async.py

@@ -1,28 +1,33 @@
-from gql import gql, AIOHTTPTransport, Client
 import asyncio
 
+from gql import Client, gql
+from gql.transport.aiohttp import AIOHTTPTransport
+
+
 async def main():
 
-    transport = AIOHTTPTransport(url='https://countries.trevorblades.com/graphql')
+    transport = AIOHTTPTransport(url="https://countries.trevorblades.com/graphql")
 
     # Using `async with` on the client will start a connection on the transport
     # and provide a `session` variable to execute queries on this connection
     async with Client(
-        transport=transport,
-        fetch_schema_from_transport=True,
-        ) as session:
+        transport=transport, fetch_schema_from_transport=True,
+    ) as session:
 
         # Execute single query
-        query = gql('''
+        query = gql(
+            """
             query getContinents {
               continents {
                 code
                 name
               }
             }
-        ''')
+        """
+        )
 
         result = await session.execute(query)
         print(result)
 
+
 asyncio.run(main())

docs/code_examples/aiohttp_sync.py

@@ -1,4 +1,5 @@
-from gql import gql, Client, AIOHTTPTransport
+from gql import Client, gql
+from gql.transport.aiohttp import AIOHTTPTransport
 
 # Select your transport with a defined url endpoint
 transport = AIOHTTPTransport(url="https://countries.trevorblades.com/")

docs/code_examples/requests_sync.py

@@ -1,25 +1,22 @@
-from gql import gql, Client
+from gql import Client, gql
 from gql.transport.requests import RequestsHTTPTransport
 
-sample_transport=RequestsHTTPTransport(
-    url='https://countries.trevorblades.com/',
-    verify=True,
-    retries=3,
+sample_transport = RequestsHTTPTransport(
+    url="https://countries.trevorblades.com/", verify=True, retries=3,
 )
 
-client = Client(
-    transport=sample_transport,
-    fetch_schema_from_transport=True,
-)
+client = Client(transport=sample_transport, fetch_schema_from_transport=True,)
 
-query = gql('''
+query = gql(
+    """
     query getContinents {
       continents {
         code
         name
       }
     }
-''')
+"""
+)
 
 result = client.execute(query)
 print(result)

docs/code_examples/websockets_async.py

@@ -1,41 +1,48 @@
+import asyncio
 import logging
+
+from gql import Client, gql
+from gql.transport.websockets import WebsocketsTransport
+
 logging.basicConfig(level=logging.INFO)
 
-from gql import gql, Client, WebsocketsTransport
-import asyncio
 
 async def main():
 
-    transport = WebsocketsTransport(url='wss://countries.trevorblades.com/graphql')
+    transport = WebsocketsTransport(url="wss://countries.trevorblades.com/graphql")
 
     # Using `async with` on the client will start a connection on the transport
     # and provide a `session` variable to execute queries on this connection
     async with Client(
-        transport=transport,
-        fetch_schema_from_transport=True,
-        ) as session:
+        transport=transport, fetch_schema_from_transport=True,
+    ) as session:
 
         # Execute single query
-        query = gql('''
+        query = gql(
+            """
             query getContinents {
               continents {
                 code
                 name
               }
             }
-        ''')
+        """
+        )
         result = await session.execute(query)
         print(result)
 
         # Request subscription
-        subscription = gql('''
+        subscription = gql(
+            """
             subscription {
                 somethingChanged {
                     id
                 }
             }
-        ''')
+        """
+        )
         async for result in session.subscribe(subscription):
             print(result)
 
+
 asyncio.run(main())

docs/intro.rst

@@ -1,17 +1,18 @@
 Introduction
 ============
 
-`GQL 3`_ is a `GraphQL`_ Client for Python 3.6+ which plays nicely with other graphql implementations compatible with the spec.
+`GQL 3`_ is a `GraphQL`_ Client for Python 3.6+ which plays nicely with other
+graphql implementations compatible with the spec.
 
 Under the hood, it uses `GraphQL-core`_ which is a Python port of `GraphQL.js`_,
 the JavaScript reference implementation for GraphQL.
 
 Installation
 ------------
 
-You can install GQL 3 using pip_::
+You can install GQL 3 and all the extra dependencies using pip_::
 
-    pip install --pre gql
+    pip install --pre gql[all]
 
 .. warning::
 
@@ -21,6 +22,39 @@ You can install GQL 3 using pip_::
 After installation, you can start using GQL by importing from the top-level
 :mod:`gql` package.
 
+Less dependencies
+^^^^^^^^^^^^^^^^^
+
+GQL supports multiple :ref:`transports <transports>` to communicate with the backend.
+Each transport can each necessitate specific dependencies.
+If you only need one transport, instead of using the "`all`" extra dependency
+as described above which installs everything,
+you might want to install only the dependency needed for your transport.
+
+If for example you only need the :ref:`AIOHTTPTransport <aiohttp_transport>`,
+which needs the :code:`aiohttp` dependency, then you can install GQL with::
+
+    pip install --pre gql[aiohttp]
+
+The corresponding between extra dependencies required and the GQL transports is:
+
++-------------------+----------------------------------------------------------------+
+| Extra dependency  | Transports                                                     |
++===================+================================================================+
+| aiohttp           | :ref:`AIOHTTPTransport <aiohttp_transport>`                    |
++-------------------+----------------------------------------------------------------+
+| websockets        | :ref:`WebsocketsTransport <websockets_transport>`              |
+|                   |                                                                |
+|                   | :ref:`PhoenixChannelWebsocketsTransport <phoenix_transport>`   |
++-------------------+----------------------------------------------------------------+
+| requests          | :ref:`RequestsHTTPTransport <requests_transport>`              |
++-------------------+----------------------------------------------------------------+
+
+.. note::
+
+    It is also possible to install multiple extra dependencies if needed
+    using commas: :code:`gql[aiohttp,websockets]`
+
 Reporting Issues and Contributing
 ---------------------------------
 

docs/transports/phoenix.rst

@@ -1,3 +1,5 @@
+.. _phoenix_transport:
+
 PhoenixChannelWebsocketsTransport
 =================================