Projects

albert.collections.projects.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.
get_by_id	Retrieve a project by its ID.
update	Update a project.
delete	Delete a project by its ID.
search	Search for Project matching the provided criteria.
document_search	Search for documents (attachments) linked to a project.
get_all	Retrieve fully hydrated Project entities with optional filters.

Attributes:

Name	Type	Description
base_path

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

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())

get_by_id

get_by_id(*, id: ProjectId) -> 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

@validate_call
def get_by_id(self, *, id: ProjectId) -> 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())

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)

delete

delete(*, id: ProjectId) -> 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

@validate_call
def delete(self, *, id: ProjectId) -> 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)

search

search(
    *,
    text: str | None = None,
    status: list[str] | None = None,
    market_segment: list[str] | None = None,
    application: list[str] | None = None,
    technology: list[str] | None = None,
    created_by: list[str] | None = None,
    location: list[str] | None = None,
    program: list[str] | None = None,
    technical_lead: list[str] | None = None,
    from_created_at: str | None = None,
    to_created_at: str | None = None,
    facet_field: str | None = None,
    facet_text: str | None = None,
    contains_field: list[str] | None = None,
    contains_text: list[str] | None = None,
    linked_to: str | None = None,
    my_project: bool | None = None,
    my_role: list[str] | None = None,
    metadata_filters: dict[str, Any] | None = None,
    order_by: OrderBy = DESCENDING,
    sort_by: str | None = None,
    offset: int | None = None,
    max_items: int | None = None,
) -> Iterator[ProjectSearchItem]

Search for Project matching the provided criteria.

⚠️ This method returns partial (unhydrated) entities to optimize performance. To retrieve fully detailed entities, use :meth:get_all instead.

Parameters:

Name	Type	Description	Default
text	str	Full-text search query.	None
status	list[str]	Filter by project statuses.	None
market_segment	list[str]	Filter by market segment.	None
application	list[str]	Filter by application.	None
technology	list[str]	Filter by technology tags.	None
created_by	list[str]	Filter by user names who created the project.	None
location	list[str]	Filter by location(s).	None
program	list[str]	Filter by project program (custom field).	None
technical_lead	list[str]	Filter by technical lead (custom field).	None
from_created_at	str	Earliest creation date in 'YYYY-MM-DD' format.	None
to_created_at	str	Latest creation date in 'YYYY-MM-DD' format.	None
facet_field	str	Facet field to filter on.	None
facet_text	str	Facet text to search for.	None
contains_field	list[str]	Fields to search inside.	None
contains_text	list[str]	Values to search for within the contains_field.	None
linked_to	str	Entity ID the project is linked to.	None
my_project	bool	If True, return only projects owned by current user.	None
my_role	list[str]	User roles to filter by.	None
metadata_filters	dict[str, Any]	Filters for custom field values, sent in the metadataFilters request body field. Warning Do not use this for application, technology, program, technical lead, or market segment. Use their corresponding query parameters instead.	None
order_by	OrderBy	Sort order. Default is DESCENDING.	DESCENDING
sort_by	str	Field to sort by.	None
offset	int	Pagination offset.	None
max_items	int	Maximum number of items to return in total. If None, fetches all available items.	None

Returns:

Type	Description
Iterator[ProjectSearchItem]	An iterator of matching partial (unhydrated) Project results.

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

