Package: graphql-relay
Relay Library for GraphQL PythonGraphQL-relay-py is theRelaylibrary forGraphQL-core.It allows the easy creation of Relay-compliant servers using GraphQL-core.GraphQL-Relay-Py is a Python port ofgraphql-relay-js,
while GraphQL-Core is a Python port ofGraphQL.js,
the reference implementation of GraphQL for JavaScript.Since version 3, GraphQL-Relay-Py and GraphQL-Core support Python 3.6 and above only.
For older versions of Python, you can use version 2 of these libraries.Getting StartedA basic understanding of GraphQL and of the GraphQL Python implementation is needed
to provide context for this library.An overview of GraphQL in general is available in theREADMEfor theSpecification for GraphQL.This library is designed to work with the
theGraphQL-CorePython reference implementation of a GraphQL server.An overview of the functionality that a Relay-compliant GraphQL server should provide
is in theGraphQL Relay Specificationon theRelay website.
That overview describes a simple set of examples that exist
astestsin this repository.
A good way to get started with this repository is to walk through that documentation
and the corresponding tests in this library together.Using Relay Library for GraphQL Python (graphql-core)Install Relay Library for GraphQL Pythonpipinstallgraphql-core
pipinstallgraphql-relayWhen building a schema forGraphQL,
the provided library functions can be used to simplify the creation of Relay patterns.All the functions that are explained in the following sections must be
imported from the top level of thegraphql_relaypackage, like this:fromgraphql_relayimportconnection_definitionsConnectionsHelper functions are provided for both building the GraphQL types
for connections and for implementing theresolvemethod for fields
returning those types.connection_argsreturns the arguments that fields should provide when
they return a connection type that supports bidirectional pagination.forward_connection_argsreturns the arguments that fields should provide when
they return a connection type that only supports forward pagination.backward_connection_argsreturns the arguments that fields should provide when
they return a connection type that only supports backward pagination.connection_definitionsreturns aconnection_typeand its associatededgeType, given a name and a node type.connection_from_arrayis a helper method that takes an array and the
arguments fromconnection_args, does pagination and filtering, and returns
an object in the shape expected by aconnection_type'sresolvefunction.cursor_for_object_in_connectionis a helper method that takes an array and a
member object, and returns a cursor for use in the mutation payload.offset_to_cursortakes the index of a member object in an array
and returns an opaque cursor for use in the mutation payload.cursor_to_offsettakes an opaque cursor (created withoffset_to_cursor)
and returns the corresponding array index.An example usage of these methods from thetest schema:ship_edge,ship_connection=connection_definitions(ship_type,"Ship")faction_type=GraphQLObjectType(name="Faction",description="A faction in the Star Wars saga",fields=lambda:{"id":global_id_field("Faction"),"name":GraphQLField(GraphQLString,description="The name of the faction."),"ships":GraphQLField(ship_connection,description="The ships used by the faction.",args=connection_args,resolve=lambdafaction,_info,**args:connection_from_array([get_ship(ship)forshipinfaction.ships],args),),},interfaces=[node_interface],)This shows adding ashipsfield to theFactionobject that is a connection.
It usesconnection_definitions(ship_type, "Ship")to create the connection
type, addsconnection_argsas arguments on this function, and then implements
the resolver function by passing the array of ships and the arguments toconnection_from_array.Object IdentificationHelper functions are provided for both building the GraphQL types
for nodes and for implementing global IDs around local IDs.node_definitionsreturns theNodeinterface that objects can implement,
and returns thenoderoot field to include on the query type.
To implement this, it takes a function to resolve an ID to an object,
and to determine the type of a given object.to_global_idtakes a type name and an ID specific to that type name,
and returns a "global ID" that is unique among all types.from_global_idtakes the "global ID" created byto_global_id, and
returns the type name and ID used to create it.global_id_fieldcreates the configuration for anidfield on a node.plural_identifying_root_fieldcreates a field that accepts a list of
non-ID identifiers (like a username) and maps then to their corresponding
objects.An example usage of these methods from thetest schema:defget_node(global_id,_info):type_,id_=from_global_id(global_id)iftype_=="Faction":returnget_faction(id_)iftype_=="Ship":returnget_ship(id_)returnNone# pragma: no coverdefget_node_type(obj,_info,_type):ifisinstance(obj,Faction):returnfaction_type.namereturnship_type.namenode_interface,node_field=node_definitions(get_node,get_node_type)[:2]faction_type=GraphQLObjectType(name="Faction",description="A faction in the Star Wars saga",fields=lambda:{"id":global_id_field("Faction"),"name":GraphQLField(GraphQLString,description="The name of the faction."),"ships":GraphQLField(ship_connection,description="The ships used by the faction.",args=connection_args,resolve=lambdafaction,_info,**args:connection_from_array([get_ship(ship)forshipinfaction.ships],args),),},interfaces=[node_interface],)query_type=GraphQLObjectType(name="Query",fields=lambda:{"rebels":GraphQLField(faction_type,resolve=lambda_obj,_info:get_rebels()),"empire":GraphQLField(faction_type,resolve=lambda_obj,_info:get_empire()),"node":node_field,},)This usesnode_definitionsto construct theNodeinterface and thenodefield; it usesfrom_global_idto resolve the IDs passed in the implementation
of the function mapping ID to object. It then uses theglobal_id_fieldmethod to
create theidfield onFaction, which also ensures implements thenode_interface. Finally, it adds thenodefield to the query type, using thenode_fieldreturned bynode_definitions.MutationsA helper function is provided for building mutations with
single inputs and client mutation IDs.mutation_with_client_mutation_idtakes a name, input fields, output fields,
and a mutation method to map from the input fields to the output fields,
performing the mutation along the way. It then creates and returns a field
configuration that can be used as a top-level field on the mutation type.An example usage of these methods from thetest schema:classIntroduceShipMutation:def__init__(self,shipId,factionId,clientMutationId=None):self.shipId=shipIdself.factionId=factionIdself.clientMutationId=clientMutationIddefmutate_and_get_payload(_info,shipName,factionId,**_input):new_ship=create_ship(shipName,factionId)returnIntroduceShipMutation(shipId=new_ship.id,factionId=factionId)ship_mutation=mutation_with_client_mutation_id("IntroduceShip",input_fields={"shipName":GraphQLInputField(GraphQLNonNull(GraphQLString)),"factionId":GraphQLInputField(GraphQLNonNull(GraphQLID)),},output_fields={"ship":GraphQLField(ship_type,resolve=lambdapayload,_info:get_ship(payload.shipId)),"faction":GraphQLField(faction_type,resolve=lambdapayload,_info:get_faction(payload.factionId)),},mutate_and_get_payload=mutate_and_get_payload,)mutation_type=GraphQLObjectType("Mutation",fields=lambda:{"introduceShip":ship_mutation})This code creates a mutation namedIntroduceShip, which takes a faction
ID and a ship name as input. It outputs theFactionand theShipin
question.mutate_and_get_payloadthen gets each input field as keyword
parameter, performs the mutation by constructing the new ship, then returns
an object that will be resolved by the output fields.Our mutation type then creates theintroduceShipfield using the return
value ofmutation_with_client_mutation_id.ContributingAfter cloning this repository from GitHub,
we recommend usingPoetryto create a test environment. With poetry installed,
you do this with the following command:poetryinstallYou can then run the complete test suite like this:poetryrunpytestIn order to run only a part of the tests with increased verbosity,
you can add pytest options, like this:poetryrunpytesttests/node-vvIn order to check the code style with flake8, use this:poetryrunflake8Use thetoxcommand to run the test suite with different
Python versions and perform all additional source code checks.
You can also restrict tox to an individual environment, like this:poetryruntox-epy39