Merge branch 'master' into fix_aiohttp_wait_for_closed_connections

Author: leszekhanusz

.github/workflows/tests.yml

@@ -8,15 +8,15 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9-dev", "pypy3"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "pypy3"]
         os: [ubuntu-latest, windows-latest]
         exclude:
           - os: windows-latest
             python-version: "3.6"
           - os: windows-latest
             python-version: "3.7"
           - os: windows-latest
-            python-version: "3.9-dev"
+            python-version: "3.9"
           - os: windows-latest
             python-version: "pypy3"
 
@@ -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

@@ -36,22 +36,27 @@ The main features of GQL are:
 
 * Execute GraphQL queries using [different protocols](https://gql.readthedocs.io/en/latest/transports/index.html) (http, websockets, ...)
 * Possibility to [validate the queries locally](https://gql.readthedocs.io/en/latest/usage/validation.html) using a GraphQL schema provided locally or fetched from the backend using an instrospection query
-* Supports GraphQL queries, mutations and subscriptions
+* Supports GraphQL queries, mutations and [subscriptions](https://gql.readthedocs.io/en/latest/usage/subscriptions.html)
 * Supports [sync or async usage](https://gql.readthedocs.io/en/latest/async/index.html), [allowing concurrent requests](https://gql.readthedocs.io/en/latest/advanced/async_advanced_usage.html#async-advanced-usage)
 * Supports [File uploads](https://gql.readthedocs.io/en/latest/usage/file_upload.html)
+* [gql-cli script](https://gql.readthedocs.io/en/latest/gql-cli/intro.html) to execute GraphQL queries from the command line
+* [DSL module](https://gql.readthedocs.io/en/latest/advanced/dsl_module.html) to compose GraphQL queries dynamically
 
 ## Installation
 
 > **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
 
 ### Basic usage
 
 ```python
-from gql import gql, Client, AIOHTTPTransport
+from gql import gql, Client
+from gql.transport.aiohttp import AIOHTTPTransport
 
 # Select your transport with a defined url endpoint
 transport = AIOHTTPTransport(url="https://countries.trevorblades.com/")

docs/advanced/dsl_module.rst

@@ -2,33 +2,225 @@ Compose queries dynamically
 ===========================
 
 Instead of providing the GraphQL queries as a Python String, it is also possible to create GraphQL queries dynamically.
-Using the DSL module, we can create a query using a Domain Specific Language which is created from the schema.
+Using the :mod:`DSL module <gql.dsl>`, we can create a query using a Domain Specific Language which is created from the schema.
+
+The following code:
 
 .. code-block:: python
 
-    from gql.dsl import DSLSchema
+    ds = DSLSchema(StarWarsSchema)
+
+    query = dsl_gql(
+        DSLQuery(
+            ds.Query.hero.select(
+                ds.Character.id,
+                ds.Character.name,
+                ds.Character.friends.select(ds.Character.name),
+            )
+        )
+    )
+
+will generate a query equivalent to:
+
+.. code-block:: python
+
+    query = gql("""
+        query {
+          hero {
+            id
+            name
+            friends {
+              name
+            }
+          }
+        }
+    """)
+
+How to use
+----------
+
+First generate the root using the :class:`DSLSchema <gql.dsl.DSLSchema>`::
+
+    ds = DSLSchema(client.schema)
+
+Then use auto-generated attributes of the :code:`ds` instance
+to get a root type (Query, Mutation or Subscription).
+This will generate a :class:`DSLType <gql.dsl.DSLType>` instance::
+
+    ds.Query
+
+From this root type, you use auto-generated attributes to get a field.
+This will generate a :class:`DSLField <gql.dsl.DSLField>` instance::
+
+    ds.Query.hero
+
+hero is a GraphQL object type and needs children fields. By default,
+there is no children fields selected. To select the fields that you want
+in your query, you use the :meth:`select <gql.dsl.DSLField.select>` method.
+
+To generate the children fields, we use the same method as above to auto-generate the fields
+from the :code:`ds` instance
+(ie :code:`ds.Character.name` is the field `name` of the type `Character`)::
+
+    ds.Query.hero.select(ds.Character.name)
 
-    client = Client(schema=StarWarsSchema)
-    ds = DSLSchema(client)
+The select method return the same instance, so it is possible to chain the calls::
 
-    query_dsl = ds.Query.hero.select(
+    ds.Query.hero.select(ds.Character.name).select(ds.Character.id)
+
+Or do it sequencially::
+
+    hero_query = ds.Query.hero
+
+    hero_query.select(ds.Character.name)
+    hero_query.select(ds.Character.id)
+
+As you can select children fields of any object type, you can construct your complete query tree::
+
+    ds.Query.hero.select(
         ds.Character.id,
         ds.Character.name,
-        ds.Character.friends.select(ds.Character.name,),
+        ds.Character.friends.select(ds.Character.name),
     )
 
-will create a query equivalent to:
+Once your root query fields are defined, you can put them in an operation using
+:class:`DSLQuery <gql.dsl.DSLQuery>`,
+:class:`DSLMutation <gql.dsl.DSLMutation>` or
+:class:`DSLSubscription <gql.dsl.DSLSubscription>`::
 
-.. code-block:: python
+    DSLQuery(
+        ds.Query.hero.select(
+            ds.Character.id,
+            ds.Character.name,
+            ds.Character.friends.select(ds.Character.name),
+        )
+    )
+
+
+Once your operations are defined,
+use the :func:`dsl_gql <gql.dsl.dsl_gql>` function to convert your operations into
+a document which will be able to get executed in the client or a session::
+
+    query = dsl_gql(
+        DSLQuery(
+            ds.Query.hero.select(
+                ds.Character.id,
+                ds.Character.name,
+                ds.Character.friends.select(ds.Character.name),
+            )
+        )
+    )
+
+    result = client.execute(query)
+
+Arguments
+^^^^^^^^^
+
+It is possible to add arguments to any field simply by calling it
+with the required arguments::
+
+    ds.Query.human(id="1000").select(ds.Human.name)
+
+It can also be done using the :meth:`args <gql.dsl.DSLField.args>` method::
+
+    ds.Query.human.args(id="1000").select(ds.Human.name)
 
-    hero {
-      id
-      name
-      friends {
-        name
-      }
+Aliases
+^^^^^^^
+
+You can set an alias of a field using the :meth:`alias <gql.dsl.DSLField.alias>` method::
+
+    ds.Query.human.args(id=1000).alias("luke").select(ds.Character.name)
+
+It is also possible to set the alias directly using keyword arguments of an operation::
+
+    DSLQuery(
+        luke=ds.Query.human.args(id=1000).select(ds.Character.name)
+    )
+
+Or using keyword arguments in the :meth:`select <gql.dsl.DSLField.select>` method::
+
+    ds.Query.hero.select(
+        my_name=ds.Character.name
+    )
+
+Mutations
+^^^^^^^^^
+
+For the mutations, you need to start from root fields starting from :code:`ds.Mutation`
+then you need to create the GraphQL operation using the class
+:class:`DSLMutation <gql.dsl.DSLMutation>`. Example::
+
+    query = dsl_gql(
+        DSLMutation(
+            ds.Mutation.createReview.args(
+                episode=6, review={"stars": 5, "commentary": "This is a great movie!"}
+            ).select(ds.Review.stars, ds.Review.commentary)
+        )
+    )
+
+Subscriptions
+^^^^^^^^^^^^^
+
+For the subscriptions, you need to start from root fields starting from :code:`ds.Subscription`
+then you need to create the GraphQL operation using the class
+:class:`DSLSubscription <gql.dsl.DSLSubscription>`. Example::
+
+    query = dsl_gql(
+        DSLSubscription(
+            ds.Subscription.reviewAdded(episode=6).select(ds.Review.stars, ds.Review.commentary)
+        )
+    )
+
+Multiple fields in an operation
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to create an operation with multiple fields::
+
+    DSLQuery(
+        ds.Query.hero.select(ds.Character.name),
+        hero_of_episode_5=ds.Query.hero(episode=5).select(ds.Character.name),
+    )
+
+Operation name
+^^^^^^^^^^^^^^
+
+You can set the operation name of an operation using a keyword argument
+to :func:`dsl_gql <gql.dsl.dsl_gql>`::
+
+    query = dsl_gql(
+        GetHeroName=DSLQuery(ds.Query.hero.select(ds.Character.name))
+    )
+
+will generate the request::
+
+    query GetHeroName {
+        hero {
+            name
+        }
     }
 
-.. warning::
+Multiple operations in a document
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+It is possible to create an Document with multiple operations::
+
+    query = dsl_gql(
+        operation_name_1=DSLQuery( ... ),
+        operation_name_2=DSLQuery( ... ),
+        operation_name_3=DSLMutation( ... ),
+    )
+
+Executable examples
+-------------------
+
+Async example
+^^^^^^^^^^^^^
+
+.. literalinclude:: ../code_examples/aiohttp_async_dsl.py
+
+Sync example
+^^^^^^^^^^^^^
+
+.. literalinclude:: ../code_examples/requests_sync_dsl.py
 
-    Please note that the DSL module is still considered experimental in GQL 3 and is subject to changes

docs/advanced/index.rst

@@ -5,5 +5,6 @@ Advanced
    :maxdepth: 2
 
    async_advanced_usage
+   logging
    local_schema
    dsl_module

docs/advanced/logging.rst

@@ -0,0 +1,21 @@
+Logging
+=======
+
+GQL use the python `logging`_ module.
+
+In order to debug a problem, you can enable logging to see the messages exchanged between the client and the server.
+To do that, set the loglevel at **INFO** at the beginning of your code:
+
+.. code-block:: python
+
+    import logging
+    logging.basicConfig(level=logging.INFO)
+
+For even more logs, you can set the loglevel at **DEBUG**:
+
+.. code-block:: python
+
+    import logging
+    logging.basicConfig(level=logging.DEBUG)
+
+.. _logging: https://docs.python.org/3/howto/logging.html