Notebooks

class datarobot.models.notebooks.enums.NotebookType: Types of notebooks.

class datarobot.models.notebooks.enums.RunType: Types of notebook job runs.

class datarobot.models.notebooks.enums.ManualRunType: A subset of RunType To be used in API schemas.

class datarobot.models.notebooks.enums.SessionType: Types of notebook sessions. Triggered sessions include notebook job runs whether manually triggered or scheduled.

class datarobot.models.notebooks.enums.ScheduleStatus: Possible statuses for notebook schedules.

class datarobot.models.notebooks.enums.ScheduledRunStatus: Possible statuses for scheduled notebook runs.

class datarobot.models.notebooks.enums.NotebookPermissions: Permissions for notebooks.

class datarobot.models.notebooks.enums.NotebookStatus: Possible statuses for notebook sessions.

class datarobot.models.notebooks.enums.KernelExecutionStatus: Possible statuses for kernel execution.

class datarobot.models.notebooks.enums.CellType: Types of cells in a notebook.

class datarobot.models.notebooks.enums.RuntimeLanguage: Languages as used in notebook jupyter kernels.

class datarobot.models.notebooks.enums.ImageLanguage: Languages as used and supported in notebook images.

class datarobot.models.notebooks.enums.KernelSpec: Kernel specifications for Jupyter notebook kernels.

class datarobot.models.notebooks.enums.KernelState: Possible states for notebook kernels.

exception datarobot.models.notebooks.exceptions.KernelNotAssignedError: Raised when a Codespace notebook does not have a kernel assigned.

class datarobot.models.notebooks.notebook.ManualRunPayload

class datarobot.models.notebooks.notebook.Notebook

Metadata for a DataRobot Notebook accessible to the user.

Variables:

id (str) – The ID of the Notebook.
name (str) – The name of the Notebook.
type (NotebookType) – The type of the Notebook. Can be “plain” or “codespace”.
permissions (List[NotebookPermissions]) – The permissions the user has for the Notebook.
tags (List[str]) – Any tags that have been added to the Notebook. Default is an empty list.
created (NotebookActivity) – Information on when the Notebook was created and who created it.
updated (NotebookActivity) – Information on when the Notebook was updated and who updated it.
last_viewed (NotebookActivity) – Information on when the Notebook was last viewed and who viewed it.
settings (NotebookSettings) – Information on global settings applied to the Notebook.
org_id (Optional[str]) – The organization ID associated with the Notebook.
tenant_id (Optional[str]) – The tenant ID associated with the Notebook.
description (Optional[str]) – The description of the Notebook. Optional.
session (Optional[NotebookSession]) – Metadata on the current status of the Notebook and its kernel. Optional.
use_case_id (Optional[str]) – The ID of the Use Case the Notebook is associated with. Optional.
use_case_name (Optional[str]) – The name of the Use Case the Notebook is associated with. Optional.
has_schedule (bool) – Whether or not the notebook has a schedule.
has_enabled_schedule (bool) – Whether or not the notebook has a currently enabled schedule.

get_uri()

Returns:: url – Permanent static hyperlink to this Notebook in its Use Case or standalone.
Return type:: str

classmethod get(notebook_id)

Retrieve a single notebook.

Parameters:: notebook_id (str) – The ID of the notebook you want to retrieve.
Returns:: notebook – The requested notebook.
Return type:: Notebook

Examples

from datarobot.models.notebooks import Notebook

notebook = Notebook.get(notebook_id='6556b00dcc4ea0bb7ea48121')

create_revision(name=None, notebook_path=None, is_auto=False)

Create a new revision for the notebook.

Parameters:

name (Optional[str]) – The name of the revision. Optional.
notebook_path (Optional[str]) – The path of the notebook to execute within the codespace. Required if notebook is in a codespace.
is_auto (bool) – Indicates whether the revision was auto-saved versus a user interaction. Default is False.

Returns:

notebook_revision – Information about the created notebook revision.

Return type:

NotebookRevision

download_revision(revision_id, file_path=None, filelike=None)

Downloads the notebook as a JSON (.ipynb) file for the specified revision.

Parameters:

