Attachments

albert.collections.attachments

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

session = session

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

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

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

NotesCollection

NotesCollection(*, session: AlbertSession)

Bases: BaseCollection

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

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

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

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

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)

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}")

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],
    )

Attachment

Bases: BaseResource

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

id

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

parent_id

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

name

name: str

key

key: str

namespace

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

category

category: Literal[OTHER] | None = None

file_size

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

mime_type

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

signed_url

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

signed_url_v2

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

metadata

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

FileCategory

Bases: str, Enum

SDS

SDS = 'SDS'

OTHER

OTHER = 'Other'

FileNamespace

Bases: str, Enum

AGENT

AGENT = 'agent'

BREAKTHROUGH

BREAKTHROUGH = 'breakthrough'

PIPELINE

PIPELINE = 'pipeline'

PUBLIC

PUBLIC = 'public'

RESULT

RESULT = 'result'

SDS

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()}!"

parent_id

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

note

note: str

id

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

attachments

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

AttachmentCollection

AttachmentCollection(*, session)

Bases: BaseCollection

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

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

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)