Differences from GraphQL.js
The goal of GraphQL-core 3 is to be a faithful replication of GraphQL.js, the JavaScript reference implementation for GraphQL, in Python 3, and to keep it aligned and up to date with the ongoing development of GraphQL.js. Therefore, we strive to be as compatible as possible to the original JavaScript library, sometimes at the cost of being less Pythonic than other libraries written particularly for Python. We also avoid incorporating additional features that do not exist in the JavaScript library, in order to keep the task of maintaining the Python code and keeping it in line with the JavaScript code manageable. The preferred way of getting new features into GraphQL-core is to propose and discuss them on the GraphQL.js issue tracker first, try to get them included into GraphQL.js, and from there ported to GraphQL-core.
Having said this, in a few places we allowed the API to be a bit more Pythonic than the direct equivalent would have been. We also added a few features that do not exist in the JavaScript library, mostly to support existing higher level libraries such as Graphene and the different naming conventions in Python. The most notable differences are the following:
Direct attribute access in GraphQL types
You can access
the fields of GraphQLObjectTypes, GraphQLInterfaceTypes and GraphQLInputObjectTypes,
the interfaces of GraphQLObjectTypes,
the types of GraphQLUnionTypes,
the values of GraphQLEnumTypes and
the query, mutation, subscription and type_map of GraphQLSchemas
directly as attributes, instead of using getters.
For example, to get the fields of a GraphQLObjectType obj
, you write obj.fields
instead of obj.getFields()
.
Arguments, fields and values are dictionaries
The arguments of GraphQLDirectives and GraphQLFields,
the fields of GraphQLObjectTypes, GraphQLInterfaceTypes and GraphQLInputObjectTypes, and
the values of GraphQLEnumTypes
are always Python dictionaries in GraphQL-core, while they are returned as Arrays in GraphQL.js. Also, the values of these dictionaries do not have name
attributes, since the names are already used as the keys of these dictionaries.
Shorthand notation for creating GraphQL types
The following shorthand notations are possible:
Where you need to pass a GraphQLArgumentMap, i.e. a dictionary with names as keys and GraphQLArguments as values, you can also pass GraphQLInputTypes as values. The GraphQLInputTypes are then automatically wrapped into GraphQLArguments.
Where you need to pass a GraphQLFieldMap, i.e. a dictionary with names as keys and GraphQLFields as values, you can also pass GraphQLOutputTypes as values. The GraphQLOutputTypes are then automatically wrapped into GraphQLFields.
Where you need to pass a GraphQLInputFieldMap, i.e. a dictionary with names as keys and GraphQLInputFields as values, you can also pass GraphQLInputTypes as values. The GraphQLInputTypes are then automatically wrapped into GraphQLInputFields.
Where you need to pass a GraphQLEnumValueMap, i.e. a dictionary with names as keys and GraphQLEnumValues as values, you can pass any other Python objects as values. These will be automatically wrapped into GraphQLEnumValues. You can also pass a Python Enum type as GraphQLEnumValueMap.
Custom output names of arguments and input fields
You can pass a custom out_name
argument to GraphQLArgument
and GraphQLInputField
that allows using JavaScript naming conventions (camelCase) on ingress and Python naming conventions (snake_case) on egress. This feature is used by Graphene.
Custom output types of input object types
You can also pass a custom out_type
argument to GraphQLInputObjectType
that allows conversion to any Python type on egress instead of conversion to a dictionary, which is the default. This is used to support the container feature of Graphene InputObjectTypes.
Custom middleware
The execute()
function takes an additional middleware
argument which must be a sequence of middleware functions or a MiddlewareManager
object. This feature is used by Graphene to affect the evaluation of fields using custom middleware. There has been a request to add this to GraphQL.js as well, but so far this feature only exists in GraphQL-core.
Custom execution context
The execute()
function takes an additional execution_context_class
argument which allows specifying a custom execution context class instead of the default ExecutionContext
used by GraphQL-core.
Registering special types for descriptions
Normally, descriptions for GraphQL types must be strings. However, sometimes you may want to use other kinds of objects which are not strings, but are only resolved to strings at runtime. This is possible if you register the classes of such objects with pyutils.register_description()
.
If you notice any other important differences, please let us know so that they can be either removed or listed here.