Lists

albert.collections.lists

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

ListItem

Bases: BaseResource

An item in a list.

Attributes:

Name	Type	Description
name	str	The name of the list item.
id	str | None	The Albert ID of the list item. Set when the list item is retrieved from Albert.
category	ListItemCategory | None	The category of the list item. Allowed values are businessDefined, userDefined, projects, and extensions.
list_type	str | None	The type of the list item. Allowed values are projectState for projects and extensions for extensions.

Methods:

Name	Description
validate_list_type

category class-attribute instance-attribute

category: ListItemCategory | None = Field(default=None)

id class-attribute instance-attribute

id: str | None = Field(default=None, alias='albertId')

list_type class-attribute instance-attribute

list_type: str | None = Field(
    default=None, alias="listType"
)

name instance-attribute

name: str

validate_list_type

validate_list_type() -> ListItem

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

@model_validator(mode="after")
def validate_list_type(self) -> "ListItem":
    if (
        self.category == ListItemCategory.PROJECTS
        and self.list_type is not None
        and self.list_type != "projectState"
    ) or (
        self.category == ListItemCategory.EXTENSIONS
        and self.list_type is not None
        and self.list_type != "extensions"
    ):
        raise ValueError(
            f"List type {self.list_type} is not allowed for category {self.category}"
        )
    return self

ListItemCategory

Bases: str, Enum

BUSINESS_DEFINED class-attribute instance-attribute

BUSINESS_DEFINED = 'businessDefined'

EXTENSIONS class-attribute instance-attribute

EXTENSIONS = 'extensions'

INVENTORY class-attribute instance-attribute

INVENTORY = 'inventory'

PROJECTS class-attribute instance-attribute

PROJECTS = 'projects'

USER_DEFINED class-attribute instance-attribute

USER_DEFINED = 'userDefined'

ListsCollection

ListsCollection(*, session: AlbertSession)

Bases: BaseCollection

ListsCollection is a collection class for managing ListItem entities in the Albert platform.

Example

stages = [
    "1. Discovery",
    "2. Concept Validation",
    "3. Proof of Concept",
    "4. Prototype Development",
    "5. Preliminary Evaluation",
    "6. Feasibility Study",
    "7. Optimization",
    "8. Scale-Up",
    "9. Regulatory Assessment",
]
# Initialize the Albert client
client = Albert()

# Get the custom field this list is associated with
stage_gate_field = client.custom_fields.get_by_id(id="CF123")

# Create the list items
for s in stages:
    item = ListItem(
        name=s,
        category=stage_gate_field.category,
        list_type=stage_gate_field.name,
    )

    client.lists.create(list_item=item)

Parameters:

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

Methods:

Name	Description
create	Creates a list entity.
delete	Delete a lists entry item by its ID.
get_by_id	Retrieves a list entity by its ID.
get_matching_item	Get a list item by name and list type.
list	Generates a list of list entities with optional filters.
update	Update a list item.

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

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

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

base_path instance-attribute

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

create

create(*, list_item: ListItem) -> ListItem

Creates a list entity.

Parameters:

Name	Type	Description	Default
list_item	ListItem	The list entity to create.	required

Returns:

Type	Description
List	The created list entity.

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

def create(self, *, list_item: ListItem) -> ListItem:
    """
    Creates a list entity.

    Parameters
    ----------
    list_item : ListItem
        The list entity to create.

    Returns
    -------
    List
        The created list entity.
    """
    response = self.session.post(
        self.base_path,
        json=list_item.model_dump(by_alias=True, exclude_none=True, mode="json"),
    )
    return ListItem(**response.json())

delete

delete(*, id: str) -> None

Delete a lists entry item by its ID.

Parameters:

Name	Type	Description	Default
id	str	The ID of the lists item.	required

Returns:

Type	Description
None

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

def delete(self, *, id: str) -> None:
    """
    Delete a lists entry item by its ID.

    Parameters
    ----------
    id : str
        The ID of the lists item.

    Returns
    -------
    None
    """
    url = f"{self.base_path}/{id}"
    self.session.delete(url)

