evo-blockmodels

GitHub source

BlockModelAPIClient

evo.blockmodels.client.BlockModelAPIClient

__init__

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

Constructor for the Block Model Service client.

Some methods need a cache to store temporary files. If you want to use these methods, you must provide a cache.

Parameters:

Name	Type	Description	Default
environment	Environment	The environment object.	required
connector	APIConnector	The connector object.	required
cache	ICache | None	The cache to use for storing temporary files.	None

from_context classmethod

from_context(context: IContext) -> BlockModelAPIClient

Create a BlockModelAPIClient 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
BlockModelAPIClient	A BlockModelAPIClient instance.

get_service_health async

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

Get the health of the 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_block_models async

list_block_models() -> list[BlockModel]

List block models in the current workspace.

Returns a list of BlockModels for the workspace referenced by the client's Environment. Limited to the first 100 results.

list_all_block_models async

list_all_block_models(page_limit: int | None = 100) -> list[BlockModel]

Return all block models for the current workspace, following paginated responses.

This method will page through the list_block_models endpoint using offset and limit until all entries are retrieved. The page_limit is clamped to the service maximum (100).

Parameters:

Name	Type	Description	Default
page_limit	int | None	Maximum items to request per page (1..100). Defaults to 100.	100

Returns:

Type	Description
list[BlockModel]	A list of BlockModel dataclasses for the workspace.

list_versions async

list_versions(bm_id: UUID) -> list[Version]

List versions of a block model.

Returns a list of Versions for the block model referenced by bm_id, limited to the first 100 results (or the service maximum).

Versions are ordered from newest to oldest.

Parameters:

Name	Type	Description	Default
bm_id	UUID	The ID of the block model.	required

Returns:

Type	Description
list[Version]	A list of Version dataclasses for the block model, ordered newest to oldest.

list_all_versions async

list_all_versions(bm_id: UUID, page_limit: int | None = 100) -> list[Version]

Return all versions of a block model, following paginated responses.

This method will page through the list_block_model_versions endpoint using offset and limit until all entries are retrieved. The page_limit is clamped to the service maximum (100).

Versions are ordered from newest to oldest.

Parameters:

Name	Type	Description	Default
bm_id	UUID	The ID of the block model.	required
page_limit	int | None	Maximum items to request per page (1..100). Defaults to 100.	100

Returns:

Type	Description
list[Version]	A list of Version dataclasses for the block model, ordered newest to oldest.

create_block_model async

create_block_model(
    name: str,
    grid_definition: BaseGridDefinition,
    description: str | None = None,
    object_path: str | None = None,
    coordinate_reference_system: str | None = None,
    size_unit_id: str | None = None,
    initial_data: Table | None = None,
    units: dict[str, str] | None = None,
) -> tuple[BlockModel, Version]

Create a block model.

Optionally, takes initial data to populate the block model with. Units for the columns within the initial data can be provided in the units dictionary. This requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

If initial_data is provided, this method will wait for the initial data to be successfully uploaded and processed before returning. This then returns both the block model and the version created from the initial data update.

Otherwise, if initial_data is not provided, this waits for the block model creation job to complete before returning. This then returns both the block model and the initial block model version.

Parameters:

Name	Type	Description	Default
name	str	Name of the block model. This may not contain / nor \.	required
grid_definition	BaseGridDefinition	Definition of the block model grid.	required
description	str | None	Description of the block model.	None
object_path	str | None	Path of the folder in Geoscience Object Service to create the reference object in.	None
coordinate_reference_system	str | None	Coordinate reference system used in the block model.	None
size_unit_id	str | None	Unit ID denoting the length unit used for the block model's blocks.	None
initial_data	Table | None	The initial data to populate the block model with.	None
units	dict[str, str] | None	A dictionary mapping column names within initial_data to units.	None

Returns:

Type	Description
tuple[BlockModel, Version]	A tuple containing the created block model and the version of the block model.

add_new_subblocked_columns async

add_new_subblocked_columns(bm_id: UUID, data: Table, units: dict[str, str] | None = None)

Add new columns to an existing sub-blocked block model. This will not change the sub-blocking structure, thus the provided data must match existing sub-blocks in the model.

Units for the columns can be provided in the units dictionary.

This method requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
bm_id	UUID	The ID of the block model to add columns to.	required
data	Table	The data containing the new columns to add.	required
units	dict[str, str] | None	A dictionary mapping column names within data to units.	None

Returns:

Type	Description
	The new version of the block model with the added columns.

Raises:

Type	Description
CacheNotConfiguredException	If the cache is not configured.

add_new_columns async

add_new_columns(bm_id: UUID, data: Table, units: dict[str, str] | None = None)

Add new columns to an existing regular block model.

Units for the columns can be provided in the units dictionary.

This method requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
bm_id	UUID	The ID of the block model to add columns to.	required
data	Table	The data containing the new columns to add.	required
units	dict[str, str] | None	A dictionary mapping column names within data to units.	None

Returns:

Type	Description
	The new version of the block model with the added columns.

Raises:

Type	Description
CacheNotConfiguredException	If the cache is not configured.

update_block_model_columns async

