Projects

albert.collections.projects

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

OrderBy

Bases: str, Enum

ASCENDING class-attribute instance-attribute

ASCENDING = 'asc'

DESCENDING class-attribute instance-attribute

DESCENDING = 'desc'

Project

Bases: BaseResource

A project in Albert.

Attributes:

Name	Type	Description
description	str	The description of the project. Used as the name of the project as well.
id	str | None	The Albert ID of the project. Set when the project is retrieved from Albert.
locations	list[Location] | None	The locations associated with the project. Optional.
project_class	ProjectClass	The class of the project. Defaults to PRIVATE.
metadata	dict[str, str | list[EntityLink] | EntityLink] | None	The metadata of the project. Optional. Metadata allowed values can be found using the Custom Fields API.
prefix	str | None	The prefix of the project. Optional.
acl	list[ACL] | None	The ACL of the project. Optional.
task_config	list[TaskConfig] | None	The task configuration of the project. Optional.
grid	GridDefault | None	The default grid of the project. Optional.
state	State | None	The state/status of the project. Allowed states are customizeable using the entitystatus API. Optional.
application_engineering_inventory_ids	list[str] | None	Inventory Ids to be added as application engineering. Optional.

Methods:

Name	Description
validate_status	Somehow, some statuses are capitalized in the API response. This ensures they are always lowercase.

acl class-attribute instance-attribute

acl: list[ACL] | None = Field(
    default_factory=list, alias="ACL"
)

application_engineering_inventory_ids class-attribute instance-attribute

application_engineering_inventory_ids: list[str] | None = (
    Field(
        default=None,
        alias="appEngg",
        description="Inventory Ids to be added as application engineering",
    )
)

description class-attribute instance-attribute

description: str = Field(min_length=1, max_length=2000)

grid class-attribute instance-attribute

grid: GridDefault | None = None

id class-attribute instance-attribute

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

locations class-attribute instance-attribute

locations: list[SerializeAsEntityLink[Location]] | None = (
    Field(
        default=None,
        min_length=1,
        max_length=20,
        alias="Locations",
    )
)

metadata class-attribute instance-attribute

metadata: dict[str, MetadataItem] | None = Field(
    alias="Metadata", default=None
)

old_api_params class-attribute instance-attribute

old_api_params: dict | None = None

prefix class-attribute instance-attribute

prefix: str | None = Field(default=None)

project_class class-attribute instance-attribute

project_class: ProjectClass | None = Field(
    default=PRIVATE, alias="class"
)

state class-attribute instance-attribute

state: State | None = Field(default=None, exclude=True)

status class-attribute instance-attribute

status: str | None = Field(
    default=None, exclude=True, frozen=True
)

task_config class-attribute instance-attribute

task_config: list[TaskConfig] | None = Field(
    default_factory=list
)

validate_status

validate_status(value)

Somehow, some statuses are capitalized in the API response. This ensures they are always lowercase.

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

@field_validator("status", mode="before")
def validate_status(cls, value):
    """Somehow, some statuses are capitalized in the API response. This ensures they are always lowercase."""
    if isinstance(value, str):
        return value.lower()
    return value

ProjectCollection

ProjectCollection(*, session: AlbertSession)

Bases: BaseCollection

ProjectCollection is a collection class for managing Project entities in the Albert platform.

Parameters:

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

Methods:

Name	Description
create	Create a new project.
delete	Delete a project by its ID.
get_by_id	Retrieve a project by its ID.
list	List projects with optional filters.
update	Update a project.

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

def __init__(self, *, session: AlbertSession):
    """
    Initialize a ProjectCollection object.

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

base_path instance-attribute

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

create

create(*, project: Project) -> Project

Create a new project.

Parameters:

Name	Type	Description	Default
project	Project	The project to create.	required

Returns:

Type	Description
Optional[Project]	The created project object if successful, None otherwise.

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

def create(self, *, project: Project) -> Project:
    """
    Create a new project.

    Parameters
    ----------
    project : Project
        The project to create.

    Returns
    -------
    Optional[Project]
        The created project object if successful, None otherwise.
    """
    response = self.session.post(
        self.base_path, json=project.model_dump(by_alias=True, exclude_unset=True, mode="json")
    )
    return Project(**response.json())

delete

delete(*, id: str) -> None

Delete a project by its ID.

Parameters:

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

Returns:

Type	Description
None

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

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

    Parameters
    ----------
    id : str
        The ID of the project to delete.

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

get_by_id

get_by_id(*, id: str) -> Project

Retrieve a project by its ID.

Parameters:

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

Returns:

Type	Description
Project	The project object if found

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

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

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

    Returns
    -------
    Project
        The project object if found
    """
    url = f"{self.base_path}/{id}"
    response = self.session.get(url)

    return Project(**response.json())

list

