The App Object (pdv)

pdv is a session-level app object injected into the kernel namespace alongside pdv_tree. It exposes operations that act on the running PDV application rather than on project data.

pdv.working_dir              # Path to the session working directory
pdv.save()                   # Save the project (prompts if no save path)
pdv.new_note('notes.intro')  # Create a markdown note at a tree path
pdv.help()                   # Print a quick reference

Tab-completing pdv. in a code cell lists every available operation.

pdv

pdv — Physics Data Viewer kernel support package.

This package implements the kernel side of the PDV comm protocol. It is installed into the user's Python environment and loaded when a PDV-managed Jupyter kernel starts.

Public API

PDVTree : class The live project data tree. Injected into the kernel namespace as pdv_tree. This is the sole authority on all project data. PDVScript : class Lightweight wrapper for a script file stored as a tree node. PDVError : exception Base exception for all pdv errors. bootstrap : function Called by IPython startup machinery. Registers the PDV comm target, injects pdv_tree into the protected namespace, and sends the pdv.ready message. See ARCHITECTURE.md §5.3.

Do not import comms, handlers, or namespace internals directly — they are implementation details and their interfaces may change.

save

save() -> None

Trigger a project save. Equivalent to File -> Save in the UI.

save_project

save_project(path: str | None = None) -> None

Save the current project to a directory.

Parameters:

Name	Type	Description	Default
path	str or None	Absolute or ~-prefixed path to the project directory. If None, saves to the current project location (falls back to :func:save if no project is open).	None

save_project_as

save_project_as(path: str) -> None

Save the project to a new directory (Save As).

Parameters:

Name	Type	Description	Default
path	str	Absolute or ~-prefixed path to the new project directory.	required

open_project

open_project(path: str) -> None

Open a project from a directory.

Parameters:

Name	Type	Description	Default
path	str	Absolute or ~-prefixed path to the project directory.	required

add_file

add_file(source_path: str) -> PDVFile

Import an arbitrary file into the tree as a :class:PDVFile.

Eagerly copies the source file into the session working directory under a fresh UUID-based storage path. The returned node is not yet attached to the tree — assign it at the desired tree path::

mesh = pdv.add_file("~/Downloads/mesh.h5")
pdv_tree["simulation.mesh"] = mesh

Parameters:

Name	Type	Description	Default
source_path	str	Filesystem path to the source file. ~ is expanded.	required

Returns:

Type	Description
PDVFile	A new file-backed node wrapping the imported file.

Raises:

Type	Description
FileNotFoundError	If source_path does not exist.
ValueError	If source_path is not a regular file.
PDVError	If no kernel working directory is available.

new_note

new_note(path: str, title: str | None = None) -> None

Create a markdown note in the tree.

Parameters:

Name	Type	Description	Default
path	str	Dot-separated tree path for the new note (e.g. 'notes.intro').	required
title	str or None	Optional title. If provided, the file is initialized with a # Title heading. Otherwise the file starts empty.	None

help

help(topic: str | None = None) -> None

Print PDV help.

Parameters:

Name	Type	Description	Default
topic	str	A specific topic to get help on. If None, prints a general overview.	None

log

log(*args, **kwargs) -> None

Print a debug message directly to stderr, bypassing ipykernel's stdout capture.

Output appears in the Electron terminal prefixed with [kernel:<id>]. Accepts the same arguments as the built-in print().

Module authoring

Two additional attributes are attached to pdv at kernel startup:

• pdv.handle — decorator for registering double-click handlers on custom types. See the Module API.
• pdv.register_serializer — register save/load callbacks for types PDV does not know how to persist on its own. See the Module API.

Both are only relevant when authoring a module library, which is why they are documented there.

If you control the class you want PDV to recognize — i.e. you're shipping it from a PyPI package rather than wrapping someone else's type — prefer the dunder protocol instead. It lets your class self-register through methods like __pdv_format__ and __pdv_handle__ without your package depending on pdv at all, and without the user having to import your module before opening their project.