labapi.tree.notebook.Notebook#

class labapi.tree.notebook.Notebook( init: NotebookInit, user: User, notebooks: Notebooks, )[source]#

Bases: AbstractTreeContainer

Represents a LabArchives notebook, acting as the root of a tree structure.

A notebook is a specialized AbstractTreeContainer that holds directories and pages. It provides methods to access notebook-specific information and manage its contents.

__init__( init: NotebookInit, user: User, notebooks: Notebooks, )[source]#

Initialize a notebook.

Parameters:

init – Initial data for the notebook.
user – The authenticated user.
notebooks – The collection of notebooks this notebook belongs to.

Methods

`__init__`(init, user, notebooks)	Initialize a notebook.
`all_items`()	Return `(name, child)` pairs in container order, preserving duplicates.
`all_keys`()	Return child names in container order, preserving duplicates.
`all_values`()	Return child nodes in container order, preserving duplicates.
`as_dir`()	Return this node cast to `AbstractTreeContainer`.
`as_page`()	Return this node cast to `NotebookPage`.
`create`(cls, name, *[, parents, if_exists])	Create a child page or directory in this container.
`dir`(name)	Ensure a directory exists at `name` and return it.
`enumerate_all`(*[, depth, timeout])	Enumerate descendant directory and page paths.
`enumerate_dirs`(*[, depth, timeout])	Enumerate descendant directory paths.
`enumerate_nodes`(*[, depth, timeout])	Enumerate descendant paths paired with their concrete node objects.
`enumerate_pages`(*[, depth, timeout])	Enumerate descendant page paths.
`get`(k[,d])
`is_dir`()	Return `True` because containers are directories.
`is_parent_of`(other)	Return whether this container is a strict ancestor of `other`.
`items`()	Return a mapping-compatible view of `(name, child)` pairs.
`keys`()	Return a mapping-compatible view of child names.
`page`(name)	Ensure a page exists at `name` and return it.
`refresh`()	Refresh this container by clearing its cached children.
`traverse`(path)	Traverse the notebook tree and return the node at `path`.
`values`()	Return a mapping-compatible view of child nodes.

Attributes

`children`	Return a snapshot of this container's direct children.
`id`	Return the notebook identifier.
`is_default`	Return whether this notebook is the user's default notebook.
`name`	Return the tree node name.
`parent`	Return this node's parent container.
`path`	Return the cached absolute path for this node.
`root`	Return the root node of the tree.
`tree_id`	Return the node identifier within the LabArchives tree.
`user`	Return the authenticated user associated with this node.

property id: str#

Return the notebook identifier.

Returns:: The notebook’s ID.

property name: str#

Return the tree node name.

Returns:: The name of the node.

property is_default: bool#

Return whether this notebook is the user’s default notebook.

Returns:: True if the notebook is the default, False otherwise.

all_items() → Sequence[tuple[str, AbstractBaseTreeNode]]#: Return (name, child) pairs in container order, preserving duplicates.

all_keys() → Sequence[str]#: Return child names in container order, preserving duplicates.

all_values() → Sequence[AbstractBaseTreeNode]#: Return child nodes in container order, preserving duplicates.

as_dir() → AbstractTreeContainer#

Return this node cast to AbstractTreeContainer.

This method provides a convenient way to perform directory-specific operations on a node after checking its type, with static type checking support.

Returns:: The node cast to an AbstractTreeContainer.
Raises:: TypeError – If the node is not a directory (i.e., is_dir() returns False).

as_page() → NotebookPage#

Return this node cast to NotebookPage.

This method provides a convenient way to perform page-specific operations on a node after checking its type, with static type checking support.

Returns:: The node cast to a NotebookPage.
Raises:: TypeError – If the node is not a page (i.e., is_dir() returns True).

property children: Sequence[AbstractTreeNode]#

Return a snapshot of this container’s direct children.

Returns:: An immutable point-in-time sequence of AbstractTreeNode objects.

create( cls: Type[T], name: str | NotebookPath, *, parents: bool = False, if_exists: InsertBehavior = InsertBehavior.Raise, ) → T#

Create a child page or directory in this container.

This method supports different behaviors if a node with the same name already exists.

Parameters:

cls – The class of the node to create (e.g., NotebookPage or NotebookDirectory).
name – The name of the new node.
parents – If True, intermediate directories in the path will be created using InsertBehavior.Retain if they don’t exist.
if_exists – The behavior to take if a node with the same name and type already exists. Default is to raise a RuntimeError.

Returns:

The newly created (or existing) node of type cls.

Raises:

RuntimeError – If if_exists is InsertBehavior.Raise and the node already exists.

dir(name: str | NotebookPath) → NotebookDirectory#

Ensure a directory exists at name and return it.

Shorthand for create() with cls=NotebookDirectory, if_exists=InsertBehavior.Retain, and parents=True.

