hdmf.utils module

class hdmf.utils.AllowPositional(value)

Bases: Enum

An enumeration.

ALLOWED = 1
WARNING = 2
ERROR = 3
hdmf.utils.docval_macro(macro)

Class decorator to add the class to a list of types associated with the key macro in the __macros dict

hdmf.utils.get_docval_macro(key=None)

Return a deepcopy of the docval macros, i.e., strings that represent a customizable list of types for use in docval.

Parameters:

key – Name of the macro. If key=None, then a dictionary of all macros is returned. Otherwise, a tuple of the types associated with the key is returned.

hdmf.utils.get_docval(func, *args)

Get a copy of docval arguments for a function. If args are supplied, return only docval arguments with value for ‘name’ key equal to the args

hdmf.utils.fmt_docval_args(func, kwargs)

Separate positional and keyword arguments

Useful for methods that wrap other methods

hdmf.utils.call_docval_func(func, kwargs)

Call the function with only the keyword arguments that are accepted by the function’s docval.

Extra keyword arguments are not passed to the function unless the function’s docval has allow_extra=True.

hdmf.utils.docval(*validator, **options)

A decorator for documenting and enforcing type for instance method arguments.

This decorator takes a list of dictionaries that specify the method parameters. These dictionaries are used for enforcing type and building a Sphinx docstring.

The first arguments are dictionaries that specify the positional arguments and keyword arguments of the decorated function. These dictionaries must contain the following keys: 'name', 'type', and 'doc'. This will define a positional argument. To define a keyword argument, specify a default value using the key 'default'. To validate the dimensions of an input array add the optional 'shape' parameter. To allow a None value for an argument, either the default value must be None or a different default value must be provided and 'allow_none': True must be passed.

The decorated method must take self and **kwargs as arguments.

When using this decorator, the functions getargs and popargs can be used for easily extracting arguments from kwargs.

The following code example demonstrates the use of this decorator:

@docval({'name': 'arg1':,   'type': str,           'doc': 'this is the first positional argument'},
        {'name': 'arg2':,   'type': int,           'doc': 'this is the second positional argument'},
        {'name': 'kwarg1':, 'type': (list, tuple), 'doc': 'this is a keyword argument', 'default': list()},
        returns='foo object', rtype='Foo'))
def foo(self, **kwargs):
    arg1, arg2, kwarg1 = getargs('arg1', 'arg2', 'kwarg1', **kwargs)
    ...
Parameters:

  • enforce_type – Enforce types of input parameters (Default=True)

  • returns – String describing the return values

  • rtype – String describing the data type of the return values

  • is_method – True if this is decorating an instance or class method, False otherwise (Default=True)

  • enforce_shape – Enforce the dimensions of input arrays (Default=True)

  • validator – dict objects specifying the method parameters

  • allow_extra – Allow extra arguments (Default=False)

  • allow_positional – Allow positional arguments (Default=True)

  • options – additional options for documenting and validating method parameters

hdmf.utils.getargs(*argnames, argdict)

Convenience function to retrieve arguments from a dictionary in batch.

The last argument should be a dictionary, and the other arguments should be the keys (argument names) for which to retrieve the values.

Raises:

ValueError – if a argument name is not found in the dictionary or there is only one argument passed to this function or the last argument is not a dictionary

Returns:

a single value if there is only one argument, or a list of values corresponding to the given argument names

hdmf.utils.popargs(*argnames, argdict)

Convenience function to retrieve and remove arguments from a dictionary in batch.

The last argument should be a dictionary, and the other arguments should be the keys (argument names) for which to retrieve the values.

Raises:

ValueError – if a argument name is not found in the dictionary or there is only one argument passed to this function or the last argument is not a dictionary

Returns:

a single value if there is only one argument, or a list of values corresponding to the given argument names

hdmf.utils.popargs_to_dict(keys, argdict)

Convenience function to retrieve and remove arguments from a dictionary in batch into a dictionary.

Same as {key: argdict.pop(key) for key in keys} with a custom ValueError

Parameters:

  • keys (Iterable) – Iterable of keys to pull out of argdict

  • argdict – Dictionary to process

Raises:

ValueError – if an argument name is not found in the dictionary

Returns:

a dict of arguments removed

class hdmf.utils.ExtenderMeta(name, bases, namespace, **kwargs)

Bases: ABCMeta

A metaclass that will extend the base class initialization routine by executing additional functions defined in classes that use this metaclass

In general, this class should only be used by core developers.

classmethod pre_init(func)
classmethod post_init(func)

A decorator for defining a routine to run after creation of a type object.

An example use of this method would be to define a classmethod that gathers any defined methods or attributes after the base Python type construction (i.e. after type has been called)

hdmf.utils.get_data_shape(data, strict_no_data_load=False)

Helper function used to determine the shape of the given array.

In order to determine the shape of nested tuples, lists, and sets, this function recursively inspects elements along the dimensions, assuming that the data has a regular, rectangular shape. In the case of out-of-core iterators, this means that the first item along each dimension would potentially be loaded into memory. Set strict_no_data_load=True to enforce that this does not happen, at the cost that we may not be able to determine the shape of the array.

