Attachments

albert.collections.attachments

Attachment

Bases: BaseResource

Used for attching files to Notes on Tasks, Projects, Inventory, etc. Key should match File.name

category class-attribute instance-attribute

category: Literal[OTHER] | None = None

file_size class-attribute instance-attribute

file_size: int | None = Field(
    default=None,
    alias="fileSize",
    exclude=True,
    frozen=True,
)

id class-attribute instance-attribute

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

key instance-attribute

key: str

metadata class-attribute instance-attribute

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

mime_type class-attribute instance-attribute

mime_type: str | None = Field(
    default=None,
    alias="mimeType",
    exclude=True,
    frozen=True,
)

name instance-attribute

name: str

namespace class-attribute instance-attribute

namespace: str = Field(default='result', alias='nameSpace')

parent_id class-attribute instance-attribute

parent_id: str = Field(..., alias='parentId')

signed_url class-attribute instance-attribute

signed_url: str | None = Field(
    default=None,
    alias="signedURL",
    exclude=True,
    frozen=True,
)

signed_url_v2 class-attribute instance-attribute

signed_url_v2: str | None = Field(
    default=None,
    alias="signedURLV2",
    exclude=True,
    frozen=True,
)

AttachmentCollection

AttachmentCollection(*, session)

Bases: BaseCollection

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

Methods:

Name	Description
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.

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

def __init__(self, *, session):
    super().__init__(session=session)
    self.base_path = f"/api/{AttachmentCollection._api_version}/attachments"

base_path instance-attribute

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

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

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: str) -> 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

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

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)

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

FileCategory

Bases: str, Enum

OTHER class-attribute instance-attribute

OTHER = 'Other'

SDS class-attribute instance-attribute

SDS = 'SDS'

FileCollection

FileCollection(*, session: AlbertSession)

Bases: BaseCollection

FileCollection is a collection class for managing File entities in the Albert platform.

Parameters:

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

Methods:

Name	Description
get_by_name	Gets a file by name and namespace.
get_signed_download_url	Get a signed download URL for a file.
get_signed_upload_url	Get a signed upload URL for a file.
sign_and_upload_file	Sign and upload a file to Albert.

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

