lsdtools.views reference

``lsdtools.views`` — the data-view façade. Lazy imports (the ``generate_step`` pattern): importing
``lsdtools`` never drags a view package (or cairo/GTK) into the process; each factory imports its
package on first use and raises a clear error if it is not installed.

    from lsdtools import views
    v = views.table(my_table)                    # a TableView, fed
    c = views.chart(kind="line", title="Loss")
    f = views.flowchart("A\n  B\n  C")
    print(v.to_text()); c.to_image("chart.png")

A custom data view registers its GTK drawing shell here — the one sanctioned place a package writes
GTK. In your view's ``gtk`` module (loaded via the ``lsd.view_gtk`` entry point)::

    from lsdtools.views import set_view_shell
    set_view_shell("my.kind", build_my_shell)     # build_my_shell(view) -> a Gtk.Widget

One fresh exact input choice for a hierarchy View action.

Renderers must enumerate choices again at invocation and pass the exact
``values`` mapping.  A first/default choice is never inferred.

id: str

label: str

values: Mapping[str, Any]

description: str

description = ''

values_dict(self) -> dict[str, Any]

self: (unannotated)

Return a detached mutable copy of the exact input values.

Raised when an action exposes fresh choices but none was supplied.

Raised when supplied values do not match one freshly enumerated choice.

A safe, user-facing error raised by the hierarchy action-input contract.

HierarchyView(self, **config: Any) -> None

A scalable keyed hierarchy with package-overridable interaction hooks.

kind = 'hierarchy'

search = param(str, default='', label='Search', description='Case-insensitive label, description, and node-kind search.')

selection = param(str, default='single', choices=['none', 'single', 'multi'], label='Selection')

__init__(self, **config: Any) -> None

config: Any
self: (unannotated)

get_action_choices(self, action_name: str) -> Sequence[HierarchyActionChoice]

action_name: str
self: (unannotated)

Return fresh exact choices for *action_name*; subclasses override.

invoke_action(self, action_name: str, *, values: Mapping[str, Any] | None=None) -> Any

action_name: str
self: (unannotated)
values: Mapping[str, Any] | None

Invoke an action with an optional freshly validated exact choice.

action_input(self, action_name: str | None=None) -> dict[str, Any] | None

action_name: str | None
self: (unannotated)

Return a detached exact choice only while its action is executing.

feed(self, data: Any) -> HierarchyView

data: Any
self: (unannotated)

Replace the forest after validating every row, edge, cycle, and count.

Input order is the stable order for roots and siblings.  Optional fields
may be omitted, but unknown fields are rejected and the exposed rows
always contain the complete canonical contract.

nodes(self) -> tuple[dict[str, Any], ...]

self: (unannotated)

All canonical rows in stable forest preorder (detached copies).

semantic_item_count(self) -> int

self: (unannotated)

Return the number of canonical hierarchy items, independent of UI state.

semantic_items(self, *, offset: int=0, limit: int=100) -> tuple[dict[str, Any], ...]

limit: int
offset: int
self: (unannotated)

Return one bounded detached page of canonical items in forest preorder.

Discovery is independent of search, expansion, and selection. The
preorder is sliced before row dictionaries are materialized so a small
request never copies the complete hierarchy.

node(self, node_id: str) -> dict[str, Any]

node_id: str
self: (unannotated)

Return one canonical detached row by exact node id.

selected_ids(self) -> tuple[str, ...]

self: (unannotated)

Durable selection ids in user selection order, including pending restored ids.

expanded_ids(self) -> tuple[str, ...]

self: (unannotated)

Durable expansion ids in first-expanded order, including pending restored ids.

visible_nodes(self) -> tuple[dict[str, Any], ...]

self: (unannotated)

Rows currently visible under search and expansion, in stable preorder.

Search reveals each match and its ancestor path without mutating durable
expansion state.  With no search, only roots and descendants of expanded
nodes are returned.

expand(self, node_id: str) -> None

node_id: str
self: (unannotated)

collapse(self, node_id: str) -> None

node_id: str
self: (unannotated)

toggle(self, node_id: str) -> None

node_id: str
self: (unannotated)

