DB Handle Client

The DB Handle client provides methods to create, update and delete Handles directly via the (SQL) database of the Handle System server.

Note

The current version of the library supports MySQL database.

Important

The DB client does not provide a read-only mode. All operations require authentication.

Instantiation

As described in the PyHandleClient, credentials and information about the database server are required in order to instantiate the DB client.

from pyhandle.handleclient import PyHandleClient
client = PyHandleClient('db', credentials)

The credentials can loaded from a file or passed as a dictionary to the PyHandleClient

credentials = {'db_host':'', 'db_user':'', 'db_pass':'', 'db_name':''}

Credentials can be also loaded from a json file using the PIDClientCredentials class as follows:

cred = PIDClientCredentials.load_from_JSON('my_credentials.json')
client = PyHandleClient('db', cred)

The JSON file should look like this:

{
  "client":"",
  "db_host": "https://handle.server",
  "db_user": "db_user",
  "db_password": "db_password",
  "db_name": "db_name"
}

Then the client’s methods can be used to read, create, modify or delete Handles

value = client.some_methods(...)

Basic Handle interaction

Creating a Handle

Use register_handle() to create a Handle with a custom name

or generate_and_register_handle() to create a Handle with a random UUID-based name.

Deleting a Handle

Use delete_handle().

Retrieving a full Handle record

This can be done by retrieve_handle_record().

Retrieving a single value

Use get_value_from_handle() to retrieve a single Handle record value.

Modifying a Handle record

Use modify_handle_value() to modify any number of values in a specific Handle record. To remove individual values, use delete_handle_value().

Searching for a Handle

Use search_handle() to search for Handles with a specific key and value. For multiple key-value search use search_handle_multiple_keys()

Registering new Handles (HS_ADMIN)

An administrator Handle (HS_ADMIN entry) is automatically added to the created Handle. It contains the name of the admin Handle, the index and the permissions. These values must be passed as parameters to register_handle()

Example

To create the Handle 123/NEW_HANDLE, which has 123/admin as admin Handle, the following parameters need to be provided:

'HS_ADMIN': "{'index': 200, 'handle': '123/admin', 'permissions': '011111110011'}"

Then the method register_handle() is called as follows

register_handle(handle, url, admin_handle='123/admin', admin_handle_index=200, permissions='011111110011')

Note

The sequence of the permissions should be respected and is in form: (create hdl, delete hdl, create derived prefix, delete derived prefix, read val, modify val, del val, add val, moodify admin, del, admin, add admin, list)

Full method documentation

Constructors

DBHandleClient.__init__(credentials, **args)

Initialize the DB client. Instantiate a connection object and connect to the HS database

Parameters:

• db_host – host where the handle server database is located

• db_user – username to log in as

• db_password – password for db_user

• db_name – database name

Handle record methods

DBHandleClient.register_handle(handle, url, overwrite=False, **args)

Register a new Handle with given name. If the handle already exists and overwrite is not set to True, the method will throw an exception.

Parameters:

• handle – The full name of the handle to be registered (prefix and suffix)

• url – The URL of the data entity to be referenced

• overwrite – Optional. If set to True, an existing handle record will be overwritten. Defaults to False.

• args –

  Mandatory key_value parameters for the admin of the Handle being created. Example:

  admin_handle = ‘prefix/suffix’.

  admin_handle_index = 200.

  perm = ‘111111111111’

Raises:

HandleAlreadyExistsException Only if overwrite is not set or set to False.

DBHandleClient.generate_and_register_handle(prefix, location, checksum=None, **extratypes)

Register a new Handle with a unique random name (random UUID).

Parameters:

• prefix – The prefix of the handle to be registered. The method will generate a suffix.

• location – The URL of the data entity to be referenced.

• checksum – Optional. The checksum string.

• extratypes – Optional. Additional key value pairs as dict.

Returns:

The new handle name.

DBHandleClient.delete_handle(handle)

Delete handle and its handle record.

