External - IBM¶

Environmental Intelligence: Geospatial APIs SDK (ibmpairs): A Python module to wrap the core functionality of the Geospatial APIs component.

SPDX-License-Identifier: BSD-3-Clause

class external.ibm.IBMCOSBucket(api_key: str = None, resource_instance_id: str = None, ibm_auth_endpoint: str = None, endpoint: str = None, bucket: str = None, access_key_id: str = None, secret_access_key: str = None, ibm_cos_service_credentials: IBMCOSServiceCredentials = None, ibm_cos_file: IBMCOSFile = None)¶

An object to represent an IBM Cloud Object Storage (COS) bucket.

Parameters:

api_key (str) – API Key.
resource_instance_id (str) – Resource Instance ID.
ibm_auth_endpoint (str) – IBM Authentication Endpoint.
endpoint (str) – Endpoint.
bucket (str) – Bucket name.
access_key_id (str) – Access Key ID.
secret_access_key (str) – Secret Access Key.
ibm_cos_service_credentials (ibmpairs.external.ibm.IBMCOSServiceCredentials) – An IBMCOSServiceCredentials instance.
ibm_cos_file (ibmpairs.external.ibm.IBMCOSFile) – An IBMCOSFile instance.

Raises:

Exception – If a client could not be found or created, if a resource could not be found or created, if ibm_cos_service_credentials provided but not valid, if ibm_cos_file provided but not valid.

delete(key: str, bucket: str = None)¶

Deletes a (data) object from the IBM COS bucket

Parameters:

key (str) – Name of (data) object to be deleted
bucket (str) – (Optional) name of the bucket.

download(key: str, download_path='download', bucket: str = None)¶

Downloads the key in bucket to local. Will raise an exception of file_name if the file does not exist.

Parameters:

file_name (str) – Name of (data) file to download.
key (str) – (Optional) name of the file in the bucket.
bucket (str) – (Optional) name of the bucket.

Raises:

Exception – If upload fails with an IBMClientError, if upload operation fails.

from_dict()¶

Create an IBMCOSBucket object from a dictionary.

Parameters:: cos_bucket_dict (Any) – A dictionary that contains the keys of an IBMCOSBucket.
Return type:: ibmpairs.external.ibm.IBMCOSBucket
Raises:: Exception – If not a dictionary.

from_json()¶

Create an IBMCOSBucket object from json (dictonary or str).

Parameters:: cos_client_json (Any) – A json dictionary that contains the keys of an IBMCOSBucket or a string representation of a json dictionary.
Return type:: ibmpairs.external.ibm.IBMCOSBucket
Raises:: Exception – If not a dictionary or a string.

get(key: str, bucket: str = None)¶

Gets an object from a bucket.

Parameters:

key (str) – Name of object in the bucket.
bucket (str) – (Optional) name of the bucket.

Raises:

Exception – If operation fails.

get_presigned_url(key: str, bucket: str = None, expiration_time: int = 86400)¶

Generates a presigned URL for the object key.

Parameters:

key (str) – Name of object in the bucket.
bucket (str) – (Optional) name of the bucket.
expiration_time (int) – Expiration time of the URL (in seconds).

set_client(access_key_id: str = None, secret_access_key: str = None, resource_instance_id: str = None, ibm_auth_endpoint: str = None, endpoint: str = None, client=None)¶

Populates the self._cos_client attribute. If a client is provided, the method uses this, if not, a new IBMCOSClient is created.

Parameters:

access_key_id (str) – Access Key ID.
secret_access_key (str) – Secret Access Key.
resource_instance_id (str) – Resource Instance ID.
ibm_auth_endpoint (str) – IBM Authentication Endpoint.
endpoint (str) – Endpoint.
client (ibmpairs.external.ibm.IBMCOSClient) – An existing IBMCOSClient.

Raises:

Exception – If ibm_boto3.client could not be created.

set_resource(api_key: str = None, resource_instance_id: str = None, ibm_auth_endpoint: str = None, endpoint: str = None, resource=None)¶

Populates the self._cos_resource attribute. If a resource is provided, the method uses this, if not, a new IBMCOSResource is created.

Parameters:

api_key (str) – API Key.
resource_instance_id (str) – Resource Instance ID.
ibm_auth_endpoint (str) – IBM Authentication Endpoint.
endpoint (str) – Endpoint.
resource (ibmpairs.external.ibm.IBMCOSResource) – An existing IBMCOSResource.

Raises:

Exception – If ibm_boto3.resource could not be created.

to_dict()¶

Create a dictionary from the objects structure.

Return type:: dict

to_json()¶

