labapi.tree.mixins.AbstractTreeContainer#

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

Bases: AbstractBaseTreeNode, Mapping[IdOrNameIndex, AbstractBaseTreeNode | Sequence[AbstractBaseTreeNode]]

Abstract base class for a tree node that can contain other tree nodes (e.g., Notebooks, Directories).

This class extends AbstractBaseTreeNode and implements collections.abc.Mapping to allow access to its children by ID or name. It provides methods for managing its children, such as creating new pages or directories.

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

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.

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 node 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.
property children: Sequence[AbstractTreeNode]#

Return a snapshot of this container’s direct children.

Returns:

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

keys() → KeysView[str][source]#

Return a mapping-compatible view of child names.

items() → ItemsView[str, AbstractBaseTreeNode][source]#

Return a mapping-compatible view of (name, child) pairs.

values() → ValuesView[AbstractBaseTreeNode][source]#

Return a mapping-compatible view of child nodes.

all_keys() → Sequence[str][source]#

Return child names in container order, preserving duplicates.

all_items() → Sequence[tuple[str, AbstractBaseTreeNode]][source]#

Return (name, child) pairs in container order, preserving duplicates.

all_values() → Sequence[AbstractBaseTreeNode][source]#

Return child nodes in container order, preserving duplicates.

is_parent_of(
other: AbstractBaseTreeNode,
) → bool[source]#

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.

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

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_nodes(
*,
depth: int = 1,
timeout: timedelta = datetime.timedelta(seconds=5),
) → Sequence[tuple[str, AbstractTreeNode]][source]#

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_dirs(
*,
depth: int = 1,
timeout: timedelta = datetime.timedelta(seconds=5),
) → Sequence[str][source]#

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_pages(
*,
depth: int = 1,
timeout: timedelta = datetime.timedelta(seconds=5),
) → Sequence[str][source]#

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.

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

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.

dir(
name: str | NotebookPath,
) → NotebookDirectory[source]#

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.

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

get(
k[,
d,]
) → D[k] if k in D, else d.  d defaults to None.#
abstract property id: str#

Return the node identifier.

Returns:

The node’s ID.

property name: str#

Return the tree node name.

Returns:

The name of the node.

page(
name: str | NotebookPath,
) → NotebookPage[source]#

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.

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.

is_dir() → Literal[True][source]#

Return True because containers are directories.

Returns:

Always True.

refresh() → Self[source]#

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.