The Tree (pdv_tree)

pdv_tree is the live project data tree. It behaves like a Python dict but with a few important differences:

• Dot-paths. Keys may contain . to address nested nodes: pdv_tree['results.run_01.temperature'] resolves through intermediate dicts, creating them on write if needed.
• Change notifications. Assignments, deletions, and mutations are observed by the app; the UI tree panel refreshes automatically.
• Persistence. Everything stored in pdv_tree is serialized when the project is saved. Values outside the tree are not.

The tree is the sole source of truth for project data. Any state a user wants to keep across sessions must live here.

PDVTree

PDVTree(*args: Any, **kwargs: Any)

Bases: dict

The live project data tree. The sole authority on all project data.

A dict subclass that supports:

• Dot-path access: pdv_tree['data.waveforms.ch1']
• Change notification: mutations emit a pdv.tree.changed comm push notification (when a comm is attached via _attach_comm).
• Script execution: pdv_tree.run_script('scripts.analysis.fit', x=1)

Injected into the kernel namespace as pdv_tree (protected — cannot be reassigned).

Parameters:

Name	Type	Description	Default
*args	Any	Forwarded to dict.init.	()
**kwargs	Any	Forwarded to dict.init.	()

See Also

ARCHITECTURE.md §5.6, §7.1

set_quiet

set_quiet(key: str, value: Any) -> None

Set a value at a dot-path without emitting notifications.

Used by bulk loaders (project load, module register) to populate the tree without flooding the comm channel with per-node pdv.tree.changed events. Uses the same dot-path traversal and "replace non-dict intermediate" branch as :meth:__setitem__.

After bulk loading completes, callers typically emit a single pdv.project.loaded push so renderers know to refetch.

Parameters:

Name	Type	Description	Default
key	str	A plain key or dot-separated path.	required
value	Any	The value to store.	required

pop

pop(key: str, *args: Any) -> Any

Remove and return value at key, emitting a change notification.

Supports dot-separated paths. Accepts an optional default that is returned (without notification) when key is missing.

update

update(*args: Any, **kwargs: Any) -> None

Merge key/value pairs, emitting a notification for each key.

clear

clear() -> None

Remove all keys, emitting a removal notification for each.

setdefault

setdefault(key: str, default: Any = None) -> Any

Get key if present, otherwise set it to default and notify.

popitem

popitem() -> tuple

Remove and return an arbitrary (key, value) pair with notification.

run_script

run_script(script_path: str, **kwargs: Any) -> Any

Execute a script stored in the tree.

Resolves script_path to a :class:PDVScript node and calls script.run(self, **kwargs).

Parameters:

Name	Type	Description	Default
script_path	str	Dot-separated path to the script node (e.g. 'scripts.analysis.fit_model').	required
**kwargs	Any	Forwarded to the script's run() function.	{}

Returns:

Type	Description
Any	Return value of the script's run() function.

Raises:

Type	Description
PDVKeyError	If no node exists at script_path.
TypeError	If the node at script_path is not a :class:PDVScript.
PDVScriptError	If the script raises during execution.