@validate_call
def search(
    self,
    *,
    text: str | None = None,
    status: list[str] | None = None,
    market_segment: list[str] | None = None,
    application: list[str] | None = None,
    technology: list[str] | None = None,
    created_by: list[str] | None = None,
    location: list[str] | None = None,
    program: list[str] | None = None,
    technical_lead: list[str] | None = None,
    from_created_at: str | None = None,
    to_created_at: str | None = None,
    facet_field: str | None = None,
    facet_text: str | None = None,
    contains_field: list[str] | None = None,
    contains_text: list[str] | None = None,
    linked_to: str | None = None,
    my_project: bool | None = None,
    my_role: list[str] | None = None,
    metadata_filters: dict[str, Any] | None = None,
    order_by: OrderBy = OrderBy.DESCENDING,
    sort_by: str | None = None,
    offset: int | None = None,
    max_items: int | None = None,
) -> Iterator[ProjectSearchItem]:
    """
    Search for Project matching the provided criteria.

    ⚠️ This method returns partial (unhydrated) entities to optimize performance.
    To retrieve fully detailed entities, use :meth:`get_all` instead.

    Parameters
    ----------
    text : str, optional
        Full-text search query.
    status : list[str], optional
        Filter by project statuses.
    market_segment : list[str], optional
        Filter by market segment.
    application : list[str], optional
        Filter by application.
    technology : list[str], optional
        Filter by technology tags.
    created_by : list[str], optional
        Filter by user names who created the project.
    location : list[str], optional
        Filter by location(s).
    program : list[str], optional
        Filter by project program (custom field).
    technical_lead : list[str], optional
        Filter by technical lead (custom field).
    from_created_at : str, optional
        Earliest creation date in 'YYYY-MM-DD' format.
    to_created_at : str, optional
        Latest creation date in 'YYYY-MM-DD' format.
    facet_field : str, optional
        Facet field to filter on.
    facet_text : str, optional
        Facet text to search for.
    contains_field : list[str], optional
        Fields to search inside.
    contains_text : list[str], optional
        Values to search for within the `contains_field`.
    linked_to : str, optional
        Entity ID the project is linked to.
    my_project : bool, optional
        If True, return only projects owned by current user.
    my_role : list[str], optional
        User roles to filter by.
    metadata_filters : dict[str, Any], optional
        Filters for custom field values, sent in the `metadataFilters` request body field.
        !!! warning
            Do not use this for application, technology, program, technical lead, or
            market segment. Use their corresponding query parameters instead.
    order_by : OrderBy, optional
        Sort order. Default is DESCENDING.
    sort_by : str, optional
        Field to sort by.
    offset : int, optional
        Pagination offset.
    max_items : int, optional
        Maximum number of items to return in total. If None, fetches all available items.

    Returns
    -------
    Iterator[ProjectSearchItem]
        An iterator of matching partial (unhydrated) Project results.
    """
    query_params = {
        "order": order_by,
        "offset": offset,
        "text": text,
        "sortBy": sort_by,
        "status": status,
        "marketSegment": market_segment,
        "application": application,
        "technology": technology,
        "createdBy": created_by,
        "location": location,
        "program": program,
        "technicalLead": technical_lead,
        "fromCreatedAt": from_created_at,
        "toCreatedAt": to_created_at,
        "facetField": facet_field,
        "facetText": facet_text,
        "containsField": contains_field,
        "containsText": contains_text,
        "linkedTo": linked_to,
        "myProject": my_project,
        "myRole": my_role,
    }

    if metadata_filters is not None:
        payload: dict[str, Any] = {
            **query_params,
            "metadataFilters": {"metadata": metadata_filters},
        }
        return AlbertPaginator(
            mode=PaginationMode.OFFSET,
            path=f"{self.base_path}/search",
            session=self.session,
            max_items=max_items,
            deserialize=lambda items: [
                ProjectSearchItem(**item)._bind_collection(self) for item in items
            ],
            method="POST",
            json=payload,
        )

    return AlbertPaginator(
        mode=PaginationMode.OFFSET,
        path=f"{self.base_path}/search",
        session=self.session,
        params=query_params,
        max_items=max_items,
        deserialize=lambda items: [
            ProjectSearchItem(**item)._bind_collection(self) for item in items
        ],
    )

document_search

document_search(
    *,
    linked_to: SearchProjectId,
    text: str | None = None,
    order_by: OrderBy = DESCENDING,
    sort_by: str | None = None,
    offset: int | None = None,
    max_items: int | None = None,
) -> Iterator[DocumentSearchItem]

