Skip to main content

A Python GraphQL client.

Project description

travis coveralls pypi version commit

kirjava is a Python GraphQL client.


>>> import kirjava
>>> client = kirjava.Client("")
>>> client.execute("""{ me { name email }}""")
{'data': {'me': {'name': 'Jon Snow', 'email': ''}}}



kirjava can be installed using pip:

$ pip3 install kirjava

If you get permission errors, try using sudo:

$ sudo pip3 install kirjava

Or alternatively, consider using a virtual environment.


The repository for kirjava, containing the most recent iteration, can be found here. To clone the kirjava repository directly from there, use:

$ git clone git://


kirjava requires requests.


kirjava is a lightweight Python GraphQL client.

Making Queries with a Client

GraphQL services are interacted with using a Client object:

>>> import kirjava
>>> client = kirjava.Client("")

The client is associated with a particular URL upon creation.

Queries are then made using the execute method.

>>> client.execute("{ me { name email }}")
{'data': {'me': {'name': 'Jon Snow', 'email': ''}}}

If authentication tokens need to be added, they can be inserted into the headers:

>>> client.headers["Authorization"] = "dani123"

Variables can be passed along with the query:

>>> client.execute("{ me { name email }}", variables={"var1": 123})

You can instruct the client to retry failed requests:

>>> client.execute("{ me { name email }}", retries=3, retry_statuses=[500, 502, 503, 504])

You can see all previous queries made by a client:

>>> client.history
(({'string': { me { name email }}, 'variables': {'var1': 123}, {'data': {'me
': {'name': 'Jon Snow', 'email': ''}}}), ({'string': {
me { name email }}, 'variables': {}}, {'data': {'me': {'name': 'Jon Snow', '
email': ''}}}))

Clients use requests sessions internally, and you can access any cookies set by the server via client.session.cookies.

Uploading Files

If you want to upload files as part of your request, kirjava can do this. Just add them as a variable:

>>> mutation = "mutation sendFile($file: Upload) {sendFile(file: $file) { success }}"
>>> f = open("local_file.txt", "rb"):
>>> response = client.execute(mutation, variables={"file": f})
>>> f.close()

kirjava does this by implementing the GraphQL multipart request specification under the hood, and using this if any of the variables supplied are Python file objects.

Note that the GraphQL server on the other end must be set up to process multipart requests.

Making Queries without a Client

Alternatively, if creating a dedicated Client object is somehow beneath you, and you just want to fire off a quick request without any of that overhead, there is a module level execute function:

>>> kirjava.execute("", "{ me { name email }}", headers={"Authorization": "dani123"}, variables={"var1": 123})


Release 0.4.0

21 August 2023

  • You can retry failed requests.

Release 0.3.0

6 August 2020

  • File upload array type now supported.

Release 0.2.0

11 December 2020

  • Implements GraphQL multipart request specification to allow file upload.

  • Refactored into full package.

Release 0.1.3

16 November 2020

  • Provides access to requests cookie jar.

  • Better handling of non-JSON responses.

Release 0.1.2

1 April 2019

  • Added module-level execute function.

Release 0.1.1

30 March 2019

  • Added tests.

  • Clients now store history of their queries.

Release 0.1.0

23 March 2019

  • Created basic Client.

Project details

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distributions

No source distribution files available for this release. See tutorial on generating distribution archives.

Built Distribution

kirjava-0.4.0-py3-none-any.whl (7.9 kB view hashes)

Uploaded py3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page