Worksheets

albert.collections.worksheets

ProjectId module-attribute

ProjectId = Annotated[
    str, AfterValidator(ensure_project_id)
]

AlbertSession

AlbertSession(
    *,
    base_url: str,
    token: str | None = None,
    auth_manager: AlbertClientCredentials
    | AlbertSSOClient
    | None = None,
    retries: int | None = None,
)

Bases: Session

A session that has a base URL, which is prefixed to all request URLs.

Parameters:

Name	Type	Description	Default
base_url	str	The base URL to prefix to all relative request paths (e.g., "https://app.albertinvent.com").	required
token	str | None	A static JWT token for authentication. Ignored if auth_manager is provided.	None
auth_manager	AlbertClientCredentials | AlbertSSOClient	An authentication manager used to dynamically fetch and refresh tokens. If provided, it overrides token.	None
retries	int	The number of automatic retries on failed requests (default is 3).	None

Methods:

Name	Description
request

Source code in src/albert/core/session.py

def __init__(
    self,
    *,
    base_url: str,
    token: str | None = None,
    auth_manager: AlbertClientCredentials | AlbertSSOClient | None = None,
    retries: int | None = None,
):
    super().__init__()
    self.base_url = base_url
    self.headers.update(
        {
            "Content-Type": "application/json",
            "Accept": "application/json",
            "User-Agent": f"albert-SDK V.{albert.__version__}",
        }
    )

    if token is None and auth_manager is None:
        raise ValueError("Either `token` or `auth_manager` must be specified.")

    self._auth_manager = auth_manager
    self._provided_token = token

    # Set up retry logic
    retries = retries if retries is not None else 3
    retry = Retry(
        total=retries,
        read=retries,
        connect=retries,
        backoff_factor=0.3,
        status_forcelist=(500, 502, 503, 504, 403),
        raise_on_status=False,
    )
    adapter = HTTPAdapter(max_retries=retry)
    self.mount("http://", adapter)
    self.mount("https://", adapter)

base_url instance-attribute

base_url = base_url

request

request(
    method: str, path: str, *args, **kwargs
) -> Response

Source code in src/albert/core/session.py

def request(self, method: str, path: str, *args, **kwargs) -> requests.Response:
    self.headers["Authorization"] = f"Bearer {self._access_token}"
    full_url = urljoin(self.base_url, path) if not path.startswith("http") else path
    with handle_http_errors():
        response = super().request(method, full_url, *args, **kwargs)
        response.raise_for_status()
        return response

BaseCollection

BaseCollection(*, session: AlbertSession)

BaseCollection is the base class for all collection classes.

Parameters:

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

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

def __init__(self, *, session: AlbertSession):
    self.session = session

session instance-attribute

session = session

Worksheet

Bases: BaseSessionResource

A worksheet entity.

Attributes:

Name	Type	Description
sheets	List[Sheet]	A list of sheet entities.
project_name	str | None	The name of the project.
sheets_enabled	bool	Whether the sheets are enabled.
project_id	str	The Albert ID of the project.

Methods:

Name	Description
add_session_to_sheets

project_id class-attribute instance-attribute

project_id: str = Field(alias='projectId')

project_name class-attribute instance-attribute

project_name: str | None = Field(
    default=None, alias="projectName"
)

sheets class-attribute instance-attribute

sheets: list[Sheet] = Field(alias='Sheets')

sheets_enabled class-attribute instance-attribute

sheets_enabled: bool = Field(
    default=True, alias="sheetEnabled"
)

add_session_to_sheets

add_session_to_sheets()

Source code in src/albert/resources/worksheets.py

@model_validator(mode="after")
def add_session_to_sheets(self):
    if self.session is not None:
        for s in self.sheets:
            s._session = self.session
            for d in s.designs:
                d._session = self.session
    return self

WorksheetCollection

WorksheetCollection(*, session: AlbertSession)

Bases: BaseCollection

WorksheetCollection is a collection class for managing Worksheet entities in the Albert platform.

Methods:

Name	Description
add_sheet	Create a new blank sheet in the Worksheet with the specified name.
get_by_project_id	Retrieve a worksheet by its project ID. Projects and Worksheets are 1:1 in the Albert platform.
setup_new_sheet_from_template	Create a new sheet in the Worksheet related to the specified Project from a template.
setup_worksheet	Setup a new worksheet for a project.

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