select(self, node_ids: str | Iterable[str]) -> Any

node_ids: str | Iterable[str]
self: (unannotated)

Set the keyed selection, then invoke ``on_selection_changed``.

Explicit interactive selection accepts only resident ids.  Restored
state may retain pending ids until a later feed, mirroring keyed table
selection across asynchronous data delivery.

clear_selection(self) -> Any

self: (unannotated)

activate(self, node_id: str) -> Any

node_id: str
self: (unannotated)

Activate one resident node and invoke ``on_activated``.

on_selection_changed(self, selected_ids: tuple[str, ...]) -> Any

selected_ids: tuple[str, ...]
self: (unannotated)

Override to project generic keyed selection into domain behavior.

on_activated(self, node_id: str) -> Any

node_id: str
self: (unannotated)

Override to handle row activation without coupling the generic view.

get_state(self) -> dict[str, Any]

self: (unannotated)

apply_state(self, state: dict[str, Any]) -> None

self: (unannotated)
state: dict[str, Any]

to_text(self) -> str

self: (unannotated)

One fresh, exact input choice for an inherited :func:`lsdtools.action`.

``id`` is stable identity for renderers, while ``values`` is the exact JSON-safe mapping that is
validated again at invocation time. Containers are recursively frozen; :meth:`values_dict`
returns a detached ordinary dictionary for a caller that needs one.

id: str

label: str

values: Mapping[str, Any]

description: str

description = ''

values_dict(self) -> dict[str, Any]

self: (unannotated)

A detached mutable copy of the exact action values.

Raised when an action declares choices but no exact choice was supplied.

Raised when supplied action values do not match a freshly enumerated choice.

A safe, user-facing error raised by the table action-input contract.

TableView(self, **config: Any) -> None

Show a :class:`~lsdtools.Table` as an interactive grid. ``feed(table_or_data)`` sets the data;
the config params below choose the presentation (column subset, page size, selection mode) and the
live view state (``sort_by`` / ``sort_desc`` / ``filter``). The headless ``to_text()`` is the
aligned-ASCII preview of the composed (filtered + sorted) view.

kind = 'table'

columns = param(str, default='', label='Columns', description='Comma-separated subset to show; empty = all')

page_size = param(int, default=20, min=1, max=10000, label='Rows per page')

selection = param(str, default='none', choices=['none', 'single', 'multi'], label='Selection')

key_columns = param(str, default='', label='Key columns', description='Comma-separated columns that uniquely identify a row. When set, selection survives sorting, filtering, paging, and replacement feeds.')

sort_by = param(str, default='', label='Sort by', description="Column to sort on; empty = the data's natural order")

sort_desc = param(bool, default=False, label='Descending')

filter = param(str, default='', label='Filter', description='Case-insensitive substring; keeps rows matching in any shown column')

__init__(self, **config: Any) -> None

config: Any
self: (unannotated)

get_action_choices(self, action_name: str) -> Sequence[TableActionChoice]

action_name: str
self: (unannotated)

Return fresh exact choices for *action_name*.

Subclasses override this for actions whose inputs depend on live project state. Returning an
empty sequence preserves ordinary zero-argument ``View.invoke`` behaviour. Choices are never
cached by the model and must not be treated as durable domain state.

invoke_action(self, action_name: str, *, values: Mapping[str, Any] | None=None) -> Any

action_name: str
self: (unannotated)
values: Mapping[str, Any] | None

Invoke an inherited action with an optional exact dynamic choice.

Choices are re-enumerated on every call. If one or more exist, *values* must exactly match
one fresh choice; no first/default choice is inferred. The validated detached mapping is
available only for the duration of the ordinary zero-argument action through
:meth:`action_input`, preserving the canonical :meth:`View.invoke` dispatch and event.

action_input(self, action_name: str | None=None) -> dict[str, Any] | None

action_name: str | None
self: (unannotated)

Return the validated input for the currently executing action, else ``None``.

The result is detached on every read. Supplying *action_name* guards against accidentally
consuming a nested action's input and raises when it does not name the active action.

feed(self, data: Any) -> None

data: Any
self: (unannotated)

