Skip to main content

Capable GraphQL client

Project description


.. raw:: html

<p align="center">

<img src="https://raw.githubusercontent.com/ariebovenberg/quiz/master/docs/_static/quiz-logo.png" height="150">

<br/>

<a href="https://travis-ci.org/ariebovenberg/quiz" class="reference external image-reference">
<img src="https://img.shields.io/travis/ariebovenberg/quiz.svg?style=flat-square&logo=travis" alt="Build status">
</a>

<a href="https://codecov.io/gh/ariebovenberg/quiz" class="reference external image-reference">
<img src="https://img.shields.io/codecov/c/github/ariebovenberg/quiz.svg?style=flat-square&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAaCAMAAACaYWzBAAABX1BMVEUAAAD///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////8P/Ub/AAAAdHRSTlMAAQIDBAUGBw0PERIVFhcZGhsgISQmKSorLS8zODk6PUFDR0lLTE1YXF5fYGRlaHB1dnd4eXt/g4eKjJKVlpeYmZqcnqOkpaanqqusrq+xsrW3ubu8vb7Hzc7Q1dfZ3N3e3+Dh4ujp6uzt7/Hz9fb3+Pv9/mHMvTIAAAFPSURBVHgBbdDXcxJRGIbx55zvnI1ijJI1YuxiEkWNsRjsKPYiFuxFsRdREH3//5Hd2YvMLL/bZ76L9yMTYe74o95g+L57qgaRQiC9qbF+X2N35zBHxmj80bC9mFYqs/sv/NLfZXxWAiekq5soTLekJgaRw9IyxOCd8yHCIekoEbaMdITEKFhCQ/9qwB1dIWGNhIu6D9s0qDJlnoIPU8z0tZ1VXSITDMACmfNq8liL0/X6jnXgIcCGXUsLmxf0jA96q7Fv7RQz5m/kI9/pI1+lTw/vvZC0F1YkPb/V6Uk/0Ot6ANJrn2c4KbVmAbfvlTgNmDmosidf6s2AVYpnmoenOlssjUBw5Iyt+lnByLkAhchB3SZQEjmmM8RJYUXnJoXAkp5glHg2/laNZNLJZXUh8a588l3XHWWB3SO9aVTXW7nMv5TUwblS4cCDLzsx4D/omEB2BXPuawAAAABJRU5ErkJggg==" alt="Test coverage">
</a>

<img src="https://img.shields.io/badge/dependabot-enabled-brightgreen.svg?longCache=true&logo=dependabot&style=flat-square" alt="Dependabot">

<a href="http://quiz.readthedocs.io/" class="reference external image-reference">
<img src="https://img.shields.io/readthedocs/quiz.svg?style=flat-square&logo=read-the-docs&logoColor=white" alt="Documentation status">
</a>

<br/>

<a href="https://pypi.python.org/pypi/quiz" class="reference external image-reference">
<img src="https://img.shields.io/pypi/status/quiz.svg?style=flat-square&colorB=orange&logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAABgAAAAYCAMAAADXqc3KAAABIFBMVEUAAAAAAAD///+AgID///+qqqr////////////V1dX///////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////////9biOZSAAAAX3RSTlMAAQECAgMDBAUGBggJCg4QERITFBceICQpLC0uMDM0QUJFRkdISktPUlNUXF5hbW5vcHZ7fYCBgoSGjI+Ql5iam6Cio6SlsLW5u73CxcjK1Nvd3+3z9Pb3+Pn6+/z9/ugrIWMAAAEFSURBVHgBZc7nUupgGEXhRQ4niVHArtgFFcTeiwKigtg7BkT2/d+FI6Lmmzwz+ZHsyZqXEMt8sadz2Uwmu5juNhaXCXXM4xl/9CxcaHtNt9kEUYJsNjWIikQwuexrfEBl3NCwq9G4znAwOex8DaehwWNPY706x8MQJf5c6488aRgHs3SiFUipyj/LCM3oiohLSUt4wdD/B41gWyReX/qwjVu3iNl2jGWVcP6+J3VNR1kpvJ8QN7o8KuYLhXzxuKLHrk7MY12+fr3pEBfAZqimZtOvt/nvH9IUTrtUUV0BDd2BhUtOjVaQfG3g4lBVvWVo6B5wWFXIwfddyblZQ3oSLNpPiMUn8+xFVjc7sxcAAAAASUVORK5CYII=&logoColor=white" alt="Development status">
</a>

