Skip to content

Tree Node Types

The tree stores two kinds of values:

  1. Plain Python data — numbers, strings, lists, NumPy arrays, pandas DataFrames, and nested dicts. PDV serializes these directly using its built-in type detection.
  2. Typed file nodes — instances of the classes documented below. Each one wraps a file on disk and carries enough metadata for PDV to render, edit, or execute it from the UI.

Construct a node and assign it into the tree at a dot-path:

from pdv import PDVScript, PDVNote

pdv_tree['analysis.fit'] = PDVScript(relative_path='fit.py')
pdv_tree['notes.intro']  = PDVNote(relative_path='intro.md', title='Intro')

All node types are importable from the top-level pdv package. PDVFile is the base class for every file-backed node — its attributes (relative_path, source_rel_path, resolve_path) are inherited by all of the subclasses below.

PDVFile 

PDVFile(uuid: str, filename: str, source_rel_path: str | None = None)

Base class for file-backed PDV tree nodes.

Provides shared UUID-based file storage and preview() interface used by both :class:PDVScript and :class:PDVNote, and any future file-backed node types (images, data files, etc.).

Parameters:

Name Type Description Default
uuid str

12-hex-character UUID identifying this node's storage directory.

 required
filename str

Original filename including extension (e.g. 'fit.py').

 required
source_rel_path str or None

For module-owned files, the path of this file relative to the module root (e.g. "scripts/run.py" or "lib/helpers.py") as it exists inside the pristine <saveDir>/modules/<id>/ directory. Used by the save-time sync step in handle_project_save so edits made in the working directory can be mirrored back to the project-local module copy. None for non-module files (ordinary project scripts, notes, etc.).

 None
See Also

ARCHITECTURE.md §5.7, §5.13

uuid property 

uuid: str

12-hex-character UUID for this node's storage directory.

Returns:

Type Description
str

filename property 

filename: str

Original filename including extension.

Returns:

Type Description
str

source_rel_path property 

source_rel_path: str | None

Path relative to the owning module's root, or None.

Returns:

Type Description
str or None

For module-owned files, the rel-path inside <saveDir>/modules/<id>/. None for files that do not belong to a module.

resolve_path 

resolve_path(working_dir: str | None = None) -> str

Resolve the backing file to an absolute path.

Computes <working_dir>/tree/<uuid>/<filename>.

Parameters:

Name Type Description Default
working_dir str or None

Working directory (or save directory) containing the tree/ subdirectory. When None, the current session's working directory is obtained from the global pdv_tree.

 None

Returns:

Type Description
str

Absolute file path.

Raises:

Type Description
RuntimeError

If no working directory is available (no argument and no active session).

preview 

preview() -> str

Return a short human-readable preview for the tree panel.

Returns:

Type Description
str

Preview string. Subclasses should override for domain-specific previews.

PDVScript 

PDVScript(uuid: str, filename: str, language: str = 'python', doc: str | None = None, module_id: str = '', source_rel_path: str | None = None)

Bases: PDVFile

Lightweight wrapper for a script file stored as a PDV tree node.

Stored as the value at a tree path (e.g. pdv_tree['scripts.analysis.fit']). Calling script.run(pdv_tree, **kwargs) loads the script module fresh (no cache) and calls its run(tree, **kwargs) function.

Parameters:

Name Type Description Default
uuid str

12-hex-character UUID for this node's storage directory.

 required
filename str

Script filename including extension (e.g. 'fit.py').

 required
language str

Language of the script. Currently only 'python' is supported.

 'python'
doc str or None

First line of the script's docstring, used as a preview. If None, extracted from the file automatically.

 None
See Also

ARCHITECTURE.md §5.7

language property 

language: str

Script language. Currently always 'python'.

Returns:

Type Description
str

Script language identifier.

doc property 

doc: str | None

First line of the script docstring, or None.

Returns:

Type Description
str or None

Cached script doc preview line.

preview 

preview() -> str

Return a short human-readable preview string for the tree panel.

Returns:

Type Description
str

The first line of the docstring, or empty string when the script has no docstring (the chip already says script).

run 

run(tree: 'PDVTree' | None = None, **kwargs: Any) -> Any

Load and execute the script, calling its run() function.

Loads the module fresh on every call (no import cache). The script module must define a run(tree, **kwargs) function.

Parameters:

Name Type Description Default
tree PDVTree or None

The live project data tree, passed as the first argument to the script's run() function. When omitted, the bootstrapped global tree from pdv.comms is used.

 None
**kwargs Any

Additional keyword arguments forwarded to run().

 {}

Returns:

Type Description
Any

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

Raises:

Type Description
FileNotFoundError

If the script file does not exist on disk.
PDVScriptError

If the script has no run() function, if no tree is available, or if run() raises.

PDVNote 

PDVNote(uuid: str, filename: str, title: str | None = None)

Bases: PDVFile

Lightweight wrapper for a markdown file stored as a PDV tree node.

Stored as the value at a tree path (e.g. pdv_tree['notes.intro']). Backed by a .md file in the working directory.

Parameters:

Name Type Description Default
uuid str

12-hex-character UUID for this node's storage directory.

 required
filename str

Note filename (e.g. 'intro.md').

 required
title str or None

Optional title for the note, used as a preview fallback. If None, the first non-empty line of the file is used.

 None
