Workbook

class nominal.core.Workbook(rid: str, title: str, description: str, labels: Sequence[str], properties: Mapping[str, str], workbook_type: WorkbookType, run_rids: Sequence[str] | None, asset_rids: Sequence[str] | None)

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() → None

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 – 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 – New description for the cloned workbook. Defaults to the source workbook’s latest description.

• title_suffix – 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 – Labels for the clone. None inherits the source labels; an empty sequence clears them.

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

• runs – 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 – 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 – Whether to create the clone as a draft. Defaults to False; None inherits the source’s draft status.

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

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

Note

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

Returns:

Reference to the cloned workbook

delete() → None

Delete the workbook permanently.

get_refnames() → Sequence[str]

Get the list of refnames used within the workbook.

is_archived() → bool

Return whether or not the workbook is currently archived.

is_draft() → bool

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.

is_locked() → bool

Return whether or not the workbook is currently locked.

lock() → None

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() → None

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

refresh() → Self

unarchive() → None

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() → None

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() → None

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

update(*, title: str | None = None, description: str | None = None, properties: Mapping[str, str] | None = None, labels: Sequence[str] | None = None, is_draft: bool | None = None, is_locked: bool | None = None) → Self

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 – Replacement title.

• description – Replacement description. An empty string clears it.

• properties – Replacement properties. An empty mapping clears them.

• labels – Replacement labels. An empty sequence clears them.

• is_draft – True makes the workbook private; False publishes it.

• is_locked – True locks content editing; False unlocks it.

Returns:

This instance with refreshed metadata, without an additional fetch.

update_refnames(refname_map: Mapping[str, str]) → None

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