pninexus.h5cpp.node

Enumerations

class pninexus.h5cpp.node.Type

Enumeration identifying the type of node.

DATASET the node is a dataset

GROUP the node is a group

DATATYPE the node is a committed datatype

class pninexus.h5cpp.node.LinkType

Enumeration determining the type of a particular link.

ERROR invalid link

HARD a hard link

EXTERNAL an external link to a node in a different file

SOFT soft (symbolic) link to a node within the same file

Classes

Node
Group
Dataset

class pninexus.h5cpp.node.Node

Base class for all node types.

hello world this is some stupid text

attributes

Read-only property providing access to the pninexus.h5cpp.attribute.AttributeManager instance associated with the node

is_valid

Read-only property returning true if the node is a valid HDF5 object. False otherweise.

Returns:

True if node is valid object, False otherwise

Return type:

Boolean

link

Read-only attribute providing access to Link used to access this node in the first place.

type

Read only attribute returning the Type of the particular node.

class pninexus.h5cpp.node.Group

HDF5 group class.

Parameters:

• parent (Group) – the parent group below which to construct the new group

• name (str) – the name for the new group

• lcpl (pninexus.h5cpp.property.LinkCreationList) – optional link creation property list

• gcpl (pninexus.h5cpp.property.GroupCreationList) – optional group creation property list

• gapl (pninexus.h5cpp.property.GroupAccessList) – optional group access property list

links

Read only property returning the link view instance associated with this group instance.

Return type:

LinkView

nodes

Read only property returning the node view instance associated with this group.

Return type:

NodeView

close()

Closes the group. After a call to this method the is_valid property returns False.

group = Group(...)
group.is_valid   #returns True

group.close()
group.is_valid   #returns False

class pninexus.h5cpp.node.Dataset

Datasets are the primary data storing nodes in HDF5.

The constructor for a dataset takes the following arguments:

Parameters:

• parent (Group) – the parent group for the new dataset

• name (str) – the name for the new dataset

• type (pninexus.h5cpp.datatype.Datatype) – the datatype for the new dataset

• space (pninexus.h5cpp.dataspace.Dataspace) – the dataspace for the dataset

• lcpl (pninexus.h5cpp.property.LinkCreationList) – an optional link creation property list

• dcpl (pninexus.h5cpp.property.DatasetCreationList) – an optional dataset creation property list

• dapl (pninexus.h5cpp.property.DatasetAccessList) – an optional dataset access property list

access_list

Read-only attribute returning the access property list used when opening the dataset.

Return type:

pninexus.h5cpp.property.DatasetAccessList

creation_list

Read-only attribute returning the creation property list used during dataset creation.

Return type:

pninexus.h5cpp.property.DatasetCreationList

dataspace

Read only attribute returning the associated with this dataset

Return type:

pninexus.h5cpp.dataspace.Dataspace

datatype

Read only attribute returning the datatype associated with the dataset.

Return type:

pninexus.h5cpp.datatype.Datatype

close()

Closes the dataset. After calling this function is_valid should return False.

refresh()

When built with HDF5 > 1.10 this method can be used in SWMR mode to obtain updates to the dataset from the writer.

extent(new_shape)

Set the extent (number of elements along each dimension) for a dataset. new_shape is a tuple or list with the new number of elements. In order for this method to succeed

• the number of dimensions (or rank) must remain the same

• the dataset must be constructed with a chunked storage layout

Parameters:

new_shape (tuple) – new number of elements

Raises:

RuntimeError – in case of a failure

extent(dim_index, dim_delta)

Change the number of elements of a dataset along a particular dimensions by a delta.

from pninexus.h5cpp.dataspace import Simple,UNLIMITED
from pninexus.h5cpp.node import Dataset

current_space = Simple((10,10),(UNLIMITED,10))
dataset = Dataset(...,current_space)

#do something with the dataset here


dataset.extent(0,10)
current_space = dataset.dataspace
print(current_space.current_dimensions)
#output (15,10)

Parameters:

• dim_index (int) – index of the dimension for which to reset the extent

• dim_delta (int) – change in number of dimensions

Raises:

RuntimeError – in case of a failure

write(data, selection=None)

write data to a dataset

Writes data to a dataset

Parameters:

• data (object) – Python object with data to write

• selection (pninexus.h5cpp.dataspace.Selection) – an optional selection

Raises:

RuntimeError – in case of a failure

Write data to the dataset. The data argument is a reference to the Python object storing the data to write. Internally this object will be converted to a numpy array which is then written to disk. If data is already an instance of numpy.ndarray this conversion is omitted.

In addition to the data an optinal reference to an HDF5 selection pninexus.h5cpp.dataspace.Selection can be passed to the method determining where in the dataset the data will be written. If no selection is passed the data will be assumed to fit into the entire dataset.

Parameters:

• write (object) – reference to the object to write

• selection (pninexus.h5cpp.dataspace.Selection) – optional selection for the dataset

Raises:

RuntimeError – in case of a failure

