Merge branch 'master' into fix_aiohttp_wait_for_closed_connections

Author: leszekhanusz

.github/workflows/tests.yml

@@ -8,7 +8,7 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: ["3.6", "3.7", "3.8", "3.9", "pypy3"]
+        python-version: ["3.6", "3.7", "3.8", "3.9", "3.10", "pypy3"]
         os: [ubuntu-latest, windows-latest]
         exclude:
           - os: windows-latest
@@ -17,6 +17,8 @@ jobs:
             python-version: "3.7"
           - os: windows-latest
             python-version: "3.9"
+          - os: windows-latest
+            python-version: "3.10"
           - os: windows-latest
             python-version: "pypy3"
 

.readthedocs.yaml

@@ -0,0 +1,29 @@
+# .readthedocs.yaml
+# Read the Docs configuration file
+# See https://docs.readthedocs.io/en/stable/config-file/v2.html for details
+
+# Required
+version: 2
+
+# Set the version of Python and other tools you might need
+build:
+  os: ubuntu-20.04
+  tools:
+    python: "3.9"
+
+# Build documentation in the docs/ directory with Sphinx
+sphinx:
+   configuration: docs/conf.py
+
+# Optionally build your docs in additional formats such as PDF
+formats:
+  - pdf
+
+python:
+  install:
+    - requirements: docs/requirements.txt
+    - method: pip
+      path: .
+      extra_requirements:
+        - all
+  system_packages: true

CONTRIBUTING.md

@@ -31,7 +31,7 @@ virtualenv gql-dev
 Activate the virtualenv and install dependencies by running:
 
 ```console
-python pip install -e.[dev]
+python -m pip install -e.[dev]
 ```
 
 If you are using Linux or MacOS, you can make use of Makefile command

MANIFEST.in

@@ -4,6 +4,7 @@ include CODEOWNERS
 include LICENSE
 include README.md
 include CONTRIBUTING.md
+include .readthedocs.yaml
 
 include dev_requirements.txt
 include Makefile

README.md

@@ -39,7 +39,8 @@ The main features of GQL are:
 * 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
+* Supports [Custom scalars / Enums](https://gql.readthedocs.io/en/latest/usage/custom_scalars_and_enums.html)
+* [gql-cli script](https://gql.readthedocs.io/en/latest/gql-cli/intro.html) to execute GraphQL queries or download schemas from the command line
 * [DSL module](https://gql.readthedocs.io/en/latest/advanced/dsl_module.html) to compose GraphQL queries dynamically
 
 ## Installation

docs/advanced/dsl_module.rst

@@ -159,6 +159,47 @@ then you need to create the GraphQL operation using the class
         )
     )
 
+Variable arguments
+^^^^^^^^^^^^^^^^^^
+
+To provide variables instead of argument values directly for an operation, you have to:
+
+* Instantiate a :class:`DSLVariableDefinitions <gql.dsl.DSLVariableDefinitions>`::
+
+    var = DSLVariableDefinitions()
+
+* From this instance you can generate :class:`DSLVariable <gql.dsl.DSLVariable>` instances
+  and provide them as the value of the arguments::
+
+    ds.Mutation.createReview.args(review=var.review, episode=var.episode)
+
+* Once the operation has been defined, you have to save the variable definitions used
+  in it::
+
+    operation.variable_definitions = var
+
+The following code:
+
+.. code-block:: python
+
+    var = DSLVariableDefinitions()
+    op = DSLMutation(
+        ds.Mutation.createReview.args(review=var.review, episode=var.episode).select(
+            ds.Review.stars, ds.Review.commentary
+        )
+    )
+    op.variable_definitions = var
+    query = dsl_gql(op)
+
+will generate a query equivalent to::
+
+    mutation ($review: ReviewInput, $episode: Episode) {
+      createReview(review: $review, episode: $episode) {
+        stars
+        commentary
+      }
+    }
+
 Subscriptions
 ^^^^^^^^^^^^^
 
@@ -211,6 +252,103 @@ It is possible to create an Document with multiple operations::
         operation_name_3=DSLMutation( ... ),
     )
 
