# GQL
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`.
[![GitHub-Actions][gh-image]][gh-url]
[![pyversion][pyversion-image]][pyversion-url]
[![pypi][pypi-image]][pypi-url]
[![Anaconda-Server Badge][conda-image]][conda-url]
[![codecov][codecov-image]][codecov-url]
[gh-image]: https://github.com/graphql-python/gql/workflows/Tests/badge.svg
[gh-url]: https://github.com/graphql-python/gql/actions?query=workflow%3ATests
[pyversion-image]: https://img.shields.io/pypi/pyversions/gql
[pyversion-url]: https://pypi.org/project/gql/
[pypi-image]: https://img.shields.io/pypi/v/gql.svg?style=flat
[pypi-url]: https://pypi.org/project/gql/
[conda-image]: https://img.shields.io/conda/vn/conda-forge/gql.svg
[conda-url]: https://anaconda.org/conda-forge/gql
[codecov-image]: https://codecov.io/gh/graphql-python/gql/branch/master/graph/badge.svg
[codecov-url]: https://codecov.io/gh/graphql-python/gql
## Documentation
The complete documentation for GQL can be found at
[gql.readthedocs.io](https://gql.readthedocs.io).
## Features
* Execute GraphQL queries using [different protocols](https://gql.readthedocs.io/en/latest/transports/index.html):
* http
* websockets:
* apollo or graphql-ws protocol
* Phoenix channels
* 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](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
## Installation
You can install GQL with all the optional dependencies using pip:
```bash
# Quotes may be required on certain shells such as zsh.
pip install "gql[all]"
```
> **NOTE**: See also [the documentation](https://gql.readthedocs.io/en/latest/intro.html#less-dependencies) to install GQL with less extra dependencies depending on the transports you would like to use or for alternative installation methods.
## Usage
### Sync usage
```python
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)
# Provide a GraphQL query
query = gql(
"""
query getContinents {
continents {
code
name
}
}
"""
)
# Execute the query on the transport
result = client.execute(query)
print(result)
```
Executing the above code should output the following result:
```
$ python basic_example.py
{'continents': [{'code': 'AF', 'name': 'Africa'}, {'code': 'AN', 'name': 'Antarctica'}, {'code': 'AS', 'name': 'Asia'}, {'code': 'EU', 'name': 'Europe'}, {'code': 'NA', 'name': 'North America'}, {'code': 'OC', 'name': 'Oceania'}, {'code': 'SA', 'name': 'South America'}]}
```
> **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/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)
## License
[MIT License](https://github.com/graphql-python/gql/blob/master/LICENSE)
Raw data
{
"_id": null,
"home_page": "https://github.com/graphql-python/gql",
"name": "gql",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8.1",
"maintainer_email": null,
"keywords": "api graphql protocol rest relay gql client",
"author": "Syrus Akbary",
"author_email": "me@syrusakbary.com",
"download_url": "https://files.pythonhosted.org/packages/06/9f/cf224a88ed71eb223b7aa0b9ff0aa10d7ecc9a4acdca2279eb046c26d5dc/gql-4.0.0.tar.gz",
"platform": "any",
"description": "# GQL\n\nThis is a GraphQL client for Python.\nPlays nicely with `graphene`, `graphql-core`, `graphql-js` and any other GraphQL implementation\ncompatible with the [GraphQL specification](https://spec.graphql.org).\n\nGQL architecture is inspired by `React-Relay` and `Apollo-Client`.\n\n[![GitHub-Actions][gh-image]][gh-url]\n[![pyversion][pyversion-image]][pyversion-url]\n[![pypi][pypi-image]][pypi-url]\n[![Anaconda-Server Badge][conda-image]][conda-url]\n[![codecov][codecov-image]][codecov-url]\n\n[gh-image]: https://github.com/graphql-python/gql/workflows/Tests/badge.svg\n[gh-url]: https://github.com/graphql-python/gql/actions?query=workflow%3ATests\n[pyversion-image]: https://img.shields.io/pypi/pyversions/gql\n[pyversion-url]: https://pypi.org/project/gql/\n[pypi-image]: https://img.shields.io/pypi/v/gql.svg?style=flat\n[pypi-url]: https://pypi.org/project/gql/\n[conda-image]: https://img.shields.io/conda/vn/conda-forge/gql.svg\n[conda-url]: https://anaconda.org/conda-forge/gql\n[codecov-image]: https://codecov.io/gh/graphql-python/gql/branch/master/graph/badge.svg\n[codecov-url]: https://codecov.io/gh/graphql-python/gql\n\n## Documentation\n\nThe complete documentation for GQL can be found at\n[gql.readthedocs.io](https://gql.readthedocs.io).\n\n## Features\n\n* Execute GraphQL queries using [different protocols](https://gql.readthedocs.io/en/latest/transports/index.html):\n * http\n * websockets:\n * apollo or graphql-ws protocol\n * Phoenix channels\n * AWS AppSync realtime protocol (experimental)\n* 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\n* Supports GraphQL queries, mutations and [subscriptions](https://gql.readthedocs.io/en/latest/usage/subscriptions.html)\n* 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)\n* Supports [File uploads](https://gql.readthedocs.io/en/latest/usage/file_upload.html)\n* Supports [Custom scalars / Enums](https://gql.readthedocs.io/en/latest/usage/custom_scalars_and_enums.html)\n* Supports [Batching requests](https://gql.readthedocs.io/en/latest/advanced/batching_requests.html)\n* [gql-cli script](https://gql.readthedocs.io/en/latest/gql-cli/intro.html) to execute GraphQL queries or download schemas from the command line\n* [DSL module](https://gql.readthedocs.io/en/latest/advanced/dsl_module.html) to compose GraphQL queries dynamically\n\n## Installation\n\nYou can install GQL with all the optional dependencies using pip:\n\n```bash\n# Quotes may be required on certain shells such as zsh.\npip install \"gql[all]\"\n```\n\n> **NOTE**: See also [the documentation](https://gql.readthedocs.io/en/latest/intro.html#less-dependencies) to install GQL with less extra dependencies depending on the transports you would like to use or for alternative installation methods.\n\n## Usage\n\n### Sync usage\n\n```python\nfrom gql import Client, gql\nfrom gql.transport.aiohttp import AIOHTTPTransport\n\n# Select your transport with a defined url endpoint\ntransport = AIOHTTPTransport(url=\"https://countries.trevorblades.com/\")\n\n# Create a GraphQL client using the defined transport\nclient = Client(transport=transport)\n\n# Provide a GraphQL query\nquery = gql(\n \"\"\"\n query getContinents {\n continents {\n code\n name\n }\n }\n\"\"\"\n)\n\n# Execute the query on the transport\nresult = client.execute(query)\nprint(result)\n```\n\nExecuting the above code should output the following result:\n\n```\n$ python basic_example.py\n{'continents': [{'code': 'AF', 'name': 'Africa'}, {'code': 'AN', 'name': 'Antarctica'}, {'code': 'AS', 'name': 'Asia'}, {'code': 'EU', 'name': 'Europe'}, {'code': 'NA', 'name': 'North America'}, {'code': 'OC', 'name': 'Oceania'}, {'code': 'SA', 'name': 'South America'}]}\n```\n\n> **WARNING**: Please note that this basic example won't work if you have an asyncio event loop running. In some\n> python environments (as with Jupyter which uses IPython) an asyncio event loop is created for you. In that case you\n> should use instead the [async usage example](https://gql.readthedocs.io/en/latest/usage/async_usage.html#async-usage).\n\n### Async usage\n\n```python\nimport asyncio\n\nfrom gql import Client, gql\nfrom gql.transport.aiohttp import AIOHTTPTransport\n\n\nasync def main():\n\n # Select your transport with a defined url endpoint\n transport = AIOHTTPTransport(url=\"https://countries.trevorblades.com/graphql\")\n\n # Create a GraphQL client using the defined transport\n client = Client(transport=transport)\n\n # Provide a GraphQL query\n query = gql(\n \"\"\"\n query getContinents {\n continents {\n code\n name\n }\n }\n \"\"\"\n )\n\n # Using `async with` on the client will start a connection on the transport\n # and provide a `session` variable to execute queries on this connection\n async with client as session:\n\n # Execute the query\n result = await session.execute(query)\n print(result)\n\n\nasyncio.run(main())\n```\n\n## Contributing\nSee [CONTRIBUTING.md](CONTRIBUTING.md)\n\n## License\n\n[MIT License](https://github.com/graphql-python/gql/blob/master/LICENSE)\n",
"bugtrack_url": null,
"license": "MIT",
"summary": "GraphQL client for Python",
"version": "4.0.0",
"project_urls": {
"Homepage": "https://github.com/graphql-python/gql"
},
"split_keywords": [
"api",
"graphql",
"protocol",
"rest",
"relay",
"gql",
"client"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "ac9430bbd09e8d45339fa77a48f5778d74d47e9242c11b3cd1093b3d994770a5",
"md5": "5ec98b7c0c64047426501b483b13d8ff",
"sha256": "f3beed7c531218eb24d97cb7df031b4a84fdb462f4a2beb86e2633d395937479"
},
"downloads": -1,
"filename": "gql-4.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "5ec98b7c0c64047426501b483b13d8ff",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8.1",
"size": 89900,
"upload_time": "2025-08-17T14:32:34",
"upload_time_iso_8601": "2025-08-17T14:32:34.029312Z",
"url": "https://files.pythonhosted.org/packages/ac/94/30bbd09e8d45339fa77a48f5778d74d47e9242c11b3cd1093b3d994770a5/gql-4.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "069fcf224a88ed71eb223b7aa0b9ff0aa10d7ecc9a4acdca2279eb046c26d5dc",
"md5": "65c18cc1472f7a17283e22539f02e918",
"sha256": "f22980844eb6a7c0266ffc70f111b9c7e7c7c13da38c3b439afc7eab3d7c9c8e"
},
"downloads": -1,
"filename": "gql-4.0.0.tar.gz",
"has_sig": false,
"md5_digest": "65c18cc1472f7a17283e22539f02e918",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8.1",
"size": 215644,
"upload_time": "2025-08-17T14:32:35",
"upload_time_iso_8601": "2025-08-17T14:32:35.397571Z",
"url": "https://files.pythonhosted.org/packages/06/9f/cf224a88ed71eb223b7aa0b9ff0aa10d7ecc9a4acdca2279eb046c26d5dc/gql-4.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 14:32:35",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "graphql-python",
"github_project": "gql",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "gql"
}
JSON
