pyrelay 0.1.0__py3-none-any.whl

pyrelay/__init__.py

@@ -0,0 +1,57 @@
+"""pyrelay: Relay-spec GraphQL server helpers, independent of any GraphQL library.
+
+Provides global object IDs, cursor-based connection pagination, a ``node``
+resolver registry, and ``clientMutationId`` handling for input-object mutations.
+"""
+
+from __future__ import annotations
+
+from .connection import (
+    Connection,
+    ConnectionArguments,
+    Edge,
+    PageInfo,
+    connection_from_sequence,
+    connection_from_sequence_slice,
+)
+from .cursors import cursor_for_object_in_sequence, cursor_to_offset, offset_to_cursor
+from .errors import (
+    ConnectionArgumentError,
+    InvalidCursorError,
+    InvalidGlobalIdError,
+    RelayError,
+)
+from .ids import ResolvedGlobalId, from_global_id, to_global_id
+from .mutation import CLIENT_MUTATION_ID, relay_mutation
+from .node import NodeRegistry
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "__version__",
+    # ids
+    "to_global_id",
+    "from_global_id",
+    "ResolvedGlobalId",
+    # cursors
+    "offset_to_cursor",
+    "cursor_to_offset",
+    "cursor_for_object_in_sequence",
+    # connections
+    "PageInfo",
+    "Edge",
+    "Connection",
+    "ConnectionArguments",
+    "connection_from_sequence",
+    "connection_from_sequence_slice",
+    # node
+    "NodeRegistry",
+    # mutations
+    "CLIENT_MUTATION_ID",
+    "relay_mutation",
+    # errors
+    "RelayError",
+    "InvalidGlobalIdError",
+    "InvalidCursorError",
+    "ConnectionArgumentError",
+]

pyrelay/connection.py