Search for documents (attachments) linked to a project.

Parameters:

Name	Type	Description	Default
linked_to	SearchProjectId	The project ID to filter documents by (e.g. P770).	required
text	str	Full-text search query for document names.	None
order_by	OrderBy	Sort order. Default is DESCENDING.	DESCENDING
sort_by	str	Field to sort by (for example createdAt).	None
offset	int	Pagination offset.	None
max_items	int	Maximum number of items to return in total. If None, fetches all.	None

Returns:

Type	Description
Iterator[DocumentSearchItem]	Matching document search results.

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

@validate_call
def document_search(
    self,
    *,
    linked_to: SearchProjectId,
    text: str | None = None,
    order_by: OrderBy = OrderBy.DESCENDING,
    sort_by: str | None = None,
    offset: int | None = None,
    max_items: int | None = None,
) -> Iterator[DocumentSearchItem]:
    """Search for documents (attachments) linked to a project.

    Parameters
    ----------
    linked_to : SearchProjectId
        The project ID to filter documents by (e.g. ``P770``).
    text : str, optional
        Full-text search query for document names.
    order_by : OrderBy, optional
        Sort order. Default is DESCENDING.
    sort_by : str, optional
        Field to sort by (for example ``createdAt``).
    offset : int, optional
        Pagination offset.
    max_items : int, optional
        Maximum number of items to return in total. If None, fetches all.

    Returns
    -------
    Iterator[DocumentSearchItem]
        Matching document search results.
    """
    query_params = {
        "linkedTo": linked_to,
        "text": text,
        "order": order_by,
        "sortBy": sort_by,
        "offset": offset,
    }

    return AlbertPaginator(
        mode=PaginationMode.OFFSET,
        path=f"{self.base_path}/documentsearch",
        session=self.session,
        params=query_params,
        max_items=max_items,
        deserialize=lambda items: [DocumentSearchItem(**item) for item in items],
    )

get_all

get_all(
    *,
    text: str | None = None,
    status: list[str] | None = None,
    market_segment: list[str] | None = None,
    application: list[str] | None = None,
    technology: list[str] | None = None,
    created_by: list[str] | None = None,
    location: list[str] | None = None,
    program: list[str] | None = None,
    technical_lead: list[str] | None = None,
    from_created_at: str | None = None,
    to_created_at: str | None = None,
    facet_field: str | None = None,
    facet_text: str | None = None,
    contains_field: list[str] | None = None,
    contains_text: list[str] | None = None,
    linked_to: str | None = None,
    my_project: bool | None = None,
    my_role: list[str] | None = None,
    order_by: OrderBy = DESCENDING,
    sort_by: str | None = None,
    offset: int | None = None,
    max_items: int | None = None,
) -> Iterator[Project]

Retrieve fully hydrated Project entities with optional filters.

This method returns complete entity data using get_by_id. Use :meth:search for faster retrieval when you only need lightweight, partial (unhydrated) entities.

Parameters:

Name	Type	Description	Default
text	str	Full-text search query.	None
status	list[str]	Filter by project statuses.	None
market_segment	list[str]	Filter by market segment.	None
application	list[str]	Filter by application.	None
technology	list[str]	Filter by technology tags.	None
created_by	list[str]	Filter by user names who created the project.	None
location	list[str]	Filter by location(s).	None
program	list[str]	Filter by project program (custom field).	None
technical_lead	list[str]	Filter by technical lead (custom field).	None
from_created_at	str	Earliest creation date in 'YYYY-MM-DD' format.	None
to_created_at	str	Latest creation date in 'YYYY-MM-DD' format.	None
facet_field	str	Facet field to filter on.	None
facet_text	str	Facet text to search for.	None
contains_field	list[str]	Fields to search inside.	None
contains_text	list[str]	Values to search for within the contains_field.	None
linked_to	str	Entity ID the project is linked to.	None
my_project	bool	If True, return only projects owned by current user.	None
my_role	list[str]	User roles to filter by.	None
order_by	OrderBy	Sort order. Default is DESCENDING.	DESCENDING
sort_by	str	Field to sort by.	None
offset	int	Pagination offset.	None
max_items	int	Maximum number of items to return in total. If None, fetches all available items.	None

