Accessing Items with Index#

Use Index when you want explicit, deterministic lookup behavior for notebooks, directories, and pages.

Warning

Name-based lookup is ambiguous when duplicate names exist. coll["name"] returns the first match and can silently select the wrong item. For deterministic access in integration code, use coll[Index.Id: "..."].

Supported Collection Types#

Index-based lookup is supported for:

Warning

Page Entries do not support Index. Access entries by integer index or iteration instead.

Note

Iterating over user.notebooks or a tree container yields names. Use values() for objects and items() for (name, object) pairs.

Basic Access by Name#

By default, a string key looks up the first item with that name:

notebook = user.notebooks["My Research Notebook"]
experiments = notebook["Experiments"]

If you need duplicate-preserving results, use all_keys(), all_items(), and all_values() on the collection instead of plain mapping helpers.

Explicit Indexing with Index#

Use Index when you want to say whether you are looking up by ID or by name.

Access by ID#

from labapi import Index

notebook = user.notebooks[Index.Id:"12345"]
page = notebook[Index.Id:"67890"]

Access by Name#

from labapi import Index

shared_notebooks = user.notebooks[Index.Name:"Shared Data"]
protocols = experiments[Index.Name:"Protocol"]

Summary of Indexing Methods#

Syntax

Method

Returns

coll["name"]

Implicit name lookup

First item with matching name

coll[Index.Id: "id"]

Explicit ID lookup

The unique item with matching ID

coll[Index.Name: "n"]

Explicit name list lookup

A list of all items with matching name