<a href="https://pypi.python.org/pypi/quiz" class="reference external image-reference">
<img src="https://img.shields.io/pypi/v/quiz.svg?style=flat-square&logo=python&logoColor=white" alt="Latest version">
</a>

<a href="https://pypi.python.org/pypi/quiz" class="reference external image-reference">
<img src="https://img.shields.io/pypi/l/quiz.svg?style=flat-square&logo=github&logoColor=white&colorB=blue" alt="License">
</a>

<a href="https://pypi.python.org/pypi/quiz" class="reference external image-reference">
<img src="https://img.shields.io/pypi/pyversions/quiz.svg?style=flat-square&logo=python&logoColor=white" alt="Supported python versions">
</a>

</p>


Quiz
====

Capable GraphQL client for Python.

Features:

* Sync/async compatible, pluggable HTTP clients.
* Auto-generate typed and documented python APIs
* ORM-like syntax to write GraphQL.

Note that this project is in an early alpha stage.
Some features are not yet implemented (see the roadmap below),
and it may be a little rough around the edges.
If you encounter a problem or have a feature request,
don't hesitate to open an issue in the `issue tracker <https://github.com/ariebovenberg/quiz/issues>`_.


Quickstart
----------

A quick 'n dirty request to GitHub's new V4 API:

.. code-block:: python3

>>> import quiz
>>> query = '''
... {
... repository(owner: "octocat", name: "Hello-World") {
... createdAt
... description
... }
... }
... '''
>>> quiz.execute(query, url='https://api.github.com/graphql',
... auth=('me', 'password'))
{"repository": ...}


Features
--------

1. **Adaptability**. Built on top of `snug <http://snug.readthedocs.io/>`_,
quiz supports different HTTP clients

.. code-block:: python3

import requests
result = quiz.execute(query, ..., client=requests.Session())

as well as async execution
(optionally with `aiohttp <http:aiohttp.readthedocs.io/>`_):

.. code-block:: python3

result = await quiz.execute_async(query, ...)

2. **Typing**.
Convert a GraphQL schema into documented python classes:

.. code-block:: python3

>>> schema = quiz.Schema.from_url('https://api.github.com/graphql',
... auth=('me', 'password'))
>>> help(schema.Repository)
class Repository(Node, ProjectOwner, Subscribable, Starrable,
UniformResourceLocatable, RepositoryInfo, quiz.types.Object)
| A repository contains the content for a project.
|
| Method resolution order:
| ...
|
| Data descriptors defined here:
|
| assignableUsers
| : UserConnection
| A list of users that can be assigned to issues in this repo
|
| codeOfConduct
| : CodeOfConduct or None
| Returns the code of conduct for this repository
...


3. **GraphQL "ORM"**. Write queries as you would with an ORM:

.. code-block:: python3

>>> _ = quiz.SELECTOR
>>> query = schema.query[
... _
... .repository(owner='octocat', name='Hello-World')[
... _
... .createdAt
... .description
... ]
... ]
>>> str(query)
query {
repository(owner: "octocat", name: "Hello-World") {
createdAt
description
}
}

4. **Offline query validation**. Use the schema to catch errors quickly:

.. code-block:: python3

>>> schema.query[
... _
... .repository(owner='octocat', name='Hello-World')[
... _
... .createdAt
... .foo
... .description
... ]
... ]
SelectionError: SelectionError on "Query" at path "repository":

SelectionError: SelectionError on "Repository" at path "foo":

NoSuchField: field does not exist

5. **Deserialization into python objects**. Responses are loaded into the schema's types.
Use ``.`` to access fields:

.. code-block:: python3

>>> r = quiz.execute(query, ...)
>>> r.repository.description
"My first repository on GitHub!"
>>> isinstance(r.repository, schema.Repository)
True

If you prefer the raw JSON response, you can always do:

.. code-block:: python3

>>> quiz.execute(str(query), ...)
{"repository": ...}


Installation
------------

``quiz`` and its dependencies are pure python. Installation is easy as:

.. code-block:: bash

pip install quiz


Contributing
------------

After you've cloned the repo locally, set up the development environment
with:

.. code-block:: bash

make init

For quick test runs, run:

.. code-block:: bash

pytest

To run all tests and checks on various python versions, run:

.. code-block:: bash

make test

Generate the docs with:

.. code-block:: bash

make docs


Pull requests welcome!


