ObjectAPIClient

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