def __init__(self, *, session: AlbertSession):
    """
    Initialize the FileCllection with the provided session.

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

base_path instance-attribute

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

get_by_name

get_by_name(
    *,
    name: str,
    namespace: FileNamespace,
    generic: bool = False,
) -> FileInfo

Gets a file by name and namespace.

Parameters:

Name	Type	Description	Default
name	str	The Name of the file	required
namespace	FileNamespace	The namespace of the file (e.g. AGENT, BREAKTHROUGH, PIPELINE, PUBLIC, RESULT, SDS)	required
generic	bool	description, by default False	False

Returns:

Type	Description
FileInfo	The file information related to the matching file.

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

def get_by_name(
    self,
    *,
    name: str,
    namespace: FileNamespace,
    generic: bool = False,
) -> FileInfo:
    """Gets a file by name and namespace.

    Parameters
    ----------
    name : str
        The Name of the file
    namespace : FileNamespace
        The namespace of the file (e.g. AGENT, BREAKTHROUGH, PIPELINE, PUBLIC, RESULT, SDS)
    generic : bool, optional
        _description_, by default False

    Returns
    -------
    FileInfo
        The file information related to the matching file.
    """
    params = {
        "name": name,
        "namespace": namespace,
        "generic": json.dumps(generic),
    }
    response = self.session.get(f"{self.base_path}/info", params=params)
    return FileInfo(**response.json())

get_signed_download_url

get_signed_download_url(
    *,
    name: str,
    namespace: FileNamespace,
    version_id: str | None = None,
    generic: bool = False,
    category: FileCategory | None = None,
) -> str

Get a signed download URL for a file.

Parameters:

Name	Type	Description	Default
name	str	The Name of the file	required
namespace	FileNamespace	The namespace of the file (e.g. AGENT, BREAKTHROUGH, PIPELINE, PUBLIC, RESULT, SDS)	required
version_id	str | None	The version of the file, by default None	None
category	FileCategory | None	The file category (E.g., SDS, OTHER), by default None	None

Returns:

Type	Description
str	description

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

def get_signed_download_url(
    self,
    *,
    name: str,
    namespace: FileNamespace,
    version_id: str | None = None,
    generic: bool = False,
    category: FileCategory | None = None,
) -> str:
    """Get a signed download URL for a file.

    Parameters
    ----------
    name : str
        The Name of the file
    namespace : FileNamespace
        The namespace of the file (e.g. AGENT, BREAKTHROUGH, PIPELINE, PUBLIC, RESULT, SDS)
    version_id : str | None, optional
        The version of the file, by default None
    category : FileCategory | None, optional
        The file category (E.g., SDS, OTHER), by default None

    Returns
    -------
    str
        _description_
    """
    params = {
        "name": name,
        "namespace": namespace,
        "versionId": version_id,
        "generic": json.dumps(generic),
        "category": category,
    }
    response = self.session.get(
        f"{self.base_path}/sign",
        params={k: v for k, v in params.items() if v is not None},
    )
    return response.json()["URL"]

get_signed_upload_url

get_signed_upload_url(
    *,
    name: str,
    namespace: FileNamespace,
    content_type: str,
    generic: bool = False,
    category: FileCategory | None = None,
) -> str

Get a signed upload URL for a file.

Parameters:

Name	Type	Description	Default
name	str	The Name of the file	required
namespace	FileNamespace	The namespace of the file (e.g. AGENT, BREAKTHROUGH, PIPELINE, PUBLIC, RESULT, SDS)	required
content_type	str	The content type of the file	required
category	FileCategory | None	The File category (E.g., SDS, OTHER), by default None	None

Returns:

Type	Description
str	description

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

def get_signed_upload_url(
    self,
    *,
    name: str,
    namespace: FileNamespace,
    content_type: str,
    generic: bool = False,
    category: FileCategory | None = None,
) -> str:
    """Get a signed upload URL for a file.

    Parameters
    ----------
    name : str
        The Name of the file
    namespace : FileNamespace
        The namespace of the file (e.g. AGENT, BREAKTHROUGH, PIPELINE, PUBLIC, RESULT, SDS)
    content_type : str
        The content type of the file
    category : FileCategory | None, optional
        The File category (E.g., SDS, OTHER), by default None

    Returns
    -------
    str
        _description_
    """
    params = {"generic": json.dumps(generic)}

    post_body = SignURLPOST(
        files=[
            SignURLPOSTFile(
                name=name,
                namespace=namespace,
                content_type=content_type,
                category=category,
            )
        ]
    )

    response = self.session.post(
        f"{self.base_path}/sign",
        json=post_body.model_dump(by_alias=True, exclude_unset=True, mode="json"),
        params=params,
    )
    return response.json()[0]["URL"]

sign_and_upload_file

sign_and_upload_file(
    data: IO,
    name: str,
    namespace: FileNamespace,
    content_type: str,
    generic: bool = False,
    category: FileCategory | None = None,
) -> None

Sign and upload a file to Albert.

Parameters:

Name	Type	Description	Default
data	IO	The file data	required
name	str	The name of the file	required
namespace	FileNamespace	The File Namespace (e.g., AGENT, BREAKTHROUGH, PIPELINE, PUBLIC, RESULT, SDS)	required
content_type	str	The content type of the file	required
category	FileCategory | None	The category of the file (E.g., SDS, OTHER), by default None	None

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

def sign_and_upload_file(
    self,
    data: IO,
    name: str,
    namespace: FileNamespace,
    content_type: str,
    generic: bool = False,
    category: FileCategory | None = None,
) -> None:
    """Sign and upload a file to Albert.

    Parameters
    ----------
    data : IO
        The file data
    name : str
        The name of the file
    namespace : FileNamespace
        The File Namespace (e.g., AGENT, BREAKTHROUGH, PIPELINE, PUBLIC, RESULT, SDS)
    content_type : str
        The content type of the file
    category : FileCategory | None, optional
        The category of the file (E.g., SDS, OTHER), by default None
    """
    upload_url = self.get_signed_upload_url(
        name=name,
        namespace=namespace,
        content_type=content_type,
        generic=generic,
        category=category,
    )
    requests.put(upload_url, data=data, headers={"Content-Type": content_type})

FileNamespace

Bases: str, Enum

AGENT class-attribute instance-attribute

AGENT = 'agent'

BREAKTHROUGH class-attribute instance-attribute

BREAKTHROUGH = 'breakthrough'

PIPELINE class-attribute instance-attribute

PIPELINE = 'pipeline'

PUBLIC class-attribute instance-attribute

PUBLIC = 'public'

RESULT class-attribute instance-attribute

RESULT = 'result'

SDS class-attribute instance-attribute

SDS = 'sds'

Note

Bases: BaseResource

Represents a Note on the Albert Platform. Users can be mentioned in notes 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()}!"

attachments class-attribute instance-attribute

attachments: list[EntityLink] | None = Field(
    default=None,
    exclude=True,
    frozen=True,
    alias="Attachments",
)

id class-attribute instance-attribute

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

note instance-attribute

note: str

parent_id class-attribute instance-attribute

parent_id: str = Field(..., alias='parentId')

NotesCollection

NotesCollection(*, session: AlbertSession)

Bases: BaseCollection

NotesCollection is a collection class for managing Note entities in the Albert platform.

Methods:

Name	Description
create	Creates a new note.
delete	Deletes a note by its ID.
get_by_id	Retrieves a note by its ID.
list	Lists notes by their parent ID.
update	Updates a note.

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

def __init__(self, *, session: AlbertSession):
    super().__init__(session=session)
    self.base_path = f"/api/{NotesCollection._api_version}/notes"

base_path instance-attribute

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

create

create(*, note: Note) -> Note

Creates a new note.

Parameters:

Name	Type	Description	Default
note	str	The note content.	required

Returns:

Type	Description
Note	The created note.

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

def create(self, *, note: Note) -> Note:
    """
    Creates a new note.

    Parameters
    ----------
    note : str
        The note content.

    Returns
    -------
    Note
        The created note.
    """
    response = self.session.post(
        self.base_path, json=note.model_dump(by_alias=True, exclude_unset=True, mode="json")
    )
    return Note(**response.json())

delete

delete(*, id: str) -> None

Deletes a note by its ID.

Parameters:

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

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

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

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

get_by_id

get_by_id(*, id: str) -> Note

Retrieves a note by its ID.

Parameters:

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

Returns:

Type	Description
Note	The note if found, None otherwise.

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

def get_by_id(self, *, id: str) -> Note:
    """
    Retrieves a note by its ID.

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

    Returns
    -------
    Note
        The note if found, None otherwise.
    """
    response = self.session.get(f"{self.base_path}/{id}")
    return Note(**response.json())

list

list(
    *, parent_id: str, order_by: OrderBy = DESCENDING
) -> list[Note]

Lists notes by their parent ID.

Parameters:

Name	Type	Description	Default
parent_id	str	The parent ID of the notes to list.	required
order_by	OrderBy	The order to list notes in, by default OrderBy.DESCENDING.	DESCENDING

Returns:

Type	Description
List[Note]	The list of notes.

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

def list(self, *, parent_id: str, order_by: OrderBy = OrderBy.DESCENDING) -> list[Note]:
    """
    Lists notes by their parent ID.

    Parameters
    ----------
    parent_id : str
        The parent ID of the notes to list.
    order_by : OrderBy, optional
        The order to list notes in, by default OrderBy.DESCENDING.

    Returns
    -------
    List[Note]
        The list of notes.
    """

    params = {"parentId": parent_id, "orderBy": order_by.value}
    return AlbertPaginator(
        session=self.session,
        path=self.base_path,
        mode=PaginationMode.KEY,
        params=params,
        deserialize=lambda items: [Note(**item) for item in items],
    )

update

update(*, note: Note) -> Note

Updates a note.

Parameters:

Name	Type	Description	Default
note	Note	The note to update. The note must have an ID.	required

Returns:

Type	Description
Note	The updated note as returned by the server.

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

def update(self, *, note: Note) -> Note:
    """Updates a note.

    Parameters
    ----------
    note : Note
        The note to update. The note must have an ID.

    Returns
    -------
    Note
        The updated note as returned by the server.
    """
    patch = self._generate_patch_payload(
        existing=self.get_by_id(id=note.id), updated=note, generate_metadata_diff=False
    )
    self.session.patch(
        f"{self.base_path}/{note.id}",
        json=patch.model_dump(mode="json", by_alias=True, exclude_unset=True),
    )
    return self.get_by_id(id=note.id)