# 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`](https://dev.nominal.io/python/ref/generated/nominal.core.Workbook.md#nominal.core.Workbook.asset_rids "nominal.core.Workbook.asset_rids").

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

### asset_rids: Sequence[str] | None

Mutually exclusive with [`run_rids`](https://dev.nominal.io/python/ref/generated/nominal.core.Workbook.md#nominal.core.Workbook.run_rids "nominal.core.Workbook.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*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *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*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      New description for the cloned workbook. Defaults to the source workbook’s latest description.
    - **title_suffix** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Custom suffix for the server-generated title, e.g. “Run analysis” produces
      “Source title - Run analysis”. Defaults to “copy”. Ignored when [`title`](https://dev.nominal.io/python/ref/generated/nominal.core.Workbook.md#nominal.core.Workbook.title "nominal.core.Workbook.title") is provided.
    - **labels** (*Sequence**[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Labels for the clone. None inherits the source labels; an empty sequence clears them.
    - **properties** (*Mapping**[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Properties for the clone. None inherits the source properties; an empty mapping clears them.
    - **runs** (*Sequence**[*[*Run*](https://dev.nominal.io/python/ref/generated/nominal.core.Run.md#nominal.core.Run "nominal.core.Run") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *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*](https://dev.nominal.io/python/ref/generated/nominal.core.Asset.md#nominal.core.Asset "nominal.core.Asset") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *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*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      Whether to create the clone as a draft. Defaults to False;
      None inherits the source’s draft status.
    - **is_locked** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)"))

      Whether to lock the clone. Defaults to False, including when the source workbook is locked.
    - **workspace** ([*Workspace*](https://dev.nominal.io/python/ref/generated/nominal.core.Workspace.md#nominal.core.Workspace "nominal.core.Workspace") *|* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *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*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")[[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")]

### is_archived()

Return whether or not the workbook is currently archived.

Return type:
:   [*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")

### 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*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")

### is_locked()

Return whether or not the workbook is currently locked.

Return type:
:   [*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)")

### 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*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### 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*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Replacement title.
    - **description** ([*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)") *|* *None*)

      Replacement description. An empty string clears it.
    - **properties** ([*Mapping*](https://docs.python.org/3/library/typing.html#typing.Mapping "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*,* [*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Replacement properties. An empty mapping clears them.
    - **labels** ([*Sequence*](https://docs.python.org/3/library/typing.html#typing.Sequence "(in Python v3.15)")*[*[*str*](https://docs.python.org/3/builtins/stdtypes.html#str "(in Python v3.15)")*]* *|* *None*)

      Replacement labels. An empty sequence clears them.
    - **is_draft** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      True makes the workbook private; False publishes it.
    - **is_locked** ([*bool*](https://docs.python.org/3/builtins/functions.html#bool "(in Python v3.15)") *|* *None*)

      True locks content editing; False unlocks it.

Returns:
:   This instance with refreshed metadata, without an additional fetch.

Return type:
:   [*Self*](https://docs.python.org/3/library/typing.html#typing.Self "(in Python v3.15)")

### update_refnames(refname_map)

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