Worksheets

albert.collections.worksheets

ProjectId module-attribute

ProjectId = Annotated[
    str, AfterValidator(ensure_project_id)
]

AlbertSession

AlbertSession(
    *,
    base_url: str,
    token: str | None = None,
    client_credentials: ClientCredentials | 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 requests. (e.g., "https://sandbox.albertinvent.com")	required
retries	int	The number of retries for failed requests. Defaults to 3.	None
client_credentials	ClientCredentials | None	The client credentials for programmatic authentication. Optional if token is provided.	None
token	str | None	The JWT token for authentication. Optional if client credentials are provided.	None

Methods:

Name	Description
request

Source code in src/albert/session.py

def __init__(
    self,
    *,
    base_url: str,
    token: str | None = None,
    client_credentials: ClientCredentials | 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 client_credentials is None:
        raise ValueError("Either client credentials or token must be specified.")

    self._provided_token = token
    self._token_manager = (
        TokenManager(base_url, client_credentials) if client_credentials is not None else None
    )

    # 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/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

Worksheet(**data)

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

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

def __init__(self, **data):
    super().__init__(**data)
    self._session = data.get("session")

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)