list(
    *,
    text: str = None,
    status: list[str] = None,
    market_segment: list[str] = None,
    application: list[str] = None,
    technology: list[str] = None,
    created_by: list[str] = None,
    location: list[str] = None,
    from_created_at: str = None,
    to_created_at: str = None,
    facet_field: str = None,
    facet_text: str = None,
    contains_field: list[str] = None,
    contains_text: list[str] = None,
    linked_to: str = None,
    my_projects: bool = None,
    my_role: list[str] = None,
    order_by: OrderBy = DESCENDING,
    sort_by: str = None,
    limit: int = 50,
) -> Iterator[Project]

List projects with optional filters.

Parameters:

Name	Type	Description	Default
text	str	Search any test in the project.	None
status	list[str]	The status filter for the projects.	None
market_segment	list[str]	The market segment filter for the projects.	None
application	list[str]	The application filter for the projects.	None
technology	list[str]	The technology filter for the projects.	None
created_by	list[str]	The name of the user who created the project.	None
location	list[str]	The location filter for the projects.	None
from_created_at	str	The start date filter for the projects.	None
to_created_at	str	The end date filter for the projects.	None
facet_field	str	The facet field for the projects.	None
facet_text	str	The facet text for the projects.	None
contains_field	list[str]	To power project facets search	None
contains_text	list[str]	To power project facets search	None
linked_to	str	To pass text for linked to dropdown search in Task creation flow.	None
my_projects	bool	Return Projects owned by you.	None
my_role	list[str]	Filter Projects to ones which you have a specific role in.	None
order_by	OrderBy	The order in which to retrieve items (default is OrderBy.DESCENDING).	DESCENDING
sort_by	str	The field to sort by.	None

Returns:

Type	Description
Iterator[Project]	An iterator of Project resources.

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

def list(
    self,
    *,
    text: str = None,
    status: list[str] = None,
    market_segment: list[str] = None,
    application: list[str] = None,
    technology: list[str] = None,
    created_by: list[str] = None,
    location: list[str] = None,
    from_created_at: str = None,
    to_created_at: str = None,
    facet_field: str = None,
    facet_text: str = None,
    contains_field: list[str] = None,
    contains_text: list[str] = None,
    linked_to: str = None,
    my_projects: bool = None,
    my_role: list[str] = None,
    order_by: OrderBy = OrderBy.DESCENDING,
    sort_by: str = None,
    limit: int = 50,
) -> Iterator[Project]:
    """
    List projects with optional filters.

    Parameters
    ----------
    text : str, optional
        Search any test in the project.
    status : list[str], optional
        The status filter for the projects.
    market_segment : list[str], optional
        The market segment filter for the projects.
    application : list[str], optional
        The application filter for the projects.
    technology : list[str], optional
        The technology filter for the projects.
    created_by : list[str], optional
        The name of the user who created the project.
    location : list[str], optional
        The location filter for the projects.
    from_created_at : str, optional
        The start date filter for the projects.
    to_created_at : str, optional
        The end date filter for the projects.
    facet_field : str, optional
        The facet field for the projects.
    facet_text : str, optional
        The facet text for the projects.
    contains_field : list[str], optional
        To power project facets search
    contains_text : list[str], optional
        To power project facets search
    linked_to : str, optional
        To pass text for linked to dropdown search in Task creation flow.
    my_projects : bool, optional
        Return Projects owned by you.
    my_role : list[str], optional
        Filter Projects to ones which you have a specific role in.
    order_by : OrderBy, optional
        The order in which to retrieve items (default is OrderBy.DESCENDING).
    sort_by : str, optional
        The field to sort by.

    Returns
    ------
    Iterator[Project]
        An iterator of Project resources.
    """
    params = {
        "limit": limit,
        "order": order_by.value,
        "text": text,
        "sortBy": sort_by,
        "status": status,
        "marketSegment": market_segment,
        "application": application,
        "technology": technology,
        "createdBy": created_by,
        "location": location,
        "fromCreatedAt": from_created_at,
        "toCreatedAt": to_created_at,
        "facetField": facet_field,
        "facetText": facet_text,
        "containsField": contains_field,
        "containsText": contains_text,
        "linkedTo": linked_to,
        "myProjects": my_projects,
        "myRole": my_role,
    }
    return AlbertPaginator(
        mode=PaginationMode.OFFSET,
        path=f"{self.base_path}/search",
        session=self.session,
        params=params,
        deserialize=lambda items: [Project(**item) for item in items],
    )

update

update(*, project: Project) -> Project

Update a project.

Parameters:

Name	Type	Description	Default
project	Project	The updated project object.	required

Returns:

Type	Description
Project	The updated project object as returned by the server.

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

def update(self, *, project: Project) -> Project:
    """Update a project.

    Parameters
    ----------
    project : Project
        The updated project object.

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

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

    return self.get_by_id(id=project.id)