Module H5P

HDF5 property list interface.

Functional API

h5py.h5p.create(PropClassID cls) → PropID

Create a new property list as an instance of a class; classes are:

  • FILE_CREATE

  • FILE_ACCESS

  • DATASET_CREATE

  • DATASET_XFER

  • DATASET_ACCESS

  • LINK_CREATE

  • LINK_ACCESS

  • GROUP_CREATE

  • OBJECT_COPY

  • OBJECT_CREATE

Base classes

class h5py.h5p.PropID

Bases: ObjectID

Base class for all property lists and classes

equal(PropID plist) → BOOL

Compare this property list (or class) to another for equality.

class h5py.h5p.PropClassID

Bases: PropID

An HDF5 property list class.

  • Hashable: Yes, by identifier

  • Equality: Logical H5P comparison

class h5py.h5p.PropInstanceID

Bases: PropID

Base class for property list instance objects. Provides methods which are common across all HDF5 property list classes.

  • Hashable: No

  • Equality: Logical H5P comparison

copy() → PropList newid

Create a new copy of an existing property list object.

get_class() → PropClassID

Determine the class of a property list object.

class h5py.h5p.PropCreateID

Bases: PropInstanceID

Generic object creation property list.

class h5py.h5p.PropOCID

Bases: PropCreateID

Object creation property list

This seems to be a super class for dataset creation property list and group creation property list.

The documentation is somewhat hazy

get_attr_creation_order() → UINT flags

Get tracking and indexing of creation order for object attributes

get_attr_phase_change()

Retrieves threshold values for attribute storage on an object.

get_obj_track_times()

Determines whether times associated with an object are being recorded.

set_attr_creation_order(UINT flags)

Set tracking and indexing of creation order for object attributes

flags – h5p.CRT_ORDER_TRACKED, h5p.CRT_ORDER_INDEXED

set_attr_phase_change(UINT max_compact, UINT min_dense)

Set threshold value for attribute storage on an object

max_compact – maximum number of attributes to be stored in compact storage(default:8) must be greater than or equal to min_dense min_dense – minmum number of attributes to be stored in dense storage(default:6)

set_obj_track_times()

Sets the recording of times associated with an object.

class h5py.h5p.PropCopyID

Bases: PropInstanceID

Generic object copy property list

get_copy_object() → UINT flags

Get copy process flags. Legal flags are h5o.COPY*.

set_copy_object(UINT flags)

Set flags for object copying process. Legal flags are from the h5o.COPY* family:

h5o.COPY_SHALLOW_HIERARCHY_FLAG

Copy only immediate members of a group.

h5o.COPY_EXPAND_SOFT_LINK_FLAG

Expand soft links into new objects.

h5o.COPY_EXPAND_EXT_LINK_FLAG

Expand external link into new objects.

h5o.COPY_EXPAND_REFERENCE_FLAG

Copy objects that are pointed to by references.

h5o.COPY_WITHOUT_ATTR_FLAG

Copy object without copying attributes.

File creation

class h5py.h5p.PropFCID

Bases: PropOCID

File creation property list.

get_file_space_page_size() → LONG fsp_size

Retrieve the file space page size.

get_file_space_strategy() -> TUPLE(UINT strategy, BOOL persist, ULONGLONG threshold)

Retrieve the file space handling strategy, persisting free-space condition and threshold value for a file creation property list.

Get tracking and indexing of creation order for links added to this group

get_sizes() → TUPLE sizes

Determine addressing offsets and lengths for objects in an HDF5 file, in bytes. Return value is a 2-tuple with values:

  1. UINT Address offsets

  2. UINT Lengths

get_userblock() → LONG size

Determine the user block size, in bytes.

get_version() → TUPLE version_info

Determine version information of various file attributes. Elements are:

  1. UINT Super block version number

  2. UINT Freelist version number

  3. UINT Symbol table version number

  4. UINT Shared object header version number

set_file_space_page_size(LONG fsp_size)

Set the file space page size used in paged aggregation and paged buffering. Minimum page size is 512 bytes. A value less than 512 will raise an error. The size set may not be changed for the life of the file.

set_file_space_strategy(UINT strategy, BOOL persist, ULONGLONG threshold)

Set the file space handling strategy and persisting free-space values.

Set tracking and indexing of creation order for links added to this group

flags – h5p.CRT_ORDER_TRACKED, h5p.CRT_ORDER_INDEXED

set_sizes(UINT addr, UINT size)

Set the addressing offsets and lengths for objects in an HDF5 file, in bytes.

set_userblock(INT/LONG size)

Set the file user block size, in bytes. Must be a power of 2, and at least 512.

File access

class h5py.h5p.PropFAID

