ObjectAPIClient - Evo Python SDK

GitHub source

## evo.objects.client.api_client.ObjectAPIClient

### __init__

    __init__(environment: Environment, connector: APIConnector, cache: ICache | None = None) -> None

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`environment` | `Environment` | The target Evo environment, providing org and workspace IDs. | required
`connector` | `APIConnector` | The API connector to use for making API calls. | required
`cache` | `ICache | None` | An optional cache to use for data downloads. | `None`

### from_context `classmethod`

    from_context(context: IContext) -> ObjectAPIClient

Create a ObjectAPIClient from the given context.

The context must have a hub_url, org_id, and workspace_id set.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`context` | `IContext` | The context to create the client from. | required

Returns:

Type | Description
--- | ---
`ObjectAPIClient` | A ObjectAPIClient instance.

### get_service_health `async`

    get_service_health(check_type: HealthCheckType = HealthCheckType.FULL) -> ServiceHealth

Get the health of the geoscience object service.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`check_type` | `HealthCheckType` | The type of health check to perform. | `FULL`

Returns:

Type | Description
--- | ---
`ServiceHealth` | A ServiceHealth object.

Raises:

Type | Description
--- | ---
`EvoAPIException` | If the API returns an unexpected status code.
`ClientValueError` | If the response is not a valid service health check response.

### list_objects `async`

    list_objects(
        offset: int = 0,
        limit: int = 5000,
        order_by: dict[ObjectOrderByEnum | str, OrderByOperatorEnum] | None = None,
        schema_id: list[str] | None = None,
        deleted: bool | None = None,
        request_timeout: int | float | tuple[int | float, int | float] | None = None,
    ) -> Page[ObjectMetadata]

List up to `limit` geoscience objects, starting at `offset`.

The geoscience objects will be the latest version of the object. If there are no objects to list, the page will be empty.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`offset` | `int` | The number of objects to skip before listing. | `0`
`limit` | `int` | Max number of objects to list. | `5000`
`order_by` | `dict[ObjectOrderByEnum | str, OrderByOperatorEnum] | None` | A dictionary of fields to order the results by, with the field name as the key and the direction of ordering as the value. | `None`
`schema_id` | `list[str] | None` | A list of schema IDs to filter the objects by. If None, objects of all schema types are returned. | `None`
`deleted` | `bool | None` | When true, only objects that have been deleted will be returned. If false or None, only non-deleted objects will be returned. | `None`
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`Page[ObjectMetadata]` | A page of all objects from the query.

### list_all_objects `async`

    list_all_objects(
        limit_per_request: int = 5000,
        order_by: dict[ObjectOrderByEnum | str, OrderByOperatorEnum] | None = None,
        schema_id: list[str] | None = None,
        deleted: bool | None = None,
        request_timeout: int | float | tuple[int | float, int | float] | None = None,
    ) -> list[ObjectMetadata]

List all geoscience objects in the workspace.

This method makes multiple calls to the `list_objects` endpoint until all objects have been listed.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`limit_per_request` | `int` | The maximum number of objects to list in one request. | `5000`
`order_by` | `dict[ObjectOrderByEnum | str, OrderByOperatorEnum] | None` | A dictionary of fields to order the results by, with the field name as the key and the direction of ordering as the value. | `None`
`schema_id` | `list[str] | None` | A list of schema IDs to filter the objects by. If None, objects of all schema types are returned. | `None`
`deleted` | `bool | None` | When true, only objects that have been deleted will be returned. If false or None, only non-deleted objects will be returned. | `None`
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`list[ObjectMetadata]` | A list of all objects in the workspace.

### list_objects_for_instance `async`

    list_objects_for_instance(
        offset: int = 0,
        limit: int = 5000,
        order_by: dict[ObjectOrderByEnum | str, OrderByOperatorEnum] | None = None,
        schema_id: list[str] | None = None,
        deleted: bool | None = None,
        request_timeout: int | float | tuple[int | float, int | float] | None = None,
    ) -> Page[OrgObjectMetadata]

List up to `limit` geoscience objects for all accessible workspaces in the instance, starting at `offset`.

