arcgis.gis.agonb module | ArcGIS API for Python

property runtimes: RuntimeManager: Deprecated since version 2.4.2: Removed in: 2.4.5. Use the runtime_manager instead.

Deprecated since version 2.4.2: Removed in: 2.4.5. Use the runtime_manager instead.

property services: returns the service manager.

property snapshots: SnapshotManager

Returns tools to work with snapshots on notebooks

Returns:: SnapshotManager

ContainerManager

class arcgis.gis.agonb.ContainerManager(url: str, gis: GIS)

Bases: object

Provides the ability to manage notebook containers in ArcGIS Online organization.

Parameter	Description
url	Required String. The base url for the ContainerManager endpoints.
gis	Required `GIS`. The ArcGIS Online connection object.

# Initialize the ContainerManager instance through notebook server manager object

from arcgis.gis import GIS

gis = GIS(profile="your_online_admin_profile")
notebook_manager = gis.notebook_server[0]

container_manager = notebook_manager.containers
container_manager

get(id: str) → Container

Gets an instance of a container through container id.

Example:

# Usage Example: Get a container by container ID

from arcgis.gis import GIS

gis = GIS(profile="your_online_admin_profile")

notebook_manager = gis.notebook_server[0]
container_manager = notebook_manager.containers

container = container_manager.get("9bc769b888c8400e9c983846c5a64830")
container

Output:

<arcgis.gis.agonb.containers.Container at 0x315f87cb0>

Returns:: A Container object for the given container ID.

list(as_dict: bool = True) → list[dict[str, Any]] | list[Container]

Returns a list of Container instances or dictionaries representing containers.

Parameter	Description
as_dict	Optional Boolean. If True, returns a list of dictionaries representing containers. If False, returns a list of Container instances. Default is True.

Example:

# Usage Example: Listing notebook containers as default dictionaries

from arcgis.gis import GIS

gis = GIS(profile="your_online_admin_profile")

notebook_manager = gis.notebook_server[0]
container_manager = notebook_manager.containers

containers = container_manager.list()
containers

Output:

[{'id': 'e5d305ec99be480987762e8c1138a486',
  'username': 'ArcGISPyAPIBot',
  'dateCreated': 1785257430577,
  'type': 'openNotebook',
  'notebookRuntimeId': 'arcgis-notebook-python-standard:12.1.0.786',
  'notebookRuntimeVersion': '14.0',
  'notebookRuntimeName': 'ArcGIS Notebook Python 3 Standard',
  'numNotebooks': 0}]

Example:

# Usage Example: Listing notebook containers in a list

from arcgis.gis import GIS
gis = GIS(profile="your_online_admin_profile")

notebook_manager = gis.notebook_server[0]
container_manager = notebook_manager.containers

containers = container_manager.list(as_dict=False)
containers

Output:

[<arcgis.gis.agonb.containers.Container at 0x36bcd0180>]

Returns:: A list of dictionaries with key-value pairs respresenting a

a container, or a list of Container instances. :rtype: list[dict[str, Any]] | list[Container]

start(runtime: str, instance_type: str | None = None) → Future

Starts a container.

Example:

# Usage Example: Start a notebook container with the first available runtime

from arcgis.gis import GIS

gis = GIS(profile="your_online_admin_profile")

notebook_managers = gis.notebook_server
notebook_manager = notebook_managers[0]

runtime_id = notebook_manager.runtime_manager.list()[0]["id"]

container_manager = notebook_manager.containers
start_future = container_manager.start(runtime=runtime_id)

start_status = start_future.result()
start_status

Output:

True

Returns:: A Future for the container start operation. Calling result() returns the result of the start operation.

Container

class arcgis.gis.agonb.Container(url: str, gis: GIS)

Bases: object

Represents a Single Notebook container. Instances of this class are not meant to be intialized directly, but instead are returned by the get() or list() methods of the ContainerManager.

Parameter	Description
url	Required String. The url for the container.
gis	Required GIS. The ArcGIS Online connection object.

Example: Get a Container instance through the ContainerManager.

