Registry / web-framework / graphql-relay

graphql-relay

JSON →
library3.2.0pypypi✓ verified 24d ago

graphql-relay-py is the Python port of the JavaScript Relay library for GraphQL, designed to facilitate the creation of Relay-compliant GraphQL servers using graphql-core. It provides utilities for global object identification (Nodes) and cursor-based pagination (Connections). The library maintains a regular release cadence, often aligning with updates to graphql-core and the upstream graphql-relay-js specification. The current version is 3.2.0.

pip install graphql-relay graphql-core
INSTALL
IMPORT
SIG · GRAPHQL-RELAY
G
graphql-relay
web-frameworkpythonv3.2.0
Install
1.8s avg
Import
372ms
Disk
18MB
Pass rate
10/ 10
Env Coverage10 / 10
glibc
3.93.13
musl
3.93.13
Install & Compatibility
Where this runs
tested against v3.2.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
py 3.103.95 runs
installs and imports cleanly · install 0.0s · import 0.408s · 20MB
glibc
py 3.103.95 runs
installs and imports cleanly · install 1.8s · import 0.336s · 20MB
18MB installed
● package 18MB
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

connection_args
from graphql_relay import connection_args
connection_definitions
from graphql_relay import connection_definitions
connection_from_array
from graphql_relay import connection_from_array
from_global_id
from graphql_relay import from_global_id
to_global_id
from graphql_relay import to_global_id
global_id_field
from graphql_relay import global_id_field
node_definitions
from graphql_relay import node_definitions
arrayconnection
from graphql_relay.connection.arrayconnection import connection_from_array_slice
from graphql_relay.connection.arrayconnection import connection_from_array
The `arrayconnection` module was temporarily removed/renamed to `array_connection` in `v3.1.1` and later re-added for backward compatibility in `v3.1.5`. Direct imports from `graphql_relay` for core connection functions like `connection_from_array` are generally preferred.

This quickstart demonstrates how to set up a basic Relay-compliant GraphQL schema using `graphql-relay` with `graphene`. It includes defining a Node interface for global object identification and a Connection for pagination. It showcases `node_definitions`, `global_id_field`, `connection_definitions`, `connection_from_array`, and `connection_args`.

import graphene from graphql.execution.execute import execute from graphql.language.parser import parse from graphql_relay import node_definitions, global_id_field, connection_definitions, connection_from_array, connection_args, from_global_id class User: def __init__(self, id, name): self.id = id self.name = name users_data = { "1": User("1", "Alice"), "2": User("2", "Bob"), } def get_user(id): return users_data.get(id) def get_object_from_global_id(global_id, info): type_name, id = from_global_id(global_id) if type_name == 'User': return get_user(id) return None node_interface, node_field = node_definitions( get_object_from_global_id, lambda obj, info: UserNode if isinstance(obj, User) else None ) class UserNode(graphene.ObjectType): class Meta: name = 'User' interfaces = (node_interface,) id = global_id_field('User') name = graphene.String() UserConnection = connection_definitions(UserNode, 'UserConnection').connection_type class Query(graphene.ObjectType): node = node_field users = graphene.Field( UserConnection, args=connection_args, resolve=lambda obj, info, **args: connection_from_array(list(users_data.values()), args) ) schema = graphene.Schema(query=Query) # Example Usage: query_str = ''' query { users (first: 1) { edges { node { id name } } } node(id: "VXNlcjox") { id ... on User { name } } } ''' # Assuming "VXNlcjox" is the global ID for User:1 (to_global_id('User', '1')) # Use 'User:1' -> base64 -> 'VXNlcjox' result = execute(schema, parse(query_str)) print(result.data)
Debug
Known issues
breakingVersion 3.0.0 introduced significant breaking changes to align with graphql-core version 3.x. Code written for graphql-relay-py v2.x (compatible with graphql-core v2.x) will not work with v3.x without migration.
fix
Migrate your graphql-core dependency to v3.x and update your graphql-relay-py imports and API calls as necessary. Review the graphql-core and graphql-relay-py v3 release notes for specific changes. This also requires Python 3.6+.
affects: >=3.0.0
breakingVersions 2.0.0 and 0.5.0 introduced breaking changes relating to compatibility with specific major versions of `graphql-core`. `v2.0.0` was compatible with `graphql-core < 3`, and `v0.5.0` with `graphql-core < 2`.
fix
Ensure that your `graphql-relay-py` version matches the expected `graphql-core` major version. For new projects, use `graphql-relay-py` v3.x with `graphql-core` v3.x.
affects: 2.0.0, 0.5.0
gotchaThe internal `arrayconnection` module was temporarily renamed to `array_connection` in `v3.1.1` as part of a `snake_case` consistency drive, which could break direct imports. It was later re-added for backward compatibility in `v3.1.5`.
fix
For new code, prefer importing connection-related utilities like `connection_from_array` directly from the top-level `graphql_relay` package. If you must use `arrayconnection`, ensure your version is `3.1.5` or later, or adapt to `array_connection` if on affected versions.
affects: 3.1.1 - 3.1.4
gotchaThe behavior of `unbase64` changed in `v3.1.2` to return an empty string on errors instead of potentially raising an exception, and `from_global_id` behavior was adjusted in `v3.1.3` to match `relay-js`.
fix
Update your code to handle `unbase64` returning an empty string for invalid inputs if you were previously relying on exceptions for error handling. Review `from_global_id` usage, especially if parsing IDs from external sources.
affects: >=3.1.2
breakingThe 'graphene' package is a core dependency and must be installed. This error occurs when 'graphene' is not found in the Python environment.
fix
Ensure 'graphene' is installed in your Python environment, e.g., by running `pip install graphene`.
affects: all
breakingThe 'graphene' package was not found. This indicates that `graphene` is not installed in the environment where the script is being executed.
fix
Ensure that the `graphene` package is installed in your environment. You can typically install it using `pip install graphene`.
affects: *
Upgrade
Version history
3.2.0latest on PyPI · released Apr 16, 2022
Audit
Dependencies
graphql-corerequiredThis library is built on top of graphql-core and requires it for core GraphQL functionality. Version 3.x of graphql-relay-py is compatible with graphql-core version 3.x.
Agent activity
9 hits · last 30 days
node
8
Resources
graphql-relay — pip install graphql-relay · libregistry