The geoscience objects will be the latest version of the object. If there are no objects to list, the page will be empty.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`offset` | `int` | The number of objects to skip before listing. | `0`
`limit` | `int` | Max number of objects to list. | `5000`
`order_by` | `dict[ObjectOrderByEnum | str, OrderByOperatorEnum] | None` | A dictionary of fields to order the results by, with the field name as the key and the direction of ordering as the value. | `None`
`schema_id` | `list[str] | None` | A list of schema IDs to filter the objects by. If None, objects of all schema types are returned. | `None`
`deleted` | `bool | None` | When true, only objects that have been deleted will be returned. If false or None, only non-deleted objects will be returned. | `None`
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`Page[OrgObjectMetadata]` | A page of all objects from the query.

### list_versions_by_path `async`

    list_versions_by_path(
        path: str, request_timeout: int | float | tuple[int | float, int | float] | None = None
    ) -> list[ObjectVersion]

List all version for the given object.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`path` | `str` | The path to the geoscience object. | required
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`list[ObjectVersion]` | A sorted list of object versions. The latest version is the first element of the list.

### list_versions_by_id `async`

    list_versions_by_id(
        object_id: UUID, request_timeout: int | float | tuple[int | float, int | float] | None = None
    ) -> list[ObjectVersion]

List all version for the given object.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`object_id` | `UUID` | The UUID of the geoscience object. | required
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`list[ObjectVersion]` | A sorted list of object versions. The latest version is the first element of the list.

### prepare_data_upload `async`

    prepare_data_upload(data_identifiers: Sequence[str | UUID]) -> AsyncIterator[ObjectDataUpload]

Prepare to upload multiple data files to the geoscience object service.

Referenced data that already exists in the workspace will be skipped.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`data_identifiers` | `Sequence[str | UUID]` | A list of sha256 digests or UUIDs for the data to be uploaded. | required

Returns:

Type | Description
--- | ---
`AsyncIterator[ObjectDataUpload]` | An async iterator of data upload contexts that can be used to upload the data. Data identifiers that already exist in the workspace will be skipped.

### prepare_data_download `async`

    prepare_data_download(
        object_id: UUID,
        version_id: str,
        data_identifiers: Sequence[str | UUID],
        request_timeout: int | float | tuple[int | float, int | float] | None = None,
    ) -> AsyncIterator[ObjectDataDownload]

Prepare to download multiple data files from the geoscience object service.

Any data IDs that are not associated with the requested object will raise a DataNotFoundError.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`object_id` | `UUID` | The ID of the object to download data from. | required
`version_id` | `str` | The version ID of the object to download data from. | required
`data_identifiers` | `Sequence[str | UUID]` | A list of sha256 digests or UUIDs for the data to be downloaded. | required
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`AsyncIterator[ObjectDataDownload]` | An async iterator of data download contexts that can be used to download the data.

Raises:

Type | Description
--- | ---
`DataNotFoundError` | If any requested data ID is not associated with the referenced object.

### get_data_client

    get_data_client(cache: ICache) -> ObjectDataClient

Get a data client for the geoscience object service.

The data client provides a high-level interface for uploading and downloading data that is referenced in geoscience objects, and caching the data locally. It depends on the optional dependency `pyarrow`, which is not installed by default. This dependency can be installed with `pip install evo-objects[utils]`.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`cache` | `ICache` | The cache to use for data downloads. | required

Returns:

Type | Description
--- | ---
`ObjectDataClient` | An ObjectDataClient instance.

Raises:

Type | Description
--- | ---
`RuntimeError` | If the `pyarrow` package is not installed.

### create_geoscience_object `async`

    create_geoscience_object(
        path: str, object_dict: dict, request_timeout: int | float | tuple[int | float, int | float] | None = None
    ) -> ObjectMetadata

Upload a new geoscience object to the geoscience object service.

New geoscience objects must not have a UUID, so that one can be assigned by the Geoscience Object Service. The `object_instance` that is passed in will be updated with the service-assigned UUID after it has been uploaded, and the metadata of the created object will be returned.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`path` | `str` | The path to upload the object to. | required
`object_dict` | `dict` | The geoscience object to be uploaded. | required
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`ObjectMetadata` | The metadata of the uploaded object.

Raises:

Type | Description
--- | ---
`ObjectUUIDError` | If the provided object has a UUID.

### move_geoscience_object `async`

    move_geoscience_object(
        path: str, object_dict: dict, request_timeout: int | float | tuple[int | float, int | float] | None = None
    ) -> ObjectMetadata

