Reference

h5preserve is a thin wrapper around h5py, providing easier serialisation of native python types.

copyright:

3. 2016 James Tocknell

license:

3-clause BSD

class h5preserve.DatasetContainer(attrs=None, **kwargs)

Representation of an hdf5 dataset for use in h5preserve.

Parameters:

• attrs (Mapping) – mapping containing the attributes of the group
• **kwargs – properties of the group, which get passed to create group

clear() → None. Remove all items from D.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

items() → list of D's (key, value) pairs, as 2-tuples

iteritems() → an iterator over the (key, value) items of D

iterkeys() → an iterator over the keys of D

itervalues() → an iterator over the values of D

keys() → list of D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of D's values

class h5preserve.GroupContainer(attrs=None, **kwargs)

Representation of an hdf5 group for use in h5preserve.

Parameters:

• attrs (Mapping) – mapping containing the attributes of the group
• **kwargs – datasets or subgroups to add to the group

clear() → None. Remove all items from D.

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

items() → list of D's (key, value) pairs, as 2-tuples

iteritems() → an iterator over the (key, value) items of D

iterkeys() → an iterator over the keys of D

itervalues() → an iterator over the values of D

keys() → list of D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of D's values

class h5preserve.H5PreserveFile(h5py_file, registries)

Thin wrapper around h5py.File to automatically use h5preserve when accessing the file contents.

Acts like h5preserve.H5PreserveGroup, but allows access to the associated h5py.File instance via h5py_file.

Parameters:

• h5py_file (a h5py.File) – the hdf5 file to wrap
• registries (RegistryContainer) – the collection of registries that you want to use to read from the hdf5 file

clear() → None. Remove all items from D.

create_group(name)

Creates a new group in the associated hdf5 file

Parameters:name (string, or other identifier accepted by h5py) – name of the new group Returns:The new group wrapped by H5PreserveGroup Return type:H5PreserveGroup

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

h5py_file

h5py.File – the instance of h5py.File which H5PreserveFile wraps

h5py_group

h5py.Group – the instance of h5py.Group which H5PreserveGroup wraps

items() → list of D's (key, value) pairs, as 2-tuples

iteritems() → an iterator over the (key, value) items of D

iterkeys() → an iterator over the keys of D

itervalues() → an iterator over the values of D

keys() → list of D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

require_group(name)

Returns the group associated with name, creating it if necessary.

Parameters:name (string, or other identifier accepted by h5py) – name of the desired group Returns:The group wrapped by H5PreserveGroup Return type:H5PreserveGroup

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of D's values

class h5preserve.H5PreserveGroup(h5py_group, registries)

Thin wrapper around h5py.Group to automatically use h5preserve when accessing the group contents.

Parameters:

• h5py_group (h5py.Group) –
• registries (RegistryContainer) – the collection of registries that you want to use to read from the hdf5 file

clear() → None. Remove all items from D.

create_group(name)

Creates a new group in the associated hdf5 file

Parameters:name (string, or other identifier accepted by h5py) – name of the new group Returns:The new group wrapped by H5PreserveGroup Return type:H5PreserveGroup

get(k[, d]) → D[k] if k in D, else d. d defaults to None.

h5py_group

h5py.Group – the instance of h5py.Group which H5PreserveGroup wraps

items() → list of D's (key, value) pairs, as 2-tuples

iteritems() → an iterator over the (key, value) items of D

iterkeys() → an iterator over the keys of D

itervalues() → an iterator over the values of D

keys() → list of D's keys

pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

require_group(name)

Returns the group associated with name, creating it if necessary.

Parameters:name (string, or other identifier accepted by h5py) – name of the desired group Returns:The group wrapped by H5PreserveGroup Return type:H5PreserveGroup

setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

values() → list of D's values

class h5preserve.HardLink(obj)

Represent a h5py hard link to be created via h5preserve.

Parameters:obj (string, h5py.Group or h5py.Dataset) – the h5py object that the hard link points to, can either be an h5py object, or a string with the absolute path of the object

h5py_obj

h5py.Group or h5py.Dataset – the object which the hard link will point to

class h5preserve.Registry(name)

Register of functions for converting between hdf5 and python.

This is the core of h5preserve, containing the information about how to convert to and from hdf5 files, what version to use, and the namespace of created data.

Parameters:name (string) – name of registry for identification purposes

dumper(cls, label, version)

Decorator function to create a dumper function.

Parameters:

• cls (any class) – the class which this dumper operates on
• label (string) – the label or tag associated with this class
• version (integer, None) – The version of the output that this function returns.

freeze()

Freeze the registry, preventing further changes to the registry.

loader(label, version)

Decorator function to create a loader function.

Parameters:

• label (string) – the label or tag associated with this class
• version (integer, any, all, None) – The version of the output that this function reads.

name

str – name of the registry

class h5preserve.RegistryContainer(*registries)

Ordered container of registries which manages interaction with the hdf5 file.

Parameters:*registries (list of Registry) – the list of registries to be associated with this container

append(value)

S.append(object) – append object to the end of the sequence

count(value) → integer -- return number of occurrences of value

dump(obj)

Dump native python object to h5preserve representation

Parameters:obj – the object to dump

extend(values)

S.extend(iterable) – extend sequence by appending elements from the iterable

from_file(h5py_obj)

Return an representation of a hdf5 object from a hdf5 file

Parameters:h5py_obj (a h5py object, e.g. group, dataset) –

index(value) → integer -- return first index of value.

Raises ValueError if the value is not present.

load(obj)

Load native python object from h5preserve representation

Parameters:obj – the object to dump

lock_version(cls, version)

Lock output version for a specific class

Parameters:

• cls (any class) – the class to lock the version of
• version (integer, any, all, None) – the version which will always be used

pop([index]) → item -- remove and return item at index (default last).

Raise IndexError if list is empty or index is out of range.

remove(value)

S.remove(value) – remove first occurrence of value. Raise ValueError if the value is not present.

reverse()

S.reverse() – reverse IN PLACE

to_file(h5py_group, key, val)

Dump h5preserve object to hdf5 file

Parameters:

• h5py_group (h5py.Group) – the group to add the object to
• key (string) – the name for the object
• val – the object to add

h5preserve.new_registry_list(*registries)

Create a new list of registries which includes builtin registries.

Parameters:*registries (list of Registry) – the list of registries to be associated with this container

h5preserve.open(filename, registries, **kwargs)

Open a hdf5 file wrapped with h5preserve.

Parameters:

• filename (string, or other identifier accepted by h5py.File) –
• registries (RegistryContainer) – the collection of registries that you want to use to read from the hdf5 file
• **kwargs – additional keyword arguments to pass to h5py.File