Notebooks

albert.collections.notebooks.NotebookCollection

NotebookCollection(*, session: AlbertSession)

Bases: BaseCollection

NotebookCollection is a collection class for managing Notebook entities in the Albert platform.

Parameters:

Name	Type	Description	Default
session	AlbertSession	The Albert session instance.	required

Methods:

Name	Description
get_by_id	Retrieve a Notebook by its ID.
list_by_parent_id	Retrieve a Notebook by parent ID.
create	Create or return notebook for the provided notebook.
delete	Deletes a notebook by its ID.
update	Update a notebook.
update_block_content	Updates the block content of a Notebook. This does not update the notebook name (use .update for that).
get_block_by_id	Retrieve a Notebook Block by its ID.
copy	Create a copy of a Notebook into a specified parent

Attributes:

Name	Type	Description
base_path

Source code in src/albert/collections/notebooks.py

def __init__(self, *, session: AlbertSession):
    """
    Initializes the NotebookCollection with the provided session.

    Parameters
    ----------
    session : AlbertSession
        The Albert session instance.
    """
    super().__init__(session=session)
    self.base_path = f"/api/{NotebookCollection._api_version}/notebooks"

base_path

base_path = f'/api/{_api_version}/notebooks'

get_by_id

get_by_id(*, id: str) -> Notebook

Retrieve a Notebook by its ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the Notebook to retrieve.	required

Returns:

Type	Description
Notebook	The Notebook object.

Source code in src/albert/collections/notebooks.py

def get_by_id(self, *, id: str) -> Notebook:
    """Retrieve a Notebook by its ID.

    Parameters
    ----------
    id : str
        The ID of the Notebook to retrieve.

    Returns
    -------
    Notebook
        The Notebook object.
    """
    response = self.session.get(f"{self.base_path}/{id}")
    return Notebook(**response.json())

list_by_parent_id

list_by_parent_id(*, parent_id: str) -> list[Notebook]

Retrieve a Notebook by parent ID.

Parameters:

Name	Type	Description	Default
parent_id	str	The ID of the parent ID, e.g. task.	required

Returns:

Type	Description
list[Notebook]	list of notebook references.

Source code in src/albert/collections/notebooks.py

def list_by_parent_id(self, *, parent_id: str) -> list[Notebook]:
    """Retrieve a Notebook by parent ID.

    Parameters
    ----------
    parent_id : str
        The ID of the parent ID, e.g. task.

    Returns
    -------
    list[Notebook]
        list of notebook references.

    """

    # search
    response = self.session.get(f"{self.base_path}/{parent_id}/search")
    # return
    return [self.get_by_id(id=x["id"]) for x in response.json()["Items"]]

create

create(*, notebook: Notebook) -> Notebook

Create or return notebook for the provided notebook. This endpoint automatically tries to find an existing notebook with the same parameter setpoints, and will either return the existing notebook or create a new one.

Parameters:

Name	Type	Description	Default
notebook	Notebook	A list of Notebook objects to find or create.	required

Returns:

Type	Description
Notebook	A list of created or found Notebook objects.

Source code in src/albert/collections/notebooks.py

def create(self, *, notebook: Notebook) -> Notebook:
    """Create or return notebook for the provided notebook.
    This endpoint automatically tries to find an existing notebook with the same parameter setpoints, and will either return the existing notebook or create a new one.

    Parameters
    ----------
    notebook : Notebook
        A list of Notebook objects to find or create.

    Returns
    -------
    Notebook
        A list of created or found Notebook objects.
    """
    if notebook.blocks:
        # This check keeps a user from corrupting the Notebook data.
        msg = (
            "Cannot create a Notebook with pre-filled blocks. "
            "Set `blocks=[]` (or do not set it) when creating it. "
            "Use `.update_block_content()` afterward to add, update, or delete blocks."
        )
        raise AlbertException(msg)
    response = self.session.post(
        url=self.base_path,
        json=notebook.model_dump(mode="json", by_alias=True, exclude_none=True),
        params={"parentId": notebook.parent_id},
    )
    return Notebook(**response.json())

delete

delete(*, id: str) -> None

Deletes a notebook by its ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the notebook to delete.	required

Source code in src/albert/collections/notebooks.py

def delete(self, *, id: str) -> None:
    """
    Deletes a notebook by its ID.

    Parameters
    ----------
    id : str
        The ID of the notebook to delete.
    """
    self.session.delete(f"{self.base_path}/{id}")