file_path (string, optional) – The destination to write the file to.
filelike (file, optional) – A file-like object to write to. The object must be able to write bytes. The user is responsible for closing the object.

Return type:

None

Examples

from datarobot.models.notebooks import Notebook

notebook = Notebook.get(notebook_id='6556b00dcc4ea0bb7ea48121')
manual_run = notebook.run_as_job()
revision_id = manual_run.wait_for_completion()
notebook.download_revision(revision_id=revision_id, file_path="./results.ipynb")

delete()

Delete a single notebook :rtype: None

Examples

from datarobot.models.notebooks import Notebook

notebook = Notebook.get(notebook_id='6556b00dcc4ea0bb7ea48121')
notebook.delete()

classmethod list(created_before=None, created_after=None, order_by=None, tags=None, owners=None, query=None, use_cases=None)

List all Notebooks available to the user.

Parameters:

created_before (Optional[str]) – List Notebooks created before a certain date. Optional.
created_after (Optional[str]) – List Notebooks created after a certain date. Optional.
order_by (Optional[str]) – Property to sort returned Notebooks. Optional. Supported properties are “name”, “created”, “updated”, “tags”, and “lastViewed”. Prefix the attribute name with a dash to sort in descending order, e.g. order_by=’-created’. By default, the order_by parameter is None.
tags (Optional[List[str]]) – A list of tags that returned Notebooks should be associated with. Optional.
owners (Optional[List[str]]) – A list of user IDs used to filter returned Notebooks. The respective users share ownership of the Notebooks. Optional.
query (Optional[str]) – A specific regex query to use when filtering Notebooks. Optional.
use_cases (Optional[UseCase or List[UseCase] or str or List[str]]) – Filters returned Notebooks by a specific Use Case or Cases. Accepts either the entity or the ID. Optional. If set to [None], the method filters the notebook’s datasets by those not linked to a UseCase.

Returns:

notebooks – A list of Notebooks available to the user.

Return type:

List[Notebook]

Examples

from datarobot.models.notebooks import Notebook

notebooks = Notebook.list()

is_running()

Check if the notebook session is currently running.

Return type:: bool

get_session_status()

Get the status of the notebook session.

Return type:: NotebookStatus

start_session(is_triggered_run=False, parameters=None, open_file_paths=None, clone_repository=None)

Start a new session for the notebook.

Parameters:

is_triggered_run (bool) – Whether the session being started is considered an “interactive” or “triggered” session. Default is False.
parameters (Optional[List[StartSessionParameters]]) – A list of dictionaries in the format {“name”: “FOO”, “value”: “my_value”} representing environment variables propagated to the notebook session.
open_file_paths (Optional[List[str]]) – A list of file paths to open upon instantiation of the notebook session.
clone_repository (Optional[CloneRepositorySchema]) – Information used to clone a remote repository as part of the environment setup flow.

Returns:

notebook_session – The created notebook session.

Return type:

NotebookSession

Examples

from datarobot.models.notebooks import Notebook

notebook = Notebook.get(notebook_id='6556b00dcc4ea0bb7ea48121')
session = notebook.start_session()

stop_session()

Stop the current session for the notebook.

Returns:: notebook_session – The stopped notebook session.
Return type:: NotebookSession

Examples

from datarobot.models.notebooks import Notebook

notebook = Notebook.get(notebook_id='6556b00dcc4ea0bb7ea48121')
session = notebook.stop_session()

execute(notebook_path=None, cell_ids=None)

Execute the notebook. Assumes session is already started.

Parameters:

notebook_path (Optional[str]) – The path of the notebook to execute within the Codespace. Required if the notebook is in a Codespace.
cell_ids (Optional[List[str]]) – The list of cell IDs to execute for a notebook. Not supported if the notebook is in a Codespace. Optional. If not provided, the whole notebook will be executed.

Return type:

None

get_execution_status()

Get the execution status information of the notebook.

Returns:: execution_status – The notebook execution status information.
Return type:: NotebookExecutionStatus

is_finished_executing(notebook_path=None)

Check if the notebook is finished executing.

Parameters:

notebook_path (Optional[str]) – The path of the notebook the Codespace. Required only if the notebook is in a Codespace. Will raise an error if working with a standalone notebook.

Returns:

