{"id":13499336,"url":"https://github.com/graphql-python/graphql-relay-py","last_synced_at":"2025-04-12T18:51:56.351Z","repository":{"id":44779486,"uuid":"42670247","full_name":"graphql-python/graphql-relay-py","owner":"graphql-python","description":"A library to help construct a graphql-py server supporting react-relay","archived":false,"fork":false,"pushed_at":"2023-02-27T18:38:50.000Z","size":341,"stargazers_count":144,"open_issues_count":11,"forks_count":40,"subscribers_count":17,"default_branch":"main","last_synced_at":"2025-04-03T21:12:32.126Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/graphql-python.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":null,"support":null,"governance":null}},"created_at":"2015-09-17T17:16:20.000Z","updated_at":"2025-03-20T06:17:32.000Z","dependencies_parsed_at":"2023-07-12T23:50:17.405Z","dependency_job_id":null,"html_url":"https://github.com/graphql-python/graphql-relay-py","commit_stats":null,"previous_names":["syrusakbary/graphql-relay-py"],"tags_count":15,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-python%2Fgraphql-relay-py","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-python%2Fgraphql-relay-py/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-python%2Fgraphql-relay-py/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/graphql-python%2Fgraphql-relay-py/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/graphql-python","download_url":"https://codeload.github.com/graphql-python/graphql-relay-py/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248618225,"owners_count":21134200,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-07-31T22:00:32.301Z","updated_at":"2025-04-12T18:51:56.326Z","avatar_url":"https://github.com/graphql-python.png","language":"Python","readme":"# Relay Library for GraphQL Python\n\nGraphQL-relay-py is the [Relay](https://relay.dev/) library for\n[GraphQL-core](https://github.com/graphql-python/graphql-core).\n\nIt allows the easy creation of Relay-compliant servers using GraphQL-core.\n\nGraphQL-Relay-Py is a Python port of\n[graphql-relay-js](https://github.com/graphql/graphql-relay-js),\nwhile GraphQL-Core is a Python port of\n[GraphQL.js](https://github.com/graphql/graphql-js),\nthe reference implementation of GraphQL for JavaScript.\n\nSince version 3, GraphQL-Relay-Py and GraphQL-Core support Python 3.6 and above only.\nFor older versions of Python, you can use version 2 of these libraries.\n\n[![PyPI version](https://badge.fury.io/py/graphql-relay.svg)](https://badge.fury.io/py/graphql-relay)\n![Test Status](https://github.com/graphql-python/graphql-relay-py/actions/workflows/test.yml/badge.svg)\n![Lint Status](https://github.com/graphql-python/graphql-relay-py/actions/workflows/lint.yml/badge.svg)\n[![Code Style](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/ambv/black)\n\n## Getting Started\n\nA basic understanding of GraphQL and of the GraphQL Python implementation is needed\nto provide context for this library.\n\nAn overview of GraphQL in general is available in the\n[README](https://github.com/graphql-python/graphql-core/blob/master/README.md) for the\n[Specification for GraphQL](https://github.com/graphql-python/graphql-core).\n\nThis library is designed to work with the\nthe [GraphQL-Core](https://github.com/graphql-python/graphql-core)\nPython reference implementation of a GraphQL server.\n\nAn overview of the functionality that a Relay-compliant GraphQL server should provide\nis in the [GraphQL Relay Specification](https://facebook.github.io/relay/docs/graphql-relay-specification.html)\non the [Relay website](https://facebook.github.io/relay/).\nThat overview describes a simple set of examples that exist\nas [tests](tests) in this repository.\nA good way to get started with this repository is to walk through that documentation\nand the corresponding tests in this library together.\n\n## Using Relay Library for GraphQL Python (graphql-core)\n\nInstall Relay Library for GraphQL Python\n\n```sh\npip install graphql-core\npip install graphql-relay\n```\n\nWhen building a schema for [GraphQL](https://github.com/graphql-python/graphql-core),\nthe provided library functions can be used to simplify the creation of Relay patterns.\n\nAll the functions that are explained in the following sections must be\nimported from the top level of the `graphql_relay` package, like this:\n```python\nfrom graphql_relay import connection_definitions\n```\n\n### Connections\n\nHelper functions are provided for both building the GraphQL types\nfor connections and for implementing the `resolve` method for fields\nreturning those types.\n\n - `connection_args` returns the arguments that fields should provide when\nthey return a connection type that supports bidirectional pagination.\n - `forward_connection_args` returns the arguments that fields should provide when\nthey return a connection type that only supports forward pagination.\n - `backward_connection_args` returns the arguments that fields should provide when\nthey return a connection type that only supports backward pagination.\n - `connection_definitions` returns a `connection_type` and its associated\n`edgeType`, given a name and a node type.\n - `connection_from_array` is a helper method that takes an array and the\narguments from `connection_args`, does pagination and filtering, and returns\nan object in the shape expected by a `connection_type`'s `resolve` function.\n - `cursor_for_object_in_connection` is a helper method that takes an array and a\nmember object, and returns a cursor for use in the mutation payload.\n - `offset_to_cursor` takes the index of a member object in an array\n and returns an opaque cursor for use in the mutation payload.\n - `cursor_to_offset` takes an opaque cursor (created with `offset_to_cursor`)\nand returns the corresponding array index.\n\nAn example usage of these methods from the [test schema](tests/star_wars_schema.py):\n\n```python\nship_edge, ship_connection = connection_definitions(ship_type, \"Ship\")\n\nfaction_type = GraphQLObjectType(\n    name=\"Faction\",\n    description=\"A faction in the Star Wars saga\",\n    fields=lambda: {\n        \"id\": global_id_field(\"Faction\"),\n        \"name\": GraphQLField(GraphQLString, description=\"The name of the faction.\"),\n        \"ships\": GraphQLField(\n            ship_connection,\n            description=\"The ships used by the faction.\",\n            args=connection_args,\n            resolve=lambda faction, _info, **args: connection_from_array(\n                [get_ship(ship) for ship in faction.ships], args\n            ),\n        ),\n    },\n    interfaces=[node_interface],\n)\n```\n\nThis shows adding a `ships` field to the `Faction` object that is a connection.\nIt uses `connection_definitions(ship_type, \"Ship\")` to create the connection\ntype, adds `connection_args` as arguments on this function, and then implements\nthe resolver function by passing the array of ships and the arguments to\n`connection_from_array`.\n\n### Object Identification\n\nHelper functions are provided for both building the GraphQL types\nfor nodes and for implementing global IDs around local IDs.\n\n - `node_definitions` returns the `Node` interface that objects can implement,\n    and returns the `node` root field to include on the query type.\n    To implement this, it takes a function to resolve an ID to an object,\n    and to determine the type of a given object.\n - `to_global_id` takes a type name and an ID specific to that type name,\n    and returns a \"global ID\" that is unique among all types.\n - `from_global_id` takes the \"global ID\" created by `to_global_id`, and\n    returns the type name and ID used to create it.\n - `global_id_field` creates the configuration for an `id` field on a node.\n - `plural_identifying_root_field` creates a field that accepts a list of\n    non-ID identifiers (like a username) and maps then to their corresponding\n    objects.\n\nAn example usage of these methods from the [test schema](tests/star_wars_schema.py):\n\n```python\ndef get_node(global_id, _info):\n    type_, id_ = from_global_id(global_id)\n    if type_ == \"Faction\":\n        return get_faction(id_)\n    if type_ == \"Ship\":\n        return get_ship(id_)\n    return None  # pragma: no cover\n\ndef get_node_type(obj, _info, _type):\n    if isinstance(obj, Faction):\n        return faction_type.name\n    return ship_type.name\n\nnode_interface, node_field = node_definitions(get_node, get_node_type)[:2]\n\nfaction_type = GraphQLObjectType(\n    name=\"Faction\",\n    description=\"A faction in the Star Wars saga\",\n    fields=lambda: {\n        \"id\": global_id_field(\"Faction\"),\n        \"name\": GraphQLField(GraphQLString, description=\"The name of the faction.\"),\n        \"ships\": GraphQLField(\n            ship_connection,\n            description=\"The ships used by the faction.\",\n            args=connection_args,\n            resolve=lambda faction, _info, **args: connection_from_array(\n                [get_ship(ship) for ship in faction.ships], args\n            ),\n        ),\n    },\n    interfaces=[node_interface],\n)\n\nquery_type = GraphQLObjectType(\n    name=\"Query\",\n    fields=lambda: {\n        \"rebels\": GraphQLField(faction_type, resolve=lambda _obj, _info: get_rebels()),\n        \"empire\": GraphQLField(faction_type, resolve=lambda _obj, _info: get_empire()),\n        \"node\": node_field,\n    },\n)\n```\n\nThis uses `node_definitions` to construct the `Node` interface and the `node`\nfield; it uses `from_global_id` to resolve the IDs passed in the implementation\nof the function mapping ID to object. It then uses the `global_id_field` method to\ncreate the `id` field on `Faction`, which also ensures implements the\n`node_interface`. Finally, it adds the `node` field to the query type, using the\n`node_field` returned by `node_definitions`.\n\n### Mutations\n\nA helper function is provided for building mutations with\nsingle inputs and client mutation IDs.\n\n - `mutation_with_client_mutation_id` takes a name, input fields, output fields,\nand a mutation method to map from the input fields to the output fields,\nperforming the mutation along the way. It then creates and returns a field\nconfiguration that can be used as a top-level field on the mutation type.\n\nAn example usage of these methods from the [test schema](tests/star_wars_schema.py):\n\n```python\nclass IntroduceShipMutation:\n\n    def __init__(self, shipId, factionId, clientMutationId=None):\n        self.shipId = shipId\n        self.factionId = factionId\n        self.clientMutationId = clientMutationId\n\ndef mutate_and_get_payload(_info, shipName, factionId, **_input):\n    new_ship = create_ship(shipName, factionId)\n    return IntroduceShipMutation(shipId=new_ship.id, factionId=factionId)\n\nship_mutation = mutation_with_client_mutation_id(\n    \"IntroduceShip\",\n    input_fields={\n        \"shipName\": GraphQLInputField(GraphQLNonNull(GraphQLString)),\n        \"factionId\": GraphQLInputField(GraphQLNonNull(GraphQLID)),\n    },\n    output_fields={\n        \"ship\": GraphQLField(\n            ship_type, resolve=lambda payload, _info: get_ship(payload.shipId)\n        ),\n        \"faction\": GraphQLField(\n            faction_type, resolve=lambda payload, _info: get_faction(payload.factionId)\n        ),\n    },\n    mutate_and_get_payload=mutate_and_get_payload,\n)\n\nmutation_type = GraphQLObjectType(\n    \"Mutation\", fields=lambda: {\"introduceShip\": ship_mutation}\n)\n```\n\nThis code creates a mutation named `IntroduceShip`, which takes a faction\nID and a ship name as input. It outputs the `Faction` and the `Ship` in\nquestion. `mutate_and_get_payload` then gets each input field as keyword\nparameter, performs the mutation by constructing the new ship, then returns\nan object that will be resolved by the output fields.\n\nOur mutation type then creates the `introduceShip` field using the return\nvalue of `mutation_with_client_mutation_id`.\n\n## Contributing\n\nAfter cloning this repository from GitHub,\nwe recommend using [Poetry](https://poetry.eustace.io/)\nto create a test environment. With poetry installed,\nyou do this with the following command:\n\n```sh\npoetry install\n```\n\nYou can then run the complete test suite like this:\n\n```sh\npoetry run pytest\n```\n\nIn order to run only a part of the tests with increased verbosity,\nyou can add pytest options, like this:\n\n```sh\npoetry run pytest tests/node -vv\n```\n\nIn order to check the code style with flake8, use this:\n\n```sh\npoetry run flake8\n```\n\nUse the `tox` command to run the test suite with different\nPython versions and perform all additional source code checks.\nYou can also restrict tox to an individual environment, like this:\n\n```sh\npoetry run tox -e py39\n```\n","funding_links":[],"categories":["Libraries","Python","Implementations"],"sub_categories":["Python Libraries","Python"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphql-python%2Fgraphql-relay-py","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgraphql-python%2Fgraphql-relay-py","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgraphql-python%2Fgraphql-relay-py/lists"}