BlockModelAPIClient - Evo Python SDK

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.

get_block_model `async`

get_block_model(bm_id: UUID) -> BlockModel

Get a block model by ID.

Parameters:

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

Returns:

Type	Description
`BlockModel`	The BlockModel metadata.

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.

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

evo.blockmodels.client.BlockModelAPIClient

__init__

from_context classmethod

get_service_health async

list_block_models async

get_block_model async

list_all_block_models async

list_versions async

list_all_versions async

create_block_model async

add_new_subblocked_columns async

add_new_columns async

update_block_model_columns async

update_subblocked_columns async

update_column_metadata async

rename_block_model_columns async

delete_block_model_columns async

query_block_model_as_table async

init

from_context `classmethod`

get_service_health `async`

list_block_models `async`

get_block_model `async`

list_all_block_models `async`

list_versions `async`

list_all_versions `async`

create_block_model `async`

add_new_subblocked_columns `async`

add_new_columns `async`

update_block_model_columns `async`

update_subblocked_columns `async`

update_column_metadata `async`

rename_block_model_columns `async`

delete_block_model_columns `async`

query_block_model_as_table `async`