@@ -0,0 +1,212 @@
+"""Cursor-based connection pagination per the Relay Cursor Connections spec.
+
+The algorithm mirrors ``connectionFromArraySlice`` from ``graphql-relay-js``:
+``after``/``before`` narrow the window, then ``first`` keeps the head of it and
+``last`` keeps the tail. ``hasPreviousPage`` is only computed when ``last`` is
+given and ``hasNextPage`` only when ``first`` is given, as the spec permits.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any, Callable, Dict, Generic, List, Mapping, Optional, Sequence, TypeVar
+
+from .cursors import cursor_to_offset, offset_to_cursor
+from .errors import ConnectionArgumentError
+
+__all__ = [
+    "PageInfo",
+    "Edge",
+    "Connection",
+    "ConnectionArguments",
+    "connection_from_sequence",
+    "connection_from_sequence_slice",
+]
+
+T = TypeVar("T")
+
+
+@dataclass(frozen=True)
+class PageInfo:
+    """Pagination metadata for a :class:`Connection`."""
+
+    has_previous_page: bool
+    has_next_page: bool
+    start_cursor: Optional[str] = None
+    end_cursor: Optional[str] = None
+
+    def to_dict(self) -> Dict[str, Any]:
+        """Return the GraphQL-shaped (camelCase) representation."""
+        return {
+            "hasPreviousPage": self.has_previous_page,
+            "hasNextPage": self.has_next_page,
+            "startCursor": self.start_cursor,
+            "endCursor": self.end_cursor,
+        }
+
+
+@dataclass(frozen=True)
+class Edge(Generic[T]):
+    """A node together with the cursor that locates it."""
+
+    node: T
+    cursor: str
+
+    def to_dict(self, serialize_node: Optional[Callable[[T], Any]] = None) -> Dict[str, Any]:
+        """Return ``{"node": ..., "cursor": ...}``, optionally transforming the node."""
+        node = serialize_node(self.node) if serialize_node else self.node
+        return {"node": node, "cursor": self.cursor}
+
+
+@dataclass(frozen=True)
+class Connection(Generic[T]):
+    """A page of edges plus :class:`PageInfo`."""
+
+    edges: List[Edge[T]]
+    page_info: PageInfo
+    total_count: Optional[int] = field(default=None)
+    """Total length of the underlying sequence, when known."""
+
+    @property
+    def nodes(self) -> List[T]:
+        """The nodes of :attr:`edges`, in order."""
+        return [edge.node for edge in self.edges]
+
+    def to_dict(self, serialize_node: Optional[Callable[[T], Any]] = None) -> Dict[str, Any]:
+        """Return the GraphQL-shaped representation.
+
+        ``totalCount`` is included only when :attr:`total_count` is known.
+        """
+        result: Dict[str, Any] = {
+            "edges": [edge.to_dict(serialize_node) for edge in self.edges],
+            "pageInfo": self.page_info.to_dict(),
+        }
+        if self.total_count is not None:
+            result["totalCount"] = self.total_count
+        return result
+
+
+@dataclass(frozen=True)
+class ConnectionArguments:
+    """The four standard connection arguments.
+
+    Use :meth:`from_mapping` to build one from raw GraphQL arguments.
+    """
+
+    first: Optional[int] = None
+    after: Optional[str] = None
+    last: Optional[int] = None
+    before: Optional[str] = None
+
+    def __post_init__(self) -> None:
+        for name in ("first", "last"):
+            value = getattr(self, name)
+            if value is None:
+                continue
+            if isinstance(value, bool) or not isinstance(value, int):
+                raise ConnectionArgumentError(f"Argument '{name}' must be an int")
+            if value < 0:
+                raise ConnectionArgumentError(
+                    f"Argument '{name}' must be a non-negative integer"
+                )
+
+    @classmethod
+    def from_mapping(cls, args: Mapping[str, Any]) -> "ConnectionArguments":
+        """Build from a mapping such as GraphQL resolver ``**kwargs``.
+
+        Unknown keys are ignored so the full field arguments can be passed.
+        """
+        return cls(
+            first=args.get("first"),
+            after=args.get("after"),
+            last=args.get("last"),
+            before=args.get("before"),
+        )
+
+
+def connection_from_sequence(
+    data: Sequence[T],
+    args: Optional[ConnectionArguments] = None,
+    *,
+    include_total_count: bool = False,
+) -> Connection[T]:
+    """Paginate an in-memory sequence.
+
+    >>> conn = connection_from_sequence("ABCDE", ConnectionArguments(first=2))
+    >>> conn.nodes, conn.page_info.has_next_page
+    (['A', 'B'], True)
+
+    :raises ConnectionArgumentError: if ``first``/``last`` are negative.
+    :raises InvalidCursorError: if ``after``/``before`` are malformed.
+    """
+    return connection_from_sequence_slice(
+        data,
+        args,
+        slice_start=0,
+        sequence_length=len(data),
+        include_total_count=include_total_count,
+    )
+
+
+def connection_from_sequence_slice(
+    sequence_slice: Sequence[T],
+    args: Optional[ConnectionArguments] = None,
+    *,
+    slice_start: int,
+    sequence_length: int,
+    include_total_count: bool = False,
+) -> Connection[T]:
+    """Paginate when only a window of the full sequence is in memory.
+
+    This is the building block for database-backed connections: fetch rows
+    ``[slice_start, slice_start + len(sequence_slice))`` (e.g. with
+    ``OFFSET``/``LIMIT``), report the full ``sequence_length``, and the
+    resulting cursors stay consistent with :func:`connection_from_sequence`.
+
+    :raises ConnectionArgumentError: on negative ``first``/``last``, a
+        negative ``slice_start``, or a ``sequence_length`` smaller than the slice end.
+    :raises InvalidCursorError: if ``after``/``before`` are malformed.
+    """
+    args = args or ConnectionArguments()
+    if slice_start < 0:
+        raise ConnectionArgumentError("slice_start must be non-negative")
+    slice_end = slice_start + len(sequence_slice)
+    if sequence_length < slice_end:
+        raise ConnectionArgumentError(
+            "sequence_length must be >= slice_start + len(sequence_slice)"
+        )
+
+    before_offset = cursor_to_offset(args.before) if args.before is not None else sequence_length
+    after_offset = cursor_to_offset(args.after) if args.after is not None else -1
+
+    start_offset = max(slice_start - 1, after_offset, -1) + 1
+    end_offset = min(slice_end, before_offset, sequence_length)
+
+    if args.first is not None:
+        end_offset = min(end_offset, start_offset + args.first)
+    if args.last is not None:
+        start_offset = max(start_offset, end_offset - args.last)
+
+    lo = max(start_offset - slice_start, 0)
+    hi = max(len(sequence_slice) - (slice_end - end_offset), 0)
+    window = list(sequence_slice[lo:hi]) if hi > lo else []
+
+    edges = [
+        Edge(node=node, cursor=offset_to_cursor(start_offset + index))
+        for index, node in enumerate(window)
+    ]
+
+    lower_bound = after_offset + 1 if args.after is not None else 0
+    upper_bound = before_offset if args.before is not None else sequence_length
+
+    page_info = PageInfo(
+        has_previous_page=start_offset > lower_bound if args.last is not None else False,
+        has_next_page=end_offset < upper_bound if args.first is not None else False,
+        start_cursor=edges[0].cursor if edges else None,
+        end_cursor=edges[-1].cursor if edges else None,
+    )
+    return Connection(
+        edges=edges,
+        page_info=page_info,
+        total_count=sequence_length if include_total_count else None,
+    )

pyrelay/cursors.py

@@ -0,0 +1,63 @@
+"""Opaque offset-based cursors for connection pagination.
+
+Cursors are ``base64("arrayconnection:<offset>")`` -- the same format used by
+``graphql-relay-js`` -- so clients never need to understand their contents.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from typing import Any, Optional, Sequence
+
+from .errors import InvalidCursorError
+
+__all__ = [
+    "CURSOR_PREFIX",
+    "offset_to_cursor",
+    "cursor_to_offset",
+    "cursor_for_object_in_sequence",
+]
+
+CURSOR_PREFIX = "arrayconnection:"
+
+
+def offset_to_cursor(offset: int) -> str:
+    """Return the opaque cursor for a zero-based ``offset``.
+
+    :raises ValueError: if ``offset`` is negative or not an integer.
+    """
+    if isinstance(offset, bool) or not isinstance(offset, int) or offset < 0:
+        raise ValueError(f"offset must be a non-negative int (got {offset!r})")
+    return base64.b64encode(f"{CURSOR_PREFIX}{offset}".encode("ascii")).decode("ascii")
+
+
+def cursor_to_offset(cursor: str) -> int:
+    """Return the zero-based offset encoded in ``cursor``.
+
+    :raises InvalidCursorError: if the cursor was not produced by
+        :func:`offset_to_cursor`.
+    """
+    if not isinstance(cursor, str) or not cursor:
+        raise InvalidCursorError(f"Invalid cursor: {cursor!r}")
+    try:
+        decoded = base64.b64decode(cursor, validate=True).decode("ascii")
+    except (binascii.Error, UnicodeDecodeError, ValueError) as exc:
+        raise InvalidCursorError(f"Invalid cursor: {cursor!r}") from exc
+    if not decoded.startswith(CURSOR_PREFIX):
+        raise InvalidCursorError(f"Invalid cursor: {cursor!r}")
+    digits = decoded[len(CURSOR_PREFIX):]
+    if not digits.isdigit():
+        raise InvalidCursorError(f"Invalid cursor: {cursor!r}")
+    return int(digits)
+
+
+def cursor_for_object_in_sequence(data: Sequence[Any], obj: Any) -> Optional[str]:
+    """Return the cursor of the first item in ``data`` equal to ``obj``.
+
+    Returns ``None`` when ``obj`` is not present.
+    """
+    for index, item in enumerate(data):
+        if item == obj:
+            return offset_to_cursor(index)
+    return None

