pyrelay

Relay-spec GraphQL helpers for Python. Framework-agnostic, with zero dependencies.

Relay's server conventions (opaque global IDs, cursor connections, the node refetch field, clientMutationId on mutations) are small, but they're easy to get subtly wrong. Each Python GraphQL library also tends to ship its own version. pyrelay implements them once as plain Python functions and dataclasses. You can use it with Strawberry, Graphene, Ariadne, graphql-core, or a hand-rolled resolver layer. The ID and cursor formats match the reference graphql-relay-js implementation, so existing Relay clients and data keep working.

Features

• Global object IDs: to_global_id / from_global_id encode and decode base64("Type:id"), with strict validation.
• Cursor connections: connection_from_sequence implements the Relay Cursor Connections spec (first/after/last/before) and produces correct PageInfo.
• Database-friendly slicing: connection_from_sequence_slice paginates when only an OFFSET/LIMIT window is loaded.
• Node registry: NodeRegistry maps type names to loaders for the node(id:) field. It forwards context and works with async loaders.
• Mutation helper: the @relay_mutation decorator strips clientMutationId from the input and echoes it back in the payload. It works for sync and async functions.
• GraphQL-shaped output: .to_dict() emits camelCase edges / pageInfo / totalCount.
• Fully type-hinted (py.typed), standard library only, Python 3.9+.

Install

pip install pyrelay            # once published
# or, from a checkout:
pip install -e .

Quickstart

from pyrelay import (
    ConnectionArguments,
    NodeRegistry,
    connection_from_sequence,
    from_global_id,
    relay_mutation,
    to_global_id,
)

# 1. Global object IDs
gid = to_global_id("User", 42)
assert gid == "VXNlcjo0Mg=="
assert from_global_id(gid) == ("User", "42")

# 2. Cursor pagination over any sequence
users = [{"id": i, "name": n} for i, n in enumerate(["Ada", "Grace", "Linus", "Guido"])]
page1 = connection_from_sequence(users, ConnectionArguments(first=2))
assert [u["name"] for u in page1.nodes] == ["Ada", "Grace"]
assert page1.page_info.has_next_page

page2 = connection_from_sequence(
    users, ConnectionArguments(first=2, after=page1.page_info.end_cursor)
)
assert [u["name"] for u in page2.nodes] == ["Linus", "Guido"]
assert not page2.page_info.has_next_page

# GraphQL-shaped result, e.g. to return from a resolver
data = page2.to_dict(lambda u: {"id": to_global_id("User", u["id"]), "name": u["name"]})
assert set(data) == {"edges", "pageInfo"}

# 3. The `node(id:)` field
registry = NodeRegistry()

@registry.register("User")
def load_user(local_id: str, context=None):
    return users[int(local_id)]

assert registry.resolve(registry.global_id("User", 1))["name"] == "Grace"
assert registry.resolve(to_global_id("Unknown", 1)) is None

# 4. Input-object mutations with clientMutationId
@relay_mutation
def rename_user(input, context=None):
    user = registry.resolve(input["id"], context)
    user["name"] = input["name"]
    return {"user": user}

payload = rename_user(
    {"id": to_global_id("User", 0), "name": "Countess Ada", "clientMutationId": "m-1"}
)
assert payload == {"user": {"id": 0, "name": "Countess Ada"}, "clientMutationId": "m-1"}

Paginating a database query

Load only the window you need, then tell pyrelay where that window sits:

from pyrelay import ConnectionArguments, connection_from_sequence_slice, cursor_to_offset

rows = list(range(100))                      # pretend this is a table
args = ConnectionArguments(first=10, after="YXJyYXljb25uZWN0aW9uOjQ=")  # offset 4

offset = cursor_to_offset(args.after) + 1 if args.after else 0
window = rows[offset : offset + args.first]  # SELECT ... OFFSET :offset LIMIT :first

conn = connection_from_sequence_slice(
    window, args, slice_start=offset, sequence_length=len(rows), include_total_count=True
)
assert conn.nodes == list(range(5, 15))
assert conn.page_info.has_next_page and conn.total_count == 100

API overview

Everything below can be imported from the top-level pyrelay package.

Global IDs (pyrelay.ids)

Cursors (pyrelay.cursors)

Connections (pyrelay.connection)

As in graphql-relay-js, has_previous_page is computed only when last is given, and has_next_page only when first is given. Otherwise they are False.

Node registry (pyrelay.node)

Mutations (pyrelay.mutation)

Errors (pyrelay.errors)

__version__ holds the package version string ("0.1.0").

Development

python3 -m venv .venv && . .venv/bin/activate
pip install -e '.[test]'
python -m pytest            # or, without pytest:
PYTHONPATH=src python3 -m unittest discover -s tests -v

The test suite also runs every Python block in this README and checks that each public name is documented here, so the docs and code stay in sync.

License

MIT