is_finished_executing – Whether or not the notebook has finished executing.

Return type:

bool

Raises:

InvalidUsageError – If attempting to check if a standalone notebook has finished executing and incorrectly passing a notebook path. If attempting to check if a codespace notebook has finished executing without passing a notebook path.
KernelNotAssignedError – If attempting to check if a codespace notebook has finished executing but the notebook does not have a kernel assigned.

run_as_job(title=None, notebook_path=None, parameters=None, manual_run_type=ManualRunType.MANUAL)

Create a manual scheduled job that runs the notebook.

Notes

The notebook must be part of a Use Case. If the notebook is in a Codespace then notebook_path is required.

Parameters:

title (Optional[str]) – The title of the background job. Optional.
notebook_path (Optional[str]) – The path of the notebook to execute within the Codespace. Required if notebook is in a Codespace.
parameters (Optional[List[StartSessionParameters]]) – A list of dictionaries in the format {“name”: “FOO”, “value”: “my_value”} representing environment variables predefined in the notebook session. Optional.
manual_run_type (Optional[ManualRunType]) – The type of manual run being triggered. Defaults to “manual” as opposed to “pipeline”.

Returns:

notebook_scheduled_job – The created notebook schedule job.

Return type:

NotebookScheduledJob

Raises:

InvalidUsageError – If attempting to create a manual scheduled run for a Codespace without a notebook path.

Examples

from datarobot.models.notebooks import Notebook

notebook = Notebook.get(notebook_id='6556b00dcc4ea0bb7ea48121')
manual_run = notebook.run_as_job()

# Alternatively, with title and parameters:
# manual_run = notebook.run_as_job(title="My Run", parameters=[{"name": "FOO", "value": "bar"}])

revision_id = manual_run.wait_for_completion()

list_schedules(enabled_only=False)

List all NotebookScheduledJobs associated with the notebook.

Parameters:: enabled_only (bool) – Whether or not to return only enabled schedules.
Returns:: notebook_schedules – A list of schedules for the notebook.
Return type:: List[NotebookScheduledJob]
Raises:: InvalidUsageError – If attempting to list schedules for a notebook not associated with a Use Case.

Examples

from datarobot.models.notebooks import Notebook

notebook = Notebook.get(notebook_id='6556b00dcc4ea0bb7ea48121')
enabled_schedules = notebook.list_schedules(enabled_only=True)

class datarobot.models.notebooks.execution_environment.ExecutionEnvironmentAssignPayload: Payload for assigning an execution environment to a notebook.

class datarobot.models.notebooks.execution_environment.Image

Execution environment image information.

Variables:

id (str) – The ID of the image.
name (str) – The name of the image.
default (bool) – Whether the image is the default image.
description (str) – The description of the image.
environment_id (str) – The ID of the environment.
gpu_optimized (bool) – Whether the image is GPU optimized.
language (ImageLanguage) – The runtime language of the image. For example “Python” or “R”
language_version (str) – The version of the language. For example “3.11” or “4.3”
libraries (list[str]) – A list of pre-installed libraries on the image.

class datarobot.models.notebooks.execution_environment.Machine

Execution environment machine information.

Variables:

id (str) – The ID of the machine.
name (str) – The name of the machine. Values include “XS”, “S”, “M”, “L” etc.
default (bool) – Whether the machine is the default machine.
cpu (str) – The CPU of the machine. For example a value like “2000m”.
cpu_cores (int) – The number of CPU cores.
ephemeral_storage (str) – The ephemeral storage of the machine. For example a value like “15Gi”.
has_gpu (bool) – Whether the machine has a GPU.
memory (str) – The memory of the machine. For example a value like “8Gi”.
ram_gb (int) – The amount of RAM of the machine.

class datarobot.models.notebooks.execution_environment.ExecutionEnvironment

An execution environment associated with a notebook.

Variables:

image (Image) – The image associated with the execution environment.
machine (Machine) – The machine associated with the execution environment.
time_to_live (int) – The inactivity timeout for notebook session.

classmethod get(notebook_id)

Get a notebook execution environment by its notebook ID.

Parameters:: notebook_id (str) – The ID of the notebook.
Returns:: The notebook execution environment.
Return type:: ExecutionEnvironment

