DownloadedObject

GitHub source

DownloadedObject

evo.objects.client.object_client.DownloadedObject

A downloaded geoscience object.

This class also implements the IContext interface, allowing it to be used directly as a context for further API operations.

schema property

schema: ObjectSchema

The schema of the object.

metadata property

metadata: ObjectMetadata

The metadata of the object.

__init__

__init__(
    object_: GeoscienceObject,
    metadata: ObjectMetadata,
    urls_by_name: dict[str, str],
    connector: APIConnector,
    cache: ICache | None = None,
) -> None

Parameters:

Name	Type	Description	Default
object_	GeoscienceObject	The raw geoscience object model.	required
metadata	ObjectMetadata	The parsed metadata for the object.	required
urls_by_name	dict[str, str]	A mapping of data names to their initial download URLs.	required
connector	APIConnector	The API connector to use for downloading data.	required
cache	ICache | None	An optional cache to use for data downloads.	None

from_reference async staticmethod

from_reference(
    connector: APIConnector,
    reference: ObjectReference | str,
    cache: ICache | None = None,
    request_timeout: int | float | tuple[int | float, int | float] | None = None,
) -> DownloadedObject

Download a geoscience object from the service, given an object reference.

Parameters:

Name	Type	Description	Default
connector	APIConnector	The API connector to use for downloading data.	required
reference	ObjectReference | str	The reference to the object to download, or a URL as a string that can be parsed into a reference.	required
cache	ICache | None	An optional cache to use for data downloads.	None
request_timeout	int | float | tuple[int | float, int | float] | None	An optional timeout to use for API requests. See evo.common.APIConnector for details.	None

Raises:

Type	Description
ValueError	If the reference is invalid, or if the connector base URL does not match the reference hub URL.

from_context async staticmethod

from_context(context: IContext, reference: ObjectReference | str) -> DownloadedObject

Download a geoscience object from the service using a context.

Parameters:

Name	Type	Description	Default
context	IContext	The context providing the connector and cache.	required
reference	ObjectReference | str	The reference to the object to download, or a URL as a string that can be parsed into a reference.	required

Raises:

Type	Description
ValueError	If the reference is invalid, or if the connector base URL does not match the reference hub URL.

get_environment

get_environment() -> Environment

Gets the Environment associated with this object.

Returns:

Type	Description
Environment	The Environment.

get_org_id

get_org_id() -> UUID

Gets the organization ID associated with this object.

Returns:

Type	Description
UUID	The organization ID.

get_connector

get_connector() -> APIConnector

Gets the APIConnector associated with this object.

Returns:

Type	Description
APIConnector	The APIConnector.

get_cache

get_cache() -> ICache | None

Gets the ICache associated with this object, if any.

Returns:

Type	Description
ICache | None	The ICache, or None if no cache is associated.

as_dict

as_dict() -> dict

Get this object as a dictionary.

search

search(expression: str) -> Any

Search the object metadata using a JMESPath expression.

Parameters:

Name	Type	Description	Default
expression	str	The JMESPath expression to use for the search.	required

Returns:

Type	Description
Any	The result of the search.

prepare_data_download

prepare_data_download(data_identifiers: Sequence[str | UUID]) -> Iterator[ObjectDataDownload]

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

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

Parameters:

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

Returns:

Type	Description
Iterator[ObjectDataDownload]	An 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 this object.

update async

update(
    object_dict: dict,
    check_for_conflict: bool = True,
    request_timeout: int | float | tuple[int | float, int | float] | None = None,
) -> DownloadedObject

Update the geoscience object on the geoscience object service. Returning a new DownloadedObject representing the new version of the object.

This will create a new version of the object, that fully replaces the existing properties of the object with those provided in object_dict.

Note, this will not update the "DownloadedObject" instance in-place - it will still represent the original version of the object. You will need to download the updated version separately if you wish to work with it.

Parameters:

Name	Type	Description	Default
object_dict	dict	The new properties of the object as a dictionary.	required
check_for_conflict	bool	If True, and if a newer version of the object exists on the geoscience object service, the update will fail with a ObjectModifiedError exception. If False, it will not check whether there is a newer version, so will perform the update regardless.	True
request_timeout	int | float | tuple[int | float, int | float] | None	An optional timeout to use for API requests. See evo.common.APIConnector for details.	None

Returns:

Type	Description
DownloadedObject	The new version of the object as a DownloadedObject.

download_table async

download_table(
    table_info: TableInfo | str,
    fb: IFeedback = NoFeedback,
    *,
    nan_values: list[int] | list[float] | str | None = None,
    column_names: Sequence[str] | None = None,
) -> pa.Table

Download the data referenced by the given table info as a PyArrow Table.

Parameters:

Name	Type	Description	Default
table_info	TableInfo | str	The table info dict, ot JMESPath to table info within the object.	required
fb	IFeedback	An optional feedback instance to report download progress to.	NoFeedback
nan_values	list[int] | list[float] | str | None	An optional list of values to treat as null. Can also be a JMESPath expression to the list of nan values, or the nan_description structure.	None
column_names	Sequence[str] | None	An optional list of column names for the table, instead of those in the Parquet file.	None

Returns:

Type	Description
Table	A PyArrow Table containing the downloaded data.

download_category_table async

download_category_table(
    category_info: CategoryInfo | str,
    *,
    nan_values: list[int] | list[float] | str | None = None,
    column_names: Sequence[str] | None = None,
    fb: IFeedback = NoFeedback,
) -> pa.Table

Download the data referenced by the given category info as a PyArrow Table.

The arrays into the table will be DictionaryArrays constructed from the values and lookup tables.

Parameters:

Name	Type	Description	Default
category_info	CategoryInfo | str	The category info dict, or JMESPath to the category info within the object.	required
nan_values	list[int] | list[float] | str | None	An optional list of values to treat as null. Can also be a JMESPath expression to nan_description structure.	None
column_names	Sequence[str] | None	An optional list of column names for the table, instead of those in the Parquet file.	None
fb	IFeedback	An optional feedback instance to report download progress to.	NoFeedback

Returns:

Type	Description
Table	A PyArrow Table containing the downloaded data.

download_attribute_table async

download_attribute_table(attribute: AttributeInfo | str, fb: IFeedback = NoFeedback) -> pa.Table

Download the data referenced by the given attribute as a PyArrow Table.

Parameters:

Name	Type	Description	Default
attribute	AttributeInfo | str	The attribute info dict, or JMESPath to the attribute info within the object.	required
fb	IFeedback	An optional feedback instance to report download progress to.	NoFeedback

Returns:

Type	Description
Table	A PyArrow Table containing the downloaded data.

download_dataframe async

download_dataframe(
    table_info: TableInfo | str,
    fb: IFeedback = NoFeedback,
    *,
    nan_values: list[int] | list[float] | str | None = None,
    column_names: Sequence[str] | None = None,
) -> pd.DataFrame

Download the data referenced by the given table info as a Pandas DataFrame.

Parameters:

Name	Type	Description	Default
table_info	TableInfo | str	The table info dict, JMESPath to table info within the object.	required
fb	IFeedback	An optional feedback instance to report download progress to.	NoFeedback
nan_values	list[int] | list[float] | str | None	An optional list of values to treat as null. Can also be a JMESPath expression to nan_description structure.	None
column_names	Sequence[str] | None	An optional list of column names for the table, instead of those from the Parquet file.	None

Returns:

Type	Description
DataFrame	A Pandas DataFrame containing the downloaded data.

download_category_dataframe async

download_category_dataframe(
    category_info: CategoryInfo | str,
    fb: IFeedback = NoFeedback,
    *,
    nan_values: list[int] | list[float] | str | None = None,
    column_names: Sequence[str] | None = None,
) -> pd.DataFrame

Download the data referenced by the given category info as a Pandas DataFrame.

Parameters:

Name	Type	Description	Default
category_info	CategoryInfo | str	The category info dict, or JMESPath to the category info within the object.	required
nan_values	list[int] | list[float] | str | None	An optional list of values to treat as null. Can also be a JMESPath expression to nan_description structure.	None
column_names	Sequence[str] | None	An optional list of column names for the table, instead of those from the Parquet file.	None
fb	IFeedback	An optional feedback instance to report download progress to.	NoFeedback

Returns:

Type	Description
DataFrame	A Pandas DataFrame containing the downloaded data.

download_attribute_dataframe async

download_attribute_dataframe(attribute: AttributeInfo | str, fb: IFeedback = NoFeedback) -> pd.DataFrame

Download the data referenced by the given attribute as a Pandas DataFrame.

Parameters:

Name	Type	Description	Default
attribute	AttributeInfo | str	The attribute info dict, or JMESPath to the attribute within the object.	required
fb	IFeedback	An optional feedback instance to report download progress to.	NoFeedback

Returns:

Type	Description
DataFrame	A Pandas DataFrame containing the downloaded data.

download_array async

download_array(table_info: TableInfo | str, fb: IFeedback = NoFeedback) -> np.ndarray

Download the data referenced by the given table info as a NumPy array.

Parameters:

Name	Type	Description	Default
table_info	TableInfo | str	The table info dict, JMESPath to table info within the object.	required
fb	IFeedback	An optional feedback instance to report download progress to.	NoFeedback

Returns:

Type	Description
ndarray	A NumPy array containing the downloaded data.