pyrelay/errors.py

@@ -0,0 +1,26 @@
+"""Exception hierarchy for :mod:`pyrelay`."""
+
+from __future__ import annotations
+
+__all__ = [
+    "RelayError",
+    "InvalidGlobalIdError",
+    "InvalidCursorError",
+    "ConnectionArgumentError",
+]
+
+
+class RelayError(Exception):
+    """Base class for every error raised by pyrelay."""
+
+
+class InvalidGlobalIdError(RelayError, ValueError):
+    """Raised when a string cannot be decoded as a Relay global object ID."""
+
+
+class InvalidCursorError(RelayError, ValueError):
+    """Raised when a pagination cursor is malformed or was not issued by pyrelay."""
+
+
+class ConnectionArgumentError(RelayError, ValueError):
+    """Raised when ``first``/``last``/``after``/``before`` arguments are invalid."""

pyrelay/ids.py

@@ -0,0 +1,66 @@
+"""Relay global object identification.
+
+A *global ID* is an opaque string that uniquely identifies an object across
+every type in a schema. Following the reference implementation
+(``graphql-relay-js``), pyrelay encodes it as ``base64("<TypeName>:<local id>")``,
+so IDs produced here interoperate with other Relay servers and clients.
+"""
+
+from __future__ import annotations
+
+import base64
+import binascii
+from typing import NamedTuple, Union
+
+from .errors import InvalidGlobalIdError
+
+__all__ = ["ResolvedGlobalId", "to_global_id", "from_global_id"]
+
+LocalId = Union[str, int]
+
+
+class ResolvedGlobalId(NamedTuple):
+    """The decoded parts of a global ID."""
+
+    type: str
+    """The GraphQL type name, e.g. ``"User"``."""
+
+    id: str
+    """The type-local identifier, always returned as a string."""
+
+
+def to_global_id(type_name: str, local_id: LocalId) -> str:
+    """Encode ``type_name`` and ``local_id`` into an opaque global ID.
+
+    >>> to_global_id("User", 42)
+    'VXNlcjo0Mg=='
+
+    :raises ValueError: if ``type_name`` is empty or contains ``":"``.
+    """
+    if not type_name:
+        raise ValueError("type_name must be a non-empty string")
+    if ":" in type_name:
+        raise ValueError(f"type_name must not contain ':' (got {type_name!r})")
+    raw = f"{type_name}:{local_id}".encode("utf-8")
+    return base64.b64encode(raw).decode("ascii")
+
+
+def from_global_id(global_id: str) -> ResolvedGlobalId:
+    """Decode a global ID produced by :func:`to_global_id`.
+
+    >>> from_global_id("VXNlcjo0Mg==")
+    ResolvedGlobalId(type='User', id='42')
+
+    :raises InvalidGlobalIdError: if the value is not valid base64, not UTF-8,
+        or lacks a ``"Type:id"`` structure with a non-empty type and id.
+    """
+    if not isinstance(global_id, str) or not global_id:
+        raise InvalidGlobalIdError(f"Invalid global ID: {global_id!r}")
+    try:
+        decoded = base64.b64decode(global_id, validate=True).decode("utf-8")
+    except (binascii.Error, UnicodeDecodeError, ValueError) as exc:
+        raise InvalidGlobalIdError(f"Invalid global ID: {global_id!r}") from exc
+    type_name, sep, local_id = decoded.partition(":")
+    if not sep or not type_name or not local_id:
+        raise InvalidGlobalIdError(f"Invalid global ID: {global_id!r}")
+    return ResolvedGlobalId(type_name, local_id)

