Repository files navigation

GraphQL-core 3 is a Python 3.6+ port ofGraphQL.js,the JavaScript reference implementation forGraphQL,a query language for APIs created by Facebook.

An extensive test suite with over 2500 unit tests and 100% coverage replicates thecomplete test suite of GraphQL.js, ensuring that this port is reliable and compatiblewith GraphQL.js.

The current stable version 3.2.6 of GraphQL-core is up-to-date with GraphQL.jsversion 16.8.2 and supports Python versions 3.6 to 3.13.

You can also try out the latest alpha version 3.3.0a8 of GraphQL-core,which is up-to-date with GraphQL.js version 17.0.0a3.Please note that this new minor version of GraphQL-core does not supportPython 3.6 anymore.

Note that for various reasons, GraphQL-core does not use SemVer like GraphQL.js.Changes in the major version of GraphQL.js are reflected in the minor version ofGraphQL-core instead. This means there can be breaking changes in the APIwhen the minor version changes, and only patch releases are fully backward compatible.Therefore, we recommend using something like~= 3.2.0 as the version specifierwhen including GraphQL-core as a dependency.

More detailed documentation for GraphQL-core 3 can be found atgraphql-core-3.readthedocs.io.

The documentation for GraphQL.js can be found atgraphql.org/graphql-js/.

The documentation for GraphQL itself can be found atgraphql.org.

There will be alsoblog articles with more usageexamples.

A general overview of GraphQL is available in theREADME for theSpecification for GraphQL. This overviewincludes a simple set of GraphQL examples that are also available astestsin this repository. A good way to get started with this repository is to walk throughthat README and the corresponding tests in parallel.

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

python -m pip install graphql-core

You can also usepoetry for installation in avirtual environment:

poetry install

GraphQL-core provides two important capabilities: building a type schema andserving queries against that type schema.

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

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

This defines a simple schema, with one type and one field, that resolves to a fixedvalue. Theresolve function can return a value, a co-routine object or a list ofthese. It takes two positional arguments; the first one provides the root or theresolved parent field, the second one provides aGraphQLResolveInfo object whichcontains information about the execution state of the query, including acontextattribute holding per-request state such as authentication information or databasesession. Any GraphQL arguments are passed to theresolve functions as individualkeyword 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 aGraphQLField object explicitly.Similarly, GraphQL arguments must be passed asGraphQLArgument objects.

A more complex example is included in the top-leveltests directory.

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

fromgraphqlimportgraphql_syncsource='{ hello }'print(graphql_sync(schema,source))

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

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

Thegraphql_sync function will first ensure the query is syntactically andsemantically valid before executing it, reporting errors otherwise.

fromgraphqlimportgraphql_syncsource='{ BoyHowdy }'print(graphql_sync(schema,source))

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

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

Thegraphql_sync function assumes that all resolvers return values synchronously.By using coroutines as resolvers, you can also create results in an asynchronousfashion with thegraphql function.

importasynciofromgraphqlimport (graphql,GraphQLSchema,GraphQLObjectType,GraphQLField,GraphQLString)asyncdefresolve_hello(obj,info):awaitasyncio.sleep(3)return'world'schema=GraphQLSchema(query=GraphQLObjectType(name='RootQueryType',fields={'hello':GraphQLField(GraphQLString,resolve=resolve_hello)        }))asyncdefmain():query='{ hello }'print('Fetching the result...')result=awaitgraphql(schema,query)print(result)asyncio.run(main())

GraphQL-core aims to reproduce the code of the reference implementation GraphQL.jsin Python as closely as possible while staying up-to-date with the latest developmentof GraphQL.js.

GraphQL-core 3 (formerly known as GraphQL-core-next) was created as a modernalternative toGraphQL-core 2,a prior work by Syrus Akbary based on an older version of GraphQL.js that stillsupported legacy Python versions. While some parts of GraphQL-core 3 were inspired byGraphQL-core 2 or directly taken over with slight modifications, most of the code hasbeen re-implemented from scratch. This re-implementation closely replicates the latestcode in GraphQL.js and adds type hints for Python.

Design goals for the GraphQL-core 3 library were:

• to be a simple, cruft-free, state-of-the-art GraphQL implementation for currentPython versions
• to be very close to the GraphQL.js reference implementation, while still providinga Pythonic API and code style
• to make extensive use of Python type hints, similar to how GraphQL.js used Flow(and is now using TypeScript)
• to useblack to achieve a consistent code stylewhile saving time and mental energy for more important matters(we are now usingruff instead)
• to replicate the complete Mocha-based test suite of GraphQL.jsusingpytestwithpytest-describe

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

• requires Python 3.6 or newer (Python 3.7 and newer in latest version)
• does not support some already deprecated methods and options of GraphQL.js
• supports asynchronous operations only via async.io(does not support the additional executors in GraphQL-core)

Note that meanwhile we are using the amazingruff toolto both format and check the code of GraphQL-core 3,in addition to usingmypy as type checker.

• Graphene is a more high-level framework for buildingGraphQL APIs in Python, and there is already a whole ecosystem of libraries, serverintegrations and tools built on top of Graphene. Most of this Graphene ecosystem hasalso been created by Syrus Akbary, who meanwhile has handed over the maintenanceand future development to members of the GraphQL-Python community.

  Graphene 3 is now using Graphql-core 3 as core library for much of the heavy lifting.

• Ariadne is a Python library for implementingGraphQL servers using schema-first approach created by Mirumee Software.

  Ariadne is also using GraphQL-core 3 as its GraphQL implementation.

• Strawberry, created by PatrickArminio, is a new GraphQL library for Python 3, inspired by dataclasses,that is also using GraphQL-core 3 as underpinning.

• Typed GraphQL, thin layer over GraphQL-core that uses native Python types for creating GraphQL schemas.

Changes are tracked asGitHub releases.

The GraphQL-core 3 library

• has been created and is maintained by Christoph Zwerschke
• uses ideas and code from GraphQL-core 2, a prior work by Syrus Akbary
• is a Python port of GraphQL.js which has been developed by Lee Byron and othersat Facebook, Inc. and is now maintainedby theGraphQL foundation

Please watch the recording of Lee Byron's short keynote on thehistory of GraphQLat the open source leadership summit 2019 to better understandhow and why GraphQL was created at Facebook and then became open sourcedand ported to many different programming languages.

GraphQL-core 3 isMIT-licensed,just like GraphQL.js.