Copy page

• Copy page
• View source

Navigating the Tree

Once you have a Notebook object, you can move through its directories and pages in several ways. The examples below assume you already have a notebook object from Your First Entry.

Warning

Duplicate-name and first-match behavior are documented in Accessing Items with Index. Review that page before relying on name-based lookup in automation code.

Traversing the Tree with Paths

The most common way to navigate is with traverse(), which accepts a slash-separated path string.

page = notebook.traverse("Experiments/Project A/Results")

experiments = notebook.traverse("Experiments")
project_a = experiments.traverse("Project A")

Fluent Navigation with dir() and page()

For a more concise style, use dir() and page().

These methods return the existing node if it is present, or create it if it is missing.

page = notebook.dir("Experiments").dir("Project A").page("Results")
page = notebook.dir("Experiments/Project A").page("Results")

See create() for more control over duplicate handling and parent creation.

Accessing Children by Name

Use dictionary-style indexing to get the first child with a matching name:

experiments = notebook["Experiments"]
project_a = experiments["Project A"]

Note

For deterministic lookup in integration code, prefer ID-based access with Id.

Accessing Children by ID or Name

For more explicit lookups, use Index.

Access by ID

from labapi import Index

page = notebook[Index.Id:"123.45"]

Access by Name

from labapi import Index

results_pages = notebook[Index.Name:"Results"]

Enumerating Children

labapi provides enumeration helpers on Notebook and NotebookDirectory.

List All Children

all_items = notebook.enumerate_all()
all_items = notebook.enumerate_all(depth=3)

experiments = notebook["Experiments"]
experiment_items = experiments.enumerate_all(depth=2)

Note

The depth parameter controls how many levels deep labapi walks the tree.

Given this tree structure:

Notebook/
|-- Experiments/
|   |-- 2024/
|   |   `-- Results
|   `-- Archive
`-- Notes

• depth=1 returns ["Experiments", "Notes"].

• depth=2 returns ["Experiments", "Experiments/2024", "Experiments/Archive", "Notes"].

• depth=3 returns ["Experiments", "Experiments/2024", "Experiments/2024/Results", "Experiments/Archive", "Notes"].

List Only Directories

directories = notebook.enumerate_dirs()
directories = notebook.enumerate_dirs(depth=2)

experiments = notebook["Experiments"]
subdirs = experiments.enumerate_dirs()

List Only Pages

pages = notebook.enumerate_pages()
pages = notebook.enumerate_pages(depth=2)

experiments = notebook["Experiments"]
experiment_pages = experiments.enumerate_pages(depth=2)

Accessing Parent and Root

Every node except the root has a parent. Any node can also reach the notebook root through root.

page = notebook.traverse("Experiments/Project A/Results")
project_a = page.parent
notebook_root = page.root

Type-Safe Directory Access

Use as_dir() when you need to tell a type checker that a node is a directory:

from labapi import NotebookPage

node = notebook.traverse("Experiments/Project A")
if node.is_dir():
    directory = node.as_dir()
    directory.create(NotebookPage, "New Page")

If you call as_dir() on a page, it raises TypeError.

Related Pages

• Your First Entry for getting the initial notebook object.

• Working with Paths for deeper path-resolution rules.

• Accessing Items with Index for duplicate-name and explicit lookup behavior.