Introduction
============

`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 and all the extra dependencies using pip_::

    pip install --pre gql[all]

.. 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 "`--pre`"

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
---------------------------------

Please visit the `GitHub repository for gql`_ if you're interested in the current development or
want to report issues or send pull requests.

We welcome all kinds of contributions if the coding guidelines are respected.
Please check the  `Contributing`_ file to learn how to make a good pull request.

.. _GraphQL: https://graphql.org/
.. _GraphQL-core: https://github.com/graphql-python/graphql-core
.. _GraphQL.js: https://github.com/graphql/graphql-js
.. _GQL 3: https://github.com/graphql-python/gql
.. _pip: https://pip.pypa.io/
.. _GitHub repository for gql: https://github.com/graphql-python/gql
.. _Contributing: https://github.com/graphql-python/gql/blob/master/CONTRIBUTING.md