Parameters:

  • data (List, numpy.ndarray, DataChunkIterator, any object that support __len__ or .shape.) – Array for which we should determine the shape.

  • strict_no_data_load – If True and data is an out-of-core iterator, None may be returned. If False (default), the first element of data may be loaded into memory.

Returns:

Tuple of ints indicating the size of known dimensions. Dimensions for which the size is unknown will be set to None.

hdmf.utils.pystr(s)

Convert a string of characters to Python str object

hdmf.utils.to_uint_array(arr)

Convert a numpy array or array-like object to a numpy array of unsigned integers with the same dtype itemsize.

For example, a list of int32 values is converted to a numpy array with dtype uint32. :raises ValueError: if input array contains values that are not unsigned integers or non-negative integers.

class hdmf.utils.LabelledDict(label, key_attr='name', add_callable=None, remove_callable=None)

Bases: dict

A dict wrapper that allows querying by an attribute of the values and running a callable on removed items.

For example, if the key attribute is set as ‘name’ in __init__, then all objects added to the LabelledDict must have a ‘name’ attribute and a particular object in the LabelledDict can be accessed using the syntax [‘object_name’] if the object.name == ‘object_name’. In this way, LabelledDict acts like a set where values can be retrieved using square brackets around the value of the key attribute. An ‘add’ method makes clear the association between the key attribute of the LabelledDict and the values of the LabelledDict.

LabelledDict also supports retrieval of values with the syntax my_dict[‘attr == val’], which returns a set of objects in the LabelledDict which have an attribute ‘attr’ with a string value ‘val’. If no objects match that condition, a KeyError is raised. Note that if ‘attr’ equals the key attribute, then the single matching value is returned, not a set.

LabelledDict does not support changing items that have already been set. A TypeError will be raised when using __setitem__ on keys that already exist in the dict. The setdefault and update methods are not supported. A TypeError will be raised when these are called.

A callable function may be passed to the constructor to be run on an item after adding it to this dict using the __setitem__ and add methods.

A callable function may be passed to the constructor to be run on an item after removing it from this dict using the __delitem__ (the del operator), pop, and popitem methods. It will also be run on each removed item when using the clear method.

Usage:

LabelledDict(label=’my_objects’, key_attr=’name’) my_dict[obj.name] = obj my_dict.add(obj) # simpler syntax

Example

# MyTestClass is a class with attributes ‘prop1’ and ‘prop2’. MyTestClass.__init__ sets those attributes. ld = LabelledDict(label=’all_objects’, key_attr=’prop1’) obj1 = MyTestClass(‘a’, ‘b’) obj2 = MyTestClass(‘d’, ‘b’) ld[obj1.prop1] = obj1 # obj1 is added to the LabelledDict with the key obj1.prop1. Any other key is not allowed. ld.add(obj2) # Simpler ‘add’ syntax enforces the required relationship ld[‘a’] # Returns obj1 ld[‘prop1 == a’] # Also returns obj1 ld[‘prop2 == b’] # Returns set([obj1, obj2]) - the set of all values v in ld where v.prop2 == ‘b’

Parameters:

  • label (str) – the label on this dictionary

  • key_attr (str) – the attribute name to use as the key

  • add_callable (function) – function to call on an element after adding it to this dict using the add or __setitem__ methods

  • remove_callable (function) – function to call on an element after removing it from this dict using the pop, popitem, clear, or __delitem__ methods

property label

Return the label of this LabelledDict

property key_attr

Return the attribute used as the key for values in this LabelledDict

__getitem__(args)

Get a value from the LabelledDict with the given key.

Supports syntax my_dict[‘attr == val’], which returns a set of objects in the LabelledDict which have an attribute ‘attr’ with a string value ‘val’. If no objects match that condition, an empty set is returned. Note that if ‘attr’ equals the key attribute of this LabelledDict, then the single matching value is returned, not a set.

add(value)

Add a value to the dict with the key value.key_attr.

Raises ValueError if value does not have attribute key_attr.

pop(k)

Remove an item that matches the key. If remove_callable was initialized, call that on the returned value.

popitem()

Remove the last added item. If remove_callable was initialized, call that on the returned value.

Note: popitem returns a tuple (key, value) but the remove_callable will be called only on the value.

Note: in Python 3.5 and earlier, dictionaries are not ordered, so popitem removes an arbitrary item.

clear()

Remove all items. If remove_callable was initialized, call that on each returned value.

The order of removal depends on the popitem method.

setdefault(k)

setdefault is not supported. A TypeError will be raised.

update(other)

update is not supported. A TypeError will be raised.

class hdmf.utils.StrDataset(dset, encoding, errors='strict')

Bases: Dataset

Wrapper to decode strings on reading the dataset

Create a new Dataset object by binding to a low-level DatasetID.

__getitem__(args)

Read a slice from the HDF5 dataset.

Takes slices and recarray-style field names (more than one is allowed!) in any order. Obeys basic NumPy rules, including broadcasting.

Also supports:

  • Boolean “mask” array indexing