File Service

The FileService handles file-related operations and is accessed via the file property of an active PerseusClient instance.

Upload File

Uploads a file to the Perseus API. This is a higher-level function that encapsulates create_file and the upload to a presigned URL. If a file with the same content already exists, it will be returned without uploading.

async def upload_file(file_path: str) -> File

def upload_file(file_path: str) -> File

Parameters:

• file_path (str): The local path to the file to upload.

Output:

A File object representing the uploaded or existing file, including its ID, name, status, and creation timestamp.

Create File

Creates a file record on the server and returns a presigned URL for uploading the file content.

async def create_file(name: str, source_hash: str) -> Dict

def create_file(name: str, source_hash: str) -> Dict

Parameters:

• name (str): The name of the file.
• source_hash (str): The SHA256 hash of the file's content.

Output:

A dictionary containing:

• file: A File object representing the newly created file.
• upload_url: A str (presigned URL) to which the file content should be uploaded.

Find Files

Finds and retrieves a list of files based on their IDs or source hashes.

async def find_files(ids: Optional[List[str]] = None, source_hashes: Optional[List[str]] = None) -> List[File]

def find_files(ids: Optional[List[str]] = None, source_hashes: Optional[List[str]] = None) -> List[File]

Parameters:

• ids (Optional[List[str]]): A list of file IDs to search for.
• source_hashes (Optional[List[str]]): A list of SHA256 source hashes to search for.

Output:

A list of File objects matching the criteria. Returns an empty list if no files are found.

Find File

Finds and retrieves a single file by its ID.

async def find_file(id: str) -> Optional[File]

def find_file(id: str) -> Optional[File]

Parameters:

• id (str): The ID of the file to find.

Output:

A File object if a file with the given ID is found, otherwise None.

Delete File

Deletes a file by its ID.

async def delete_file(file_id: str) -> None

def delete_file(file_id: str) -> None

Parameters:

• file_id (str): The ID of the file to delete.

Output:

None.

Wait for File Upload

Waits for a file's status to become UPLOADED or FAILED. This is useful after getting a presigned URL and uploading the file.

async def wait_for_file_upload(file_id: str, polling_interval: float = 0.5, timeout: int = 3600) -> File

def wait_for_file_upload(file_id: str, polling_interval: float = 0.5, timeout: int = 3600) -> File

Parameters:

• file_id (str): The ID of the file to wait for.
• polling_interval (float): The interval in seconds to poll for the file status. Defaults to 0.5.
• timeout (int): The maximum time in seconds to wait. Defaults to 3600.

Output:

The final File object once the upload is complete.