Accept a table-like value.

Positional selection is cleared. Keyed selection is retained, including keys not present
in this feed: a filter, remote page, or temporarily incomplete rerun must not silently
destroy the user's semantic selection.

key_column_names(self) -> List[str]

self: (unannotated)

Configured key columns in declaration order (a copy safe for callers to mutate).

view_table(self) -> Optional[Table]

self: (unannotated)

The composed view: the configured column subset, filtered by ``filter`` and ordered by
``sort_by`` / ``sort_desc`` — **all** matching rows (paging is applied separately by
:meth:`page_table`). ``None`` until fed.

semantic_item_count(self) -> int

self: (unannotated)

Number of rows addressable through the generic View semantic protocol.

semantic_items(self, *, offset: int=0, limit: int=100) -> tuple[dict[str, Any], ...]

limit: int
offset: int
self: (unannotated)

Return one composed row page using stable configured keys when available.

This is the sole control-plane projection for table rows.  Hidden key columns remain
usable as identity without being added back to the presented row data.

page_table(self) -> Optional[Table]

self: (unannotated)

The current page of the composed view (``page_size`` rows starting at ``_page``).

row_count(self) -> int

self: (unannotated)

Rows in the composed (filtered) view — not the raw fed table.

total_count(self) -> int

self: (unannotated)

Rows across every page; cursor-backed subclasses may override.

page_count(self) -> int

self: (unannotated)

set_page(self, page: int) -> None

page: int
self: (unannotated)

Select and clamp a zero-based page.

Cursor-backed subclasses override this to fetch their remote page.

selected_rows(self) -> List[int]

self: (unannotated)

Selected positions in the current composed/resident table.

With ``key_columns``, :attr:`selected_keys` is authoritative and these positions are
recomputed whenever presentation order changes.

selected_keys(self) -> List[List[Any]]

self: (unannotated)

The authoritative semantic selection as ordered JSON-safe compound keys.

selected_page_rows(self) -> List[int]

self: (unannotated)

Zero-based positions selected on the current page, for any presentation shell.

select_keys(self, keys: Any) -> None

keys: Any
self: (unannotated)

Set semantic selection directly.

Keys are ordered lists whose width matches ``key_columns``. Values must be JSON scalars;
unresolved keys are retained so remote paging and transient reruns cannot erase intent.

select_rows(self, rows: Any) -> None

rows: Any
self: (unannotated)

Set selection by composed-view row positions.

With ``key_columns`` the positions are immediately resolved to semantic keys. Otherwise this
retains the original positional behaviour. Emits ``selection-changed``.

select_page_rows(self, rows: Any) -> None

rows: Any
self: (unannotated)

Apply a UI gesture expressed as positions within the current page.

In keyed multi-select mode, selections on unloaded pages are retained. Positional mode keeps
its historical page-relative-to-global conversion.

get_selection(self) -> Optional[Table]

self: (unannotated)

Selected resident rows as a sub-table in current view order.

A remote keyed view can retain keys from unloaded pages; only selected rows in the resident
page are returned here.

set_column_renderer(self, column: str, renderer: Optional[str]) -> None

column: str
renderer: Optional[str]
self: (unannotated)

Render *column*'s cells through the registered cell renderer named *renderer* (see
:func:`lsd_view_table.register_cell_renderer`) instead of the default label. ``renderer=None``
(or ``""``) clears it. Headless config: it's stored as data here and applied by the GTK shell;
an unknown name simply falls back to the label. Emits ``data-changed`` so a live grid rebuilds.

column_renderers(self) -> Dict[str, str]

self: (unannotated)

The ``{column: renderer_name}`` map the GTK shell passes to ``ColumnGrid.set_columns``.

to_text(self) -> str

self: (unannotated)

to_csv(self) -> str

self: (unannotated)

The composed (filtered + sorted) view as CSV text — the copy / export payload.

get_state(self) -> dict

self: (unannotated)

apply_state(self, state: dict) -> None

self: (unannotated)
state: dict

View(self, *, name: str='', icon: Optional[str]=None, **config: Any) -> None

A presentable surface: ``param()`` fields + ``@action`` operations + optional data.

