labapi.tree.page.NotebookPage#

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

Bases: AbstractTreeNode

Represents a single page within a LabArchives notebook.

A NotebookPage is a leaf node in the tree structure and contains a collection of Entry objects. It provides functionalities to access and manage these entries.

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

Initialize a notebook page.

Parameters:

tree_id – The unique ID of the page.
name – The name of the page.
root – The root node of the tree (the Notebook).
parent – The parent node of this page (a Directory or Notebook).
user – The authenticated user.

Methods

`__init__`(tree_id, name, root, parent, user)	Initialize a notebook page.
`as_dir`()	Return this node cast to `AbstractTreeContainer`.
`as_page`()	Return this node cast to `NotebookPage`.
`copy_to`(destination)	Copy this page and its entries into `destination`.
`delete`()	Move this node into the special `API Deleted Items` directory.
`is_dir`()	Return `False` because pages are leaf nodes.
`move_to`(destination)	Move this node into `destination`.
`refresh`()	Refresh this page by clearing its cached entries.
`traverse`(path)	Traverse the notebook tree and return the node at `path`.

Attributes

`entries`	Return this page's entries, loading them on first access.
`id`	Return the page 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 id: str#

Return the page identifier.

Returns:: The page’s ID.

property entries: Entries#

Return this page’s entries, loading them on first access.

This property lazily loads the entries from the LabArchives API if they have not been loaded yet.

Note

Slicing on the returned collection provides snapshots. Iterators over the collection are also snapshots and are therefore insulated from later collection mutations.

Returns:: An Entries object managing the page’s entries.

copy_to( destination: AbstractTreeContainer, ) → NotebookPage[source]#

Copy this page and its entries into destination.

Warning

This method has known limitations:

LabArchives may rename attachment files during copy operations
Only certain entry types are fully supported (text, plain text, headers, attachments)
Some entry types may fail to copy and will cause errors

Parameters:: destination – The target container to copy the page to.
Returns:: A new instance of the copied page in the destination.

Copy behavior for attachments is explicit:

attachment payloads are copied by reading and re-uploading the attachment content,
attachment resources opened during copy are always released,
any per-entry copy failure is reported via warning and that entry is skipped.

Note

This method is best-effort and may produce partial copies if one or more entries fail while others succeed.

Raises:: RuntimeWarning – Emitted when an individual entry fails to copy.

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

Return False because pages are leaf nodes.

Returns:: Always False.

refresh() → Self[source]#

Refresh this page by clearing its cached entries.

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

Note

Currently only clears the entries cache. Future implementation should properly invalidate all entry objects before clearing.

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

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.

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.

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.