graphql-relay

graphql-relay is a Python library that supplies the server-side building blocks required to make a GraphQL schema compatible with Relay, Facebook’s GraphQL client. Built on top of graphql-core, it implements the Relay server specification: globally unique node identifiers, cursor-based connection pagination, and a standard mutation input/output shape.

It is a companion to graphql-core (a Python port of graphql-relay-js) that higher-level frameworks such as Graphene use to add Relay support. With it you can expose the Node interface, build connection types over lists or custom data sources, and define mutations that follow Relay’s client conventions.

What You Get

• Global object identification: a Node interface with to_global_id/from_global_id helpers
• Connection definitions with cursor-based, forward/backward pagination
• connection_from_array and related helpers to paginate lists
• Mutation helpers implementing Relay’s input/clientMutationId/payload shape
• A drop-in complement to graphql-core, used by frameworks like Graphene

Common Use Cases

• Making a graphql-core schema compatible with a React/Relay client
• Adding cursor-based connection pagination to GraphQL list fields
• Exposing globally unique node IDs and node re-fetching
• Implementing Relay-style mutations with standard input and payload shapes

Under The Hood

Architecture - The library is organized under src/graphql_relay/ into three focused sub-packages: node/ (the Node interface plus global-ID encode/decode), connection/ (connection type definitions and connection_from_array-style paginators producing edges, cursors, and page info), and mutation/ (the mutation_with_client_mutation_id helper). A shared utils/ module supports base64 cursor handling. Everything composes with graphql-core’s type system.

Tech Stack - Pure Python 3 built on graphql-core, fully type-annotated (ships py.typed), packaged with Poetry/setuptools via pyproject.toml, and tested with pytest under a tox matrix. It closely tracks the graphql-relay-js reference implementation.

Code Quality - The codebase is small, mature, and stable, with a dedicated tests/ suite and complete type hints. Development activity is low (the design is essentially complete and mirrors the JS reference), but the code is clean and well factored by concern.

API Design - The public API mirrors graphql-relay-js naming, so developers can translate Relay’s JavaScript patterns directly. The helpers are low-level primitives meant to be assembled into a schema, so some boilerplate is expected, but each function has a single clear responsibility and integrates cleanly with graphql-core.