Skip to content

API Reference

This page is generated by Zensical/mkdocstrings from exported Python package docstrings. Update the public API docstrings in src/graphrefly/ and rebuild with uv run zensical build --strict; do not edit generated site/ output by hand.

graphrefly

Python-owned facade for the GraphReFly native engine.

AsyncRunner

Framework-neutral async job runner supplied explicitly by the host.

spawn(job)

Schedule one async job in the caller-owned runtime.

ControlMessage dataclass

Non-DATA / non-ERROR observation.

Ctx

Python-owned facade for an advanced node callback invocation.

dep_len property

Return the number of declared dependencies for this invocation.

wave_data property

Return raw dep-to-wave DATA projections for advanced callbacks.

pull property

Return the active PULL demand context, if this is a pull invocation.

rewire_next property

Return the callback-scoped deferred rewire facade.

has_state property

Return whether this node has private cross-wave state.

state property writable

Return this node's private cross-wave state value.

has_data(index)

Return whether dependency index has DATA for this invocation.

data(index, default=_NO_DEFAULT) 

data(index: int) -> object

data(index: int, default: U) -> object | U

Return dependency DATA or the provided default when absent.

terminal(index)

Return terminal metadata for dependency index in this invocation.

pull_params(default=None) 

pull_params() -> object | None

pull_params(default: U) -> object | U

Return active PULL params, or default outside a param-bearing pull.

emit(value)

Emit one DATA value from this advanced node callback.

persist_state(on=True)

Opt this node's private state into checkpoint persistence.

on_invalidate(callback)

Register a cleanup hook for the current callback's INVALIDATE.

on_deactivation(callback)

Register a cleanup hook for this callback's deactivation.

request_pull(pull_id, params=None, *, toward_dep=None)

Request a PULL wave toward dependencies during this invocation.

request_pull_next(pull_id, params=None, *, toward_dep=None)

Schedule one deferred PULL request after this invocation.

DataMessage dataclass

DATA observation with a domain payload.

None is a valid domain payload in Python v1; no-DATA is represented by message shape, not by the payload value.

ErrorMessage dataclass

ERROR observation with a Python-owned error envelope.

Graph

Graph-first authoring facade over the native Rust engine.

closed property

Return whether this graph facade has been closed.

close()

Close this graph facade and release Python-owned resources.

checkpoint()

Return a strict-JSON checkpoint for this graph.

reentry_queue()

Return this graph's explicit owner-thread async re-entry queue.

retain(node, *, reason=None)

Keep a graph-local node active until the returned retain token is released.

state(value, name=None)

Create a writable graph state node with initial DATA.

producer(callback=None, name=None) 

producer(
    callback: Callable[[], T], name: str | None = None
) -> Node[T]

producer(
    callback: None = None, name: str | None = None
) -> Callable[[Callable[[], T]], Node[T]]

Create or decorate a zero-dependency producer node.

derived(deps, callback=None, name=None) 

derived(
    deps: Iterable[Node[Any]],
    callback: Callable[..., U],
    name: str | None = None,
) -> Node[U]

derived(
    deps: Iterable[Node[Any]],
    callback: None = None,
    name: str | None = None,
) -> Callable[[Callable[..., U]], Node[U]]

Create or decorate a value-level derived node over dependencies.

node(deps, callback=None, name=None, *, partial=False, complete_when_deps_complete=True, error_when_deps_error=True, terminal_as_real_input=False, pausable=True, pull_id=None, restore=None) 

node(
    deps: Iterable[Node[Any]],
    callback: Callable[[Ctx], object],
    name: str | None = None,
    *,
    partial: bool = False,
    complete_when_deps_complete: bool = True,
    error_when_deps_error: bool = True,
    terminal_as_real_input: bool = False,
    pausable: PausableMode = True,
    pull_id: str | None = None,
    restore: RestoreRef | None = None,
) -> Node[object]

node(
    deps: Iterable[Node[Any]],
    callback: None = None,
    name: str | None = None,
    *,
    partial: bool = False,
    complete_when_deps_complete: bool = True,
    error_when_deps_error: bool = True,
    terminal_as_real_input: bool = False,
    pausable: PausableMode = True,
    pull_id: str | None = None,
    restore: RestoreRef | None = None,
) -> Callable[[Callable[[Ctx], object]], Node[object]]