Move an existing geoscience object to a new path in the geoscience object service.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`path` | `str` | The new path to move the object to. | required
`object_dict` | `dict` | The geoscience object to be moved. | required
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`ObjectMetadata` | The metadata of the moved object.

Raises:

Type | Description
--- | ---
`ObjectUUIDError` | If the provided object does not have a UUID.

### update_geoscience_object `async`

    update_geoscience_object(
        object_dict: dict, request_timeout: int | float | tuple[int | float, int | float] | None = None
    ) -> ObjectMetadata

Update an existing geoscience object in the geoscience object service.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`object_dict` | `dict` | The geoscience object to be updated. | required
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`ObjectMetadata` | The metadata of the updated object.

Raises:

Type | Description
--- | ---
`ObjectUUIDError` | If the provided object does not have a UUID.

### download_object_by_path `async`

    download_object_by_path(
        path: str, version: str | None = None, request_timeout: int | float | tuple[int | float, int | float] | None = None
    ) -> DownloadedObject

Download a geoscience object definition (by path).

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`path` | `str` | The path to the geoscience object. | required
`version` | `str | None` | The version of the geoscience object to download. This will download the latest version by default. | `None`
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`DownloadedObject` | A tuple containing the object metadata and a data model of the requested geoscience object.

### download_object_by_id `async`

    download_object_by_id(
        object_id: UUID,
        version: str | None = None,
        request_timeout: int | float | tuple[int | float, int | float] | None = None,
    ) -> DownloadedObject

Download a geoscience object definition (by UUID).

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`object_id` | `UUID` | The uuid of the geoscience object. | required
`version` | `str | None` | The version of the geoscience object to download. This will download the latest version by default. | `None`
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`DownloadedObject` | A tuple containing the object metadata and a data model of the requested geoscience object.

### get_latest_object_versions `async`

    get_latest_object_versions(
        object_ids: list[UUID],
        batch_size: int = 500,
        request_timeout: int | float | tuple[int | float, int | float] | None = None,
    ) -> dict[UUID, str]

Get the latest version of each object by uuid.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`object_ids` | `list[UUID]` | A list of object uuids. | required
`batch_size` | `int` | The maximum number of objects to check in one API call (max 500). | `500`
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`dict[UUID, str]` | A mapping of uuids to the latest version id.

### delete_object_by_path `async`

    delete_object_by_path(path: str, request_timeout: int | float | tuple[int | float, int | float] | None = None) -> None

Soft-delete a geoscience object (by path).

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`path` | `str` | The path to the geoscience object. | required
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`None` | None

### delete_object_by_id `async`

    delete_object_by_id(
        object_id: UUID, request_timeout: int | float | tuple[int | float, int | float] | None = None
    ) -> None

Soft-delete a geoscience object (by UUID).

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`object_id` | `UUID` | The uuid of the geoscience object | required
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`None` | None

### restore_geoscience_object `async`

    restore_geoscience_object(
        object_id: UUID, request_timeout: int | float | tuple[int | float, int | float] | None = None
    ) -> None | ObjectMetadata

Restore a soft-deleted geoscience object in the geoscience object service.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`object_id` | `UUID` | The uuid of the geoscience object | required
`request_timeout` | `int | float | tuple[int | float, int | float] | None` | Timeout setting for this request. If one number is provided, it will be the total request timeout. It can also be a pair (tuple) of (connection, read) timeouts. | `None`

Returns:

Type | Description
--- | ---
`None | ObjectMetadata` | The metadata of the restored object, if a rename occurred. Otherwise, None.

### list_stages `async`

    list_stages() -> list[Stage]

List all available stages in the organisation.

Returns:

Type | Description
--- | ---
`list[Stage]` | A list of all available stages.

### set_stage `async`

    set_stage(object_id: UUID, version_id: int, stage_id: UUID) -> None

Set the stage of a specific version of a geoscience object.

Parameters:

Name | Type | Description | Default
--- | --- | --- | ---
`object_id` | `UUID` | The UUID of the geoscience object. | required
`version_id` | `int` | The version ID of the geoscience object. | required
`stage_id` | `UUID` | The UUID of the stage to set. | required

Returns:

Type | Description
--- | ---
`None` | None

#### Keyboard Shortcuts

Keys | Action
--- | ---
`?` | Open this help
`n` | Next page
`p` | Previous page
`s` | Search