Create a string representation of a json dictionary from the objects structure.

Return type:: string

upload(file_name: str, key: str = None, bucket: str = None)¶

Stores the local file file_name in bucket as key. Will raise an exception of file_name if the file does not exist.

Parameters:

file_name (str) – Name of (data) file to ingest.
key (str) – (Optional) name of file in bucket. file_name without parent directories will be used if not provided.
bucket (str) – (Optional) name of the bucket.

Raises:

Exception – If upload fails with an IBMClientError, if upload operation fails.

class external.ibm.IBMCOSClient(api_key: str = None, access_key_id: str = None, secret_access_key: str = None, resource_instance_id: str = None, ibm_auth_endpoint: str = None, endpoint: str = None)¶

An object to wrap the creation of an ibm_boto3.client.

Parameters:

api_key (str) – API Key.
access_key_id (str) – Access Key ID.
secret_access_key (str) – Secret Access Key.
resource_instance_id (str) – Resource Instance ID.
ibm_auth_endpoint (str) – IBM Authentication Endpoint.
endpoint (str) – Endpoint.

from_dict()¶

Create an IBMCOSClient object from a dictionary.

Parameters:: cos_client_dict (Any) – A dictionary that contains the keys of an IBMCOSClient.
Return type:: ibmpairs.external.ibm.IBMCOSClient
Raises:: Exception – If not a dictionary.

from_json()¶

Create an IBMCOSClient object from json (dictonary or str).

Parameters:: cos_client_json (Any) – A json dictionary that contains the keys of an IBMCOSClient or a string representation of a json dictionary.
Return type:: ibmpairs.external.ibm.IBMCOSClient
Raises:: Exception – If not a dictionary or a string.

set_client(api_key=None, access_key_id=None, secret_access_key=None, resource_instance_id=None, ibm_auth_endpoint=None, endpoint=None)¶

Creates an ibm_boto3.client from attributes in the object.

Parameters:

api_key (str) – API Key.
access_key_id (str) – Access Key ID.
secret_access_key (str) – Secret Access Key.
resource_instance_id (str) – Resource Instance ID.
ibm_auth_endpoint (str) – IBM Authentication Endpoint.
endpoint (str) – Endpoint.

Raises:

Exception – if ibm_boto3.client could not be created.

to_dict()¶

Create a dictionary from the objects structure.

Return type:: dict

to_json()¶

Create a string representation of a json dictionary from the objects structure.

Return type:: string

class external.ibm.IBMCOSFile(iam_service_id: str = None, ibm_api_key_id: str = None, endpoint: str = None, ibm_auth_endpoint: str = None, bucket: str = None, file: str = None)¶

An object to represent IBM Cloud Object Storage (COS) File entry returned by Watson Studio.

Parameters:

iam_service_id (str) – IAM Service ID.
ibm_api_key_id (str) – IBM API Key ID.
endpoint (str) – Endpoint.
ibm_auth_endpoint (str) – IBM Authentication Endpoint.
bucket (str) – Bucket name.
file (str) – File.

from_dict()¶

Create an IBMCOSFile object from a dictionary.

Parameters:: cos_file_dict (Any) – A dictionary that contains the keys of an IBMCOSFile.
Return type:: ibmpairs.external.ibm.IBMCOSFile
Raises:: Exception – If not a dictionary.

from_json()¶

Create an IBMCOSFile object from json (dictonary or str).

Parameters:: cos_file_json (Any) – A json dictionary that contains the keys of an IBMCOSFile or a string representation of a json dictionary.
Return type:: ibmpairs.external.ibm.IBMCOSFile
Raises:: Exception – If not a dictionary or a string.

to_dict()¶

Create a dictionary from the objects structure.

Return type:: dict

to_json()¶

Create a string representation of a json dictionary from the objects structure.

Return type:: string

class external.ibm.IBMCOSHMACKeys(access_key_id: str = None, secret_access_key: str = None)¶

An object to represent IBM Cloud Object Storage (COS) HMAC Keys.

Parameters:

access_key_id (str) – Access key ID
secret_access_key (str) – Secret access key

from_dict()¶

Create an IBMCOSHMACKeys object from a dictionary.

Parameters:: cos_hmac_keys_dict (Any) – A dictionary that contains the keys of an IBMCOSHMACKeys.
Return type:: ibmpairs.external.ibm.IBMCOSHMACKeys
Raises:: Exception – If not a dictionary.

from_json()¶

Create an IBMCOSHMACKeys object from json (dictonary or str).