pyrelay/mutation.py

@@ -0,0 +1,75 @@
+"""Relay input-object mutation helpers.
+
+Relay mutations take a single ``input`` argument and return a payload object.
+Clients may send ``clientMutationId``, which the server must echo back
+unchanged in the payload. :func:`relay_mutation` handles that bookkeeping so
+the wrapped function deals only with business fields.
+"""
+
+from __future__ import annotations
+
+import functools
+import inspect
+from typing import Any, Callable, Dict, Mapping, TypeVar, cast
+
+__all__ = ["CLIENT_MUTATION_ID", "relay_mutation"]
+
+CLIENT_MUTATION_ID = "clientMutationId"
+
+F = TypeVar("F", bound=Callable[..., Any])
+
+
+def _split_input(input: Mapping[str, Any]) -> "tuple[Any, Dict[str, Any]]":
+    if not isinstance(input, Mapping):
+        raise TypeError(f"Mutation input must be a mapping (got {type(input).__name__})")
+    client_id = input.get(CLIENT_MUTATION_ID)
+    fields = {k: v for k, v in input.items() if k != CLIENT_MUTATION_ID}
+    return client_id, fields
+
+
+def _build_payload(result: Any, client_id: Any) -> Dict[str, Any]:
+    if result is None:
+        payload: Dict[str, Any] = {}
+    elif isinstance(result, Mapping):
+        payload = dict(result)
+    else:
+        raise TypeError(
+            "Relay mutation must return a mapping or None "
+            f"(got {type(result).__name__})"
+        )
+    payload[CLIENT_MUTATION_ID] = client_id
+    return payload
+
+
+def relay_mutation(func: F) -> F:
+    """Decorate a mutation function to handle ``clientMutationId``.
+
+    The decorated callable is invoked as ``wrapped(input, *args, **kwargs)``.
+    ``clientMutationId`` is removed from ``input`` before calling ``func``, and
+    added (``None`` if absent) to the returned payload dict. ``func`` must
+    return a mapping or ``None``. Coroutine functions are supported and stay
+    awaitable.
+
+    >>> @relay_mutation
+    ... def rename(input):
+    ...     return {"name": input["name"].title()}
+    >>> rename({"name": "ada", "clientMutationId": "m1"})
+    {'name': 'Ada', 'clientMutationId': 'm1'}
+    """
+    if inspect.iscoroutinefunction(func):
+
+        @functools.wraps(func)
+        async def async_wrapper(input: Mapping[str, Any], *args: Any, **kwargs: Any) -> Dict[str, Any]:
+            client_id, fields = _split_input(input)
+            result = await func(fields, *args, **kwargs)
+            return _build_payload(result, client_id)
+
+        return cast(F, async_wrapper)
+
+    @functools.wraps(func)
+    def wrapper(input: Mapping[str, Any], *args: Any, **kwargs: Any) -> Dict[str, Any]:
+        client_id, fields = _split_input(input)
+        result = func(fields, *args, **kwargs)
+        return _build_payload(result, client_id)
+
+    return cast(F, wrapper)