Subclass it for a **panel** (params + actions). Set a ``kind`` and override ``feed`` /
``to_text`` / ``to_image`` for a **data view** (table / chart / flowchart / custom).

kind: ClassVar[str]

kind = ''

ctx: ClassVar[Any]

ctx = None

title = param(str, default='', label='Title')

location = param(str, default='editor', choices=['editor', 'sidebar'], label='Location', visibility='hidden')

__init__(self, *, name: str='', icon: Optional[str]=None, **config: Any) -> None

config: Any
icon: Optional[str]
name: str
self: (unannotated)

engine(self) -> Any

self: (unannotated)

The :class:`~lsd.runtime.engine.Engine` this view is attached to (``engine.add(view)``),
or ``None`` — the symmetry partner of :attr:`Entity.engine`.

watch(self, *targets: Any) -> 'View'

self: (unannotated)
targets: Any

Hold the output of each :class:`~lsd.tree.entity.Entity` in *targets*, and refresh on re-run.

Each target is an ``Entity``, a stable entity id, or an unambiguous display name (sugar).
Returns ``self``, so
``views.table().watch(assays)`` reads as one phrase. **Any order works**:

* *add-then-watch*, *watch-then-add* (view or entity first) — all equivalent;
* a missing string reference is kept **pending** and resolves when that entity is added;
* **auto-pull** — watching an entity that has *already* run delivers its output immediately,
  which is what makes drag-and-drop and reopened projects feel instant.

Watches are stored by entity **id**, so they survive a rename and a project reload; removal
from the Workspace auto-unwatches them. Delivery goes through :meth:`on_output` (default:
``feed(output)``) on ``engine/entity/finished`` with ``ok=True``.

watch_output(self, *references: OutputRef) -> 'View'

references: OutputRef
self: (unannotated)

Watch exact named step outputs and refresh them after successful runs.

Each reference contains only stable ``entity_id`` + ``step_id`` +
declared ``output_port`` coordinates.  A structurally valid reference
may be registered before its entity is attached; once the entity is
present, a missing step or undeclared port is rejected and never falls
back to :attr:`Entity.output`.

unwatch_output(self, *references: OutputRef) -> 'View'

references: OutputRef
self: (unannotated)

Stop watching exact output references; unknown references are ignored.

unwatch(self, *targets: Any) -> 'View'

self: (unannotated)
targets: Any

Stop watching each entity (or entity name) in *targets*. Unknown targets are ignored.
Already-delivered data stays — unwatching breaks the link, it does not clear the view.

watched(self) -> List[str]

self: (unannotated)

The names of the entities this view watches — live (a renamed entity reports its new name),
plus any names still pending an entity. Watch order is preserved.

watched_outputs(self) -> List[OutputRef]

self: (unannotated)

Exact output references in watch order (a detached copy).

on_output(self, entity: Any, output: Any) -> None

entity: Any
output: Any
self: (unannotated)

Called with a watched *entity*'s fresh output. The default hands it to :meth:`feed`.

Override for a view that watches several entities at once (e.g. a 3-D viewer keying layers by
``entity.id``), where last-write-wins ``feed`` is not what you want.

on_output_ref(self, entity: Any, reference: OutputRef, output: Any) -> None

entity: Any
output: Any
reference: OutputRef
self: (unannotated)

Receive one exact named output; defaults to :meth:`on_output`.

Multi-output views may override this method to retain ``reference`` as
the semantic key while legacy views continue to override ``on_output``.

get_actions(self) -> List[ActionInfo]

self: (unannotated)

Snapshot of all actions, in declaration order — for a renderer / CLI to build controls.

set_action_input_initial(self, name: str, value: Mapping[str, Any] | None) -> None

name: str
self: (unannotated)
value: Mapping[str, Any] | None

Replace one complete action-form snapshot, or make that form unavailable.

This is runtime presentation state, never persisted View configuration. A caller must
supply every declared field, including hidden versions and optimistic fences. Removing a
snapshot disables the form; it never turns an input action into a zero-input command.

set_action_input_initials(self, values: Mapping[str, Mapping[str, Any]]) -> None