Parameters:: cos_hmac_keys_json (Any) – A json dictionary that contains the keys of an IBMCOSHMACKeys or a string representation of a json dictionary.
Return type:: ibmpairs.external.ibm.IBMCOSHMACKeys
Raises:: Exception – If not a dictionary or a string.

to_dict()¶

Create a dictionary from the objects structure.

Return type:: dict

to_json()¶

Create a string representation of a json dictionary from the objects structure.

Return type:: string

class external.ibm.IBMCOSResource(api_key: str = None, resource_instance_id: str = None, ibm_auth_endpoint: str = None, endpoint: str = None)¶

An object to wrap the creation of an ibm_boto3.resource.

Parameters:

api_key (str) – API Key.
resource_instance_id (str) – Resource Instance ID.
ibm_auth_endpoint (str) – IBM Authentication Endpoint.
endpoint (str) – Endpoint.

from_dict()¶

Create an IBMCOSResource object from a dictionary.

Parameters:: ibm_cos_resource_dict (Any) – A dictionary that contains the keys of an IBMCOSResource.
Return type:: ibmpairs.external.ibm.IBMCOSResource
Raises:: Exception – If not a dictionary.

from_json()¶

Create an IBMCOSResource object from json (dictonary or str).

Parameters:: cos_resource_json (Any) – A json dictionary that contains the keys of an IBMCOSResource or a string representation of a json dictionary.
Return type:: ibmpairs.external.ibm.IBMCOSResource
Raises:: Exception – If not a dictionary or a string.

set_resource(api_key: str = None, resource_instance_id: str = None, ibm_auth_endpoint: str = None, endpoint: str = None)¶

Creates an ibm_boto3.resource from attributes in the object.

Parameters:

api_key (str) – API Key.
resource_instance_id (str) – Resource Instance ID.
ibm_auth_endpoint (str) – IBM Authentication Endpoint.
endpoint (str) – Endpoint.

Raises:

Exception – if ibm_boto3.resource could not be created.

to_dict()¶

Create a dictionary from the objects structure.

Return type:: dict

to_json()¶

Create a string representation of a json dictionary from the objects structure.

Return type:: string

class external.ibm.IBMCOSServiceCredentials(api_key: str = None, cos_hmac_keys=None, endpoints: str = None, iam_api_key_description: str = None, iam_api_key_name: str = None, iam_role_crn: str = None, iam_service_id_crn: str = None, resource_instance_id: str = None)¶

An object to represent IBM Cloud Object Storage (COS) Service Credentials.

Parameters:

api_key (str) – API Key
cos_hmac_keys (ibmpairs.external.ibm.IBMCOSHMACKeys) – IBM COS HMAC Keys
endpoints (str) – IBM Cloud Enpoints URL
iam_api_key_description (str) – IAM API Key Description
iam_api_key_name (str) – IAM API Key Name
iam_role_crn (str) – IAM Role CRN
iam_service_id_crn (str) – IAM Service ID CRN
resource_instance_id (str) – Resource Instance ID

Raises:

Exception – If IBMCOSHMACKeys type is unknown.

from_dict()¶

Create an IBMCOSServiceCredentials object from a dictionary.

Parameters:: cos_service_credentials_dict (Any) – A dictionary that contains the keys of an IBMCOSServiceCredentials.
Return type:: ibmpairs.external.ibm.IBMCOSServiceCredentials
Raises:: Exception – If not a dictionary.

from_json()¶

Create an IBMCOSServiceCredentials object from json (dictonary or str).

Parameters:: cos_service_credentials_json (Any) – A json dictionary that contains the keys of an IBMCOSServiceCredentials or a string representation of a json dictionary.
Return type:: ibmpairs.external.ibm.IBMCOSServiceCredentials
Raises:: Exception – If not a dictionary or a string.

to_dict()¶

Create a dictionary from the objects structure.

Return type:: dict

to_json()¶: Create a string representation of a json dictionary from the objects structure. :rtype: string

external.ibm.get_cos_auth_endpoint()¶

A helper function to get IBM COS Authentication Endpoint.

Returns:: The current IBM COS Authentication Endpoint.
Return type:: str
Raises:: Exception – If endpoint not found.

external.ibm.get_cos_endpoint_by_region(region: str, interface: str = 'public')¶

A helper function to get an IBM COS bucket endpoint by region.

Parameters:

region (str) – Region signifier (e.g. ‘us-south’).
interface (str) – A choice of endpoint type- ‘public’ or ‘private’ or ‘direct’.

Returns:

The current IBM COS bucket endpoint.

Return type:

str or None

Raises:

Exception – If response is not 200.