Bases: PropInstanceID

File access property list

get_alignment()

Retrieves the current settings for alignment properties from a file access property list.

get_cache() → TUPLE cache info

Get the metadata and raw data chunk cache settings. See the HDF5 docs for element definitions. Return is a 4-tuple with entries:

  1. INT mdc: Number of metadata objects

  2. INT rdcc: Number of raw data chunks

  3. UINT rdcc_nbytes: Size of raw data cache

  4. DOUBLE rdcc_w0: Preemption policy for data cache.

get_driver() → INT driver code

Return an integer identifier for the driver used by this list. Although HDF5 implements these as full-fledged objects, they are treated as integers by Python. Built-in drivers identifiers are listed in module h5fd; they are:

get_fapl_core() → TUPLE core_settings

Determine settings for the h5fd.CORE (memory-resident) file driver. Tuple elements are:

  1. UINT “increment”: Chunk size for new memory requests

  2. BOOL “backing_store”: If True, write the memory contents to disk when the file is closed.

get_fapl_family() → TUPLE info

Determine family driver settings. Tuple values are:

  1. UINT memb_size

  2. PropFAID memb_fapl or None

get_fapl_mpio()

Determine mpio driver MPI information.

  1. The mpi4py.MPI.Comm Communicator

  2. The mpi4py.MPI.Comm Info

get_fapl_ros3() → STRUCT config

Retrieve the ROS3 config

get_fclose_degree() → INT close_degree - h5fd. Get the file-close degree, which determines library behavior when a file is closed when objects are still open.  Legal values:
get_file_locking()

Return file locking information as a 2-tuple of boolean: (use_file_locking, ignore_when_disabled)

get_libver_bounds() -> (INT low, INT high)

Get the compatibility level for file format. Returned values are from:

get_mdc_config() → CacheConfig Returns an object that stores all the information about the meta-data cache configuration
get_page_buffer_size() -> (LONG buf_size, UINT min_meta_per, UINT min_raw_per)

Retrieves the maximum size for the page buffer and the minimum percentage for metadata and raw data pages evicition criteria.

get_sieve_buf_size() → UINT size

Get the current maximum size of the data sieve buffer (in bytes).

set_alignment()

Sets alignment properties of a file access property list.

set_cache(INT mdc, INT rdcc, UINT rdcc_nbytes, DOUBLE rdcc_w0)

Set the metadata (mdc) and raw data chunk (rdcc) cache properties. See the HDF5 docs for a full explanation.

set_driver(INT driver_id)

Sets the file driver identifier for this file access or data transfer property list.

set_fapl_core(UINT increment=64k, BOOL backing_store=True)

Use the h5fd.CORE (memory-resident) file driver.

increment

Chunk size for new memory requests (default 1 meg)

backing_store

If True (default), memory contents are associated with an on-disk file, which is updated when the file is closed. Set to False for a purely in-memory file.

set_fapl_family(UINT memb_size=2**31-1, PropFAID memb_fapl=None)

Set up the family driver.

memb_size

Member file size

memb_fapl

File access property list for each member access

set_fapl_log(STRING logfile, UINT flags, UINT buf_size)

Enable the use of the logging driver. See the HDF5 documentation for details. Flag constants are stored in module h5fd.

set_fapl_mpio(Comm comm, Info info)

Set MPI-I/O Parallel HDF5 driver.

Comm: An mpi4py.MPI.Comm instance Info: An mpi4py.MPI.Info instance

set_fapl_mpiposix()

Obsolete.

set_fapl_ros3(STRING aws_region, STRING secret_id, STRING secret_key)

Set up the ros3 driver.

set_fapl_sec2()

Select the “section-2” driver (h5fd.SEC2).

set_fapl_split()

Select the “split” driver (h5fd.SPLIT)

set_fapl_stdio()

Select the “stdio” driver (h5fd.STDIO)

set_fclose_degree(INT close_degree)

Set the file-close degree, which determines library behavior when a file is closed when objects are still open. Legal values:

set_file_image()

Copy a file image into the property list. Passing None releases any image currently loaded. The parameter image must either be None or support the buffer protocol.

set_file_locking(BOOL use_file_locking, BOOL ignore_when_disabled)

Set HDF5 file locking behavior. Warning: This setting is overridden by the HDF5_USE_FILE_LOCKING environment variable.

set_fileobj_driver(INT driver_id, OBJECT fileobj)

Select the “fileobj” file driver (h5py-specific).

set_libver_bounds(INT low, INT high)

Set the compatibility level for file format. Legal values are:

set_mdc_config(CacheConfig) → None Returns an object that stores all the information about the meta-data cache configuration
set_page_buffer_size(LONG buf_size, UINT min_meta_per, UINT min_raw_per)