See Also

ARCHITECTURE.md §7.2, PLANNED_FEATURES.md Feature 4

title property 

title: str | None

Optional title for the note.

Returns:

Type Description
str or None

Cached title, or None if not set.

preview 

preview() -> str

Return a short preview string for the tree panel.

Returns the cached title (or empty string when there is no title — the chip already says note).

Returns:

Type Description
str

A short preview string (≤100 characters).

PDVGui 

PDVGui(uuid: str, filename: str, module_id: str | None = None, source_rel_path: str | None = None)

Bases: PDVFile

File-backed GUI definition node.

Stored as the value at a tree path (e.g. pdv_tree['my_module.gui']). Backed by a .gui.json file in the working directory.

Parameters:

Name Type Description Default
uuid str

12-hex-character UUID for this node's storage directory.

 required
filename str

GUI filename (e.g. 'editor.gui.json').

 required
module_id str or None

Module identifier for module-owned GUIs. None for user-created project GUIs.

 None

module_id property 

module_id: str | None

Module identifier, or None for project-level GUIs.

Returns:

Type Description
str or None

The module id this GUI belongs to.

preview 

preview() -> str

Return a short preview string for the tree panel.

Returns empty string — the chip already says gui and the key column already shows the user-chosen name. There's no additional info worth surfacing here.

PDVNamelist 

PDVNamelist(uuid: str, filename: str, format: str = 'auto', module_id: str | None = None, source_rel_path: str | None = None)

Bases: PDVFile

File-backed namelist node. Knows its format for parsing dispatch.

Stored as the value at a tree path (e.g. pdv_tree['module.solver_nml']). Backed by a Fortran .in/.nml or TOML file.

Parameters:

Name Type Description Default
uuid str

12-hex-character UUID for this node's storage directory.

 required
filename str

Namelist filename (e.g. 'solver.nml').

 required
format str

Namelist format: 'fortran', 'toml', or 'auto' (detect from extension).

 'auto'
module_id str or None

Module identifier for module-owned namelists. None for user-created namelists.

 None
See Also

ARCHITECTURE.md §7.2

format property 

format: str

Namelist format: 'fortran', 'toml', or 'auto'.

Returns:

Type Description
str

module_id property 

module_id: str | None

Module identifier, or None for user-created namelists.

Returns:

Type Description
str or None

preview 

preview() -> str

Return a short preview string for the tree panel.

Returns the namelist format only; the chip already says namelist, so prefixing it again would be redundant.

PDVLib 

PDVLib(uuid: str, filename: str, module_id: str | None = None, source_rel_path: str | None = None)

Bases: PDVFile

File-backed Python library file provided by a module.

Stored as the value at a tree path under <alias>.lib.*. The parent directory of the on-disk file is added to sys.path so that the module is importable from scripts and entry points.

Parameters:

Name Type Description Default
uuid str

12-hex-character UUID for this node's storage directory.

 required
filename str

Library filename (e.g. 'n_pendulum.py'). Preserved exactly so that import n_pendulum works.

 required
module_id str or None

Module identifier for the owning module.

 None
See Also

ARCHITECTURE.md §5.10, §7.2

module_id property 

module_id: str | None

Module identifier, or None.

Returns:

Type Description
str or None

preview 

preview() -> str

Return a short preview string for the tree panel.

Returns the filename only; the chip already says lib, so prefixing it again would be redundant.

A PDVModule is itself a subclass of PDVTree, so it supports all the same dict-like operations. It represents a self-contained module package mounted at a tree path.

PDVModule 

PDVModule(module_id: str, name: str, version: str, gui: PDVGui | None = None, dependencies: list[dict[str, str]] | None = None, description: str = '', language: str = 'python')

Bases: PDVTree

Module metadata node. PDVTree subclass so it can hold children naturally and participate in dot-path access and change notifications.

Stored as the value at a tree path (e.g. pdv_tree['n_pendulum']). Contains child entries like scripts folder and gui node as regular dict items.

Parameters:

Name Type Description Default
module_id str

Unique module identifier.

 required
name str

Human-readable module name.

 required
version str

Semantic version string.

 required
gui PDVGui or None

Optional GUI definition node attached to this module.

 None
description str

Longer human-readable description. Persisted into pdv-module.json at export time for workflow B (create empty → author → export).

 ''
language str

Kernel language ("python" or "julia"). Defaults to "python". Also persisted into pdv-module.json at export.

 'python'
See Also

ARCHITECTURE.md §5.9, and the #140 module editing workflow plan §5.

module_id property 

module_id: str

Unique module identifier.

Returns:

Type Description
str

name property writable 

name: str

Human-readable module name.

Returns:

Type Description
str

version property writable 

version: str

Semantic version string.

Returns:

Type Description
str

description property writable 

description: str

Longer human-readable description, or empty string.

Returns:

Type Description
str

language property 

language: str

Kernel language used by this module.

Returns:

Type Description
str

"python" or "julia".

dependencies property 

dependencies: list[dict[str, str]]

Declared module dependencies (read-only).

Returns:

Type Description
list[dict[str, str]]

gui property writable 

gui: PDVGui | None

Optional GUI definition node.

Returns:

Type Description
PDVGui or None

preview 

preview() -> str

Return a short preview string for the tree panel.

Returns:

Type Description
str

Module name and version.