Merge branch 'master' into stable

Author: leszekhanusz

.github/ISSUE_TEMPLATE/bug_report.md

@@ -9,7 +9,7 @@ assignees: ''
 
 **Common problems**
 - If you receive a TransportQueryError, it means the error is coming from the backend (See [Error Handling](https://gql.readthedocs.io/en/latest/advanced/error_handling.html)) and has probably nothing to do with gql
-- If you use IPython (Jupyter, Spyder), then [you need to use the async version](https://gql.readthedocs.io/en/latest/async/async_usage.html#ipython)
+- If you use IPython (Jupyter, Spyder), then [you need to use the async version](https://gql.readthedocs.io/en/latest/usage/async_usage.html#ipython)
 - Before sending a bug report, please consider [activating debug logs](https://gql.readthedocs.io/en/latest/advanced/logging.html) to see the messages exchanged between the client and the backend
 
 **Describe the bug**

.github/workflows/deploy.yml

@@ -10,17 +10,19 @@ jobs:
     runs-on: ubuntu-24.04
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v4
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
       with:
-        python-version: 3.8
-    - name: Build wheel and source tarball
+        python-version: 3.12
+    - name: Install build dependencies
       run: |
-        pip install wheel
-        python setup.py sdist bdist_wheel
+        python -m pip install --upgrade pip
+        pip install build wheel
+    - name: Build package
+      run: |
+        python -m build
     - name: Publish a Python distribution to PyPI
-      uses: pypa/gh-action-pypi-publish@v1.1.0
+      uses: pypa/gh-action-pypi-publish@release/v1
       with:
-        user: __token__
         password: ${{ secrets.pypi_password }}

.github/workflows/lint.yml

@@ -1,17 +1,20 @@
 name: Lint
 
+permissions:
+  contents: read
+
 on: [push, pull_request]
 
 jobs:
   build:
     runs-on: ubuntu-24.04
 
     steps:
-    - uses: actions/checkout@v3
-    - name: Set up Python 3.8
-      uses: actions/setup-python@v4
+    - uses: actions/checkout@v4
+    - name: Set up Python 3.12
+      uses: actions/setup-python@v5
       with:
-        python-version: 3.8
+        python-version: 3.12
     - name: Install dependencies
       run: |
         python -m pip install --upgrade pip wheel

.github/workflows/tests.yml

@@ -1,5 +1,8 @@
 name: Tests
 
+permissions:
+  contents: read
+
 on: [push, pull_request]
 
 jobs:
@@ -8,7 +11,7 @@ jobs:
     strategy:
       max-parallel: 4
       matrix:
-        python-version: ["3.8", "3.9", "3.10", "3.11", "3.12", "pypy3.8"]
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13", "pypy3.10"]
         os: [ubuntu-24.04, windows-latest]
         exclude:
           - os: windows-latest
@@ -18,14 +21,14 @@ jobs:
           - os: windows-latest
             python-version: "3.11"
           - os: windows-latest
-            python-version: "3.12"
+            python-version: "3.13"
           - os: windows-latest
-            python-version: "pypy3.8"
+            python-version: "pypy3.10"
 
     steps:
-      - uses: actions/checkout@v3
+      - uses: actions/checkout@v4
       - name: Set up Python ${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+        uses: actions/setup-python@v5
         with:
           python-version: ${{ matrix.python-version }}
       - name: Install dependencies
@@ -45,11 +48,11 @@ jobs:
         dependency: ["aiohttp", "requests", "httpx", "websockets"]
 
     steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python 3.8
-        uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.8
+          python-version: 3.12
       - name: Install dependencies with only ${{ matrix.dependency }} extra dependency
         run: |
           python -m pip install --upgrade pip wheel
@@ -60,17 +63,24 @@ jobs:
   coverage:
     runs-on: ubuntu-24.04
 
+    permissions:
+      contents: read
+      checks: write
+
     steps:
-      - uses: actions/checkout@v3
-      - name: Set up Python 3.8
-        uses: actions/setup-python@v4
+      - uses: actions/checkout@v4
+      - name: Set up Python 3.12
+        uses: actions/setup-python@v5
         with:
-          python-version: 3.8
+          python-version: 3.12
       - name: Install test dependencies
         run: |
           python -m pip install --upgrade pip wheel
           pip install -e.[test]
       - name: Test with coverage
         run: pytest --cov=gql --cov-report=xml --cov-report=term-missing tests
       - name: Upload coverage to Codecov
-        uses: codecov/codecov-action@v1
+        uses: codecov/codecov-action@v4
+        with:
+          fail_ci_if_error: false
+          token: ${{ secrets.CODECOV_TOKEN }}

MANIFEST.in

@@ -6,18 +6,16 @@ include README.md
 include CONTRIBUTING.md
 include .readthedocs.yaml
 
-include dev_requirements.txt
 include Makefile
 
 include tox.ini
 
 include gql/py.typed
 
-recursive-include tests *.py *.graphql *.cnf *.yaml *.pem
-recursive-include docs *.txt *.rst conf.py Makefile make.bat *.jpg *.png *.gif
+recursive-include tests *.py *.graphql *.cnf *.yaml *.pem *.crt
+recursive-include docs *.txt *.rst conf.py Makefile make.bat
 recursive-include docs/code_examples *.py
 
 prune docs/_build
-prune gql-checker
 
 global-exclude *.py[co] __pycache__

Makefile

@@ -24,7 +24,7 @@ tests_websockets:
 	pytest tests --websockets-only
 
 check:
-	isort --recursive $(SRC_PYTHON)
+	isort $(SRC_PYTHON)
 	black $(SRC_PYTHON)
 	flake8 $(SRC_PYTHON)
 	mypy $(SRC_PYTHON)

README.md

@@ -1,7 +1,8 @@
 # GQL
 
-This is a GraphQL client for Python 3.7+.
-Plays nicely with `graphene`, `graphql-core`, `graphql-js` and any other GraphQL implementation compatible with the spec.
+This is a GraphQL client for Python.
+Plays nicely with `graphene`, `graphql-core`, `graphql-js` and any other GraphQL implementation
+compatible with the [GraphQL specification](https://spec.graphql.org).
 
 GQL architecture is inspired by `React-Relay` and `Apollo-Client`.
 
@@ -37,9 +38,10 @@ The complete documentation for GQL can be found at
     * AWS AppSync realtime protocol (experimental)
 * 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](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 [sync](https://gql.readthedocs.io/en/latest/usage/sync_usage.html) or [async](https://gql.readthedocs.io/en/latest/usage/async_usage.html) usage, [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)
 * Supports [Custom scalars / Enums](https://gql.readthedocs.io/en/latest/usage/custom_scalars_and_enums.html)
+* Supports [Batching requests](https://gql.readthedocs.io/en/latest/advanced/batching_requests.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
 
@@ -56,17 +58,17 @@ pip install "gql[all]"
 
 ## Usage
 
-### Basic usage
+### Sync usage
 
 ```python
-from gql import gql, Client
+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/")
 
 # Create a GraphQL client using the defined transport
-client = Client(transport=transport, fetch_schema_from_transport=True)
+client = Client(transport=transport)
 
 # Provide a GraphQL query
 query = gql(
@@ -94,7 +96,48 @@ $ python basic_example.py
 
 > **WARNING**: Please note that this basic example won't work if you have an asyncio event loop running. In some
 > python environments (as with Jupyter which uses IPython) an asyncio event loop is created for you. In that case you
-> should use instead the [async usage example](https://gql.readthedocs.io/en/latest/async/async_usage.html#async-usage).
+> should use instead the [async usage example](https://gql.readthedocs.io/en/latest/usage/async_usage.html#async-usage).
+
+### Async usage
+
+```python
+import asyncio
+
+from gql import Client, gql
+from gql.transport.aiohttp import AIOHTTPTransport
+
+
+async def main():
+
+    # Select your transport with a defined url endpoint
+    transport = AIOHTTPTransport(url="https://countries.trevorblades.com/graphql")
+
+    # Create a GraphQL client using the defined transport
+    client = Client(transport=transport)
+
+    # Provide a GraphQL query
+    query = gql(
+        """
+        query getContinents {
+          continents {
+            code
+            name
+          }
+        }
+    """
+    )
+
+    # 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 as session:
+
+        # Execute the query
+        result = await session.execute(query)
+        print(result)
+
+
+asyncio.run(main())
+```
 
 ## Contributing
 See [CONTRIBUTING.md](CONTRIBUTING.md)

docs/Makefile

@@ -3,7 +3,7 @@
 
 # You can set these variables from the command line, and also
 # from the environment for the first two.
-SPHINXOPTS    ?=
+SPHINXOPTS    ?= -n
 SPHINXBUILD   ?= sphinx-build
 SOURCEDIR     = .
 BUILDDIR      = _build

docs/advanced/async_permanent_session.rst

@@ -75,7 +75,6 @@ backoff decorator to the :code:`retry_execute` argument.
         backoff.expo,
         Exception,
         max_tries=3,
-        giveup=lambda e: isinstance(e, TransportQueryError),
     )
     session = await client.connect_async(
         reconnecting=True,
@@ -84,6 +83,18 @@ backoff decorator to the :code:`retry_execute` argument.
 
 If you don't want any retry on the execute calls, you can disable the retries with :code:`retry_execute=False`
 
+.. note::
+    If you want to retry even with :code:`TransportQueryError` exceptions,
+    then you need to make your own backoff decorator on your own method:
+
+    .. code-block:: python
+
+        @backoff.on_exception(backoff.expo,
+                              Exception,
+                              max_tries=3)
+        async def execute_with_retry(session, query):
+            return await session.execute(query)
+
 Subscription retries
 ^^^^^^^^^^^^^^^^^^^^