Set the maximum size in bytes of the page buffer. The default value is zero, meaning that page buffering is disabled. When a non-zero page buffer size is set, HDF5 library will enable page buffering if that size is larger or equal than a single page size if a paged file space strategy was set at file creation.

The function also allows setting the criteria for metadata and raw data page eviction from the buffer. The default values for both are zero.

set_sieve_buf_size(UINT size)

Set the maximum size of the data sieve buffer (in bytes). This buffer can improve I/O performance for hyperslab I/O, by combining reads and writes into blocks of the given size. The default is 64k.

Dataset creation

class h5py.h5p.PropDCID

Bases: PropOCID

Dataset creation property list.

all_filters_avail() → BOOL

Determine if all the filters in the pipelist are available to the library.

fill_value_defined() → INT fill_status

Determine the status of the dataset fill value. Return values are:

get_alloc_time() → INT alloc_time

Get the storage space allocation time. One of h5d.ALLOC_TIME*.

get_chunk() → TUPLE chunk_dimensions

Obtain the dataset chunk size, as a tuple.

get_external(UINT idx=0) → TUPLE external_file_info

Returns information about the indexed external file. Tuple elements are:

  1. STRING name of file (256 chars max)

  2. UINT offset

  3. UINT size

get_external_count() → INT

Returns the number of external files for the dataset.

get_fill_time() → INT

Determine when fill values are written to the dataset. Legal values (defined in module h5d) are:

get_fill_value(NDARRAY value)

Read the dataset fill value into a NumPy array. It will be converted to match the array dtype. If the array has nonzero rank, only the first element will contain the value.

get_filter(UINT filter_idx) → TUPLE filter_info

Get information about a filter, identified by its index. Tuple elements are:

  1. INT filter code (h5z.FILTER*)

  2. UINT flags (h5z.FLAG*)

  3. TUPLE of UINT values; filter aux data (16 values max)

  4. STRING name of filter (256 chars max)

get_filter_by_id(INT filter_code) → TUPLE filter_info or None

Get information about a filter, identified by its code (one of h5z.FILTER*). If the filter doesn’t exist, returns None. Tuple elements are:

  1. UINT flags (h5z.FLAG*)

  2. TUPLE of UINT values; filter aux data (16 values max)

  3. STRING name of filter (256 chars max)

get_layout() → INT layout_code

Determine the storage strategy of a dataset; legal values are:

get_nfilters() → INT

Determine the number of filters in the pipeline.

get_virtual_count() → UINT

Get the number of mappings for the virtual dataset.

get_virtual_dsetname(UINT index=0) → STR

Get the name of a source dataset used in the mapping of the virtual dataset at the position index.

get_virtual_filename(UINT index=0) → STR

Get the file name of a source dataset used in the mapping of the virtual dataset at the position index.

get_virtual_srcspace(UINT index=0) → SpaceID

Get a dataspace for the selection within the source dataset used in the mapping.

get_virtual_vspace(UINT index=0) → SpaceID

Get a dataspace for the selection within the virtual dataset used in the mapping.

remove_filter(INT filter_class)

Remove a filter from the pipeline. The class code is one of h5z.FILTER*.

set_alloc_time(INT alloc_time)

Set the storage space allocation time. One of h5d.ALLOC_TIME*.

set_chunk(TUPLE chunksize)

Set the dataset chunk size. It’s up to you to provide values which are compatible with your dataset.

set_deflate(UINT level=5)

Enable deflate (gzip) compression, at the given level. Valid levels are 0-9, default is 5.

set_external(STR name, UINT offset, UINT size)

Adds an external file to the list of external files for the dataset.

The first call sets the external storage property in the property list, thus designating that the dataset will be stored in one or more non-HDF5 file(s) external to the HDF5 file.

set_fill_time(INT fill_time)

Define when fill values are written to the dataset. Legal values (defined in module h5d) are:

set_fill_value(NDARRAY value)

Set the dataset fill value. The object provided should be an 0-dimensional NumPy array; otherwise, the value will be read from the first element.

set_filter(INT filter_code, UINT flags=0, TUPLE values=None)

Set a filter in the pipeline. Params are:

filter_code

One of the following:

flags

Bit flags (h5z.FLAG*) setting filter properties

values

TUPLE of UINTs giving auxiliary data for the filter

set_fletcher32()

Enable Fletcher32 error correction on this list.

set_layout(INT layout_code)

Set dataset storage strategy; legal values are:

set_scaleoffset(H5Z_SO_scale_type_t scale_type, INT scale_factor)

Enable scale/offset (usually lossy) compression; lossless (e.g. gzip) compression and other filters may be applied on top of this.