read(data=None, selection=None)

read data from a dataset

Reads data from a dataset

Parameters:

• data (object) – Python object with data to read

• selection (pninexus.h5cpp.dataspace.Selection) – an optional selection

Returns:

read data

Raises:

RuntimeError – in case of a failure

Reading data from a dataset. If called with no argument this method reads all data from the dataset and returns it as an instance of numpy.ndarray. With the selection parameter an HDF5 selection can be passed to determine what data from the dataset to read.

The optional data argument must be a reference to an instance of a numpy array (numpy.ndarray). If data is not None the method tries to read the data inplace to this numpy array thus avoiding memory additional memory allocation. In order for this to succeed the numpy array has to satisfy the following criteria

• the datatype of the datatype must be convertible to the type of the numpy array

• the number of elements of the numpy array must match those of the dataset or the selection if provided.

Parameters:

• data (numpy.ndarray) – optional data reference for inplace reading

• pninexus.h5cpp.dataspace.Selection – selection determining what to read

Raises:

• RuntimeError – in case of a failure

• TypeError – if data is not an instance of numpy.ndarray

filters()

read filters from a dataset

Reads filters from a dataset

Returns:

a list of filters

Raises:

RuntimeError – in case of a failure

read(data=None, selection=None)

read data from a dataset

Reads data from a dataset

Parameters:

• data (object) – Python object with data to read

• selection (pninexus.h5cpp.dataspace.Selection) – an optional selection

Returns:

read data

Raises:

RuntimeError – in case of a failure

write(data, selection=None)

write data to a dataset

Writes data to a dataset

Parameters:

• data (object) – Python object with data to write

• selection (pninexus.h5cpp.dataspace.Selection) – an optional selection

Raises:

RuntimeError – in case of a failure

class pninexus.h5cpp.node.LinkView

Iterable interface to the links directly attached to a group. The link view for a group can be accessed via the links attribute of a Group instance.

Iteration over the links immediately attached to a group:

group = ...

for link in group.links:
   print(link.path)

Recursive iteration over all links available below a group and its sub-groups

group = ...

for link in group.links.recursive:
   print(link.path)

recursive

Read-only property returning a recursive link iterator

exists(link_name, lapl=pninexus.h5cpp.property.LinkAccessList())

Returns True if a link of name link_name exists below the associated group, otherwise False is returned.

Parameters:

• link_name (str) – name of the link to check for

• lapl (pninexus.h5cpp.property.LinkAccessList) – optional link access property list

Returns:

True if link exists, False otherwise

Return type:

boolean

class pninexus.h5cpp.node.NodeView

Iterable interface to the nodes below an instance of Group. The instance of NodeView associated with a particular group can be accessed via the nodes property of the latter.

group = ...

for node in group.nodes:
   print(node.link.path)

like for links there is also a recursive iterator available which returns also the children of all sub-groups of a group.

group = ...

for node in group.nodes.recursive:
   print(node.link.path)

recursive

Read only property returning a recursive node iterator.

exists(node_name, lapl=pninexus.h5cpp.property.LinkAccessList())

Returns true if a node of name node_name exists below a group. Otherwise False is returned. This check involves two steps under the hood

1. check if a link of name node_name exists

2. check if the link can be resolved

only if both checks succeed True is returned.

Parameters:

• node_name (str) – the name of the node to check for

• lapl (pninexus.h5cpp.property.LinkAccessList) – optional link access property list

Returns:

True if the node exists, False otherwise

Return type:

boolean

__getitem__(key)

Allows access to the immediate child nodes of a group.

data = group.nodes["data"]

Parameters:

key (str) – name of the child node’s link

Returns:

group or dataset instance

Return type:

Dataset or Group

Raises:

RuntimeError – in case of a failure

class pninexus.h5cpp.node.Link

Class representing a link. You cannot construct an instance of Link from within Python, but you can obtain them from several methods and properties of the node classes.

exists

Read-only property returning True if the link exists, False otherwise.

Return type:

boolean

file

Read-only attribute returning the path to the file within which the link exists.

Return type:

str

is_resolvable

Read-only attribute returning True if the link can be resolved, False otherwise.

Return type:

boolean

node

Read-only property returning the node referenced by this link. This will only work if the link itself is resolvable.

link = ....

if link.is_resolvable:
   node = link.node

Return type:

Group, Dataset

Raises:

RuntimeError – if the link cannot be resolved

parent

Read only property returning the parent group of the link

Return type:

Group

path

Return the path for the link.

Return type:

pninexus.h5cpp.Path

type(lapl=pninexus.h5cpp.property.LinkAccessList())

Return the type.

Parameters:

lapl (pninexus.h5cpp.property.LinkAccessList) – optional link access proerty list

Returns:

link type enumeration

Return type:

LinkType

target(lapl=pninexus.h5cpp.property.LinkAccessList())

Return the link target

Parameters:

lapl (pninexus.h5cpp.property.LinkAccessList) – optional link access property list