Returns:

Type	Description
Iterator[Project]	An iterator of fully hydrated Project entities.

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

@validate_call
def get_all(
    self,
    *,
    text: str | None = None,
    status: list[str] | None = None,
    market_segment: list[str] | None = None,
    application: list[str] | None = None,
    technology: list[str] | None = None,
    created_by: list[str] | None = None,
    location: list[str] | None = None,
    program: list[str] | None = None,
    technical_lead: list[str] | None = None,
    from_created_at: str | None = None,
    to_created_at: str | None = None,
    facet_field: str | None = None,
    facet_text: str | None = None,
    contains_field: list[str] | None = None,
    contains_text: list[str] | None = None,
    linked_to: str | None = None,
    my_project: bool | None = None,
    my_role: list[str] | None = None,
    order_by: OrderBy = OrderBy.DESCENDING,
    sort_by: str | None = None,
    offset: int | None = None,
    max_items: int | None = None,
) -> Iterator[Project]:
    """
    Retrieve fully hydrated Project entities with optional filters.

    This method returns complete entity data using `get_by_id`.
    Use :meth:`search` for faster retrieval when you only need lightweight, partial (unhydrated) entities.

    Parameters
    ----------
    text : str, optional
        Full-text search query.
    status : list[str], optional
        Filter by project statuses.
    market_segment : list[str], optional
        Filter by market segment.
    application : list[str], optional
        Filter by application.
    technology : list[str], optional
        Filter by technology tags.
    created_by : list[str], optional
        Filter by user names who created the project.
    location : list[str], optional
        Filter by location(s).
    program : list[str], optional
        Filter by project program (custom field).
    technical_lead : list[str], optional
        Filter by technical lead (custom field).
    from_created_at : str, optional
        Earliest creation date in 'YYYY-MM-DD' format.
    to_created_at : str, optional
        Latest creation date in 'YYYY-MM-DD' format.
    facet_field : str, optional
        Facet field to filter on.
    facet_text : str, optional
        Facet text to search for.
    contains_field : list[str], optional
        Fields to search inside.
    contains_text : list[str], optional
        Values to search for within the `contains_field`.
    linked_to : str, optional
        Entity ID the project is linked to.
    my_project : bool, optional
        If True, return only projects owned by current user.
    my_role : list[str], optional
        User roles to filter by.
    order_by : OrderBy, optional
        Sort order. Default is DESCENDING.
    sort_by : str, optional
        Field to sort by.
    offset : int, optional
        Pagination offset.
    max_items : int, optional
        Maximum number of items to return in total. If None, fetches all available items.

    Returns
    -------
    Iterator[Project]
        An iterator of fully hydrated Project entities.
    """
    for project in self.search(
        text=text,
        status=status,
        market_segment=market_segment,
        application=application,
        technology=technology,
        created_by=created_by,
        location=location,
        program=program,
        technical_lead=technical_lead,
        from_created_at=from_created_at,
        to_created_at=to_created_at,
        facet_field=facet_field,
        facet_text=facet_text,
        contains_field=contains_field,
        contains_text=contains_text,
        linked_to=linked_to,
        my_project=my_project,
        my_role=my_role,
        order_by=order_by,
        sort_by=sort_by,
        offset=offset,
        max_items=max_items,
    ):
        project_id = getattr(project, "albertId", None) or getattr(project, "id", None)
        if not project_id:
            continue

        id = project_id if project_id.startswith("PRO") else f"PRO{project_id}"

        try:
            yield self.get_by_id(id=id)
        except AlbertHTTPError as e:
            logger.warning(f"Error fetching project details {id}: {e}")