Creating Pages and Entries#

This page covers the basic write operations you will use most often: creating directories and pages, then adding entries to a page. The examples assume you already have a notebook object from Your First Entry.

Notebook Structure#

LabArchives organizes content hierarchically:

  • Notebooks contain directories and pages.

  • Directories contain other directories and pages.

  • Pages contain entries arranged from top to bottom.

Create Directories and Pages#

Use create() to add new NotebookDirectories or NotebookPages.

from labapi import NotebookDirectory, NotebookPage

my_folder = notebook.create(NotebookDirectory, "Experiments")
experiment_page = my_folder.create(NotebookPage, "Experiment 1")
subfolder = my_folder.create(NotebookDirectory, "2024 Results")

Note

Tree mutation methods update local cached objects immediately. The created node is ready to use right away.

Handle Existing Nodes#

By default, create() raises NodeExistsError if a node with the same name and type already exists. Use if_exists to choose a different behavior:

from labapi import InsertBehavior, NotebookPage

page = notebook.create(NotebookPage, "Existing Page", if_exists=InsertBehavior.Raise)
page = notebook.create(NotebookPage, "Existing Page", if_exists=InsertBehavior.Ignore)
page = notebook.create(NotebookPage, "Existing Page", if_exists=InsertBehavior.Retain)
page = notebook.create(NotebookPage, "Existing Page", if_exists=InsertBehavior.Replace)

Create Entries#

Use create() to add content blocks to a page:

from labapi import Attachment, AttachmentEntry, HeaderEntry, PlainTextEntry, TextEntry

page.entries.create(HeaderEntry, "Experiment Results")
page.entries.create(TextEntry, "<p>This is <b>bold</b> text.</p>")
page.entries.create(PlainTextEntry, "Simple unformatted text")

with open("results.csv", "rb") as f:
    attachment = Attachment(f, "text/csv", "results.csv", "Experiment data")
    page.entries.create(AttachmentEntry, attachment)

Entry Types#

Entry Class

Data Type

Description

HeaderEntry

str

Section headers and titles.

TextEntry

str

Rich text with HTML formatting.

PlainTextEntry

str

Unformatted plain text.

AttachmentEntry

Attachment

File uploads such as images, documents, and data files.

Inspect What You Created#

Access entries through the page’s entries collection:

for entry in page.entries:
    print(f"Type: {entry.content_type}")
    print(f"Content: {entry.content}")

first_entry = page.entries[0]