The _pyhl module defines the IO access for reading/writing HDF5 files. The module implements two classes for building an HDF5 file representation. The nodelist class implements a list that should represent the file itself. The node class represents the items in the HDF5 file. The nodelist contain several node's for building the HDF5 file. You can use this interface to write Python programs that interfact with HDF5 files.

Todo: Make the pyhl API-reference manual look like the rest of the documentation.

_pyhl nodelist interfaces

Function: addNode(node)
  Adds the provided node to the node list
Parameters:
  node - the node to add to the node list
Returns:
  N/A.

Function: write(filename, compression=None)
Parameters:
  filename - the full path of the HDF5 file to be written
  compression - Optional compression object
Returns:
  N/A.

Function: update(compression=None)
Parameters:
  compression - Optional compression object
Returns:
  N/A.

Function: getNodeNames()
Returns:
  A list of all node names that exists in the nodelist.

Function: selectAll()
  Marks all nodes for data reading when executing fetch()
Returns:
  N/A.

Function: selectMetadata()
  Marks all nodes (except the actual dataset) for data reading when executing fetch()
Returns:
  N/A.

Function: HLNodeList_selectNode(name)
  Marks the specified node for retrival when executing fetch
Parameters:
  name - the node that should be marked for retrival
Returns:
  N/A.

Function: HLNodeList_deselectNode(name)
  Unmarks the specified node so that it is not read when executing fetch.
Parameters:
  name - the node that should be deselected
Returns:
  N/A.

Function: fetch()
  Reads the data for all nodes that has been marked for selection.
Returns:
  N/A.

Function: HLNodeList_fetchNode()
  Reads the data for the specified node and returns it.
Returns:
  The read node.

Function: getNode(name)
  Reads the data for the specified node and returns it.
Parameters:
  name - the node that should be returned. Note, that if node not has been fetched it will not contain any data.
Returns:
  The read node.

_pyhl node interfaces

Function: setScalarValue(itemsize, data, format, hid)
  Sets a scalar value in the node instance.
Parameters:
  itemsize - specifies the size of the value in bytes. It is not nessecary to specify unless
             a compound type is set. So, usually it is just to set it to -1.
  data - is the data to be set in the node.
  format - is the HL-HDF string representation of the datatype.
  hid - is the hid_t reference to the datatype, is not nessecary to
        specify unless a compound type is set. Usually, just set it to -1.

  NOTE: If the data to be set is of compound type, then the data should be of string type.
  NOTE: If the node is a Reference node, the data should be set as a string type, where the
        data is the name of the referenced node.

Returns:
  N/A.

Function: setArrayValue(itemsize, dims, data, format, hid)
  Sets an array value in the node instance.
Parameters:
  itemsize - specifies the size of the value in bytes. It is not nessecary to specify unless
             a compound type is set. So, usually it is just to set it to -1.
  dims - is a list of dimensions of the data.
  data - is the data to be set in the node.
  format - is the HL-HDF string representation of the datatype.
  hid - is the hid_t reference to the datatype, is not nessecary to
        specify unless a compound type is set. Usually, just set it to -1.

  NOTE: If the data to be set is of compound type, then the data should be of string type.

Returns:
  N/A.

Function: commit(datatype)
  Marks a node of type=TYPE_ID to be committed (named).
Parameters:
  datatype - is the hid_t reference to the datatype.

Returns:
  N/A.

Function: name()
  Returns the name of the node instance.
Returns:
  the name of the node.

Function: type()
  Returns the type of the node instance..
Returns:
  the type of the node.

Function: dims()
  Returns a list of the dimensions of the data.
Returns:
  the dimensions

Function: format()
  Returns the HL-HDF format specifier name
Returns:
  the format specifier

Function: data()
  Returns the data in fixed format (native).
  NOTE: If the data is of compound type, the data will be returned as a string.
Returns:
  the data in native format.

Function: rawdata()
  Returns the raw data (as read without conversion to native format).
  NOTE: If the data is of compound type, the data will be returned as a string.
Returns:
  the data in raw format.

Function: compound_data()
  Returns a dictionary with all attributes in the compund attribute, it only
  works if the node instance is a compound attribute.
Returns:
  the compound data as a dictionary

_pyhl filecreationproperty interfaces

The filecreationproperty object does only contain various properties that is possible to set. Depending on how the file should be created, there are different parameters that can be used.

version: This parameter is only for retrival, i.e it is not possible to change.
userblock: See the hdf5 documentation for purpose of userblock.
sizes: Is specified as a tuple of 2, (sizeof_addr,sizeof_size), see hdf5 documentation for further information.
sym_k: Is specified as a tuple of 2, (ik,lk), see hdf5 documentation for further information.
istore_k: See hdf5 documentation for further information.
meta_block_size: This is actually a file access property but have been inserted here anyway, If the value is set to 2048, then the default file access property will be used. For more information about meta_block_size, see the hdf5 documentation.

_pyhl compression interfaces

The compression object does only contain various properties that is possible to set. Depending on what compression type that was specified when creating this object there are different parameters that can be used. If ZLIB_COMPRESSION was specified the only property that can be used is:

level: Specify level of compression between 0-9 where 0 means no compression and 9 means highest compression.

If SZLIB_COMPRESSION was specified, there are two properties that can be set.

szlib_mask: This affects how the compression should be performed and can can be set up from two different sets of options.

H5_SZIP_CHIP_OPTION_MASK	Compresses exactly as in hardware.
H5_SZIP_ALLOW_K13_OPTION_MASK	Allows k split = 13 compression mode. (Default)

H5_SZIP_EC_OPTION_MASK	Selects entropy coding method. (Default)
H5_SZIP_NN_OPTION_MASK	Selects nearest neighbor coding method.

Where the paired options are mutual exclusive, i.e. it is possible to set the szlib_mask to H5_SZIP_CHIP_OPTION_MASK|H5_SZIP_EC_OPTION_MASK but not to H5_SZIP_CHIP_OPTION_MASK|H5_SZIP_ALLOW_K13_OPTION_MASK.

szlib_px_per_block: The block size must be even, with typical values being 8,10,16 and 32. The more pixel values vary, the smaller this number should be.

_pyhl interfaces

Function: nodelist()
Returns:
  a new instance of the "nodelist" class.

Function: node(type, nodename, compress=None)
Parameters:
  type     - an integer that can be one of
    ATTRIBUTE_ID, DATASET_ID, GROUP_ID, TYPE_ID or REFERENCE_ID
  nodename - the fully qualified name of this node, eg /a/b/c
  compress - the compression object
Returns:
  a new instance of the "node" class.

Function: filecreationproperty()
Returns:
  a new instance of the "filecreationproperty" class.

Function: compression()
Returns:
  a new instance of the "compression" class.

Function: read_nodelist(filename, frompath=".")
Reads the hdf5 file named filename. If frompath is specified
the node structure is read from that path and downwards in the
hierarchy.
Returns:
  the read nodelist.

Function: is_file_hdf5(filename)
Returns 1 or 0 depending on if the specified filename is a HDF5
file or not.
Returns:
  1 if the specified filename is a HDF5 file, otherwise 0.

Function: show_hdf5errors(enable)
Turns HDF5 error reporting on or off. If enable == 1, then
HDF5 error reporting is turned on. Otherwise it is turned off.
Returns:
  N/A.

Function: show_hlhdferrors(enable)
Turns HL-HDF error reporting on or off. If enable == 1, then
HL-HDF error reporting is turned on (in debugging mode). Otherwise it is turned off.
Returns:
  N/A.