Gql - A GraphQL Client In Python - GitHub

Skip to content Dismiss alert {{ message }} graphql-python / gql Public

• Notifications You must be signed in to change notification settings
• Fork 188
• Star 1.7k

• Code
• Issues 5
• Pull requests
• Actions
• Projects
• Security
• Insights

Additional navigation options

 masterBranchesTagsGo to fileCodeOpen more actions menu

Folders and files

Name		Name	Last commit message	Last commit date
Latest commit   History 402 Commits402 Commits
.github		.github
docs		docs
gql		gql
tests		tests
.gitignore		.gitignore
.readthedocs.yaml		.readthedocs.yaml
CODEOWNERS		CODEOWNERS
CONTRIBUTING.md		CONTRIBUTING.md
LICENSE		LICENSE
MANIFEST.in		MANIFEST.in
Makefile		Makefile
README.md		README.md
pyproject.toml		pyproject.toml
setup.cfg		setup.cfg
setup.py		setup.py
tox.ini		tox.ini
View all files

Repository files navigation

• README
• Contributing
• MIT license

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.

GQL architecture is inspired by React-Relay and Apollo-Client.

Documentation

The complete documentation for GQL can be found at gql.readthedocs.io.

Features

• Execute GraphQL requests using different protocols:
  • http
    • including the multipart protocol for subscriptions
  • websockets:
    • apollo or graphql-ws protocol
    • Phoenix channels
    • AWS AppSync realtime protocol
• Possibility to validate the requests locally using a GraphQL schema provided locally or fetched from the backend using an instrospection query
• Supports GraphQL queries, mutations and subscriptions
• Supports sync or async usage, allowing concurrent requests
• Supports File uploads
• Supports Custom scalars / Enums
• Supports Batching requests
• gql-cli script to execute GraphQL queries or download schemas from the command line
• DSL module to compose GraphQL queries dynamically

Installation

You can install GQL with all the optional dependencies using pip:

# Quotes may be required on certain shells such as zsh. pip install "gql[all]"

NOTE: See also the documentation to install GQL with less extra dependencies depending on the transports you would like to use or for alternative installation methods.

Usage

Sync usage

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.

Async usage

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

License

MIT License

About

A GraphQL client in Python

gql.readthedocs.io

Topics

graphql-client graphql gql async-transport websockets-transport

Resources

Readme

License

MIT license

Contributing

Contributing

Uh oh!

There was an error while loading. Please reload this page.

Activity Custom properties

Stars

1.7k stars

Watchers

25 watching

Forks

188 forks Report repository

Releases 44

v4.0.0 Latest Aug 17, 2025 + 43 releases

Packages

Uh oh!

There was an error while loading. Please reload this page.

Used by 11.3k

• 
• 
• 
• 
• 
• 
• 
• 

+ 11,283

Contributors

Uh oh!

There was an error while loading. Please reload this page.

Languages

• Python 99.9%
• Makefile 0.1%

You can’t perform that action at this time.