# Get a Container instance through ContainerManager object

from arcgis.gis import GIS
from arcgis.gis.agonb.containers import Container

gis = GIS(profile="your_online_admin_profile")
notebook_manager = gis.notebook_server[0]

container_manager = notebook_manager.containers
container = container_manager.get("9bc769b888c8400e9c983846c5a64830")
container

Output:

<arcgis.gis.agonb.containers.Container at <mem_addr>>

close(notebook_id: str) → bool

Closes a notebook

Example:

# Usage Example: Close a notebook in a container

from arcgis.gis import GIS

gis = GIS(profile="your_online_admin_profile")
notebook_manager = gis.notebook_server[0]
container_manager = notebook_manager.containers

container = container_manager.get("9bc769b888c8400e9c983846c5a64830")
close_status = container.close(notebook_id="9d57910ca80d4211aec1cfe46f2bbea6")

Output:

True

Returns:: True if the notebook was closed successfully, False on a failed async operation, or the raw response when no recognized status payload is returned.

property notebooks: list[dict[str, Any]]

List all notebooks running in the current container.

Example:

# Usage Example: Get notebooks running in a container

from arcgis.gis import GIS

gis = GIS(profile="your_online_admin_profile")
notebook_manager = gis.notebook_server[0]
container_manager = notebook_manager.containers

container = container_manager.get("9bc769b888c8400e9c983846c5a64830")
notebooks = container.notebooks
notebooks

Output:

{'notebooks': [{'id': '9d57910ca80d4211aec1cfe46f2bbea6',
                'itemTitle': 'Untitled Notebook',
                'dateCreated': 1785181559514,
                'dateLastActivity': 1785181559514,
                'type': 'openNotebook',
                'filename': '05a3a1a4bb2d40b6a53ba90603f9469b.ipynb',
                'username': 'ArcGISPyAPIBot',
                'containerId': '7991a3e17f7248d19318649b3fe95729'}],
                'num': 1}

Returns:: A dictionary with key as notebooks, whose value is a list of notebook dictionaries.

property properties

Retrieve the properties of a notebook container.

Example:

# Usage Example: Get container properties

from arcgis.gis import GIS

gis = GIS(profile="your_online_admin_profile")

notebook_manager = gis.notebook_server[0]
container_manager = notebook_manager.containers

container = container_manager.get("a7fd1047648140aaaad88528fcdd30ad")
container_props = container.properties
container_props

Output:

{'id': 'a7fd1047648140aaaad88528fcdd30ad',
 'username': 'ArcGISPyAPIBot',
 'dateCreated': 1784838876254,
 'type': 'openNotebook',
 'notebookRuntimeId': 'arcgis-notebook-python-standard:12.1.0.786',
 'notebookRuntimeVersion': '14.0',
 'notebookRuntimeName': 'ArcGIS Notebook Python 3 Standard',
 'numNotebooks': 1}

Returns:: A dictionary containing the properties of the notebook container.

shutdown() → bool

Stops the current container.

Example:

# Usage Example: Shutdown a notebook container

from arcgis.gis import GIS

gis = GIS(profile="your_online_admin_profile")
notebook_manager = gis.notebook_server[0]
container_manager = notebook_manager.containers

container = container_manager.get("9bc769b888c8400e9c983846c5a64830")
shutdown_status = container.shutdown()
shutdown_status

Output:

True

Returns:: True if the container was terminated successfully, False if the async operation fails, or the raw response when no recognized status payload is returned.

InstancePreference

class arcgis.gis.agonb.InstancePreference(url: str, gis: GIS)

Bases: object

Provides information about the available instances for notebook containers.

Deprecated since version 2.4.4: ArcGIS Online Notebooks no longer supports the underlying instancePreferences endpoint. Access through AGOLNotebookManager.instance_preferences is deprecated and will be removed in 2.5.0.

Parameter	Description
url	Required String. The base url for the InstancePreference endpoints.
gis	Required `GIS`. The ArcGIS Online connection object.

property available: dict[T, V]

Returns information on the available notebook instances.

Returns:: dict[T,V]

