labapi.tree.directory.NotebookDirectory#

class labapi.tree.directory.NotebookDirectory(
tree_id: str,
name: str,
root: AbstractTreeContainer,
parent: AbstractTreeContainer,
user: User,
)[source]#

Bases: AbstractTreeContainer, AbstractTreeNode

Represents a directory (folder) within a LabArchives notebook.

A NotebookDirectory can contain other directories and pages, forming a hierarchical structure. It inherits functionalities for both being a container and being a movable/modifiable node within the tree.

__init__(
tree_id: str,
name: str,
root: AbstractTreeContainer,
parent: AbstractTreeContainer,
user: User,
)#

Initialize a tree container node.

Parameters:

  • tree_id – The unique identifier for this container within the LabArchives tree.

  • name – The display name of the container.

  • root – The root node of the tree (e.g., the Notebook).

  • parent – The parent node of this container in the tree.

  • user – The authenticated user associated with this container.

Methods

__init__(tree_id, name, root, parent, user)

Initialize a tree container node.

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.

copy_to(destination)

Copy this directory and its contents into destination.

create(cls, name, *[, parents, if_exists])

Create a child page or directory in this container.

delete()

Move this node into the special API Deleted Items directory.

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.

move_to(destination)

Move this node into destination.

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 directory identifier.

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.
copy_to(
destination: AbstractTreeContainer,
) → NotebookDirectory[source]#

Copy this directory and its contents into destination.

This operation recursively copies all child directories and pages.

Parameters:

destination – The target container to copy the directory to.

Returns:

A new instance of the copied directory in the destination.

property id: str#

Return the directory identifier.

Returns:

The directory’s ID.

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. Defaults to InsertBehavior.Raise.

Returns:

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

Raises:

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

delete() → Self#

Move this node into the special API Deleted Items directory.

If the “API Deleted Items” directory does not exist, it will be created. The node’s name will be updated to reflect its deletion time.

Returns:

The instance of the deleted node.

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.

move_to(
destination: AbstractTreeContainer,
) → Self#

Move this node into destination.

This operation updates the node’s parent in LabArchives via an API call and updates the local tree structure.

Parameters:

destination – The target container to move the node to.

Returns:

The instance of the moved node.

property name: str#

Return the tree node name.

Returns:

The name of the node.

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 AbstractBaseTreeNode 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.