# GraphQL-core 3
GraphQL-core 3 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.
[](https://badge.fury.io/py/graphql-core)
[](https://graphql-core-3.readthedocs.io)
[](https://github.com/ambv/black)
The current version 3.2.5 of GraphQL-core is up-to-date with GraphQL.js version 16.8.2.
An extensive test suite with over 2300 unit tests and 100% coverage comprises a
replication of the complete test suite of GraphQL.js, making sure this port is
reliable and compatible with GraphQL.js.
Note that for various reasons, GraphQL-core does not use SemVer like GraphQL.js. Increases in the major version of GraphQL.js are reflected in the minor version of GraphQL-core instead. This means there can be breaking changes in the API when the minor version changes, and only patch releases are fully backward compatible. Therefore, we recommend something like `=~ 3.2.0` as version specifier when including GraphQL-core as a dependency.
## Documentation
A more detailed documentation for GraphQL-core 3 can be found at
[graphql-core-3.readthedocs.io](https://graphql-core-3.readthedocs.io/).
The documentation for GraphQL.js can be found at [graphql.org/graphql-js/](https://graphql.org/graphql-js/).
The documentation for GraphQL itself can be found at [graphql.org](https://graphql.org/).
There will be also [blog articles](https://cito.github.io/tags/graphql/) with more usage
examples.
## Getting started
A general overview of GraphQL is available in the
[README](https://github.com/graphql/graphql-spec/blob/main/README.md) for the
[Specification for GraphQL](https://github.com/graphql/graphql-spec). 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 3 can be installed from PyPI using the built-in pip command:
python -m pip install graphql-core
You can also use [poetry](https://github.com/python-poetry/poetry) for installation in a
virtual environment:
poetry install
## Usage
GraphQL-core 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 codebase:
```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
source = '{ hello }'
print(graphql_sync(schema, source))
```
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
source = '{ BoyHowdy }'
print(graphql_sync(schema, source))
```
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)
asyncio.run(main())
```
## Goals and restrictions
GraphQL-core 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.
GraphQL-core 3 (formerly known as GraphQL-core-next) has been created as a modern
alternative to [GraphQL-core 2](https://github.com/graphql-python/graphql-core-legacy),
a prior work by Syrus Akbary, based on an older version of GraphQL.js and also
targeting older Python versions. Some parts of GraphQL-core 3 have been inspired by
GraphQL-core 2 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.
Design goals for the GraphQL-core 3 library were:
* to be a simple, cruft-free, state-of-the-art GraphQL implementation for current
Python versions
* to be very close to the GraphQL.js reference implementation, while still providing
a 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 use [black](https://github.com/ambv/black) to achieve a consistent code style
while saving time and mental energy for more important matters
* to replicate the complete Mocha-based test suite of GraphQL.js
using [pytest](https://docs.pytest.org/)
with [pytest-describe](https://pypi.org/project/pytest-describe/)
Some restrictions (mostly in line with the design goals):
* requires Python 3.6 or newer
* 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 amazing [ruff](https://docs.astral.sh/ruff/) tool
to both format and check the code of GraphQL-core 3,
in addition to using [mypy](https://mypy-lang.org/) as type checker.
## Integration with other libraries and roadmap
* [Graphene](http://graphene-python.org/) is a more high-level framework for building
GraphQL APIs in Python, and there is already a whole ecosystem of libraries, server
integrations and tools built on top of Graphene. Most of this Graphene ecosystem has
also been created by Syrus Akbary, who meanwhile has handed over the maintenance
and 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](https://github.com/mirumee/ariadne) is a Python library for implementing
GraphQL servers using schema-first approach created by Mirumee Software.
Ariadne is also using GraphQL-core 3 as its GraphQL implementation.
* [Strawberry](https://github.com/strawberry-graphql/strawberry), created by Patrick
Arminio, is a new GraphQL library for Python 3, inspired by dataclasses,
that is also using GraphQL-core 3 as underpinning.
## Changelog
Changes are tracked as
[GitHub releases](https://github.com/graphql-python/graphql-core/releases).
## Credits and history
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 others
at Facebook, Inc. and is now maintained
by the [GraphQL foundation](https://gql.foundation/join/)
Please watch the recording of Lee Byron's short keynote on the
[history of GraphQL](https://www.youtube.com/watch?v=VjHWkBr3tjI)
at the open source leadership summit 2019 to better understand
how and why GraphQL was created at Facebook and then became open sourced
and ported to many different programming languages.
## License
GraphQL-core 3 is
[MIT-licensed](./LICENSE),
just like GraphQL.js.
Raw data
{
"_id": null,
"home_page": "https://github.com/graphql-python/graphql-core",
"name": "graphql-core",
"maintainer": null,
"docs_url": null,
"requires_python": "<4,>=3.6",
"maintainer_email": null,
"keywords": "graphql",
"author": "Christoph Zwerschke",
"author_email": "cito@online.de",
"download_url": "https://files.pythonhosted.org/packages/2e/b5/ebc6fe3852e2d2fdaf682dddfc366934f3d2c9ef9b6d1b0e6ca348d936ba/graphql_core-3.2.5.tar.gz",
"platform": null,
"description": "# GraphQL-core 3\n\nGraphQL-core 3 is a Python 3.6+ port of [GraphQL.js](https://github.com/graphql/graphql-js),\nthe JavaScript reference implementation for [GraphQL](https://graphql.org/),\na query language for APIs created by Facebook.\n\n[](https://badge.fury.io/py/graphql-core)\n[](https://graphql-core-3.readthedocs.io)\n\n\n[](https://github.com/ambv/black)\n\nThe current version 3.2.5 of GraphQL-core is up-to-date with GraphQL.js version 16.8.2.\n\nAn extensive test suite with over 2300 unit tests and 100% coverage comprises a\nreplication of the complete test suite of GraphQL.js, making sure this port is\nreliable and compatible with GraphQL.js.\n\nNote that for various reasons, GraphQL-core does not use SemVer like GraphQL.js. Increases in the major version of GraphQL.js are reflected in the minor version of GraphQL-core instead. This means there can be breaking changes in the API when the minor version changes, and only patch releases are fully backward compatible. Therefore, we recommend something like `=~ 3.2.0` as version specifier when including GraphQL-core as a dependency.\n\n\n## Documentation\n\nA more detailed documentation for GraphQL-core 3 can be found at\n[graphql-core-3.readthedocs.io](https://graphql-core-3.readthedocs.io/).\n\nThe documentation for GraphQL.js can be found at [graphql.org/graphql-js/](https://graphql.org/graphql-js/).\n\nThe documentation for GraphQL itself can be found at [graphql.org](https://graphql.org/).\n\nThere will be also [blog articles](https://cito.github.io/tags/graphql/) with more usage\nexamples.\n\n\n## Getting started\n\nA general overview of GraphQL is available in the\n[README](https://github.com/graphql/graphql-spec/blob/main/README.md) for the\n[Specification for GraphQL](https://github.com/graphql/graphql-spec). That overview\ndescribes a simple set of GraphQL examples that exist as [tests](tests) in this\nrepository. A good way to get started with this repository is to walk through that\nREADME and the corresponding tests in parallel.\n\n\n## Installation\n\nGraphQL-core 3 can be installed from PyPI using the built-in pip command:\n\n python -m pip install graphql-core\n\nYou can also use [poetry](https://github.com/python-poetry/poetry) for installation in a\nvirtual environment:\n\n poetry install\n\n\n## Usage\n\nGraphQL-core provides two important capabilities: building a type schema and\nserving queries against that type schema.\n\nFirst, build a GraphQL type schema which maps to your codebase:\n\n```python\nfrom graphql import (\n GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString)\n\nschema = GraphQLSchema(\n query=GraphQLObjectType(\n name='RootQueryType',\n fields={\n 'hello': GraphQLField(\n GraphQLString,\n resolve=lambda obj, info: 'world')\n }))\n```\n\nThis defines a simple schema, with one type and one field, that resolves to a fixed\nvalue. The `resolve` function can return a value, a co-routine object or a list of\nthese. It takes two positional arguments; the first one provides the root or the\nresolved parent field, the second one provides a `GraphQLResolveInfo` object which\ncontains information about the execution state of the query, including a `context`\nattribute holding per-request state such as authentication information or database\nsession. Any GraphQL arguments are passed to the `resolve` functions as individual\nkeyword arguments.\n\nNote that the signature of the resolver functions is a bit different in GraphQL.js,\nwhere the context is passed separately and arguments are passed as a single object.\nAlso note that GraphQL fields must be passed as a `GraphQLField` object explicitly.\nSimilarly, GraphQL arguments must be passed as `GraphQLArgument` objects.\n\nA more complex example is included in the top-level [tests](tests) directory.\n\nThen, serve the result of a query against that type schema.\n\n```python\nfrom graphql import graphql_sync\n\nsource = '{ hello }'\n\nprint(graphql_sync(schema, source))\n```\n\nThis runs a query fetching the one field defined, and then prints the result:\n\n```python\nExecutionResult(data={'hello': 'world'}, errors=None)\n```\n\nThe `graphql_sync` function will first ensure the query is syntactically and\nsemantically valid before executing it, reporting errors otherwise.\n\n```python\nfrom graphql import graphql_sync\n\nsource = '{ BoyHowdy }'\n\nprint(graphql_sync(schema, source))\n```\n\nBecause we queried a non-existing field, we will get the following result:\n\n```python\nExecutionResult(data=None, errors=[GraphQLError(\n \"Cannot query field 'BoyHowdy' on type 'RootQueryType'.\",\n locations=[SourceLocation(line=1, column=3)])])\n```\n\nThe `graphql_sync` function assumes that all resolvers return values synchronously. By\nusing coroutines as resolvers, you can also create results in an asynchronous fashion\nwith the `graphql` function.\n\n```python\nimport asyncio\nfrom graphql import (\n graphql, GraphQLSchema, GraphQLObjectType, GraphQLField, GraphQLString)\n\n\nasync def resolve_hello(obj, info):\n await asyncio.sleep(3)\n return 'world'\n\nschema = GraphQLSchema(\n query=GraphQLObjectType(\n name='RootQueryType',\n fields={\n 'hello': GraphQLField(\n GraphQLString,\n resolve=resolve_hello)\n }))\n\n\nasync def main():\n query = '{ hello }'\n print('Fetching the result...')\n result = await graphql(schema, query)\n print(result)\n\n\nasyncio.run(main())\n```\n\n\n## Goals and restrictions\n\nGraphQL-core tries to reproduce the code of the reference implementation GraphQL.js\nin Python as closely as possible and to stay up-to-date with the latest development of\nGraphQL.js.\n\nGraphQL-core 3 (formerly known as GraphQL-core-next) has been created as a modern\nalternative to [GraphQL-core 2](https://github.com/graphql-python/graphql-core-legacy),\na prior work by Syrus Akbary, based on an older version of GraphQL.js and also\ntargeting older Python versions. Some parts of GraphQL-core 3 have been inspired by\nGraphQL-core 2 or directly taken over with only slight modifications, but most of the\ncode has been re-implemented from scratch, replicating the latest code in GraphQL.js\nvery closely and adding type hints for Python.\n\nDesign goals for the GraphQL-core 3 library were:\n\n* to be a simple, cruft-free, state-of-the-art GraphQL implementation for current\n Python versions\n* to be very close to the GraphQL.js reference implementation, while still providing\n a Pythonic API and code style\n* to make extensive use of Python type hints, similar to how GraphQL.js used Flow\n (and is now using TypeScript)\n* to use [black](https://github.com/ambv/black) to achieve a consistent code style\n while saving time and mental energy for more important matters\n* to replicate the complete Mocha-based test suite of GraphQL.js\n using [pytest](https://docs.pytest.org/)\n with [pytest-describe](https://pypi.org/project/pytest-describe/)\n\nSome restrictions (mostly in line with the design goals):\n\n* requires Python 3.6 or newer\n* does not support some already deprecated methods and options of GraphQL.js\n* supports asynchronous operations only via async.io\n (does not support the additional executors in GraphQL-core)\n\nNote that meanwhile we are using the amazing [ruff](https://docs.astral.sh/ruff/) tool\nto both format and check the code of GraphQL-core 3,\nin addition to using [mypy](https://mypy-lang.org/) as type checker.\n\n\n## Integration with other libraries and roadmap\n\n* [Graphene](http://graphene-python.org/) is a more high-level framework for building\n GraphQL APIs in Python, and there is already a whole ecosystem of libraries, server\n integrations and tools built on top of Graphene. Most of this Graphene ecosystem has\n also been created by Syrus Akbary, who meanwhile has handed over the maintenance\n and future development to members of the GraphQL-Python community.\n\n Graphene 3 is now using Graphql-core 3 as core library for much of the heavy lifting.\n\n* [Ariadne](https://github.com/mirumee/ariadne) is a Python library for implementing\n GraphQL servers using schema-first approach created by Mirumee Software.\n\n Ariadne is also using GraphQL-core 3 as its GraphQL implementation.\n\n* [Strawberry](https://github.com/strawberry-graphql/strawberry), created by Patrick\n Arminio, is a new GraphQL library for Python 3, inspired by dataclasses,\n that is also using GraphQL-core 3 as underpinning.\n\n\n## Changelog\n\nChanges are tracked as\n[GitHub releases](https://github.com/graphql-python/graphql-core/releases).\n\n\n## Credits and history\n\nThe GraphQL-core 3 library\n\n* has been created and is maintained by Christoph Zwerschke\n* uses ideas and code from GraphQL-core 2, a prior work by Syrus Akbary\n* is a Python port of GraphQL.js which has been developed by Lee Byron and others\n at Facebook, Inc. and is now maintained\n by the [GraphQL foundation](https://gql.foundation/join/)\n\nPlease watch the recording of Lee Byron's short keynote on the\n[history of GraphQL](https://www.youtube.com/watch?v=VjHWkBr3tjI)\nat the open source leadership summit 2019 to better understand\nhow and why GraphQL was created at Facebook and then became open sourced\nand ported to many different programming languages.\n\n\n## License\n\nGraphQL-core 3 is\n[MIT-licensed](./LICENSE),\njust like GraphQL.js.\n",
"bugtrack_url": null,
"license": "MIT license",
"summary": "GraphQL implementation for Python, a port of GraphQL.js, the JavaScript reference implementation for GraphQL.",
"version": "3.2.5",
"project_urls": {
"Homepage": "https://github.com/graphql-python/graphql-core"
},
"split_keywords": [
"graphql"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "e3dc078bd6b304de790618ebb95e2aedaadb78f4527ac43a9ad8815f006636b6",
"md5": "b104f947eefe4e07d828815195f37453",
"sha256": "2f150d5096448aa4f8ab26268567bbfeef823769893b39c1a2e1409590939c8a"
},
"downloads": -1,
"filename": "graphql_core-3.2.5-py3-none-any.whl",
"has_sig": false,
"md5_digest": "b104f947eefe4e07d828815195f37453",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": "<4,>=3.6",
"size": 203189,
"upload_time": "2024-10-13T18:24:30",
"upload_time_iso_8601": "2024-10-13T18:24:30.384257Z",
"url": "https://files.pythonhosted.org/packages/e3/dc/078bd6b304de790618ebb95e2aedaadb78f4527ac43a9ad8815f006636b6/graphql_core-3.2.5-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2eb5ebc6fe3852e2d2fdaf682dddfc366934f3d2c9ef9b6d1b0e6ca348d936ba",
"md5": "aa921d596e69d898de2fba2899bc6b01",
"sha256": "e671b90ed653c808715645e3998b7ab67d382d55467b7e2978549111bbabf8d5"
},
"downloads": -1,
"filename": "graphql_core-3.2.5.tar.gz",
"has_sig": false,
"md5_digest": "aa921d596e69d898de2fba2899bc6b01",
"packagetype": "sdist",
"python_version": "source",
"requires_python": "<4,>=3.6",
"size": 504664,
"upload_time": "2024-10-13T18:24:32",
"upload_time_iso_8601": "2024-10-13T18:24:32.134024Z",
"url": "https://files.pythonhosted.org/packages/2e/b5/ebc6fe3852e2d2fdaf682dddfc366934f3d2c9ef9b6d1b0e6ca348d936ba/graphql_core-3.2.5.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-10-13 18:24:32",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "graphql-python",
"github_project": "graphql-core",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"tox": true,
"lcname": "graphql-core"
}
JSON