property instances: dict[T, V]

Returns a dictionary containing the available instance types for the system

Returns:: dict[T,V]

NotebookManager

class arcgis.gis.agonb.NotebookManager(url, gis, nbs)

Bases: object

Provides access to managing a site’s notebooks. An object of this class can be created using notebooks property of the NotebookServer class

execute_notebook(item: Item, update_portal_item: bool = True, parameters: list | None = None, save_parameters: bool = False, instance_type: str | None = None, timeout: float | int = 50, future: bool = False)

The Execute Notebook operation allows administrators to remotely run a notebook in their ArcGIS Notebook Server site. The notebook specified in the operation will be run with all cells in order.

Using this operation, you can schedule the execution of a notebook, either once or with a regular occurrence. This allows you to automate repeating tasks such as data collection and cleaning, content updates, and portal administration. On Linux machines, use a cron job to schedule the executeNotebook operation; on Windows machines, you can use the Task Scheduler app.

Note

To run this operation, you must be logged in with an ArcGIS Enterprise portal account. You cannot execute notebooks from the ArcGIS Notebook Server primary site administrator account.

You can specify parameters to be used in the notebook at execution time. If you’ve specified one or more parameters, they’ll be inserted into the notebook as a new cell. This cell will be placed at the beginning of the notebook, unless you have added the tag parameters to a cell.

Parameter	Description
item	Required `Item`. Opens an existing portal item.
update_portal_item	Optional Boolean. Specifies whether you want to update the notebook’s portal item after execution. The default is true. You may want to specify true when the notebook you’re executing contains information that needs to be updated, such as a workflow that collects the most recent version of a dataset. It may not be important to update the portal item if the notebook won’t store any new information after executing, such as an administrative notebook that emails reminders to inactive users.
parameters	Optional List. An optional array of parameters to add to the notebook for this execution. The parameters will be inserted as a new cell directly after the cell you have tagged `parameters`. Separate parameters with a comma. Use the format “x”:1 when defining parameters with numbers, and “y”:”text” when defining parameters with text strings.
save_parameters	Optional Boolean. Specifies whether the notebook parameters cell should be saved in the notebook for future use. The default is false.
instance_type	Optional String. The instance type.
timeout	Optional Int. The number of minutes to run the instance before timeout.
future	Optional boolean. If True, a Job object will be returned and the process will not wait for the task to complete. The default is False, which means wait for results.

Returns:: Dict, else If future = True, then the result is a concurrent.futures.Future object. Call result() to get the response

open_notebook(itemid: str, templateid: str | None = None, nb_runtimeid: str | None = None, template_nb: str | None = None, instance_type: str | None = None, *, future: bool = False)

Opens a notebook on the notebook server

