# GQL: Python GraphQL Client Library

[![Build Status](https://travis-ci.org/ekampf/cql.svg?branch=master)](https://travis-ci.org/ekampf/cql)
[![Coverage Status](https://coveralls.io/repos/github/ekampf/gql/badge.svg?branch=master)](https://coveralls.io/github/ekampf/gql?branch=master)

## Introduction

GQL is a GraphQL Client Python library intended to help Python application make GraphQL
API call while enjoying the advantages that come with GraphQL.

- **Strongly Typed** response objects (dynamically created in build time to match your query)
- **Query Validation** that checks your code's queries against the GraphQL server's schema.

## Installation

Simply install from PyPi:

```bash
pip install gql-next
```

Then go to your project folder and run `gql init`

## Quick Start

`gql` works by parsing query files (`**/*.graphql` by default) into their own Python module where
an class, named after the operation defined in the file, allows you to make that query and get a typed
response.

For example, given the following file `get_film.graphql` file:
```
query GetFilm($id: ID!) {
  film(id: $id) {
    title
    director
  }
}
```

A `get_film.py` will be created defining a `GetFilm` class:

```python
# AUTOGENERATED file. Do not Change!
from typing import Any, Callable, Mapping, List
from enum import Enum
from dataclasses import dataclass
from dataclasses_json import dataclass_json
from gql.clients import Client, AsyncIOClient


@dataclass_json
@dataclass
class GetFilm:
    @dataclass_json
    @dataclass
    class GetFilmData:
        @dataclass_json
        @dataclass
        class Film:
            title: str
            director: str
        film: Film = None

    data: GetFilmData = None
    errors: Any = None

    @classmethod
    def execute(cls, id: str, on_before_callback: Callable[[Mapping[str, str], Mapping[str, str]], None] = None) -> GetFilm:
        ...

    @classmethod
    async def execute_async(cls, id: str, on_before_callback: Callable[[Mapping[str, str], Mapping[str, str]], None] = None) -> GetFilm:
        ...
```

Allowing you to make the GraphQL query:

```python
from .get_film import GetFilm

result = GetFilm.execute('meaning_of_life')
film = result.data.film
```

*Important notes:*
* Operations defined in graphql query __must be named__ so that we can name the relevant Python Class which you can then import in your code


## How it works


### The `gql` client

#### `gql init`
Initializes a project to use GQL as client - writes a .gql.json configuration file.

#### `gql run`

Run through your project's files and compile GraphQL queries into into Python types.

#### `gql watch`

Useful during development. Listen to file changes in your project's folder and continuously
builds GraphQL queries as they change.
This allows you to:
* Immediately verify query changes you make are valid.
* Enjoy your IDE's autocomplete features on GraphQL auto-generated objects while developing
as `watch` will auto-update them as you change queries.


# Sponsors

<a href="https://ebates.com"><img src="https://opensource.ebates.com/static/images/ebates-rakuten.svg" width="250"></a>
