Ontology Service

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

Upload Ontology

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

async def upload_ontology(ontology_path: str) -> Ontology

def upload_ontology(ontology_path: str) -> Ontology

Parameters:

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

Output:

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

Create Ontology

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

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

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

Parameters:

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

Output:

A dictionary containing:

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

Find Ontologies

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

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

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

Parameters:

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

Output:

A list of Ontology objects matching the criteria. Returns an empty list if no ontologies are found.

Find Ontology

Finds and retrieves a single ontology by its ID.

async def find_ontology(id: str) -> Optional[Ontology]

def find_ontology(id: str) -> Optional[Ontology]

Parameters:

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

Output:

An Ontology object if an ontology with the given ID is found, otherwise None.

Delete Ontology

Deletes an ontology by its ID.

async def delete_ontology(ontology_id: str) -> None

def delete_ontology(ontology_id: str) -> None

Parameters:

• ontology_id (str): The ID of the ontology to delete.

Output:

None

Wait for Ontology Upload

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

async def wait_for_ontology_upload(ontology_id: str, polling_interval: float = 0.5, timeout: int = 3600) -> Ontology

def wait_for_ontology_upload(ontology_id: str, polling_interval: float = 0.5, timeout: int = 3600) -> Ontology

Parameters:

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

Output:

The final Ontology object once the upload is complete.