update

update(*, notebook: Notebook) -> Notebook

Update a notebook.

Parameters:

Name	Type	Description	Default
notebook	Notebook	The updated notebook object.	required

Returns:

Type	Description
Notebook	The updated notebook object as returned by the server.

Source code in src/albert/collections/notebooks.py

def update(self, *, notebook: Notebook) -> Notebook:
    """Update a notebook.

    Parameters
    ----------
    notebook : Notebook
        The updated notebook object.

    Returns
    -------
    Notebook
        The updated notebook object as returned by the server.
    """
    existing_notebook = self.get_by_id(id=notebook.id)
    patch_data = self._generate_patch_payload(existing=existing_notebook, updated=notebook)
    url = f"{self.base_path}/{notebook.id}"

    self.session.patch(url, json=patch_data.model_dump(mode="json", by_alias=True))

    return self.get_by_id(id=notebook.id)

update_block_content

update_block_content(*, notebook: Notebook) -> Notebook

Updates the block content of a Notebook. This does not update the notebook name (use .update for that). If a block in the Notebook does not already exist on Albert, it will be created. Note: The order of the Blocks in your Notebook matter and will be used in the updated Notebook!

Parameters:

Name	Type	Description	Default
notebook	Notebook	The updated notebook object.	required

Returns:

Type	Description
Notebook	The updated notebook object as returned by the server.

Source code in src/albert/collections/notebooks.py

def update_block_content(self, *, notebook: Notebook) -> Notebook:
    """
    Updates the block content of a Notebook. This does not update the notebook name (use .update for that).
    If a block in the Notebook does not already exist on Albert, it will be created.
    *Note: The order of the Blocks in your Notebook matter and will be used in the updated Notebook!*


    Parameters
    ----------
    notebook : Notebook
        The updated notebook object.

    Returns
    -------
    Notebook
        The updated notebook object as returned by the server.
    """
    put_data = self._generate_put_block_payload(notebook=notebook)
    url = f"{self.base_path}/{notebook.id}/content"

    self.session.put(url, json=put_data.model_dump(mode="json", by_alias=True))

    return self.get_by_id(id=notebook.id)

get_block_by_id

get_block_by_id(
    *, notebook_id: str, block_id: str
) -> NotebookBlock

Retrieve a Notebook Block by its ID.

Parameters:

Name	Type	Description	Default
notebook_id	str	The ID of the Notebook to which the Block belongs.	required
block_id	str	The ID of the Notebook Block to retrieve.	required

Returns:

Type	Description
NotebookBlock	The NotebookBlock object.

Source code in src/albert/collections/notebooks.py

def get_block_by_id(self, *, notebook_id: str, block_id: str) -> NotebookBlock:
    """Retrieve a Notebook Block by its ID.

    Parameters
    ----------
    notebook_id : str
        The ID of the Notebook to which the Block belongs.
    block_id : str
        The ID of the Notebook Block to retrieve.

    Returns
    -------
    NotebookBlock
        The NotebookBlock object.
    """
    response = self.session.get(f"{self.base_path}/{notebook_id}/blocks/{block_id}")
    return TypeAdapter(NotebookBlock).validate_python(response.json())

copy

copy(
    *,
    notebook_copy_info: NotebookCopyInfo,
    type: NotebookCopyType,
) -> Notebook

Create a copy of a Notebook into a specified parent

Parameters:

Name	Type	Description	Default
notebook_copy_info	NotebookCopyInfo	The copy information for the Notebook copy	required
type	NotebookCopyType	Differentiate whether copy is for templates, task, project or restoreTemplate	required

Returns:

Type	Description
Notebook	The result of the copied Notebook.

Source code in src/albert/collections/notebooks.py

def copy(self, *, notebook_copy_info: NotebookCopyInfo, type: NotebookCopyType) -> Notebook:
    """Create a copy of a Notebook into a specified parent

    Parameters
    ----------
    notebook_copy_info : NotebookCopyInfo
        The copy information for the Notebook copy
    type : NotebookCopyType
        Differentiate whether copy is for templates, task, project or restoreTemplate

    Returns
    -------
    Notebook
        The result of the copied Notebook.
    """
    response = self.session.post(
        url=f"{self.base_path}/copy",
        json=notebook_copy_info.model_dump(mode="json", by_alias=True, exclude_none=True),
        params={"type": type, "parentId": notebook_copy_info.parent_id},
    )
    return Notebook(**response.json())