Returns:

the target of the link

Return type:

LinkTarget

class pninexus.h5cpp.node.LinkTarget

LinkTarget describes the target for a link. It could be used to access this target without dereferencing the link. It is thus useful in the case of links which cannot be dereferenced. Using the target one could check whether the file or the object in it are missing or both.

file_path

Read only property with the path to the file where the link target is expected to reside in. In the case of soft links this is empty.

Return type:

str

object_path

Read only property returning the node path to the target.

Return type:

pninexus.h5cpp.Path

Node related functions

pninexus.h5cpp.node.is_dataset(node)

Returns True if the node instance represents a dataset, False otherwise.

Parameters:

node (Node) – reference to a node to check

Returns:

True if node is a dataset, False otherwise

Return type:

boolean

pninexus.h5cpp.node.is_group(node)

Returns True if the Node instance represents a group, False otherwise.

Parameters:

node (Node) – reference to the node to check

Returns:

True if node is a group, False otherwise

Return type:

boolean

pninexus.h5cpp.node.get_node(base, path, lapl=pninexus.h5cpp.property.LinkAccessList())

Returns a determined by base and path. If path is relative it is considered relative to base. If path is absolute base is only used to determine the file and root group where to look for the node.

Parameters:

• base (Group) – the base group from which to start the search

• path (Path) – absolute or relative path to the node to obtain

• lapl (pninexus.h5cpp.property.LinkAccessList) – optional link access property list

Returns:

new node instance (dataset or group)

Return type:

Group or Dataset

Raises:

RuntimeError – in case of a failure

pninexus.h5cpp.node.copy(node, base, path=None, link_creation_list=<pninexus.h5cpp._property.LinkCreationList object>, object_copy_list=<pninexus.h5cpp._property.ObjectCopyList object>)

Copy an object within the HDF5 tree

Copies an existing object node to a new location. The new location is determined by base and path argument. If path is not given a copy of the original object will be created with the same name under base. If path is given, it determines the new path and thus name of the copied object relative to the base object.

The behavior of the copy operation can be controlled by a link and object copy property list which can be passed as optional arguments.

Parameters:

• node (Node) – the object to copy

• base (Group) – the base group for the new location

• path (pninexus.h5cpp.Path) – optional HDF5 path determining the final location of the copied object

• link_creation_list (LinkCreationList) – optional link creation property list

• object_copy_list (ObjectCopyList) – optional object copy property list

Raises:

RuntimeError – in case of errors

pninexus.h5cpp.node.move(node, base, path=None, link_creation_list=<pninexus.h5cpp._property.LinkCreationList object>, link_access_list=<pninexus.h5cpp._property.LinkAccessList object>)

Moving a node within the HDF5 tree

Move an instance of Node (dataset or group) to a new location. The new location is determined by the base and path argument. If path is not given node is moved below the base using the same link name as it has under its original group. If path is given the new location is determined by this path relative to the base group.

Technically this function does not move any data but, like on a filesystem, only links are altered.

Parameters:

• node (Node) – the node (dataset or group) to move

• base (Group) – the base group where to move the node

• path (Path) – optional HDF5 path determining the new location of the node to be moved relative to the base group

• link_creation_list (LinkCreationList) – optional link creation property list

• link_access_list (LinkAccessList) – optional link access property list

pninexus.h5cpp.node.remove(node=None, base=None, path=None, link_access_list=<pninexus.h5cpp._property.LinkAccessList object>)

Remove a node from the HDF5 node tree

This function can be used in two modes:

• either the node to remove is referenced directly by node

• or by base and path.

Attention

It is important that this function does not remove any data from the file. It only removes the link to the given node. An object is considered deleted if no link leading to this node exists. However, the file size will not change. In order to remove all the data associated with this node h5repack has to be used which will simply not copy nodes without links to the new file.

Parameters:

• node (Node) – the node to remove

• base (Group) – base group from which to search

• path (Path) – HDF5 path to the object to remove

• link_access_list (LinkAccessList) – optional link access property list

Raises:

• TypeError – if any of the arguments is not of appropriate type

• RuntimeError – in case of any other error

pninexus.h5cpp.node.link(target, link_base, link_path, target_file=None, link_creation_list=<pninexus.h5cpp._property.LinkCreationList object>, link_access_list=<pninexus.h5cpp._property.LinkAccessList object>)

Create a new link

Create a new soft link to a node referenced by target under link_path relative to link_base. If target_file is set an external link is provided an external link is created.

Attention

The target object does not need to exist at the time the link is created. Only when the new link should be dereferenced the target object has to exist.

Parameters:

• target (Node/Path) – the target for the new link

• link_base (Group) – the base for the new link

• link_path (Path) – the path to the new link relative to the link_base

• link_creation_list (LinkCreationList) – optional reference to a link creation property list

• link_access_list (LinkAccessList) – optional reference to a link access property list

Raises:

• TypeError – if any of the arguments does not match the required type

• RuntimError – in the case of any other error