+Fragments
+^^^^^^^^^
+
+To define a `Fragment`_, you have to:
+
+* Instantiate a :class:`DSLFragment <gql.dsl.DSLFragment>` with a name::
+
+    name_and_appearances = DSLFragment("NameAndAppearances")
+
+* Provide the GraphQL type of the fragment with the
+  :meth:`on <gql.dsl.DSLFragment.on>` method::
+
+    name_and_appearances.on(ds.Character)
+
+* Add children fields using the :meth:`select <gql.dsl.DSLFragment.select>` method::
+
+    name_and_appearances.select(ds.Character.name, ds.Character.appearsIn)
+
+Once your fragment is defined, to use it you should:
+
+* select it as a field somewhere in your query::
+
+    query_with_fragment = DSLQuery(ds.Query.hero.select(name_and_appearances))
+
+* add it as an argument of :func:`dsl_gql <gql.dsl.dsl_gql>` with your query::
+
+    query = dsl_gql(name_and_appearances, query_with_fragment)
+
+The above example will generate the following request::
+
+    fragment NameAndAppearances on Character {
+        name
+        appearsIn
+    }
+
+    {
+        hero {
+            ...NameAndAppearances
+        }
+    }
+
+Inline Fragments
+^^^^^^^^^^^^^^^^
+
+To define an `Inline Fragment`_, you have to:
+
+* Instantiate a :class:`DSLInlineFragment <gql.dsl.DSLInlineFragment>`::
+
+    human_fragment = DSLInlineFragment()
+
+* Provide the GraphQL type of the fragment with the
+  :meth:`on <gql.dsl.DSLInlineFragment.on>` method::
+
+    human_fragment.on(ds.Human)
+
+* Add children fields using the :meth:`select <gql.dsl.DSLInlineFragment.select>` method::
+
+    human_fragment.select(ds.Human.homePlanet)
+
+Once your inline fragment is defined, to use it you should:
+
+* select it as a field somewhere in your query::
+
+    query_with_inline_fragment = ds.Query.hero.args(episode=6).select(
+        ds.Character.name,
+        human_fragment
+    )
+
+The above example will generate the following request::
+
+    hero(episode: JEDI) {
+        name
+        ... on Human {
+          homePlanet
+        }
+    }
+
+Note: because the :meth:`on <gql.dsl.DSLInlineFragment.on>` and
+:meth:`select <gql.dsl.DSLInlineFragment.select>` methods return :code:`self`,
+this can be written in a concise manner::
+
+    query_with_inline_fragment = ds.Query.hero.args(episode=6).select(
+        ds.Character.name,
+        DSLInlineFragment().on(ds.Human).select(ds.Human.homePlanet)
+    )
+
+Meta-fields
+^^^^^^^^^^^
+
+To define meta-fields (:code:`__typename`, :code:`__schema` and :code:`__type`),
+you can use the :class:`DSLMetaField <gql.dsl.DSLMetaField>` class::
+
+    query = ds.Query.hero.select(
+        ds.Character.name,
+        DSLMetaField("__typename")
+    )
+
 Executable examples
 -------------------
 
@@ -224,3 +362,5 @@ Sync example
 
 .. literalinclude:: ../code_examples/requests_sync_dsl.py
 
+.. _Fragment: https://graphql.org/learn/queries/#fragments
+.. _Inline Fragment: https://graphql.org/learn/queries/#inline-fragments

docs/advanced/logging.rst

@@ -18,4 +18,31 @@ For even more logs, you can set the loglevel at **DEBUG**:
     import logging
     logging.basicConfig(level=logging.DEBUG)
 
+Disabling logs
+--------------
+
+By default, the logs for the transports are quite verbose.
+
+On the **INFO** level, all the messages between the frontend and the backend are logged which can
+be difficult to read especially when it fetches the schema from the transport.
+
+It is possible to disable the logs only for a specific gql transport by setting a higher
+log level for this transport (**WARNING** for example) so that the other logs of your program are not affected.
+
+For this, you should import the logger from the transport file and set the level on this logger.
+
+For the RequestsHTTPTransport:
+
+.. code-block:: python
+
+    from gql.transport.requests import log as requests_logger
+    requests_logger.setLevel(logging.WARNING)
+
+For the WebsocketsTransport:
+
+.. code-block:: python
+
+    from gql.transport.websockets import log as websockets_logger
+    websockets_logger.setLevel(logging.WARNING)
+
 .. _logging: https://docs.python.org/3/howto/logging.html

docs/code_examples/aiohttp_async_dsl.py

@@ -17,7 +17,7 @@ async def main():
     # GQL will fetch the schema just after the establishment of the first session
     async with client as session:
 
-        # Instanciate the root of the DSL Schema as ds
+        # Instantiate the root of the DSL Schema as ds
         ds = DSLSchema(client.schema)
 
         # Create the query using dynamically generated attributes from ds

