Clearing Cache#

The LabArchives API client caches child-node lists and page-entry collections so repeated reads do not issue API calls. Call refresh() before reading changes made outside the current session.

Refreshing Tree and Entry Caches#

Tree nodes (notebooks, directories, and pages) provide a refresh() method that clears cached children for containers or cached entries for pages, so the next property access fetches them again.

Refreshing a Page#

When you refresh a page, the cached entries are cleared:

# Get a page
page = notebook.traverse("My Folder/My Page")

# Work with entries
entries = page.entries  # Fetches from API and caches

# Some time later, you want to see if new entries were added
page.refresh()

# Next access will fetch fresh data from the API
entries = page.entries  # Re-fetches from API

Refreshing a Directory or Notebook#

For directories and notebooks, refresh() clears cached children:

# Get a directory
directory = notebook.traverse("My Folder")

# Access children
children = directory.children  # Fetches and caches

# Refresh to see if new pages/subdirectories were added
directory.refresh()

# Next access gets fresh data
children = directory.children  # Re-fetches from API

When Local Mutations Do Not Need Refresh#

Create, rename, move, and delete operations update the in-memory tree after the API call succeeds, so refresh() is not needed to see that operation’s local result.

This includes:

  • create() appending a new page or directory to the parent container

  • node.name = "..." updating the current object’s name in memory after the API call

  • move_to() updating the node’s parent and both containers’ child lists

  • delete() renaming and moving the current node into API Deleted Items

from labapi import NotebookDirectory, NotebookPage

archive = notebook.create(NotebookDirectory, "Archive")
page = notebook.create(NotebookPage, "Fresh Results")

print("Fresh Results" in list(notebook))

page.move_to(archive)
print(page.parent is archive)  # True without refresh()

When to Refresh Data#

Use refresh() when you need to pick up changes made by another user, the LabArchives web UI, or another API session.

Example: Polling for New Entries#

import time

page = notebook.traverse("Experiment Results")

while True:
    # Clear cache and check for new entries
    page.refresh()
    entries = page.entries

    print(f"Current entry count: {len(entries)}")

    if len(entries) >= 10:
        print("Required entries found!")
        break

    time.sleep(30)  # Wait 30 seconds before checking again

Limitations#

Warning

refresh() does not update existing child-object references:

Stale object references: Existing references to child pages, directories, or entries are not replaced by refresh() and can keep stale cached data.

Example: stale entry reference

page = notebook.traverse("My Page")
entry = page.entries[0]  # Get reference to first entry

# Refresh the page
page.refresh()

# This entry object still has old cached data!
# It wasn't invalidated by the refresh
print(entry.content)  # May show stale data

After refresh(), re-fetch child objects before reading them:

page = notebook.traverse("My Page")

# Refresh and re-fetch entries
page.refresh()
entry = page.entries[0]  # Get a fresh reference

print(entry.content)  # Shows current data

What Gets Cached#

The following data is cached and will be cleared by refresh():

For notebooks and directories:

  • List of child pages and subdirectories

  • Child count

For pages:

  • List of entries on the page

  • Entry content and metadata

Not cleared by refresh():

  • User authentication state

  • The User notebooks collection, which is built once at login and is not affected by tree or page refresh()