external.ibm.ibm_cos_bucket_from_dict(ibm_cos_bucket_dictionary: dict)¶

The function converts a dictionary of IBMCOSBucket to a IBMCOSBucket object.

Parameters:: ibm_cos_bucket_dict (dict) – A dictionary that contains the keys of a IBMCOSBucket.
Return type:: ibmpairs.external.ibm.IBMCOSBucket
Raises:: Exception – if not a dict.

external.ibm.ibm_cos_bucket_from_json(ibm_cos_bucket_json: Any)¶

The function converts a dictionary or json string of IBMCOSBucket to a IBMCOSBucket object.

Parameters:: ibm_cos_bucket_json (Any) – A dictionary or json string that contains the keys of a IBMCOSBucket.
Return type:: ibmpairs.external.ibm.IBMCOSBucket
Raises:: Exception – if not a dict or a str.

external.ibm.ibm_cos_bucket_to_dict(ibm_cos_bucket: IBMCOSBucket)¶

The function converts an object of IBMCOSBucket to a dict.

Parameters:: ibm_cos_bucket (ibmpairs.external.ibm.IBMCOSBucket) – A IBMCOSBucket object.
Return type:: dict

external.ibm.ibm_cos_bucket_to_json(ibm_cos_bucket: IBMCOSBucket)¶

The function converts an object of IBMCOSBucket to a json string.

Parameters:: ibm_cos_bucket (ibmpairs.external.ibm.IBMCOSBucket) – A IBMCOSBucket object.
Return type:: str

external.ibm.ibm_cos_client_from_dict(ibm_cos_client_dictionary: dict)¶

The function converts a dictionary of IBMCOSClient to a IBMCOSClient object.

Parameters:: ibm_cos_client_dict (dict) – A dictionary that contains the keys of a IBMCOSClient.
Return type:: ibmpairs.external.ibm.IBMCOSClient
Raises:: Exception – if not a dict.

external.ibm.ibm_cos_client_from_json(ibm_cos_client_json: Any)¶

The function converts a dictionary or json string of IBMCOSClient to a IBMCOSClient object.

Parameters:: ibm_cos_client_json (Any) – A dictionary or json string that contains the keys of a IBMCOSClient.
Return type:: ibmpairs.external.ibm.IBMCOSClient
Raises:: Exception – if not a dict or a str.

external.ibm.ibm_cos_client_to_dict(ibm_cos_client: IBMCOSClient)¶

The function converts an object of IBMCOSClient to a dict.

Parameters:: ibm_cos_client (ibmpairs.external.ibm.IBMCOSClient) – A IBMCOSClient object.
Return type:: dict

external.ibm.ibm_cos_client_to_json(ibm_cos_client: IBMCOSClient)¶

The function converts an object of IBMCOSClient to a json string.

Parameters:: ibm_cos_client (ibmpairs.external.ibm.IBMCOSClient) – A IBMCOSClient object.
Return type:: str

external.ibm.ibm_cos_file_from_dict(ibm_cos_file_dictionary: dict)¶

The function converts a dictionary of IBMCOSFile to a IBMCOSFile object.

Parameters:: ibm_cos_file_dict (dict) – A dictionary that contains the keys of a IBMCOSFile.
Return type:: ibmpairs.external.ibm.IBMCOSFile
Raises:: Exception – if not a dict.

external.ibm.ibm_cos_file_from_json(ibm_cos_file_json: Any)¶

The function converts a dictionary or json string of IBMCOSFile to a IBMCOSFile object.

Parameters:: ibm_cos_file_json (Any) – A dictionary or json string that contains the keys of a IBMCOSFile.
Return type:: ibmpairs.external.ibm.IBMCOSFile
Raises:: Exception – if not a dict or a str.

external.ibm.ibm_cos_file_to_dict(ibm_cos_file: IBMCOSFile)¶

The function converts an object of IBMCOSFile to a dict.

Parameters:: ibm_cos_file (ibmpairs.external.ibm.IBMCOSFile) – A IBMCOSFile object.
Return type:: dict

external.ibm.ibm_cos_file_to_json(ibm_cos_file: IBMCOSFile)¶

The function converts an object of IBMCOSFile to a json string.

Parameters:: ibm_cos_file (ibmpairs.external.ibm.IBMCOSFile) – A IBMCOSFile object.
Return type:: str

external.ibm.ibm_cos_hmac_keys_from_dict(ibm_cos_hmac_keys_dictionary: dict)¶

The function converts a dictionary of IBMCOSHMACKeys to a IBMCOSHMACKeys object.

