Workbook#

class nominal.core.Workbook(rid, title, description, labels, properties, workbook_type, run_rids, asset_rids)#

Bases: HasRid, RefreshableConjureMixin[Notebook | NotebookMetadataWithRid]

An interactive view for visualizing data from assets and runs.

rid: str#
title: str#
description: str#
labels: Sequence[str]#
properties: Mapping[str, str]#
workbook_type: WorkbookType#
run_rids: Sequence[str] | None#

Mutually exclusive with asset_rids.

May be empty when a workbook is a fresh comparison workbook.

asset_rids: Sequence[str] | None#

Mutually exclusive with run_rids.

May be empty when a workbook is a fresh comparison workbook.

property nominal_url: str#

Returns a link to the page for this Workbook in the Nominal app

archive()#

Archive this workbook. Archived workbooks are not deleted, but are hidden from the UI.

Note

Archiving is an idemponent operation– calling archive() on a archived workbook will result in the workbook staying archived.

clone(title: str | None = None, description: str | None = None, *, title_suffix: str | None = None, labels: Sequence[str] | None = None, properties: Mapping[str, str] | None = None, runs: Sequence[Run | str] | None = None, assets: None = None, is_draft: bool | None = False, is_locked: bool = False, workspace: Workspace | str | None = None) → Self#
clone(title: str | None = None, description: str | None = None, *, title_suffix: str | None = None, labels: Sequence[str] | None = None, properties: Mapping[str, str] | None = None, runs: None = None, assets: Sequence[Asset | str] | None = None, is_draft: bool | None = False, is_locked: bool = False, workspace: Workspace | str | None = None) → Self

Create a new workbook copy from this workbook and return a reference to the cloned version.

Copies the latest content and metadata from the source workbook, retaining its workbook type. The cloned workbook is unlocked and is not a draft by default.

Parameters:

  • title (str | None)

    New title for the cloned workbook. Defaults to the source workbook’s latest title followed by “ - copy”. Copying an existing copy increments its suffix, e.g. “ - copy (2)”.

  • description (str | None)

    New description for the cloned workbook. Defaults to the source workbook’s latest description.

  • title_suffix (str | None)

    Custom suffix for the server-generated title, e.g. “Run analysis” produces “Source title - Run analysis”. Defaults to “copy”. Ignored when title is provided.

  • labels (Sequence[str] | None)

    Labels for the clone. None inherits the source labels; an empty sequence clears them.

  • properties (Mapping[str, str] | None)

    Properties for the clone. None inherits the source properties; an empty mapping clears them.

  • runs (Sequence[Run | str] | None)

    Runs or run RIDs to use as the clone’s data scope. Mutually exclusive with assets. Defaults to the source data scope. An empty sequence clears the run scope.

  • assets (Sequence[Asset | str] | None)

    Assets or asset RIDs to use as the clone’s data scope. Mutually exclusive with runs. Defaults to the source data scope. An empty sequence clears the asset scope.

  • is_draft (bool | None)

    Whether to create the clone as a draft. Defaults to False; None inherits the source’s draft status.

  • is_locked (bool)

    Whether to lock the clone. Defaults to False, including when the source workbook is locked.

  • workspace (Workspace | str | None)

    Workspace or workspace RID for the clone. Defaults to the client’s default workspace.

Return type:

Self

Note

Clones inherit labels and properties by default. Pass labels=[] and properties={} to create a copy without either.

Returns:

Reference to the cloned workbook

Return type:

Self

delete()#

Delete the workbook permanently.

get_refnames()#

Get the list of refnames used within the workbook.

Return type:

Sequence[str]

is_archived()#

Return whether or not the workbook is currently archived.

Return type:

bool

is_draft()#

Return whether or not the workbook is currently a draft. Note that a workbook in draft state isn’t visible to other users and shows up as Private in the UI.

Return type:

bool

is_locked()#

Return whether or not the workbook is currently locked.

Return type:

bool

lock()#

Locks the workbook, preventing changes from being made to it.

Note

Locking is an idemponent operation– calling lock() on a locked workbook will result in the workbook staying locked.

publish()#

Publish this workbook and refresh its metadata from the update response.

refresh()#
Return type:

Self

unarchive()#

Unarchive this workbook, allowing it to be viewed in the UI.

Note

Unarchiving is an idemponent operation– calling unarchive() on a unarchived workbook will result in the workbook staying unarchived.

unlock()#

Unlocks the workbook, allowing changes to be made to it.

Note

Unlocking is an idemponent operation– calling unlock() on an unlocked workbook will result in the workbook staying unlocked.

unpublish()#

Return this workbook to draft state and refresh its metadata from the update response.

update(*, title=None, description=None, properties=None, labels=None, is_draft=None, is_locked=None)#

Replace workbook metadata and refresh this instance from the response.

None leaves a field unchanged. Labels and properties replace existing collections; merge with their current values before calling this method to append entries.

Parameters:

  • title (str | None)

    Replacement title.

  • description (str | None)

    Replacement description. An empty string clears it.

  • properties (Mapping[str, str] | None)

    Replacement properties. An empty mapping clears them.

  • labels (Sequence[str] | None)

    Replacement labels. An empty sequence clears them.

  • is_draft (bool | None)

    True makes the workbook private; False publishes it.

  • is_locked (bool | None)

    True locks content editing; False unlocks it.

Returns:

This instance with refreshed metadata, without an additional fetch.

Return type:

Self

update_refnames(refname_map)#

Updates refnames using a provided map of original refnames to the new refnames to replace them.