pyrelay/node.py

@@ -0,0 +1,92 @@
+"""A registry implementing the Relay ``node(id: ID!)`` refetch field."""
+
+from __future__ import annotations
+
+from typing import Any, Callable, Dict, Optional, Tuple, overload
+
+from .ids import LocalId, from_global_id, to_global_id
+
+__all__ = ["NodeResolver", "NodeRegistry"]
+
+NodeResolver = Callable[..., Any]
+"""``resolver(local_id: str, *args, **kwargs) -> object | None``."""
+
+
+class NodeRegistry:
+    """Maps GraphQL type names to functions that load objects by local ID.
+
+    Register a resolver per type, then call :meth:`resolve` from your schema's
+    ``node`` field. Extra positional/keyword arguments (e.g. a request context)
+    are forwarded to the resolver unchanged, so async resolvers work too: the
+    caller simply awaits the returned value.
+
+    >>> registry = NodeRegistry()
+    >>> @registry.register("User")
+    ... def load_user(local_id):
+    ...     return {"id": local_id}
+    >>> registry.resolve(registry.global_id("User", 7))
+    {'id': '7'}
+    """
+
+    def __init__(self) -> None:
+        self._resolvers: Dict[str, NodeResolver] = {}
+
+    @overload
+    def register(self, type_name: str) -> Callable[[NodeResolver], NodeResolver]: ...
+
+    @overload
+    def register(self, type_name: str, resolver: NodeResolver) -> NodeResolver: ...
+
+    def register(self, type_name: str, resolver: Optional[NodeResolver] = None) -> Any:
+        """Register ``resolver`` for ``type_name``; usable as a decorator.
+
+        :raises ValueError: if ``type_name`` is already registered or invalid.
+        """
+        if not type_name or ":" in type_name:
+            raise ValueError(f"Invalid type name: {type_name!r}")
+
+        def decorator(fn: NodeResolver) -> NodeResolver:
+            if type_name in self._resolvers:
+                raise ValueError(f"Type {type_name!r} is already registered")
+            self._resolvers[type_name] = fn
+            return fn
+
+        return decorator(resolver) if resolver is not None else decorator
+
+    def unregister(self, type_name: str) -> None:
+        """Remove the resolver for ``type_name``.
+
+        :raises KeyError: if it is not registered.
+        """
+        del self._resolvers[type_name]
+
+    @property
+    def types(self) -> Tuple[str, ...]:
+        """Registered type names, in registration order."""
+        return tuple(self._resolvers)
+
+    def __contains__(self, type_name: object) -> bool:
+        return type_name in self._resolvers
+
+    def global_id(self, type_name: str, local_id: LocalId) -> str:
+        """Encode a global ID for a *registered* type.
+
+        :raises KeyError: if ``type_name`` is not registered (catches typos).
+        """
+        if type_name not in self._resolvers:
+            raise KeyError(f"Type {type_name!r} is not registered")
+        return to_global_id(type_name, local_id)
+
+    def resolve(self, global_id: str, *args: Any, **kwargs: Any) -> Any:
+        """Load the object identified by ``global_id``.
+
+        Returns ``None`` when the type is not registered, matching the Relay
+        convention that ``node`` yields ``null`` for unknown IDs.
+
+        :raises InvalidGlobalIdError: if ``global_id`` is malformed.
+        """
+        type_name, local_id = from_global_id(global_id)
+        resolver = self._resolvers.get(type_name)
+        if resolver is None:
+            return None
+        return resolver(local_id, *args, **kwargs)