self: (unannotated)
values: Mapping[str, Mapping[str, Any]]

Atomically replace every currently available typed-action form snapshot.

invoke(self, name: str, *, input: Any=_NO_ACTION_INPUT) -> Any

input: Any
name: str
self: (unannotated)

Run an action by name and return its result. The single dispatch entry for every
front-end. Emits ``view/action/invoked``. Unknown name → ``AttributeError``; a disabled
action is a logged no-op.

feed(self, data: Any) -> 'View'

data: Any
self: (unannotated)

Give the view its data (a Table, a payload dict, a graph…). Data views store it and call
:meth:`_data_changed`; a params-and-actions panel has no data, so the base raises.

on_view_event(self, event: str, cb: Callable[..., None]) -> None

cb: Callable[..., None]
event: str
self: (unannotated)

off_view_event(self, event: str, cb: Callable[..., None]) -> None

cb: Callable[..., None]
event: str
self: (unannotated)

emit_view_event(self, event: str, **data: Any) -> None

data: Any
event: str
self: (unannotated)

to_text(self) -> str

self: (unannotated)

A plain-text rendering (agents / CLI / logs). Data views override; the base (a panel) is a
params + actions summary.

to_image(self, path: Optional[str]=None, *, width: int=1024, height: int=768) -> 'bytes | str'

height: int
path: Optional[str]
self: (unannotated)
width: int

Render to a PNG — returns the bytes, or writes to *path* and returns it. Data views that
can draw override this (lazily importing cairo); the base signals it is unsupported.

get_state(self) -> dict

self: (unannotated)

A JSON-able snapshot: the config param values plus the ``watch`` links (data views extend
with data/selection). ``watch`` is ``{"ids": {entity id: name}, "pending": [name]}`` — ids,
so a restored view re-links to the same entities across a rename and a project reload.

apply_state(self, state: dict) -> None

self: (unannotated)
state: dict

show(self, mode: str='auto') -> Any

mode: str
self: (unannotated)

Present the view. ``mode``: ``"window"`` opens a front-end window (needs a presenter),
``"text"`` prints the console rendering, ``"auto"`` (default) is a window if a presenter is
registered (a front-end is loaded), else text.

available() -> list[str]

Installed data-view kinds, discovered without importing their packages.

cadquery_studio(*, recipe: Any, view_id: str | None=None)

recipe: Any
view_id: str | None

Build the native code-left / 3-D-right CadQuery Studio presentation.

``recipe`` must be immutable package-owned source with bounded typed
parameters.  This factory intentionally exposes no source-string executor:
arbitrary project Python remains behind Desktop's explicit code-consent
workflow.

chart(data: Any=None, *, kind: str='line', **config: Any)

config: Any
data: Any
kind: str

A :class:`ChartView` (from ``lsd-view-chart``) of *kind*, fed *data* if given.

dashboard(data: Any=None, *, document: Any=None, **config: Any)

config: Any
data: Any
document: Any

A :class:`DashboardView` (from ``lsd-view-dashboard``), optionally fed *data*.

``document`` is a versioned report definition; source tables remain transient and are never
embedded into its persisted state.

flowchart(source: Any=None, **config: Any)

config: Any
source: Any

A :class:`FlowchartView` (from ``lsd-view-flowchart``), fed *source* (DSL/Graph) if given.

hierarchy(data: Any=None, **config: Any)

config: Any
data: Any

A generic keyed :class:`HierarchyView`, fed *data* when supplied.

set_view_shell(kind: str, factory: Callable[..., Any]) -> None

factory: Callable[..., Any]
kind: str

Register the callable that turns a data view of *kind* into a front-end control (a GTK widget).
Called by a view package's ``gtk`` module — the only sanctioned place to write GTK.

table(data: Any=None, **config: Any)

config: Any
data: Any

A :class:`TableView` (from ``lsd-view-table``), fed *data* if given.

view_shell(view: 'View', **kwargs: Any) -> Any

kwargs: Any
view: 'View'

Build the front-end control for a data *view* via its registered shell, or raise a clear error.

view_type(kind: str) -> Optional[type]

kind: str