Parameters:: name – The name or path of the directory.
Returns:: The ensured NotebookDirectory.

enumerate_all( *, depth: int = 1, timeout: timedelta = datetime.timedelta(seconds=5), ) → Sequence[str]#

Enumerate descendant directory and page paths.

Returns relative path strings from the current container for all descendant nodes, including both directories and pages. Each path is relative to this container (e.g., “Folder/Page” or “Folder/Subfolder/Page”).

Parameters:

depth – The maximum depth to traverse. Default is 1 (only immediate children).
timeout – The maximum time to spend enumerating children. Defaults to 5 seconds.

Returns:

A sequence of relative path strings for all descendants.

enumerate_dirs( *, depth: int = 1, timeout: timedelta = datetime.timedelta(seconds=5), ) → Sequence[str]#

Enumerate descendant directory paths.

Returns relative path strings from the current container for all descendant directories (excluding pages). Each path is relative to this container.

Parameters:

depth – The maximum depth to traverse. Default is 1 (only immediate children).
timeout – The maximum time to spend enumerating children. Defaults to 5 seconds.

Returns:

A sequence of relative path strings for all descendant directories.

enumerate_nodes( *, depth: int = 1, timeout: timedelta = datetime.timedelta(seconds=5), ) → Sequence[tuple[str, AbstractTreeNode]]#

Enumerate descendant paths paired with their concrete node objects.

Returns relative path strings from the current container for all descendant nodes, including both directories and pages, paired with the exact in-memory node instance each path came from.

Parameters:

depth – The maximum depth to traverse. Default is 1 (only immediate children).
timeout – The maximum time to spend enumerating children. Defaults to 5 seconds.

Returns:

A sequence of (relative_path, node) pairs for all descendants.

enumerate_pages( *, depth: int = 1, timeout: timedelta = datetime.timedelta(seconds=5), ) → Sequence[str]#

Enumerate descendant page paths.

Returns relative path strings from the current container for all descendant pages (excluding directories). Each path is relative to this container.

Parameters:

depth – The maximum depth to traverse. Default is 1 (only immediate children).
timeout – The maximum time to spend enumerating children. Defaults to 5 seconds.

Returns:

A sequence of relative path strings for all descendant pages.

get( k[, d,] ) → D[k] if k in D, else d. d defaults to None.#

is_dir() → Literal[True]#

Return True because containers are directories.

Returns:: Always True.

is_parent_of( other: AbstractBaseTreeNode, ) → bool#

Return whether this container is a strict ancestor of other.

This method returns True when other is a descendant of this container at any depth (direct child or deeper). A node is not considered a parent of itself.

Nodes from different notebook roots are always considered unrelated, even if their relative paths happen to match.

Parameters:: other – The node to test as a potential descendant.
Returns:: True if this container is an ancestor of other, otherwise False.

items() → ItemsView[str, AbstractBaseTreeNode]#: Return a mapping-compatible view of (name, child) pairs.

keys() → KeysView[str]#: Return a mapping-compatible view of child names.

page(name: str | NotebookPath) → NotebookPage#

Ensure a page exists at name and return it.

Shorthand for create() with cls=NotebookPage, if_exists=InsertBehavior.Retain, and parents=True.

Parameters:: name – The name or path of the page.
Returns:: The ensured NotebookPage.

property parent: AbstractTreeContainer#

Return this node’s parent container.

Returns:: The parent tree container.

property path: NotebookPath#: Return the cached absolute path for this node.

refresh() → Self#

Refresh this container by clearing its cached children.

This method clears the internal children cache, forcing the container to re-fetch its children from the LabArchives API on the next access.

property root: AbstractTreeContainer#

Return the root node of the tree.

Returns:: The root tree container.

traverse( path: str | NotebookPath, ) → AbstractBaseTreeNode#

Traverse the notebook tree and return the node at path.

String path segments should be separated by ‘/’. Each segment is treated as a name to look up in the current container. Paths starting with ‘/’ are absolute (relative to the notebook root), while paths without a leading ‘/’ are relative to the current container.

Special path segments: - ‘..’ navigates to the parent container

Note

When multiple children have the same name, this method returns the first match.

Warning

Nodes with names that are literally ‘..’ cannot be accessed via this method, as ‘..’ is reserved for parent navigation.

Parameters:: path – The slash-separated path to the desired node (e.g., “My Folder/My Page” or “/Folder/Subfolder/Page”).
Returns:: The AbstractTreeContainer or AbstractTreeNode found at the specified path.
Raises:: TraversalError – If traversal cannot continue through a segment.

property tree_id: str#

Return the node identifier within the LabArchives tree.

This is often the same as id but can be used to distinguish if needed.

Returns:: The tree ID of the node.

property user: User#

Return the authenticated user associated with this node.

Returns:: The user object.

values() → ValuesView[AbstractBaseTreeNode]#: Return a mapping-compatible view of child nodes.