Copy page

• Copy page
• View source

labapi.tree.notebook.Notebook

class labapi.tree.notebook.Notebook(

init: NotebookInit,

user: User,

notebooks: Notebooks,

)

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.

__init__(

init: NotebookInit,

user: User,

notebooks: Notebooks,

)

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.
backup(destination, *[, ...])	Download this notebook's native LabArchives backup archive.
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.
export(destination, *[, source, overwrite])	Export this notebook to a local directory tree.
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.
search(query, *[, page_size])	Search entries in this notebook.
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.

search(

query: str,

*,

page_size: int = 25,

) → EntrySearch

Search entries in this notebook.

Search itself is read-only. The returned pages contain normal entry objects, so setting entry.content still uses the existing entry update behavior.

Parameters:

• query – LabArchives search query expression.

• page_size – Number of entries to request per result page.

Returns:

A lazy iterable over search result pages.

export(

destination: str | PathLike[str],

*,

source: Literal['auto', 'walk', 'backup'] = 'auto',

overwrite: bool = False,

) → NotebookExport

Export this notebook to a local directory tree.

Reconstructs the notebook as a folder mirror under destination: one directory per folder/page (named <order>_<name>), with each page’s content written as ordered files (NN_text.html for rich text, NN_text.txt for plain text, NN_<filename> for attachments).

Parameters:

• destination – Output directory for the exported tree. Its parent directories are created if needed.

• source – Where to read the notebook from. "walk" reads the live API tree; "backup" downloads and unpacks the native backup archive (requires the notebook owner’s sign-in and the optional py7zr dependency: pip install 'labapi[export]'); "auto" uses the backup archive when available and falls back to the walk.

• overwrite – When destination exists and is not empty, raise unless overwrite is True.

Returns:

A completed NotebookExport. Its path is the export directory.

backup(

destination: str | PathLike[str],

*,

include_attachments: bool = True,

as_json: bool = False,

) → Path

Download this notebook’s native LabArchives backup archive.

LabArchives returns the backup as a 7-Zip (.7z) archive in a proprietary format; labapi saves it verbatim. This format may change at any time, but should remain interpretable and restorable by LabArchives.

Parameters:

• destination – A filesystem path to write the archive to; its parent directories are created if needed.

• include_attachments – When False, request a backup without attachment payloads (the API no_attachments option).

• as_json – When True, request the notebook data in JSON format (the API json option).

Returns:

The Path the archive was written to.

Raises:

ApiError – If LabArchives rejects the request. Error code 4547 means the currently authenticated account is not the notebook owner. Check the owner in the LabArchives web UI, then retry with that owner’s credentials.

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.

Use after checking is_dir() to obtain a container-typed reference for static type checking.

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.

Use after checking is_dir() to obtain a page-typed reference for static type checking.

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.

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

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

Equal to id for all nodes except the Notebook root, whose tree_id is the sentinel “0” while id is the notebook ID.

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.