Metadata-Version: 2.1
Name: GraphQL-core-next
Version: 1.0.0
Summary: GraphQL-core-next is a Python port of GraphQL.js, the JavaScript reference implementation for GraphQL.
Home-page: https://github.com/graphql-python/graphql-core-next
Author: Christoph Zwerschke
Author-email: cito@online.de
License: MIT license
Keywords: graphql
Platform: UNKNOWN
Classifier: Development Status :: 5 - Production/Stable
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=3.6
Description-Content-Type: text/markdown

# GraphQL-core-next

GraphQL-core-next is a Python 3.6+ port of [GraphQL.js](https://github.com/graphql/graphql-js),
the JavaScript reference implementation for [GraphQL](https://graphql.org/),
a query language for APIs created by Facebook.

[![PyPI version](https://badge.fury.io/py/GraphQL-core-next.svg)](https://badge.fury.io/py/GraphQL-core-next)
[![Documentation Status](https://readthedocs.org/projects/graphql-core-next/badge/)](https://graphql-core-next.readthedocs.io)
[![Build Status](https://travis-ci.com/graphql-python/graphql-core-next.svg?branch=master)](https://travis-ci.com/graphql-python/graphql-core-next)
[![Coverage Status](https://coveralls.io/repos/github/graphql-python/graphql-core-next/badge.svg?branch=master)](https://coveralls.io/github/graphql-python/graphql-core-next?branch=master)
[![Dependency Updates](https://pyup.io/repos/github/graphql-python/graphql-core-next/shield.svg)](https://pyup.io/repos/github/graphql-python/graphql-core-next/)
[![Python 3 Status](https://pyup.io/repos/github/graphql-python/graphql-core-next/python-3-shield.svg)](https://pyup.io/repos/github/graphql-python/graphql-core-next/)

The current version 1.0.0 of GraphQL-core-next is up-to-date with GraphQL.js
version 14.0.0. All parts of the API are covered by an extensive test suite of
currently 1603 unit tests.


## Documentation

A more detailed documentation for GraphQL-core-next can be found at
[graphql-core-next.readthedocs.io](https://graphql-core-next.readthedocs.io/).

There will be also [blog articles](https://cito.github.io/tags/graphql/)
with more usage examples.


## Getting started

An overview of GraphQL in general is available in the
[README](https://github.com/facebook/graphql/blob/master/README.md) for the
[Specification for GraphQL](https://github.com/facebook/graphql). That overview
describes a simple set of GraphQL examples that exist as [tests](tests)
in this repository. A good way to get started with this repository is to walk
through that README and the corresponding tests in parallel.


## Installation

GraphQL-core-next can be installed from PyPI using the built-in pip command:

    python -m pip install graphql-core-next

Alternatively, you can also use [pipenv](https://docs.pipenv.org/) for
installation in a virtual environment:

    pipenv install graphql-core-next


## Usage

GraphQL-core-next provides two important capabilities: building a type schema,
and serving queries against that type schema.

First, build a GraphQL type schema which maps to your code base:

```python
from graphql import (
    GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString)

schema = GraphQLSchema(
    query=GraphQLObjectType(
        name='RootQueryType',
        fields={
            'hello': GraphQLField(
                GraphQLString,
                resolve=lambda obj, info: 'world')
        }))
```

This defines a simple schema with one type and one field, that resolves
to a fixed value. The `resolve` function can return a value, a co-routine
object or a list of these. It takes two positional arguments; the first one
provides the root or the resolved parent field, the second one provides a
`GraphQLResolveInfo` object which contains information about the execution
state of the query, including a `context` attribute holding per-request state
such as authentication information or database session. Any GraphQL arguments
are passed to the `resolve` functions as individual keyword arguments.

Note that the signature of the resolver functions is a bit different in
GraphQL.js, where the context is passed separately and arguments are passed
as a single object. Also note that GraphQL fields must be passed as a
`GraphQLField` object explicitly. Similarly, GraphQL arguments must be
passed as `GraphQLArgument` objects.

A more complex example is included in the top level [tests](tests) directory.

Then, serve the result of a query against that type schema.

```python
from graphql import graphql_sync

query = '{ hello }'

print(graphql_sync(schema, query))
```

This runs a query fetching the one field defined, and then prints the result:

```python
ExecutionResult(data={'hello': 'world'}, errors=None)
```

The `graphql_sync` function will first ensure the query is syntactically
and semantically valid before executing it, reporting errors otherwise.

```python
from graphql import graphql_sync

query = '{ boyhowdy }'

print(graphql_sync(schema, query))
```

Because we queried a non-existing field, we will get the following result:

```python
ExecutionResult(data=None, errors=[GraphQLError(
    "Cannot query field 'boyhowdy' on type 'RootQueryType'.",
    locations=[SourceLocation(line=1, column=3)])])
```

The `graphql_sync` function assumes that all resolvers return values
synchronously. By using coroutines as resolvers, you can also create
results in an asynchronous fashion with the `graphql` function.

```python
import asyncio
from graphql import (
    graphql, GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString)


async def resolve_hello(obj, info):
    await asyncio.sleep(3)
    return 'world'

schema = GraphQLSchema(
    query=GraphQLObjectType(
        name='RootQueryType',
        fields={
            'hello': GraphQLField(
                GraphQLString,
                resolve=resolve_hello)
        }))


async def main():
    query = '{ hello }'
    print('Fetching the result...')
    result = await graphql(schema, query)
    print(result)


loop = asyncio.get_event_loop()
try:
    loop.run_until_complete(main())
finally:
    loop.close()
```


## Goals and restrictions

GraphQL-core-next tries to reproduce the code of the reference implementation
GraphQL.js in Python as closely as possible and to stay up-to-date with
the latest development of GraphQL.js.

It has been created as an alternative and potential successor to
[GraphQL-core](https://github.com/graphql-python/graphql-core),
a prior work by Syrus Akbary, based on an older version of GraphQL.js and
also targeting older Python versions. GraphQL-core also serves as as the
foundation for [Graphene](http://graphene-python.org/), a more high-level
framework for building GraphQL APIs in Python. Some parts of GraphQL-core-next
have been inspired by GraphQL-core or directly taken over with only slight
modifications, but most of the code has been re-implemented from scratch,
replicating the latest code in GraphQL.js very closely and adding type hints
for Python. Though GraphQL-core has also been updated and modernized to some
extend, it might be replaced by GraphQL-core-next in the future.

Design goals for the GraphQL-core-next library are:

* to be a simple, cruft-free, state-of-the-art implementation of GraphQL using
  current library and language versions
* to be very close to the GraphQL.js reference implementation, while still
  using a Pythonic API and code style
* making use of Python type hints, similar to how GraphQL.js makes use of Flow
* replicate the complete Mocha-based test suite of GraphQL.js using
  [pytest](https://docs.pytest.org/)

Some restrictions (mostly in line with the design goals):

* requires Python 3.6 or 3.7
* does not support some already deprecated methods and options of GraphQL.js
* supports asynchronous operations only via async.io
* does not support additional executors and middleware like GraphQL-core
  (we are considering adding middleware later though)
* the benchmarks have not yet been ported to Python


## Changelog

Changes are tracked as
[GitHub releases](https://github.com/graphql-python/graphql-core-next/releases).


## Credits

The GraphQL-core-next library
* has been created and is maintained by Christoph Zwerschke
* uses ideas and code from GraphQL-core, a prior work by Syrus Akbary
* is a Python port of GraphQL.js which has been created and is maintained
  by Facebook, Inc.


## License

GraphQL-core-next is
[MIT-licensed](https://github.com/graphql-python/graphql-core-next/blob/master/LICENSE).