Create or decorate an advanced Ctx-level graph node.

effect(deps, callback=None, name=None) 

effect(
    deps: Iterable[Node[Any]],
    callback: Callable[..., object],
    name: str | None = None,
) -> Node[object]

effect(
    deps: Iterable[Node[Any]],
    callback: None = None,
    name: str | None = None,
) -> Callable[[Callable[..., object]], Node[object]]

Create or decorate a value-level effect node over dependencies.

batch(callback)

Run synchronous graph mutations inside one native batch boundary.

describe()

Return the current JSON-serializable topology snapshot.

pause(node, lock_id)

Pause a graph-local node using a caller-provided lock id.

resume(node, lock_id)

Resume a graph-local node for the given lock id.

invalidate(node)

Invalidate a graph-local node through the public graph facade.

observe(callback, *, on_error=None)

Subscribe to graph-level observation events.

GraphEvent dataclass

Graph-level observation from the native engine.

GraphReentryQueue

Owner-thread drain gate for GraphReFly-owned async completions.

closed property

Return whether this re-entry queue has been closed.

pending_count property

Return the number of private completions waiting to drain.

wrap_runner(runner)

Return an AsyncRunner adapter whose completions are drained by this queue.

drain(max_items=None)

Drain queued private completions on the graph owner thread.

close()

Close this queue and cancel queued private completions.

HttpRequest dataclass

Host-driver HTTP request material for Python network source adapters.

HttpResponse dataclass

Host-driver HTTP response material emitted by from_http.

HttpStreamChunkEvent dataclass

Streaming driver event carrying a bytes chunk.

HttpStreamCompleteEvent dataclass

Streaming driver event marking normal stream completion.

HttpStreamErrorEvent dataclass

Streaming driver event carrying a host-side stream error.

HttpStreamHead dataclass

HTTP response head material for streaming source drivers.

HttpStreamHeadEvent dataclass

Streaming driver event carrying the HTTP response head.

LocalHttpDriver

Host-owned one-shot HTTP driver used by from_http.

request(request)

Start one HTTP request and resolve to an HttpResponse.

LocalHttpStreamDriver

Host-owned streaming HTTP driver used by from_sse.

stream(request)

Start one HTTP stream and yield normalized stream events.

Node

A typed Python handle around an opaque native node.

has_value property

Return whether this node currently has cached DATA.

status property

Return the node status string from the native graph.

set(value)

Set DATA on a writable state node.

cache(default=_NO_DEFAULT) 

cache() -> T

cache(default: U) -> T | U

Return the latest cached DATA value or default when absent.

subscribe(callback, *, on_error=None)

Subscribe to this node's public observation messages.

PullContext dataclass

Read-only PULL demand context visible during a pull-holder invocation.

RestoreContext

Descriptor construction context with no raw Node/Ctx/native handles.

id property

Return the checkpoint node id being restored.

name property

Return the checkpoint node name, if one was recorded.

deps property

Return dependency ids recorded for the checkpoint node.

config property

Return restore configuration material for this node.

config_version property

Return the optional restore configuration version.

checkpoint property

Return the full loaded graph checkpoint material.

register_state()

Register the checkpoint node as a restored state node.

register_node(callback, factory=None)

Register the checkpoint node as a restored callback node.

RestoreDescriptor

A factory-name restore descriptor used by restore_graph.

create(ctx)

Create restored graph material for one checkpoint node.

RestoreRef dataclass

Factory reference metadata recorded into a strict-JSON checkpoint.

Retain

Graph-owned activation root release token.

closed property

Return whether this retain token has been released.

release()

Release this graph-owned activation root.

RewireNext

Callback-scoped deferred topology mutation facade.

subscribe_dep(dep, callback)

Subscribe this node to an additional dependency on the next wave.

unsubscribe_dep(dep, callback)

Unsubscribe this node from a dependency on the next wave.

replace_deps(deps, callback)

Replace this node's dependency set on the next wave.

Sentinel

Python representation of protocol SENTINEL in raw ctx wave data.

SseEvent dataclass

Parsed server-sent event DATA emitted by from_sse.

Subscription

Idempotent subscription handle returned by observe and subscribe calls.

closed property

