API Reference

This document contains description of the programming components used in the Workspace Python module.

---

__init__.py

class __init__.Group(group, parent=None)

Contains low-level mechanisms for handling groups in HDF5.

class __init__.HDF5Files

Serves as an interface for the list of open HDF5 files.

class __init__.Variable(group, parent=None)

Each instance of the Variable class is paired with an associated HDF5 root group and exposes convenient interface for it.

Methods

match()

Checks whether parent of group associated with specified variable has been modified.

Returns:

bool

True if there are no changes to parent of specified group, False otherwise.

Examples

Add example variable (named var1) to the HDF5 file with index = -1 on the list of files:

>>> <interface_name>[-1].create.basic("var1")

In variable var1 create dataset named dset1, which contains some numerical data:

>>> var1.data.dset1 = [1,2,3,4]

Create second variable named var2, as a children of var1:

>>> <interface_name>[-1].create.basic("var2",var1)

As for now, if we call match() method on var2, it will return True, as the var1 is up-to-date:

>>> var2.match()

True

If var1 will be modified (i.e. by adding another dataset to it, named dset2):

>>> var1.data.dset2 = [2,4,6,8]

Then var1 variable will not be up-to-date, and match() method called on var2 will return false:

>>> var2.match()

False

remove()

Removes variable from the interactive namespace and removes group paired with this variable from the HDF5 file.

Examples

Add example variable (named var1) to the HDF5 file with index = -1 on the list of files:

>>> <interface_name>[-1].create.basic("var1")

Remove var1, by calling remove() method on it:

>>> var1.remove()

rename(name)

Renames variable in the interactive namespace and HDF5 group associated to it.

Parameters:

name : str

New name of the HDF5 group.

Examples

Add example variable (named var1) to the HDF5 file with index = -1 on the list of files:

>>> <interface_name>[0].create.basic("var1")

Rename var1 to var2, by calling rename() method on it:

>>> var1.rename("var2")

class __init__.Variables

Serves as an interface for the list of created variables.

__init__.fingerprint(obj=None)

Generates 40B SHA1 digest from data of the specified object.

Allowed object types:

• HDF5 group
• IVar class
• None

Parameters:

obj : {None|Ivar class|HDF5 group}

Object available in the interactive namespace.

Returns:

string

40B SHA1 hexadecimal digest.

__init__.get(group, default=True)

By default get name of the variable associated with group, otherwise get variable itself, i.e. its instance.

Parameters:

group : obj

Specified HDF5 group.

default : bool

Indicates whether this method additionally returns instance of the variable associated with group.

Returns:

name : string

Name of the variable associated with specified HDF5 group.

__init__.index(obj)

Returns an index of the specified object(s).

Allowed object types:

• index or range of indexes (int or slice)
• HDF5 file name (string)
• h5py file object

Parameters:

obj : {int|slice|string|h5py file object}

Object available in the interactive namespace.

Returns:

index : int

Index of specified object.

---

api.py

Object:variables: List of all variables available in the interactive namespace.

Instance of __init__.Variables.

Object:hdf5_files: List of all HDF5 files available in the interactive namespace.

Instance of __init__.HDF5Files.

Object:compression: Dictionary that contains dataset compression parameters.

Available parameters:

• chunks (default = True)
• compression (default = lzf)
• shuffle (default = True)

Detailed information on dataset compression can be found in h5py dataset documentation.

api.add(filename, mode='a')

Creates or opens a HDF5 file on the hard drive and adds it to the interactive namespace.

Parameters:

filename : str

Name of the HDF5 file.

mode : str, optional

Mode in which to open file, one of (‘r’, ‘r+’, ‘w’, ‘w-‘, ‘x’, ‘a’).

r	Readonly, file must exist
r+	Read/write, file must exist
w	Create file, truncate if exists
w- or x	Create file, fail if exists
a	Read/write if exists, create otherwise (default)

Notes

Based on h5py.File(). The root group is automatically created when the HDF5 file is created.

Examples

Add a sample file to the interactive namespace:

>>> <interface_name>.add("example.h5")

api.clear()

Closes all open HDF5 files and removes them from the interactive namespace. Files are not physically deleted form the hard drive, but rather deleted from current interactive namespace.

Notes

Based on h5py.File().

Examples

Clears current interactive namespace:

>>> <interface_name>.clear()

api.close(obj=-1)

Closes HDF5 file with selected index and removes it from the interactive namespace. The default index is minus one, which means the last item on the list of files.

Notes

Based on h5py.File().

This method does not guarantee that the file will be correctly saved. To ensure no data corruption, api.flush() should be called before api.close().

Examples

Add a sample file to the interactive namespace:

>>> <interface_name>.add("example.h5")

File “example.h5” is present in interactive namespace with index = -1.

In order to close this file and remove from the interactive namespace we need to call api.close() method on <interface_name>[file_index] file object:

>>> <interface_name>[-1].close()

api.flush(obj=-1)

Forces data in HDF5 file to be copied from the memory buffer and saved on the hard drive. The default index is minus one, which means the last item on the list of files.

Notes

Based on h5py.File().

Examples

Ensure that data from the selected HDF5 file is saved on the hard drive:

>>> <interface_name>[file_index].flush()

Close it:

>>> <interface_name>[file_index].close()

---

ui.py

class ui.HDF5File(index)

Imports functions from api.py and serves as an interface for end user.

Methods

close()

Alias of api.close().

flush()

Alias of api.flush().

class ui.Interface

Imports functions from api.py and serves as an interface for end user.

Object:vars: List of all variables available in the interactive namespace. Object:compression: Dictionary that contains dataset compression parameters.

Methods

add(filename, mode='a')

Alias of api.add().

clear()

Alias of api.clear().

---

variables/__init__.py

Object:list_of_variables: List of classes containing available variable types.

Adding class (which defines variable type) to this list, makes it possible to use this variable type in the Workspace.

Notes

This mechanism allows users to create their own variable types.

This is profitable in cases when additional custom attributes are needed.

---

variables/basic.py

class variables.basic.Basic

Contains definition of Basic variable type. This type provides following attributes:

• parent: parent of group associated with selected variable
• created: datetime of variable creation

Methods

static create(group, parent)

Creates Basic variable.