Preliminary roadmap
-------------------

================================================================== ===========
Feature status
================================================================== ===========
Input objects v0.2.0
better query validation errors v0.2.0
more examples in docs v0.2.0
executing selection sets directly v0.2.0
introspection fields (i.e. ``__typename``) v0.2.0
custom scalars for existing types (e.g. ``datetime``) v0.2.0
improve Object/Interface API v0.2.0
value object docs v0.2.0
Mutations & subscriptions v0.2.0
Inline fragments v0.2.0
Fragments and fragment spreads v0.3.0
py2 unicode robustness v0.3.0
Mixing in raw GraphQL planned
Module autogeneration planned
Type inference (e.g. enum values) planned
Variables planned
Directives planned
Integer 32-bit limit planned
converting names from camelcase to snake-case idea
Autogenerate module .rst from schema idea
Autogenerate module .py from schema idea
Escaping python keywords idea
Handling markdown in descriptions idea
Warnings when using deprecated fields idea
Handle optional types descriptions in schema idea
Returning multiple validation errors at the same time idea
Explicit ordering idea
================================================================== ===========


Release history
---------------

development
+++++++++++

0.1.6 (2019-04-07)
++++++++++++++++++

- Drop python 3.4 suport

0.1.5 (2019-03-16)
++++++++++++++++++

- Include request/response metadata in responses (#95)

0.1.4 (2019-03-05)
++++++++++++++++++

- Fixed issue with single-type unions (#100)

0.1.3 (2019-02-16)
++++++++++++++++++

- Add request context to `HTTPError` (#82)

0.1.2 (2019-01-11)
++++++++++++++++++

- Handle error responses without ``data`` correctly

0.1.1 (2018-10-30)
++++++++++++++++++

- Fixed deserialization of ``Enum`` values

0.1.0 (2018-10-30)
++++++++++++++++++

- Fixed handling of HTTP error status codes (#10)
- Fix in validation exceptions (#11)
- Implement custom scalars
- Improvements to documentation

0.0.4 (2018-10-17)
++++++++++++++++++

- Remove some unneeded fields from introspection query
- Improvements to documentation
- Small fixes to API, tests

0.0.3 (2018-09-23)
++++++++++++++++++

- Established initial public API
- Improved documentation, user guide
- Field aliases
- Deserialization

0.0.2 (2018-08-21)
++++++++++++++++++

- Execution of basic GraphQL queries
- Convert GraphQL schema to python types (undocumented)
- Write GraphQL in python syntax (undocumented)

0.0.1
+++++

- initial version


Project details


Download files

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

Source Distribution

quiz-0.1.6.tar.gz (27.9 kB view details)

Uploaded Source

Built Distribution

quiz-0.1.6-py3-none-any.whl (25.8 kB view details)

Uploaded Python 3

File details

Details for the file quiz-0.1.6.tar.gz.

File metadata

  • Download URL: quiz-0.1.6.tar.gz
  • Upload date:
  • Size: 27.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.9.1 tqdm/4.30.0 CPython/3.7.2

File hashes

Hashes for quiz-0.1.6.tar.gz
Algorithm Hash digest
SHA256 16aec114c388dbeef17c448d937393607927520742c0e08aaf1eb8068babab34
MD5 62b3b4c330d067bb01564f8553595d26
BLAKE2b-256 97588cfba87cf6fe18d39838486957e36d2dd5251bfa91010437b8f7aadc5b16

See more details on using hashes here.

File details

Details for the file quiz-0.1.6-py3-none-any.whl.

File metadata

  • Download URL: quiz-0.1.6-py3-none-any.whl
  • Upload date:
  • Size: 25.8 kB
  • Tags: Python 3
  • Uploaded using Trusted Publishing? No
  • Uploaded via: twine/1.13.0 pkginfo/1.5.0.1 requests/2.21.0 setuptools/40.6.2 requests-toolbelt/0.9.1 tqdm/4.30.0 CPython/3.7.2

File hashes

Hashes for quiz-0.1.6-py3-none-any.whl
Algorithm Hash digest
SHA256 9feb4a3bfa716adee08daf0d3604c63cff4750e422d16de234bd0bcc3c703366
MD5 f61094d6c4fb2b093e6132e1e2096d8f
BLAKE2b-256 46aae7c748cd69ad56f23109683023cb166568ea76fbf417f03f848f79c354ab

See more details on using hashes here.

Supported by

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