1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
|
Introduction
============
`GraphQL-core-3`_ is a Python port of `GraphQL.js`_,
the JavaScript reference implementation for GraphQL_,
a query language for APIs created by Facebook.
`GraphQL`_ consists of three parts:
* A type system that you define
* A query language that you use to query the API
* An execution and validation engine
The reference implementation closely follows the `Specification for GraphQL`_
which consists of the following sections:
* Language_
* `Type System`_
* Introspection_
* Validation_
* Execution_
* Response_
This division into subsections is reflected in the :ref:`sub-packages` of
GraphQL-core 3. Each of these sub-packages implements the aspects specified in
one of the sections of the specification.
Getting started
---------------
You can install GraphQL-core 3 using pip_::
pip install graphql-core
You can also install GraphQL-core 3 with poetry_, if you prefer that::
poetry install
Now you can start using GraphQL-core 3 by importing from the top-level
:mod:`graphql` package. Nearly everything defined in the sub-packages
can also be imported directly from the top-level package.
.. currentmodule:: graphql
For instance, using the types defined in the :mod:`graphql.type` package,
you can define a GraphQL schema, like this simple one::
from graphql import (
GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString)
schema = GraphQLSchema(
query=GraphQLObjectType(
name='RootQueryType',
fields={
'hello': GraphQLField(
GraphQLString,
resolve=lambda obj, info: 'world')
}))
The :mod:`graphql.execution` package implements the mechanism for executing
GraphQL queries. The top-level :func:`graphql` and :func:`graphql_sync`
functions also parse and validate queries using the :mod:`graphql.language`
and :mod:`graphql.validation` modules.
So to validate and execute a query against our simple schema, you can do::
from graphql import graphql_sync
query = '{ hello }'
print(graphql_sync(schema, query))
This will yield the following output::
ExecutionResult(data={'hello': 'world'}, errors=None)
Reporting Issues and Contributing
---------------------------------
Please visit the `GitHub repository of GraphQL-core 3`_ if you're interested
in the current development or want to report issues or send pull requests.
.. _GraphQL: https://graphql.org/
.. _GraphQL.js: https://github.com/graphql/graphql-js
.. _GraphQL-core-3: https://github.com/graphql-python/graphql-core
.. _GitHub repository of GraphQL-core 3: https://github.com/graphql-python/graphql-core
.. _Specification for GraphQL: https://facebook.github.io/graphql/
.. _Language: https://facebook.github.io/graphql/draft/#sec-Language
.. _Type System: https://facebook.github.io/graphql/draft/#sec-Type-System
.. _Introspection: https://facebook.github.io/graphql/draft/#sec-Introspection
.. _Validation: https://facebook.github.io/graphql/draft/#sec-Validation
.. _Execution: https://facebook.github.io/graphql/draft/#sec-Execution
.. _Response: https://facebook.github.io/graphql/draft/#sec-Response
.. _pip: https://pip.pypa.io/
.. _poetry: https://github.com/python-poetry/poetry
|