classmethod assign_environment(notebook_id, payload)

Assign execution environment values to a notebook.

Parameters:

notebook_id (str) – The ID of the notebook.
payload (ExecutionEnvironmentAssignPayload) – The payload for the assignment/update.

Returns:

The assigned execution environment.

Return type:

ExecutionEnvironment

Examples

from datarobot.models.notebooks import ExecutionEnvironment, ExecutionEnvironmentAssignPayload

payload = ExecutionEnvironmentAssignPayload(machine_slug='medium', time_to_live=10)
exec_env = ExecutionEnvironment.assign_environment('67914bfab0279fd832dc3fd1', payload)

class datarobot.models.notebooks.kernel.NotebookKernel

A kernel associated with a codespace notebook.

Variables:

id (str) – The kernel ID.
name (str) – The kernel name.
language (RuntimeLanguage) – The kernel language. Supports Python and R.
running (bool) – Whether the kernel is running.
execution_state (KernelState) – The kernel execution state.

class datarobot.models.notebooks.revision.CreateRevisionPayload: Payload for creating a notebook revision.

class datarobot.models.notebooks.revision.NotebookRevision

Represents a notebook revision.

Variables:

revision_id (str) – The ID of the notebook revision.
notebook_id (str) – The ID of the notebook.
is_auto (bool) – Whether the revision was auto-saved.

classmethod create(notebook_id, payload=None)

Create a new notebook revision.

Parameters:

notebook_id (str) – The ID of the notebook.
payload (CreateRevisionPayload) – The payload to create the revision.

Returns:

Information about the created notebook revision.

Return type:

NotebookRevision

class datarobot.models.notebooks.scheduled_job.NotebookScheduledJob

DataRobot Notebook Schedule. A scheduled job that runs a notebook.

Variables:

id (str) – The ID of the scheduled notebook job.
enabled (bool) – Whether job is enabled or not.
run_type (RunType) – The type of the run - either manual (triggered via UI or API) or scheduled.
notebook_type (NotebookType) – The type of the notebook - either plain or codespace.
job_payload (ScheduledJobPayload) – The payload used for the background job.
next_run_time (Optional[str]) – The next time the job is scheduled to run (assuming it is enabled).
title (Optional[str]) – The title of the job. Optional.
schedule (Optional[str]) – Cron-like string to define how frequently job should be run. Optional.
schedule_localized (Optional[str]) – A human-readable localized version of the schedule. Example in English is ‘At 42 minutes past the hour’. Optional.
last_successful_run (Optional[str]) – The last time the job was run successfully. Optional.
last_failed_run (Optional[str]) – The last time the job failed. Optional.
last_run_time (Optional[str]) – The last time the job was run (failed or successful). Optional.

classmethod get(use_case_id, scheduled_job_id)

Retrieve a single notebook schedule.

Parameters:: scheduled_job_id (str) – The ID of the notebook schedule you want to retrieve.
Returns:: notebook_schedule – The requested notebook schedule.
Return type:: NotebookScheduledJob

Examples

from datarobot.models.notebooks import NotebookScheduledJob

notebook_schedule = NotebookScheduledJob.get(
    use_case_id="654ad653c6c1e889e8eab12e",
    scheduled_job_id="65734fe637157200e28bf688",
)

classmethod list(notebook_ids=None, statuses=None)

List all NotebookScheduledJobs available to the user.

Parameters:

notebook_ids (Optional[List[str]]) – Notebook IDs to filter listed schedules by. Optional.
statuses (Optional[List[ScheduleStatus]]) – Statuses to filter listed schedules by. Includes values “disabled” and “enabled”. Optional.

Returns:

notebook_schedules – A list of NotebookScheduledJobs available to the user.

Return type:

List[NotebookScheduledJob]

cancel()

Cancel a running notebook schedule.

Return type:: None

get_most_recent_run()

Retrieve the most recent run for the notebook schedule.

Returns:: notebook_scheduled_run – The most recent run for the notebook schedule, or None if no runs have been made.
Return type:: Optional[NotebookScheduledRun]

Examples

from datarobot.models.notebooks import NotebookScheduledJob

