Garphield Python API reference

The public building blocks behind projects, adapters, and notebook views.

Canonical bytes

RFC 8785 (JCS) canonical bytes determine fingerprints, not the saved file. The package exports all three functions so you can reproduce them.

from garphield import (
    canonicalize_jcs_v1,
    canonicalize_project_v1,
    canonicalize_semantic_graph_v1,
)

Function	Covers
`canonicalize_jcs_v1(value)`	Any JSON value.
`canonicalize_project_v1(project)`	The whole document. Feeds `project_fingerprint()`.
`canonicalize_semantic_graph_v1(project)`	The graph only. Feeds `semantic_fingerprint()`.

A value that cannot be canonicalized raises CanonicalizationError.

Offline project links

Function	Result
`share_string(project)`	Versioned compact `z2.` project carrier.
`share_url(project, *, base="https://garphield.com/")`	Absolute URL with the carrier in `#p=`.

Both require a validated Project, canonicalize and compress it locally, and perform no network I/O. base must be an absolute HTTP(S) URL; any existing query or fragment is removed. The browser accepts legacy z1. project links; new Python, R, and browser encoders emit z2..

Identity codecs

The adapters use these to move Python values through JSON while preserving their types. The package exports them for anyone writing another adapter.

Codec	Handles
`IdentityCodecV1`	Node identities.
`EdgeIdentityCodecV1`	Edge keys, scoped to their endpoint pair.
`AttributeNameCodecV1`	Logical attribute names, including reserved ones.

Reserved names are id, source, target, key, and anything starting with _gph:. The manifest escapes them and restores them on the way back.

Transport limits

The transport between a notebook kernel and the view has a 1 MiB payload limit. The runtime refuses larger payloads; it does not truncate them.

from garphield import TRANSPORT_RUNTIME_CONFIG_V1
TRANSPORT_RUNTIME_CONFIG_V1.to_dict()

prepare_budgeted_json, receive_budgeted_json, PreparedBudgetedJson and AnyWidgetTransportEndpoint are exported for custom hosting.

`GraphView`

show() returns GraphView. Its high-level methods are synchronous and return the view where chaining is useful.

Method	Result
`select(nodes)`, `clear_selection()`	Select logical Python node identities.
`fit()`	Fit the graph camera.
`frame(nodes=...)`, `focus(node)`, `selection_mode(mode)`	Frame/focus logical nodes and choose pointer, marquee, or lasso selection.
`select_polygon(points)`	Select nodes inside a polygon.
`set_layout(mode)`, `relax(hold=...)`	Change or locally relax layout.
`bind(channel, source)`	Bind an attribute name or `algorithm()`.
`get_selection()`	Read selected logical identities.
`to_project()`, `to_networkx()`	Read back the current settled document.
`save(path)`	Save the current document.
`capture()`	Return an in-memory PNG `Artifact`.
`save_png(path)`, `save_html(path)`	Create an app-owned artifact and write it atomically.
`export(format, target=...)`	Create a typed artifact in one of the app’s export formats.
`reclaim()`	Explicitly recover from a lost full-app peer.
`close()`	Release the runtime and connection.

status is connecting, ready, in_app, closed, or error.

Artifacts expose manifest, file_name, mime, data, and an optional path. The manifest includes semantic/project fingerprints, included state, declared losses, and replay availability. Export targets are never overwritten unless overwrite=True; results larger than the temporary notebook transport budget continue in the full Garphield app through the browser download surface.

Errors

Error	Raised when
`ProjectValidationError`	A document fails schema validation.
`ProjectShareError`	A project link or base URL cannot be encoded safely.
`ProjectShareTooLargeError`	An inline project link exceeds 262,144 characters.
`DuplicatePropertyError`	A document has the same key twice.
`CanonicalizationError`	A value cannot be canonicalized to JCS bytes.
`IdentityCollisionError`	Two identities collide once encoded.
`WidgetNotDisplayedError`	A widget call runs before the view is ready.
`WidgetEnvironmentUnsupportedError`	The environment cannot host the widget.
`WidgetTransportError`	A widget request times out or breaks protocol.
`OwnershipError`	The passive notebook attempts a live mutation or project read.
`TransportError`	A transfer exceeds the budget or arrives malformed.
`ArtifactManifest` / `Artifact`	Typed export metadata and bytes returned by the app.