Parameter	Description
itemid	Required String. Opens an existing portal item.
templateid	Optional String. The id of the portal notebook template. To get the system templates, look at the sample notebooks group: >>> from arcgis.gis import GIS >>> gis = GIS() >>> grp = gis.groups.search("title:(esri sample notebooks) AND >>> owner:"esri_notebook")[0] >>> grp.content
nb_runtimeid	Optional String. The runtime to use to generate a new notebook.
template_nb	Optional String. The start up template for the notebook.
instance_type	Optional String. The name of the instance type.
future	Optional Bool.

Returns:: Dict

RuntimeManager

class arcgis.gis.agonb.RuntimeManager(url: str, gis: GIS)

Bases: object

Class for retrieving specific runtimes and information about the *runtimes*in the ArcGIS Online organization.

Parameter	Description
url	Required String. The base url for the RuntimeManager endpoints.
gis	Required `GIS`. The ArcGIS Online connection object.

property current_runtime_version: str: Retrieves the latest released runtime version.

list() → list[dict[T, V]]

Deprecated since version 2.4.2: Removed in: 2.4.5. Use the RuntimeManager.runtimes instead.

Returns a list of runtimes in the Online organization.

Returns:: list[dict[T,V]]

manifest(id: str) → dict[T, V]

Deprecated since version 2.4.2: Removed in: 2.4.5. Use the manifest on the AGORuntime class instead.

Returns a dictionary containing all the libraries for the runtime specified by the id parameter.

Returns:: dict[T,V]

property properties: dict[str, Any]

Provides a Python dictionary with key-values pairs representing information about the runtimes resource of the organization.

Returns:: dict[str,Any]

property runtimes: Iterable[AGORuntime]

Returns all registered runtimes for the organization.

Returns:: Iterable[Runtime]

property session: EsriSession: returns the session object

AGORuntime

class arcgis.gis.agonb.AGORuntime(url: str, gis: GIS, properties: dict)

Bases: object

Provides information about the properties of a specific notebook runtime in your ArcGIS organization.

property manifest

Provides a Python list of dictionaries of all the Python libraries supported in the specified notebook runtime. Notebook authors who open notebooks using this runtime are able to import any of the libraries in the manifest into their notebooks.

Returns:: List of dictionaries with information about about each specific library.

property properties: Gets properties of the runtime resource

property session: EsriSession: returns the session object

SnapshotManager

class arcgis.gis.agonb.SnapshotManager(url: str, gis: GIS)

Bases: object

Allows for management and creation of snapshots, which are save points, for ArcGIS Online Notebooks.

Objects of this class are not initialized directly. Instead, they are typically accessed through the snapshots property of the AGOLNotebookManager.

from arcgis.gis import GIS

gis = GIS("home")
ago_nb_mgr = gis.notebook_server[0]
snapshot_mgr = ago_nb_mgr.snapshots
snapshot_mgr

Output:

<arcgis.gis.agonb.snapshot.SnapshotManager at <mem_addr>>

create(item: Item, name: str, description: str | None = None, notebook_json: dict | None = None, access: bool = False)

Creates a SnapShot of the provided notebook Item.

Parameter	Description
item	Required `Item`. The notebook item to create a a `snapshot` for.
name	Required String. The name of the snapshot. This is the identifier used to identify the snapshot.
description	Optional String. An piece of text that describes the snapshot.
notebook_json	Optional Dict. If you want to store different JSON text other than what is in the current notebook provide it here.
access	Optional Bool. When false, the snapshot will not be publicly available.

Returns:: A Python dict representing the created snapshot.

list(item: Item)

Returns a list of SnapShots for a notebook item.

Parameter	Description
item	Required Item. The Notebook `Item` to get all snapshots for.

Returns:: List of SnapShot objects

SnapShot

class arcgis.gis.agonb.SnapShot(item: Item, sm: SnapshotManager, properties: dict)

Bases: object

A single save point for a Notebook item.

Objects of this class are not meant to be created directly by users, but instead are retrieved using the list() method on the SnapshotManager.

Example: Retrieving a SnapShot object from a Notebook item

from arcgis.gis import GIS
gis = GIS("home")

nb_item = gis.content.search(
    query="City Reports *",
    item_type="Notebook"
)[0]

ago_nb_mgr = gis.notebook_server[0]
snapshot_mgr = ago_nb_mgr.snapshots
snapshots = snapshot_mgr.list(nb_item)
snapshot = snapshots[0]

delete()

Deletes a snapshot associated with the notebook item

Parameter	Description
item	Required Item. The ‘Notebook’ typed item to remove snapshots from.
snapshot	Required String. The name of the snapshot.

Returns:: A Python Boolean indicating whether the deletion was successful.

download()

Saves a snapshot locally on disk as a json file.

Returns:: A Python str representing the path of the saved file.

restore(title: str | None = None, preserve: bool = True, description: str | None = None)

Rolls back the notebook to a previous snapshot state

Note

Only users who own the notebook item can restore snapshots.

Parameter	Description
title	Optional string. The Item’s title.
preserve	Optional Bool. If True, the current notebook version is preserved as a `snapshot`.
description	Optional String. Text describing the restoration point.

Returns:: A Python dict containing the status of the operation and a JSON file as a resource.

save_as_item(title: str)

Converts a SnapShot to a new notebook Item.

Parameter	Description
title	Required String. The name of the new notebook.

Returns:: An Item object.