notebook_schedule = NotebookScheduledJob.get(
    use_case_id="654ad653c6c1e889e8eab12e",
    scheduled_job_id="65734fe637157200e28bf688",
)
most_recent_run = notebook_schedule.get_most_recent_run()

get_job_history()

Retrieve list of historical runs for the notebook schedule. Gets the most recent runs first.

Returns:: notebook_scheduled_runs – The list of historical runs for the notebook schedule.
Return type:: List[NotebookScheduledRun]

Examples

from datarobot.models.notebooks import NotebookScheduledJob

notebook_schedule = NotebookScheduledJob.get(
    use_case_id="654ad653c6c1e889e8eab12e",
    scheduled_job_id="65734fe637157200e28bf688",
)
notebook_scheduled_runs = notebook_schedule.get_job_history()

wait_for_completion(max_wait=600)

Wait for the completion of a scheduled notebook and return the revision ID corresponding to the run’s output.

Parameters:: max_wait (int) – The number of seconds to wait before giving up.
Returns:: revision_id – Returns either revision ID or message describing current state.
Return type:: str

Examples

from datarobot.models.notebooks.notebook import Notebook

notebook = Notebook.get(notebook_id='6556b00dcc4ea0bb7ea48121')
manual_run = notebook.run_as_job()
revision_id = manual_run.wait_for_completion()

class datarobot.models.notebooks.scheduled_run.ScheduledJobParam

DataRobot Schedule Job Parameter.

Variables:

name (str) – The name of the parameter.
value (str) – The value of the parameter.

class datarobot.models.notebooks.scheduled_run.ScheduledJobPayload

DataRobot Schedule Job Payload.

Variables:

uid (str) – The ID of the user who created the notebook schedule.
org_id (str) – The ID of the user’s organization who created the notebook schedule.
use_case_id (str) – The ID of the Use Case that the notebook belongs to.
notebook_id (str) – The ID of the notebook being run on a schedule.
notebook_name (str) – The name of the notebook being run on a schedule.
run_type (RunType) – The type of the run - either manual (triggered via UI or API) or scheduled.
notebook_type (NotebookType) – The type of the notebook - either plain or codespace.
parameters (List[ScheduledJobParam]) – The parameters being used in the notebook schedule. Can be an empty list.
notebook_path (Optional[str]) – The path of the notebook to execute within the codespace. Optional. Required if notebook is in a codespace.
use_case_name (Optional[str]) – The name of the Use Case that the notebook belongs to.

class datarobot.models.notebooks.scheduled_run.ScheduledRunRevisionMetadata

DataRobot Notebook Revision Metadata specifically for a scheduled run.

Both id and name can be null if for example the job is still running or has failed.

Variables:

id (Optional[str]) – The ID of the Notebook Revision. Optional.
name (Optional[str]) – The name of the Notebook Revision. Optional.

class datarobot.models.notebooks.scheduled_run.NotebookScheduledRun

DataRobot Notebook Scheduled Run. A historical run of a notebook schedule.

Variables:

id (str) – The ID of the scheduled notebook job.
use_case_id (str) – The Use Case ID of the scheduled notebook job.
status (str) – The status of the run.
payload (ScheduledJobPayload) – The payload used for the background job.
title (Optional[str]) – The title of the job. Optional.
start_time (Optional[str]) – The start time of the job. Optional.
end_time (Optional[str]) – The end time of the job. Optional.
revision (ScheduledRunRevisionMetadata) – Notebook revision data - ID and name.
duration (Optional[int]) – The job duration in seconds. May be None for example while the job is running. Optional.
run_type (Optional[RunType]) – The type of the run - either manual (triggered via UI or API) or scheduled. Optional.
notebook_type (Optional[NotebookType]) – The type of the notebook - either plain or codespace. Optional.

class datarobot.models.notebooks.session.CloneRepositorySchema: Schema for cloning a repository when starting a notebook session.

class datarobot.models.notebooks.session.StartSessionParameters: Parameters used as environment variables in a notebook session.

class datarobot.models.notebooks.session.StartSessionPayload: Payload for starting a notebook session.

class datarobot.models.notebooks.session.NotebookExecutionStatus

Notebook execution status information.

Variables:

status (str) – The status of the notebook execution.
cell_id (Optional[bson.ObjectId]) – The ID of the cell being executed. Optional.
queued_cell_ids (Optional[List[bson.ObjectId]]) – The list of cell IDs that are queued for execution. Optional.

class datarobot.models.notebooks.session.CodespaceNotebookCell: Represents a cell in a codespace notebook.

class datarobot.models.notebooks.session.CodespaceNotebookState

Notebook state information for a codespace notebook.

Variables:

name (str) – The name of the notebook.
path (str) – The path of the notebook.
generation (int) – The generation of the notebook.
nbformat (int) – The notebook format version.
nbformat_minor (int) – The notebook format minor version.
metadata (dict) – The metadata of the notebook.
cells (List[CodespaceNotebookCell]) – The list of cells in the notebook.
kernel_id (Optional[str]) – The ID of the kernel. Optional.

class datarobot.models.notebooks.session.NotebookSession

Notebook session information.

Variables:

status (NotebookStatus) – The current status of the notebook kernel.
notebook_id (str) – The ID of the notebook.
session_id (str) – The ID of the session. Incorporates the notebook_id as part of this ID.
started_at (Optional[str]) – The date and time when the notebook was started. Optional.
session_type (Optional[SessionType]) – The type of the run - either manual (triggered via UI or API) or scheduled. Optional.
ephemeral_session_key (Optional[str]) – The ID specific to ephemeral session if being used. Optional.

classmethod get(notebook_id)

Get a notebook session by its notebook ID.

Parameters:: notebook_id (str) – The ID of the notebook.
Returns:: The notebook session information.
Return type:: NotebookSession

classmethod start(notebook_id, payload)

Start a notebook session.

Parameters:

notebook_id (str) – The ID of the notebook.
payload (StartSessionPayload) – The payload to start the session.

Returns:

The notebook session information.

Return type:

NotebookSession

classmethod stop(notebook_id)

Stop a notebook session.

Parameters:: notebook_id (str) – The ID of the notebook.
Returns:: The notebook session information.
Return type:: NotebookSession

classmethod execute_notebook(notebook_id, cell_ids=None)

Execute a notebook.

Parameters:

notebook_id (str) – The ID of the notebook.
cell_ids (Optional[List[bson.ObjectId]]) – The list of cell IDs to execute. Optional. If not provided, the whole notebook will be executed.

Return type:

None

classmethod execute_codespace_notebook(notebook_id, notebook_path, generation, cells)

Execute a notebook.

Parameters:

notebook_id (str) – The ID of the notebook.
notebook_path (str) – The path of the notebook.
generation (int) – The generation of the notebook.
cells (List[CodespaceNotebookCell]) – The list of cells to execute.

Return type:

None

classmethod get_execution_status(notebook_id)

Get the execution status information of a notebook.

Parameters:: notebook_id (str) – The ID of the notebook.
Returns:: The execution status information of the notebook.
Return type:: NotebookExecutionStatus

class datarobot.models.notebooks.settings.NotebookSettings

Settings for a DataRobot Notebook.

Variables:

show_line_numbers (bool) – Whether line numbers in cells should be displayed.
hide_cell_titles (bool) – Whether cell titles should be displayed.
hide_cell_outputs (bool) – Whether the cell outputs should be displayed.
show_scrollers (bool) – Whether scroll bars should be shown on cells.
hide_cell_footers (bool) – Whether footers should be shown on cells.
highlight_whitespace (bool) – Whether whitespace should be highlighted or not.

class datarobot.models.notebooks.user.NotebookUser

A user associated with a Notebook.

Variables:

id (str) – The ID of the user.
activated (bool) – Whether or not the user is enabled.
username (str) – The username of the user, usually their email address.
first_name (str) – The first name of the user.
last_name (str) – The last name of the user.
gravatar_hash (Optional[str]) – The gravatar hash of the user. Optional.
tenant_phase (Optional[str]) – The phase that the user’s tenant is in. Optional.

class datarobot.models.notebooks.user.NotebookActivity

A record of activity (i.e. last run, updated, etc.) in a Notebook.

Variables:

at (str) – The time of the activity in the notebook.
by (NotebookUser) – The user who performed the activity.