API connection wrappers

API classes are used to implement connections to external data sources, such that the data can be obtained using a unified set of methods.

The api_core module contains the APIClass base class, which describes all

class madas.apis.api_core.APIClass(logger=None)

Base class for APIs to different data sources.

get_calculation(*args, **kwargs) → Material

Get a single material from the external data source.

Expected input:

ids: Any

Any piece of data that allows the external resource to identify which data shall be returned.

Expected to return:

material: madas.Material

Material data in a Material object.

Raises:

NotImplementedError: This function is not implemented here.

Get a list of materials from the external data source.

Expected input:

search_query: Any

Any piece of data that allows the external resource to identify which data shall be returned.

skip_entries: list[str] | None

List of ids of entries that should not be retrieved.

Expected to return:

material: List[madas.Material]

List of Material objects, containing the data from external source.

Raises:

NotImplementedError: This function is not implemented here.

get_property(**kwargs) → Any

Get a property from the external source.

Expected input:

kwargs: Any

Any piece of data that allows the external resource to identify which property for which data shall be returned.

Expected to return:

property: Any

A single property, e.g. a string or float, that can be stored to the database.

Raises:

NotImplementedError: This function is not implemented here.

hash_query(*args, **kwargs) → str

Hash a query that is passed to the API. This is used to avoid repeatedly querying the same data.

set_logger(logger: Logger) → None

Set logger of the API. The log is used to improve analysis of errors during collection of materials and increase robustness due to failures of external resources.

Arguments:

logger: logging.Logger or None

Logger object. If logger = None, errors will be written to STDERR.

Returns:

None

exception madas.apis.api_core.APIError(message: str)

A generic exception to specify errors that are raised in an APIClass.

Usage:

message = “Something went wrong!”

raise APIError(message)

exception madas.apis.api_core.DatabaseEntryDoesNotExistError(message)

A generic exception to be raised if a specific entry does not exist in an external database.

Usage:

<code that can not retieve data>

raise DatabaseEntryDoesNotExistError(“Can not retrieve entry!”)

madas.apis.api_core.api_call(call, retries: int = 3, report_function: ~typing.Callable = <built-in function print>, report_function_parameters: dict = {'file': <_io.TextIOWrapper name='<stderr>' mode='w' encoding='utf-8'>}) → Callable

Decorator function to realize 10 tries for an API call before raising an exception. For each failed function call, the decorator will pass the exception name and the number of trials to report_function. If the number of trials is exceeded, the decorator will pass the name of the failing function, the arguments and keyword arguments to report_function.

Arguments:

call: Callable

Function that tries to make an API call to an external database.

Keyword arguments:

retries: int

Number of retries before passing on the exceptions

Default: 3

report_function: Callable

Function to report error.

Default: print

report_function_parameters: dict

Keyword arguments passed to report function.

default: {"file" : sys.stderr}

Raises:

APIError: could not retrieve data

Built-in APIs