Return whether this subscription has been unsubscribed.

callback_errors property

Return observer callback failures captured at the Python boundary.

unsubscribe()

Detach this subscription from its graph node or observer.

WireBridge

Graph-owned wire bridge bundle with status and issue nodes.

release()

Release the bridge and its attached child facade bundles.

WireBridgeAckDriver

Clock-driven ack timeout driver facade for a wire bridge.

release()

Release the ack driver and its owned timeout retain.

WireBridgeAckDriverIssue dataclass

Graph-visible issue DATA emitted by the bridge ack driver.

WireBridgeAckDriverStatus dataclass

Graph-visible status DATA for the bridge ack driver.

WireBridgeAckTimeout dataclass

Graph-visible ack timeout fact emitted by the ack driver.

WireBridgeIssue dataclass

Graph-visible issue DATA emitted by a wire bridge facade.

WireBridgeProtobuf

High-level protobuf byte transport facade for a wire bridge.

release()

Release the protobuf transport facade and owned subscriptions.

WireBridgeProtobufIssue dataclass

Graph-visible protobuf validation issue DATA.

WireBridgeProtobufStatus dataclass

Graph-visible validation status for protobuf byte transport.

WireBridgeStatus dataclass

Graph-visible status DATA for a high-level wire bridge facade.

WireEdgeGroup

High-level wire edge group facade for inbound or outbound edge facts.

release()

Release the edge group facade and owned subscriptions.

WireEdgeGroupIssue dataclass

Graph-visible issue DATA emitted by a wire edge group.

WireEdgeGroupStatus dataclass

Graph-visible status DATA for a wire edge group.

CallbackError

A Python callback failed and is mapped into graph ERROR.

GraphCallbackError

Callback failure represented as a graph ERROR payload.

GraphReflyCheckpointError

Checkpoint material is not restorable strict JSON.

GraphReflyError

Base class for public Python facade errors.

GraphReflyNoDataError

A node has no cached DATA value at the public Python boundary.

GraphReflyRestoreError

A checkpoint restore failed honestly at the graph boundary.

GraphReflyRuntimeError

Runtime boundary failure from the native graph engine or host facade.

GraphReflyValueError

Invalid public API value for this facade slice.

SubscriberCallbackError

A subscribe/observe callback failed at the Python observer boundary.

DataIssue dataclass

Reserved DATA payload for domain/material issues, not protocol ERROR.

anyio_runner(task_group)

Return a convenience runner for a caller-owned AnyIO task group.

async_node(graph, deps, runner, callback, *, name=None, pausable=True)

Create a value-level async compute node over declared dependencies.

asyncio_runner(loop=None)

Return a convenience runner for a caller-owned asyncio event loop.

from_async_iter(graph, runner, factory, *, name=None, pausable=True)

Create a source from a fresh async iterable produced on each activation.

from_awaitable(graph, runner, factory, *, name=None, pausable=True)

Create a source from a fresh awaitable produced on each activation.

from_http(graph, request_or_url, *, driver=None, runner=None, name=None, pausable=True)

Create a source from one host-supplied HTTP request driver call.

from_sse(graph, request_or_url, *, stream_driver=None, runner=None, name=None, pausable=True)

Create an SSE source over a host-supplied HTTP byte-stream driver.

restore_graph(checkpoint, *, registry)

Construct a fresh graph from an already-loaded strict-JSON checkpoint.

restore_ref(ref, *, config=None, config_version=None)

Return strict-JSON factory metadata for a restorable function-backed node.

restore_registry(entries, *, include_builtins=True)

Build an explicit restore registry for restore_graph.

trio_runner(nursery)

Return a convenience runner for a caller-owned Trio nursery.

version()

Return the installed Python package version.

wire_bridge(graph, *, session_id, name=None)

Create a graph-owned high-level wire bridge facade.

wire_bridge_ack_driver(graph, bridge, *, clock, timeout_ms, name=None)

Attach a clock-driven ack timeout driver to a bridge.

wire_bridge_protobuf(graph, bridge, *, name=None)

Attach protobuf byte transport nodes to a wire bridge.

wire_edge_group(graph, bridge, *, name=None, inbound_edges=None, outbound_edges=None)

Attach inbound or outbound wire edge grouping to a bridge.