get_by_id

get_by_id(*, id: str) -> ListItem

Retrieves a list entity by its ID.

Parameters:

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

Returns:

Type	Description
List	A list entity.

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

def get_by_id(self, *, id: str) -> ListItem:
    """
    Retrieves a list entity by its ID.

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

    Returns
    -------
    List
        A list entity.
    """
    response = self.session.get(f"{self.base_path}/{id}")
    return ListItem(**response.json())

get_matching_item

get_matching_item(
    *, name: str, list_type: str
) -> ListItem | None

Get a list item by name and list type.

Parameters:

Name	Type	Description	Default
name	str	The name of it item to retrieve.	required
list_type	str	The type of list (can be the name of the custom field)	required

Returns:

Type	Description
ListItem | None	A list item with the provided name and list type, or None if not found.

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

def get_matching_item(self, *, name: str, list_type: str) -> ListItem | None:
    """Get a list item by name and list type.

    Parameters
    ----------
    name : str
        The name of it item to retrieve.
    list_type : str
        The type of list (can be the name of the custom field)

    Returns
    -------
    ListItem | None
        A list item with the provided name and list type, or None if not found.
    """
    for list_item in self.list(names=[name], list_type=list_type):
        if list_item.name.lower() == name.lower():
            return list_item
    return None

list

list(
    *,
    limit: int = 100,
    names: list[str] | None = None,
    category: ListItemCategory | None = None,
    list_type: str | None = None,
    start_key: str | None = None,
) -> Iterator[ListItem]

Generates a list of list entities with optional filters.

Parameters:

Name	Type	Description	Default
limit	int	The maximum number of list entities to return.	100
names	list[str]	A list of names of the list entity to retrieve.	None
category	ListItemCategory	The category of the list entity to retrieve.	None
list_type	str	The type of list entity to retrieve.	None

Returns:

Type	Description
Iterator[ListItem]	An iterator of ListItems.

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

def list(
    self,
    *,
    limit: int = 100,
    names: list[str] | None = None,
    category: ListItemCategory | None = None,
    list_type: str | None = None,
    start_key: str | None = None,
) -> Iterator[ListItem]:
    """
    Generates a list of list entities with optional filters.

    Parameters
    ----------
    limit : int, optional
        The maximum number of list entities to return.
    names : list[str], optional
        A list of names of the list entity to retrieve.
    category : ListItemCategory, optional
        The category of the list entity to retrieve.
    list_type : str, optional
        The type of list entity to retrieve.
    Returns
    ------
    Iterator[ListItem]
        An iterator of ListItems.
    """
    params = {
        "limit": limit,
        "startKey": start_key,
        "name": [names] if isinstance(names, str) else names,
        "category": category.value if isinstance(category, ListItemCategory) else category,
        "listType": list_type,
    }
    return AlbertPaginator(
        mode=PaginationMode.KEY,
        path=self.base_path,
        session=self.session,
        params=params,
        deserialize=lambda items: [ListItem(**item) for item in items],
    )

update

update(*, list_item=ListItem) -> ListItem

Update a list item.

Parameters:

Name	Type	Description	Default
list_item	ListItem	The list item to update.	ListItem

Returns:

Type	Description
ListItem	The updated list item.

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

def update(self, *, list_item=ListItem) -> ListItem:
    """Update a list item.

    Parameters
    ----------
    list_item : ListItem
        The list item to update.

    Returns
    -------
    ListItem
        The updated list item.
    """
    existing = self.get_by_id(id=list_item.id)
    patches = self._generate_patch_payload(
        existing=existing, updated=list_item, generate_metadata_diff=False
    )
    if len(patches.data) == 0:
        return existing
    self.session.patch(
        url=f"{self.base_path}/{list_item.id}",
        json=patches.model_dump(mode="json", by_alias=True, exclude_none=True),
    )
    return self.get_by_id(id=list_item.id)