Note that error detection (i.e. fletcher32) cannot precede this in the filter chain, or else all reads on lossily-compressed data will fail.

set_shuffle()

Enable to use of the shuffle filter. Use this immediately before the deflate filter to increase the compression ratio.

set_szip(UINT options, UINT pixels_per_block)

Enable SZIP compression. See the HDF5 docs for argument meanings, and general restrictions on use of the SZIP format.

set_virtual(SpaceID vspace, STR src_file_name, STR src_dset_name, SpaceID src_space)

Set the mapping between virtual and source datasets.

The virtual dataset is described by its virtual dataspace (vspace) to the elements. The source dataset is described by the name of the file where it is located (src_file_name), the name of the dataset (src_dset_name) and its dataspace (src_space).

Dataset access

class h5py.h5p.PropDAID

Bases: PropInstanceID

Dataset access property list

get_chunk_cache() → TUPLE chunk cache info

Get the metadata and raw data chunk cache settings. See the HDF5 docs for element definitions. Return is a 3-tuple with entries:

  1. size_t rdcc_nslots: Number of chunk slots in the raw data chunk cache hash table.

  2. size_t rdcc_nbytes: Total size of the raw data chunk cache, in bytes.

  3. DOUBLE rdcc_w0: Preemption policy.

get_efile_prefix() → STR

Get the filesystem path prefix configured for accessing external datasets.

get_virtual_prefix() → STR

Get the filesystem path prefix configured for accessing virtual datasets.

get_virtual_printf_gap() → LONG gap_size

Return the maximum number of missing source files and/or datasets with the printf-style names when getting the extent for an unlimited virtual dataset.

get_virtual_view() → UINT view

Retrieve the view of the virtual dataset.

Valid values are:

  • h5d.VDS_FIRST_MISSING

  • h5d.VDS_LAST_AVAILABLE

set_chunk_cache(size_t rdcc_nslots, size_t rdcc_nbytes, double rdcc_w0)

Sets the raw data chunk cache parameters.

set_efile_prefix(STR prefix)

Set a filesystem path prefix for looking up external datasets. This is prepended to all filenames specified in the external dataset.

set_virtual_prefix(STR prefix)

Set a filesystem path prefix for looking up virtual datasets. This is prepended to all filenames specified in the virtual dataset.

set_virtual_printf_gap(LONG gap_size=0)

Set the maximum number of missing source files and/or datasets with the printf-style names when getting the extent of an unlimited virtual dataset.

Instruct the library to stop looking for the mapped data stored in the files and/or datasets with the printf-style names after not finding gap_size files and/or datasets. The found source files and datasets will determine the extent of the unlimited virtual dataset with the printf-style mappings. Default value: 0.

set_virtual_view(UINT view)

Set the view of the virtual dataset (VDS) to include or exclude missing mapped elements.

If view is set to h5d.VDS_FIRST_MISSING, the view includes all data before the first missing mapped data. This setting provides a view containing only the continuous data starting with the dataset’s first data element. Any break in continuity terminates the view.

If view is set to h5d.VDS_LAST_AVAILABLE, the view includes all available mapped data.

Missing mapped data is filled with the fill value set in the virtual dataset’s creation property list.

Dataset transfer

class h5py.h5p.PropDXID

Bases: PropInstanceID

Data transfer property list

get_dxpl_mpio()

Get the current transfer mode for MPI I/O. Will be one of: - h5fd.MPIO_INDEPENDENT (default) - h5fd.MPIO_COLLECTIVE

set_dxpl_mpio()

Set the transfer mode for MPI I/O. Must be one of: - h5fd.MPIO_INDEPENDENT (default) - h5fd.MPIO_COLLECTIVE

Group creation

class h5py.h5p.PropGCID

Bases: PropOCID

Group creation property list

Get tracking and indexing of creation order for links added to this group

Set tracking and indexing of creation order for links added to this group

flags – h5p.CRT_ORDER_TRACKED, h5p.CRT_ORDER_INDEXED

Datatype creation

class h5py.h5p.PropTCID

Bases: PropOCID

Datatype creation property list

No methods yet.

Module constants

Predefined classes

h5py.h5p.DEFAULT
h5py.h5p.FILE_CREATE
h5py.h5p.FILE_ACCESS
h5py.h5p.DATASET_CREATE
h5py.h5p.DATASET_XFER
h5py.h5p.DATASET_ACCESS
h5py.h5p.OBJECT_COPY
h5py.h5p.GROUP_CREATE
h5py.h5p.OBJECT_CREATE

Order tracking flags

h5py.h5p.CRT_ORDER_TRACKED
h5py.h5p.CRT_ORDER_INDEXED