pyrelay-0.1.0.dist-info/METADATA

@@ -0,0 +1,211 @@
+Metadata-Version: 2.4
+Name: pyrelay
+Version: 0.1.0
+Summary: Relay-spec GraphQL helpers for Python: global object IDs, cursor connections, node registry, and mutation payloads. Framework-agnostic, zero dependencies.
+Author: nehz
+License-Expression: MIT
+Keywords: graphql,relay,pagination,cursor,connection,global-id
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Internet :: WWW/HTTP :: Dynamic Content
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Provides-Extra: test
+Requires-Dist: pytest>=7; extra == "test"
+Dynamic: license-file
+
+# 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
+
+```bash
+pip install pyrelay            # once published
+# or, from a checkout:
+pip install -e .
+```
+
+## Quickstart
+
+```python
+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:
+
+```python
+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`)
+
+| Name | Description |
+| --- | --- |
+| `to_global_id(type_name, local_id) -> str` | Returns `base64("Type:id")`. Raises `ValueError` if `type_name` is empty or contains `:`. |
+| `from_global_id(global_id) -> ResolvedGlobalId` | Decodes an ID. Raises `InvalidGlobalIdError` on malformed input. |
+| `ResolvedGlobalId` | A `NamedTuple` with fields `type: str` and `id: str`. |
+
+### Cursors (`pyrelay.cursors`)
+
+| Name | Description |
+| --- | --- |
+| `offset_to_cursor(offset) -> str` | Returns the opaque cursor `base64("arrayconnection:N")`. |
+| `cursor_to_offset(cursor) -> int` | Inverse of `offset_to_cursor`. Raises `InvalidCursorError`. |
+| `cursor_for_object_in_sequence(data, obj) -> str \| None` | Returns the cursor of the first item equal to `obj`. |
+
+### Connections (`pyrelay.connection`)
+
+| Name | Description |
+| --- | --- |
+| `ConnectionArguments(first=None, after=None, last=None, before=None)` | Frozen dataclass. Raises `ConnectionArgumentError` if `first`/`last` is negative or not an int. `ConnectionArguments.from_mapping(kwargs)` ignores unknown keys. |
+| `connection_from_sequence(data, args=None, *, include_total_count=False) -> Connection` | Paginates an in-memory sequence. |
+| `connection_from_sequence_slice(slice, args=None, *, slice_start, sequence_length, include_total_count=False) -> Connection` | Paginates a pre-fetched window of a larger sequence. |
+| `Connection` | Frozen dataclass with `edges: list[Edge]`, `page_info: PageInfo` and `total_count: int \| None`. Also has a `.nodes` property and `.to_dict(serialize_node=None)`. |
+| `Edge` | Frozen dataclass with `node` and `cursor: str`, plus `.to_dict(serialize_node=None)`. |
+| `PageInfo` | Frozen dataclass with `has_previous_page`, `has_next_page`, `start_cursor` and `end_cursor`, plus `.to_dict()`. |
+
+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`)
+
+| Name | Description |
+| --- | --- |
+| `NodeRegistry()` | Registry of `type_name -> resolver(local_id, *args, **kwargs)`. |
+| `.register(type_name, resolver=None)` | Registers a resolver. It can be used as a decorator. Raises `ValueError` on a duplicate or invalid name. |
+| `.unregister(type_name)` | Removes a resolver. Raises `KeyError` if the type is not registered. |
+| `.resolve(global_id, *args, **kwargs)` | Calls the resolver and returns its result. Returns `None` for an unregistered type. Raises `InvalidGlobalIdError` for a malformed ID. |
+| `.global_id(type_name, local_id) -> str` | Like `to_global_id`, but raises `KeyError` for an unregistered type. |
+| `.types`, `type_name in registry` | Introspection. |
+
+### Mutations (`pyrelay.mutation`)
+
+| Name | Description |
+| --- | --- |
+| `relay_mutation(func)` | Decorator. The wrapped function is called as `wrapped(input, *args, **kwargs)`. `func` receives `input` without `clientMutationId` and must return a mapping or `None`. The payload dict always includes `clientMutationId`. Coroutine functions stay awaitable. |
+| `CLIENT_MUTATION_ID` | The constant `"clientMutationId"`. |
+
+### Errors (`pyrelay.errors`)
+
+| Name | Description |
+| --- | --- |
+| `RelayError` | Base class of all pyrelay exceptions. |
+| `InvalidGlobalIdError` | Subclass of `RelayError` and `ValueError`. |
+| `InvalidCursorError` | Subclass of `RelayError` and `ValueError`. |
+| `ConnectionArgumentError` | Subclass of `RelayError` and `ValueError`. |
+
+`__version__` holds the package version string (`"0.1.0"`).
+
+## Development
+
+```bash
+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

pyrelay-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pyrelay/__init__.py,sha256=mi_EpHrEn6fWPrV10Sfe9BE3SEkrFWAM8Kro2sulCfM,1402
+pyrelay/connection.py,sha256=tAjXLzKOcybkbXAg_f2qBP996Zv-Y8A70647zDaBtCU,7323
+pyrelay/cursors.py,sha256=WmMuAyGbnhJpu4j2u9DtBlSFQ-5Zapq-mu49h5WDOYo,2111
+pyrelay/errors.py,sha256=mYmmQ3YWzNfxidWNRcfU-PeB9lPA4IuoriADQ6JGtUY,698
+pyrelay/ids.py,sha256=EwJMPwLCF--7nc7xkLAy2ySLAyAXxtruZRZBl6lYQpI,2311
+pyrelay/mutation.py,sha256=2yCoDnN2yWXMnLHAMB5jXGZ_i6zoCjq0Mlcra-HeHfU,2673
+pyrelay/node.py,sha256=72AqkeFHab4fw4yBDLKv7LZWhMRi_csbSi76Lz4_c28,3355
+pyrelay/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pyrelay-0.1.0.dist-info/licenses/LICENSE,sha256=pAfYREEW9GAy7cnK20OXjDn7ofJahYny9GCuIZQTDAA,1061
+pyrelay-0.1.0.dist-info/METADATA,sha256=63yOGL7ruhmkSzDjy1_YKikRn-Q3gKb33F3tCr1ndGE,9308
+pyrelay-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+pyrelay-0.1.0.dist-info/top_level.txt,sha256=8HaSBt3fHoKosrbC0-WDSG9L2dJD3CTFNrusjhly9rs,8
+pyrelay-0.1.0.dist-info/RECORD,,

pyrelay-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

pyrelay-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nehz
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

pyrelay-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+pyrelay