def __init__(self, *, session: AlbertSession):
    super().__init__(session=session)
    self.base_path = f"/api/{WorksheetCollection._api_version}/worksheet"

base_path instance-attribute

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

add_sheet

add_sheet(
    *, project_id: ProjectId, sheet_name: str
) -> Worksheet

Create a new blank sheet in the Worksheet with the specified name.

Parameters:

Name	Type	Description	Default
project_id	str	The project ID for the Worksheet to add the sheet to.	required
sheet_name	str	The name of the new sheet.	required

Returns:

Type	Description
Worksheet	The Worksheet object for the project.

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

def add_sheet(self, *, project_id: ProjectId, sheet_name: str) -> Worksheet:
    """Create a new blank sheet in the Worksheet with the specified name.

    Parameters
    ----------
    project_id : str
        The project ID for the Worksheet to add the sheet to.
    sheet_name : str
        The name of the new sheet.

    Returns
    -------
    Worksheet
        The Worksheet object for the project.
    """
    payload = {"name": sheet_name}
    url = f"{self.base_path}/project/{project_id}/sheets"
    self.session.put(url=url, json=payload)
    return self.get_by_project_id(project_id=project_id)

get_by_project_id

get_by_project_id(*, project_id: ProjectId) -> Worksheet

Retrieve a worksheet by its project ID. Projects and Worksheets are 1:1 in the Albert platform.

Parameters:

Name	Type	Description	Default
project_id	str	The project ID to retrieve the worksheet for.	required

Returns:

Type	Description
Worksheet	The Worksheet object for that project.

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

def get_by_project_id(self, *, project_id: ProjectId) -> Worksheet:
    """Retrieve a worksheet by its project ID. Projects and Worksheets are 1:1 in the Albert platform.

    Parameters
    ----------
    project_id : str
        The project ID to retrieve the worksheet for.

    Returns
    -------
    Worksheet
        The Worksheet object for that project.
    """

    params = {"type": "project", "id": project_id}
    response = self.session.get(self.base_path, params=params)

    response_json = response.json()

    # Sheets are themselves collections, and therefore need access to the session
    response_json = self._add_session_to_sheets(response_json)

    return Worksheet(**response_json)

setup_new_sheet_from_template

setup_new_sheet_from_template(
    *,
    project_id: ProjectId,
    sheet_template_id: str,
    sheet_name: str,
) -> Worksheet

Create a new sheet in the Worksheet related to the specified Project from a template.

Parameters:

Name	Type	Description	Default
project_id	str	description	required
sheet_template_id	str	description	required
sheet_name	str	description	required

Returns:

Type	Description
Worksheet	The Worksheet object for the project.

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

def setup_new_sheet_from_template(
    self, *, project_id: ProjectId, sheet_template_id: str, sheet_name: str
) -> Worksheet:
    """Create a new sheet in the Worksheet related to the specified Project from a template.

    Parameters
    ----------
    project_id : str
        _description_
    sheet_template_id : str
        _description_
    sheet_name : str
        _description_

    Returns
    -------
    Worksheet
        The Worksheet object for the project.
    """
    payload = {"name": sheet_name}
    params = {"templateId": sheet_template_id}
    path = f"{self.base_path}/project/{project_id}/sheets"
    self.session.post(path, json=payload, params=params)
    return self.get_by_project_id(project_id=project_id)

setup_worksheet

setup_worksheet(
    *, project_id: ProjectId, add_sheet=False
) -> Worksheet

Setup a new worksheet for a project.

Parameters:

Name	Type	Description	Default
project_id	str	The project ID to setup the worksheet for.	required
add_sheet	bool	Whether to add a blank sheet to the worksheet, by default False	False

Returns:

Type	Description
Worksheet	The Worksheet object for the project.

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

def setup_worksheet(self, *, project_id: ProjectId, add_sheet=False) -> Worksheet:
    """Setup a new worksheet for a project.

    Parameters
    ----------
    project_id : str
        The project ID to setup the worksheet for.
    add_sheet : bool, optional
        Whether to add a blank sheet to the worksheet, by default False

    Returns
    -------
    Worksheet
        The Worksheet object for the project.
    """

    params = {"sheets": str(add_sheet).lower()}
    path = f"{self.base_path}/{project_id}/setup"
    self.session.post(path, json=params)
    return self.get_by_project_id(project_id=project_id)