Skip to content

Attachments

albert.collections.attachments.AttachmentCollection 

AttachmentCollection(*, session)

Bases: BaseCollection

AttachmentCollection is a collection class for managing Attachment entities in the Albert platform.

Methods:

Name Description
get_by_id

Retrieves an attachment by its ID.
get_by_parent_ids

Retrieves attachments by their parent IDs.
attach_file_to_note

Attaches an already uploaded file to a note.
delete

Deletes an attachment by ID.
upload_and_attach_file_as_note

Uploads a file and attaches it to a new note. A user can be tagged in the note_text string by using f-string and the User.to_note_mention() method.

Attributes:

Name Type Description
base_path
Source code in src/albert/collections/attachments.py 
20
21
22
def __init__(self, *, session):
    super().__init__(session=session)
    self.base_path = f"/api/{AttachmentCollection._api_version}/attachments"

base_path 

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

get_by_id 

get_by_id(*, id: AttachmentId) -> Attachment

Retrieves an attachment by its ID.

Parameters:

Name Type Description Default
id AttachmentId

The ID of the attachment to retrieve.

 required

Returns:

Type Description
Attachment

The Attachment object corresponding to the provided ID.
Source code in src/albert/collections/attachments.py 
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
@validate_call
def get_by_id(self, *, id: AttachmentId) -> Attachment:
    """Retrieves an attachment by its ID.

    Parameters
    ----------
    id : AttachmentId
        The ID of the attachment to retrieve.

    Returns
    -------
    Attachment
        The Attachment object corresponding to the provided ID.
    """
    response = self.session.get(url=f"{self.base_path}/{id}")
    return Attachment(**response.json())

get_by_parent_ids 

get_by_parent_ids(
    *, parent_ids: list[str]
) -> dict[str, list[Attachment]]

Retrieves attachments by their parent IDs.

Note: This method returns a dictionary where the keys are parent IDs and the values are lists of Attachment objects associated with each parent ID. If the parent ID has no attachments, it will not be included in the dictionary.

If no attachments are found for any of the provided parent IDs, the API response will be an error.

Parameters:

Name Type Description Default
parent_ids list[str]

Parent IDs of the objects to which the attachments are linked.

 required

Returns:

Type Description
dict[str, list[Attachment]]

A dictionary mapping parent IDs to lists of Attachment objects associated with each parent ID.
Source code in src/albert/collections/attachments.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
def get_by_parent_ids(self, *, parent_ids: list[str]) -> dict[str, list[Attachment]]:
    """Retrieves attachments by their parent IDs.

    Note: This method returns a dictionary where the keys are parent IDs
    and the values are lists of Attachment objects associated with each parent ID.
    If the parent ID has no attachments, it will not be included in the dictionary.

    If no attachments are found for any of the provided parent IDs,
    the API response will be an error.

    Parameters
    ----------
    parent_ids : list[str]
        Parent IDs of the objects to which the attachments are linked.

    Returns
    -------
    dict[str, list[Attachment]]
        A dictionary mapping parent IDs to lists of Attachment objects associated with each parent ID.
    """
    response = self.session.get(url=f"{self.base_path}/parents", params={"id": parent_ids})
    response_data = response.json()
    return {
        parent["parentId"]: [
            Attachment(**item, parent_id=parent["parentId"]) for item in parent["Items"]
        ]
        for parent in response_data
    }

attach_file_to_note 

attach_file_to_note(
    *,
    note_id: str,
    file_name: str,
    file_key: str,
    category: FileCategory = OTHER,
) -> Attachment

Attaches an already uploaded file to a note.

Parameters:

Name Type Description Default
note_id str

The ID of the note to attach the file to.

 required
file_name str

The name of the file to attach.

 required
file_key str

The unique key of the file to attach (the returned upload name).

 required
category FileCategory

The type of file, by default FileCategory.OTHER

 OTHER

Returns:

Type Description
Attachment

The related attachment object.
Source code in src/albert/collections/attachments.py 
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
def attach_file_to_note(
    self,
    *,
    note_id: str,
    file_name: str,
    file_key: str,
    category: FileCategory = FileCategory.OTHER,
) -> Attachment:
    """Attaches an already uploaded file to a note.

    Parameters
    ----------
    note_id : str
        The ID of the note to attach the file to.
    file_name : str
        The name of the file to attach.
    file_key : str
        The unique key of the file to attach (the returned upload name).
    category : FileCategory, optional
        The type of file, by default FileCategory.OTHER

    Returns
    -------
    Attachment
        The related attachment object.
    """
    attachment = Attachment(
        parent_id=note_id, name=file_name, key=file_key, namespace="result", category=category
    )
    response = self.session.post(
        url=self.base_path,
        json=attachment.model_dump(by_alias=True, mode="json", exclude_unset=True),
    )
    return Attachment(**response.json())

delete 

delete(*, id: AttachmentId) -> None

Deletes an attachment by ID.

Parameters:

Name Type Description Default
id str

The ID of the attachment to delete.

 required
Source code in src/albert/collections/attachments.py 
111
112
113
114
115
116
117
118
119
120
@validate_call
def delete(self, *, id: AttachmentId) -> None:
    """Deletes an attachment by ID.

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

upload_and_attach_file_as_note 

upload_and_attach_file_as_note(
    parent_id: str,
    file_data: IO,
    note_text: str = "",
    file_name: str = "",
) -> Note

Uploads a file and attaches it to a new note. A user can be tagged in the note_text string by using f-string and the User.to_note_mention() method. This allows for easy tagging and referencing of users within notes. example: f"Hello {tagged_user.to_note_mention()}!"

Parameters:

Name Type Description Default
parent_id str

The ID of the parent entity onto which the note will be attached.

 required
file_data IO

The file data to upload.

 required
note_text str

Any additional text to add to the note, by default ""

 ''
file_name str

The name of the file, by default ""

 ''

Returns:

Type Description
Note

The created note.
Source code in src/albert/collections/attachments.py 
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
def upload_and_attach_file_as_note(
    self, parent_id: str, file_data: IO, note_text: str = "", file_name: str = ""
) -> Note:
    """Uploads a file and attaches it to a new note. A user can be tagged in the note_text string by using f-string and the User.to_note_mention() method.
    This allows for easy tagging and referencing of users within notes. example: f"Hello {tagged_user.to_note_mention()}!"

    Parameters
    ----------
    parent_id : str
        The ID of the parent entity onto which the note will be attached.
    file_data : IO
        The file data to upload.
    note_text : str, optional
        Any additional text to add to the note, by default ""
    file_name : str, optional
        The name of the file, by default ""

    Returns
    -------
    Note
        The created note.
    """
    file_type = mimetypes.guess_type(file_name)[0]
    file_collection = self._get_file_collection()
    note_collection = self._get_note_collection()

    file_collection.sign_and_upload_file(
        data=file_data,
        name=file_name,
        namespace=FileNamespace.RESULT.value,
        content_type=file_type,
    )
    file_info = file_collection.get_by_name(
        name=file_name, namespace=FileNamespace.RESULT.value
    )
    note = Note(
        parent_id=parent_id,
        note=note_text,
    )
    registered_note = note_collection.create(note=note)
    self.attach_file_to_note(
        note_id=registered_note.id,
        file_name=file_name,
        file_key=file_info.name,
    )
    return note_collection.get_by_id(id=registered_note.id)