Skip to content

Links

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 
28
29
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,
    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 
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 
27
28
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_by_id

Retrieves a link entity by its ID.
list

Generates a list of link entities with optional filters.
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_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())

list 

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

Generates a list of 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 list(
    self,
    *,
    limit: int = 100,
    type: str | None = None,
    category: LinkCategory | None = None,
    id: str | None = None,
) -> Iterator[Link]:
    """
    Generates a list of 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],
    )