docs/code_examples/requests_sync_dsl.py

@@ -17,7 +17,7 @@
     # We should have received the schema now that the session is established
     assert client.schema is not None
 
-    # Instanciate the root of the DSL Schema as ds
+    # Instantiate the root of the DSL Schema as ds
     ds = DSLSchema(client.schema)
 
     # Create the query using dynamically generated attributes from ds

docs/gql-cli/intro.rst

@@ -1,3 +1,5 @@
+.. _gql_cli:
+
 gql-cli
 =======
 
@@ -69,3 +71,10 @@ Then execute query from the file:
 
     $ cat query.gql | gql-cli wss://countries.trevorblades.com/graphql
     {"continent": {"name": "Africa"}}
+
+Print the GraphQL schema in a file
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. code-block:: shell
+
+    $ gql-cli https://countries.trevorblades.com/graphql --print-schema > schema.graphql

docs/intro.rst

@@ -26,10 +26,9 @@ 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.
+Each transport can necessitate specific dependencies.
+If you only need one transport you might want to install only the dependency needed for your transport,
+instead of using the "`all`" extra dependency as described above, which installs everything.
 
 If for example you only need the :ref:`AIOHTTPTransport <aiohttp_transport>`,
 which needs the :code:`aiohttp` dependency, then you can install GQL with::

docs/modules/gql.rst

@@ -21,3 +21,4 @@ Sub-Packages
    client
    transport
    dsl
+   utilities

docs/modules/transport.rst

@@ -14,3 +14,5 @@ gql.transport
 .. autoclass:: gql.transport.aiohttp.AIOHTTPTransport
 
 .. autoclass:: gql.transport.websockets.WebsocketsTransport
+
+.. autoclass:: gql.transport.phoenix_channel_websockets.PhoenixChannelWebsocketsTransport

docs/modules/utilities.rst

@@ -0,0 +1,6 @@
+gql.utilities
+=============
+
+.. currentmodule:: gql.utilities
+
+.. automodule:: gql.utilities

docs/transports/aiohttp.rst

@@ -5,11 +5,48 @@ AIOHTTPTransport
 
 This transport uses the `aiohttp`_ library and allows you to send GraphQL queries using the HTTP protocol.
 
+Reference: :class:`gql.transport.aiohttp.AIOHTTPTransport`
+
 .. note::
 
     GraphQL subscriptions are not supported on the HTTP transport.
     For subscriptions you should use the :ref:`websockets transport <websockets_transport>`.
 
 .. literalinclude:: ../code_examples/aiohttp_async.py
 
+Authentication
+--------------
+
+There are multiple ways to authenticate depending on the server configuration.
+
+1. Using HTTP Headers
+
+.. code-block:: python
+
+    transport = AIOHTTPTransport(
+        url='https://SERVER_URL:SERVER_PORT/graphql',
+        headers={'Authorization': 'token'}
+    )
+
+2. Using HTTP Cookies
+
+You can manually set the cookies which will be sent with each connection:
+
+.. code-block:: python
+
+    transport = AIOHTTPTransport(url=url, cookies={"cookie1": "val1"})
+
+Or you can use a cookie jar to save cookies set from the backend and reuse them later.
+
+In some cases, the server will set some connection cookies after a successful login mutation
+and you can save these cookies in a cookie jar to reuse them in a following connection
+(See `issue 197`_):
+
+.. code-block:: python
+
+    jar = aiohttp.CookieJar()
+    transport = AIOHTTPTransport(url=url, client_session_args={'cookie_jar': jar})
+
+
 .. _aiohttp: https://docs.aiohttp.org
+.. _issue 197: https://github.com/graphql-python/gql/issues/197

docs/transports/phoenix.rst

@@ -3,10 +3,13 @@
 PhoenixChannelWebsocketsTransport
 =================================
 
-The PhoenixChannelWebsocketsTransport is an **EXPERIMENTAL** async transport which allows you
+The PhoenixChannelWebsocketsTransport is an async transport which allows you
 to execute queries and subscriptions against an `Absinthe`_ backend using the `Phoenix`_
 framework `channels`_.
 
+Reference:
+:class:`gql.transport.phoenix_channel_websockets.PhoenixChannelWebsocketsTransport`
+
 .. _Absinthe: http://absinthe-graphql.org
 .. _Phoenix: https://www.phoenixframework.org
 .. _channels: https://hexdocs.pm/phoenix/Phoenix.Channel.html#content