Parameters:: ibm_cos_hmac_keys_dict (dict) – A dictionary that contains the keys of a IBMCOSHMACKeys.
Return type:: ibmpairs.external.ibm.IBMCOSHMACKeys
Raises:: Exception – if not a dict.

external.ibm.ibm_cos_hmac_keys_from_json(ibm_cos_hmac_keys_json: Any)¶

The function converts a dictionary or json string of IBMCOSHMACKeys to a IBMCOSHMACKeys object.

Parameters:: ibm_cos_hmac_keys_json (Any) – A dictionary or json string that contains the keys of a IBMCOSHMACKeys.
Return type:: ibmpairs.external.ibm.IBMCOSHMACKeys
Raises:: Exception – if not a dict or a str.

external.ibm.ibm_cos_hmac_keys_to_dict(ibm_cos_hmac_keys: IBMCOSHMACKeys)¶

The function converts an object of IBMCOSHMACKeys to a dict.

Parameters:: ibm_cos_hmac_keys (ibmpairs.external.ibm.IBMCOSHMACKeys) – A IBMCOSHMACKeys object.
Return type:: dict

external.ibm.ibm_cos_hmac_keys_to_json(ibm_cos_hmac_keys: IBMCOSHMACKeys)¶

The function converts an object of IBMCOSHMACKeys to a json string.

Parameters:: ibm_cos_hmac_keys (ibmpairs.external.ibm.IBMCOSHMACKeys) – A IBMCOSHMACKeys object.
Return type:: str

external.ibm.ibm_cos_resource_from_dict(ibm_cos_resource_dictionary: dict)¶

The function converts a dictionary of IBMCOSResource to a IBMCOSResource object.

Parameters:: ibm_cos_resource_dict (dict) – A dictionary that contains the keys of a IBMCOSResource.
Return type:: ibmpairs.external.ibm.IBMCOSResource
Raises:: Exception – if not a dict.

external.ibm.ibm_cos_resource_from_json(ibm_cos_resource_json: Any)¶

The function converts a dictionary or json string of IBMCOSResource to a IBMCOSResource object.

Parameters:: ibm_cos_resource_json (Any) – A dictionary or json string that contains the keys of a IBMCOSResource.
Return type:: ibmpairs.external.ibm.IBMCOSResource
Raises:: Exception – if not a dict or a str.

external.ibm.ibm_cos_resource_to_dict(ibm_cos_resource: IBMCOSResource)¶

The function converts an object of IBMCOSResource to a dict.

Parameters:: ibm_cos_resource (ibmpairs.external.ibm.IBMCOSResource) – A IBMCOSResource object.
Return type:: dict

external.ibm.ibm_cos_resource_to_json(ibm_cos_resource: IBMCOSResource)¶

The function converts an object of IBMCOSResource to a json string.

Parameters:: ibm_cos_resource (ibmpairs.external.ibm.IBMCOSResource) – A IBMCOSResource object.
Return type:: str

external.ibm.ibm_cos_service_credentials_from_dict(ibm_cos_service_credentials_dictionary: dict)¶

The function converts a dictionary of IBMCOSServiceCredentials to a IBMCOSServiceCredentials object.

Parameters:: ibm_cos_service_credentials_dict (dict) – A dictionary that contains the keys of a IBMCOSServiceCredentials.
Return type:: ibmpairs.external.ibm.IBMCOSServiceCredentials
Raises:: Exception – if not a dict.

external.ibm.ibm_cos_service_credentials_from_json(ibm_cos_service_credentials_json: Any)¶

The function converts a dictionary or json string of IBMCOSServiceCredentials to a IBMCOSServiceCredentials object.

Parameters:: ibm_cos_service_credentials_json (Any) – A dictionary or json string that contains the keys of a IBMCOSServiceCredentials.
Return type:: ibmpairs.external.ibm.IBMCOSServiceCredentials
Raises:: Exception – if not a dict or a str.

external.ibm.ibm_cos_service_credentials_to_dict(ibm_cos_service_credentials: IBMCOSServiceCredentials)¶

The function converts an object of IBMCOSServiceCredentials to a dict.

Parameters:: ibm_cos_service_credentials (ibmpairs.external.ibm.IBMCOSServiceCredentials) – A IBMCOSServiceCredentials object.
Return type:: dict

external.ibm.ibm_cos_service_credentials_to_json(ibm_cos_service_credentials: IBMCOSServiceCredentials)¶

The function converts an object of IBMCOSServiceCredentials to a json string.

Parameters:: ibm_cos_service_credentials (ibmpairs.external.ibm.IBMCOSServiceCredentials) – A IBMCOSServiceCredentials object.
Return type:: str