update_block_model_columns(
    bm_id: UUID,
    data: Table,
    new_columns: list[str],
    update_columns: set[str] | None = None,
    delete_columns: set[str] | None = None,
    units: dict[str, str] | None = None,
) -> Version

Add, update, or delete regular block model columns.

Units for the columns can be provided in the units dictionary.

This method requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
bm_id	UUID	The ID of the block model to add columns to.	required
data	Table	The data containing the new columns to add.	required
new_columns	list[str]	A list of new column names to add to the block model.	required
update_columns	set[str] | None	A set of column names to update in the block model.	None
delete_columns	set[str] | None	A set of column names to delete from the block model.	None
units	dict[str, str] | None	A dictionary mapping column names within data to units.	None

Returns:

Type	Description
Version	The new version of the block model with the added columns.

Raises:

Type	Description
CacheNotConfiguredException	If the cache is not configured.

update_subblocked_columns async

update_subblocked_columns(
    bm_id: UUID,
    data: Table,
    new_columns: list[str],
    update_columns: set[str] | None = None,
    delete_columns: set[str] | None = None,
    units: dict[str, str] | None = None,
    geometry_change: bool = False,
) -> Version

Add, update, or delete sub-blocked block model columns.

Whether the sub-blocking structure changes can be specified with the geometry_change parameter.

If True, the geometry of the sub-blocked model changes, but all existing sub-blocks columns must either be updated or deleted. If False, the geometry of the sub-blocked model does not change, but the provided data must match existing sub-blocks in the model.

Units for the columns can be provided in the units dictionary.

This method requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
bm_id	UUID	The ID of the block model to add columns to.	required
data	Table	The data containing the new columns to add.	required
new_columns	list[str]	A list of new column names to add to the block model.	required
update_columns	set[str] | None	A set of column names to update in the block model.	None
delete_columns	set[str] | None	A set of column names to delete from the block model.	None
units	dict[str, str] | None	A dictionary mapping column names within data to units.	None
geometry_change	bool	Whether the geometry of the sub-blocked model changes.	False

update_column_metadata async

update_column_metadata(bm_id: UUID, column_updates: dict[str, str | None], comment: str | None = None) -> Version

Update metadata (e.g., units) for existing block model columns.

This method updates column properties without requiring data upload or cache configuration.

Parameters:

Name	Type	Description	Default
bm_id	UUID	The ID of the block model to update.	required
column_updates	dict[str, str | None]	A dictionary mapping column titles to their new unit IDs. Set the unit ID to None to remove the unit. Example: {"Cu": "%[mass]", "Au": None}	required
comment	str | None	An optional comment describing the metadata changes. This is max 250 characters.	None

Returns:

Type	Description
Version	The new version of the block model with updated metadata.

rename_block_model_columns async

rename_block_model_columns(bm_id: UUID, column_renames: dict[str, str], comment: str | None = None) -> Version

Rename existing block model columns.

This method renames columns without requiring data upload or cache configuration.

Parameters:

Name	Type	Description	Default
bm_id	UUID	The ID of the block model to update.	required
column_renames	dict[str, str]	A dictionary mapping current column titles to their new titles. Example: {"Cu": "Copper", "Au": "Gold"}	required
comment	str | None	An optional comment describing the rename operation. This is max 250 characters.	None

Returns:

Type	Description
Version	The new version of the block model with renamed columns.

delete_block_model_columns async

delete_block_model_columns(bm_id: UUID, column_titles: list[str], comment: str | None = None) -> Version

Delete existing columns from a block model.

This method deletes columns without requiring data upload or cache configuration.

Parameters:

Name	Type	Description	Default
bm_id	UUID	The ID of the block model to update.	required
column_titles	list[str]	The titles of the columns to delete.	required
comment	str | None	An optional comment describing the rename operation. This is max 250 characters.	None

Returns:

Type	Description
Version	The new version of the block model with renamed columns.

query_block_model_as_table async

query_block_model_as_table(
    bm_id: UUID,
    columns: list[str | UUID],
    bbox: BBox | BBoxXYZ | None = None,
    version_uuid: UUID | None = None,
    geometry_columns: GeometryColumns = GeometryColumns.coordinates,
    column_headers: ColumnHeaderType = ColumnHeaderType.id,
    exclude_null_rows: bool = True,
) -> Table

Query a block model and return the result as a PyArrow Table.

This requires the pyarrow package to be installed, and the 'cache' parameter to be set in the constructor.

Parameters:

Name	Type	Description	Default
bm_id	UUID	The ID of the block model to query.	required
columns	list[str | UUID]	The columns to query, can either be the title or the ID of the column.	required
bbox	BBox | BBoxXYZ | None	The bounding box to query, if None (the default) the entire block model is queried.	None
version_uuid	UUID | None	The version UUID to query, if None (the default) the latest version is queried.	None
geometry_columns	GeometryColumns	Whether rows in the returned table should include coordinates, or block indices of the block, that the row belongs to.	coordinates
column_headers	ColumnHeaderType	Whether the names of the columns in the returned column should be the title or the ID of the block model column.	id
exclude_null_rows	bool	Whether to exclude rows where all values are null within the queried columns.	True

Returns:

Type	Description
Table	The result as a PyArrow Table.

Raises:

Type	Description
JobFailedException	If the job failed.