Parameters:

handle – Handle being deleted

Raises:

DBHandleNotFoundException

DBHandleClient.retrieve_handle_record(handle)

Retrieve all Handle record values including HS_ADMIN Extract HS_ADMIN value from the query result and converts it to Hex.

Parameters:

handle – The handle from which the values are retrieved.

Returns:

handle_records: All values of the Handle including HS_ADMIN.

DBHandleClient.get_value_from_handle(handle, key)

Retrieve a single value from a single handle.

Parameters:

• handle – The handle to take the value from.

• key – The key.

Raises:

DBHandleNotFoundException

Raises:

DBHandleKeyNotFoundException

Returns:

A string containing the value.

DBHandleClient.modify_handle_value(handle, ttl=None, add_if_not_exists=True, **kvpairs)

This statement is used to update a single handle value with new values. The value to update is identified by the handle and index. Modify entries (key-value pairs).

Parameters:

• handle – Handle whose record is to be modified

• ttl – Optional. Integer value. If ttl should be set to a non-default value.

• kvpairs – The user can specify several key-value-pairs. These will be the handle value types and values that will be modified. The keys are the names or the handle value types (e.g. “URL”). The values are the new values to store in “data”.

• add_if_not_exists – Optional.

Raises:

DBHandleNotFoundException

DBHandleClient.delete_handle_value(handle, key)

Delete a key-value pair from a handle record. If the key exists more than once, all key-value pairs with this key are deleted.

Parameters:

• handle – Handle from whose record the entry should be deleted.

• key – Key to be deleted. Also accepts a list of keys.

DBHandleClient.search_handle(pattern=None, limit=None, offset=None, **args)

Search for handles containing the specified key with the specified value (one key-value). The number of record can be controlled by limit and offset.

Parameters:

• pattern – Optional. This value can be set to do search depending on the handle name.

• limit – Optional. Limit the number of results returned in a SQL statement.

• offset – Optional. Page number, first row to return. Initial raw is 0.

• args – e.g URL=’www.example.com’

Returns:

A list of all Handles (list of strings) that bear the given key with given value of given prefix or server. The list may be empty and may also contain more than one element.

DBHandleClient.list_all_handles()

Get a list of all of the handles in the database.

Returns:

A list of all handles in the table

DBHandleClient.search_handle_multiple_keys(**args)

Search for handles containing the specified key(s) with the specified value(s).

Parameters:

args – Several search fields and values can be specified as key-value-pairs, e.g. CHECKSUM=123456, URL=www.foo.com

Returns:

A list of all Handles (list of strings) that bear the given key with given value of given prefix or server. The list may be empty and may also contain more than one element.

Helper methods

DBHandleClient.get_list_of_idx(handle)

Create a list of indices already used.

Parameters:

handle – the handle to extract the indexes from.

Returns:

list_idx: List of indices

static DBHandleClient.connection_status(handle_db_connection)

Check whether a connection to DB is open.

Parameters:

handle_db_connection –

Returns:

True if connection is open

static DBHandleClient.create_list_of_queries(query)

Create a list of queries, which will be executed in a specific order.

Parameters:

query – The query to be added to the list.

Returns:

A list of queries

Exceptions

This module contains the exceptions that may occur in libraries interacting with the Handle System (Database).

Author: Sofiane Bendoukha, DKRZ, 2016-2017

exception pyhandle.dbhsexceptions.DBHandleAlreadyExistsException(**args)

To be raised if self.handle already exists.

exception pyhandle.dbhsexceptions.DBHandleKeyNotFoundException(**args)

Raises when handle key not found

exception pyhandle.dbhsexceptions.DBHandleKeyNotSpecifiedException(**args)

Raises when no search items has been provided

exception pyhandle.dbhsexceptions.DBHandleNoCredentialsError(msg=None)

Raises when insufficient credentials are given

exception pyhandle.dbhsexceptions.DBHandleNotFoundException(**args)

Raises when handle not found in database