Skip to content

Links

AlbertPaginator 

AlbertPaginator(
    *,
    path: str,
    mode: PaginationMode,
    session: AlbertSession,
    deserialize: Callable[
        [Iterable[dict]], Iterable[ItemType]
    ],
    params: dict[str, str] | None = None,
)

Bases: Iterator[ItemType]

Helper class for pagination through Albert endpoints.

Two pagination modes are possible: - Offset-based via by the offset query parameter - Key-based via by the startKey query parameter and 'lastKey' response field

A custom deserialize function is provided when additional logic is required to load the raw items returned by the search listing, e.g., making additional Albert API calls.

Source code in src/albert/core/pagination.py 
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
def __init__(
    self,
    *,
    path: str,
    mode: PaginationMode,
    session: AlbertSession,
    deserialize: Callable[[Iterable[dict]], Iterable[ItemType]],
    params: dict[str, str] | None = None,
):
    self.path = path
    self.mode = mode
    self.session = session
    self.deserialize = deserialize

    params = params or {}
    self.params = {k: v for k, v in params.items() if v is not None}

    if "startKey" in self.params:
        self.params["startKey"] = quote_plus(self.params["startKey"])

    self._iterator = self._create_iterator()

deserialize instance-attribute 

deserialize = deserialize

mode instance-attribute 

mode = mode

params instance-attribute 

params = {k: _4for (k, v) in items() if v is not None}

path instance-attribute 

path = path

session instance-attribute 

session = session

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 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
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 
75
76
77
78
79
80
81
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 
21
22
def __init__(self, *, session: AlbertSession):
    self.session = session

session instance-attribute 

session = session

Bases: BaseResource

A link in Albert.

Attributes:

Name Type Description
parent EntityLink

The parent entity of the link.
child EntityLink

The child entity of the link.
category LinkCategory

The category of the link. Allowed values are mention, linkedTask, and synthesis.
id str | None

The Albert ID of the link. Set when the link is retrieved from Albert.
counter int | None

The counter of the link. Optional.

category class-attribute instance-attribute 

category: LinkCategory = Field(...)

child class-attribute instance-attribute 

child: EntityLink = Field(..., alias='Child')

counter class-attribute instance-attribute 

counter: int | None = Field(default=None)

id class-attribute instance-attribute 

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

parent class-attribute instance-attribute 

parent: EntityLink = Field(..., alias='Parent')

LinkCategory

Bases: str, Enum

LINKED_INVENTORY class-attribute instance-attribute 

LINKED_INVENTORY = 'linkedInventory'

LINKED_TASK class-attribute instance-attribute 

LINKED_TASK = 'linkedTask'

MENTION class-attribute instance-attribute 

MENTION = 'mention'

SYNTHESIS class-attribute instance-attribute 

SYNTHESIS = 'synthesis'

LinksCollection 

LinksCollection(*, session: AlbertSession)

Bases: BaseCollection

LinksCollection is a collection class for managing Link entities in the Albert platform.

Parameters:

Name Type Description Default
session AlbertSession

The Albert session instance.

 required

Methods:

Name Description
create

Creates a new link entity.
delete

Deletes a link entity by its ID.
get_all

Get all link entities with optional filters.
get_by_id

Retrieves a link entity by its ID.
Source code in src/albert/collections/links.py 
15
16
17
18
19
20
21
22
23
24
25
def __init__(self, *, session: AlbertSession):
    """
    Initializes the LinksCollection with the provided session.

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

base_path instance-attribute 

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

create 

create(*, links: list[Link]) -> list[Link]

Creates a new link entity.

Parameters:

Name Type Description Default
links list[Link]

List of Link entities to create.

 required

Returns:

Type Description
Link

The created link entity.
Source code in src/albert/collections/links.py 
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
def create(self, *, links: list[Link]) -> list[Link]:
    """
    Creates a new link entity.

    Parameters
    ----------
    links : list[Link]
        List of Link entities to create.

    Returns
    -------
    Link
        The created link entity.
    """
    response = self.session.post(
        self.base_path,
        json=[l.model_dump(by_alias=True, exclude_none=True, mode="json") for l in links],
    )
    return [Link(**l) for l in response.json()]

delete 

delete(*, id: str) -> None

Deletes a link entity by its ID.

Parameters:

Name Type Description Default
id str

The ID of the link entity to delete.

 required
Source code in src/albert/collections/links.py 
101
102
103
104
105
106
107
108
109
110
111
def delete(self, *, id: str) -> None:
    """
    Deletes a link entity by its ID.

    Parameters
    ----------
    id : str
        The ID of the link entity to delete.
    """
    path = f"{self.base_path}/{id}"
    self.session.delete(path)

get_all 

get_all(
    *,
    limit: int = 100,
    type: str | None = None,
    category: LinkCategory | None = None,
    id: str | None = None,
) -> Iterator[Link]

Get all link entities with optional filters.

Parameters:

Name Type Description Default
limit int

The maximum number of link entities to return.

 100
type str

The type of the link entities to return. Allowed values are parent, child, and all. If type is "all" then it will fetch both parent/child record for mentioned id.

 None
category LinkCategory

The category of the link entities to return. Allowed values are mention, linkedTask, and synthesis.

 None
id str

The ID of the link entity to return. (Use with type parameter)

 None

Returns:

Type Description
Iterator[Link]

An iterator of Links.
Source code in src/albert/collections/links.py 
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
def get_all(
    self,
    *,
    limit: int = 100,
    type: str | None = None,
    category: LinkCategory | None = None,
    id: str | None = None,
) -> Iterator[Link]:
    """
    Get all link entities with optional filters.

    Parameters
    ----------
    limit : int, optional
        The maximum number of link entities to return.
    type : str, optional
        The type of the link entities to return. Allowed values are `parent`, `child`, and `all`. If type is "all" then it will fetch both parent/child record for mentioned id.
    category : LinkCategory, optional
        The category of the link entities to return. Allowed values are `mention`, `linkedTask`, and `synthesis`.
    id : str
        The ID of the link entity to return. (Use with `type` parameter)

    Returns
    ------
    Iterator[Link]
        An iterator of Links.
    """
    params = {"limit": limit, "type": type, "category": category, "id": id}
    return AlbertPaginator(
        mode=PaginationMode.KEY,
        path=self.base_path,
        params=params,
        session=self.session,
        deserialize=lambda items: [Link(**item) for item in items],
    )

get_by_id 

get_by_id(*, id: str) -> Link

Retrieves a link entity by its ID.

Parameters:

Name Type Description Default
id str

The ID of the link entity to retrieve.

 required

Returns:

Type Description
Link

The retrieved link entity.
Source code in src/albert/collections/links.py 
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
def get_by_id(self, *, id: str) -> Link:
    """
    Retrieves a link entity by its ID.

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

    Returns
    -------
    Link
        The retrieved link entity.
    """
    path = f"{self.base_path}/{id}"
    response = self.session.get(path)
    return Link(**response.json())

PaginationMode

Bases: str, Enum

KEY class-attribute instance-attribute 

KEY = 'key'

OFFSET class-attribute instance-attribute 

OFFSET = 'offset'