# 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 – minimum number of attributes to be stored in dense storage(default:6)

  set_obj_track_times(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_link_creation_order() → UINT flags

    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:

    0. UINT Address offsets

    1. 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:

    0. UINT Super block version number

    1. UINT Freelist version number

    2. UINT Symbol table version number

    3. 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_link_creation_order(UINT flags)

    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:

    - `h5fd.CORE`

    - `h5fd.FAMILY`

    - `h5fd.LOG`

    - `h5fd.MPIO`

    - `h5fd.MULTI`

    - `h5fd.SEC2`

    - `h5fd.DIRECT` (if available)

    - `h5fd.STDIO`

    - `h5fd.ROS3` (if available)

  get_fapl_core() → TUPLE core_settings

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

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

    1. 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:

    0. UINT memb_size

    1. PropFAID memb_fapl or None

  get_fapl_mpio()

    Determine mpio driver `MPI` information.

    0. The mpi4py.MPI.Comm Communicator

    1. The mpi4py.MPI.Comm Info

  get_fapl_ros3() → STRUCT config

    Retrieve the `ROS3` config

  get_fapl_ros3_token() → BYTES token

    Get session token from the `file access property list`.

  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:

    - `h5f.CLOSE_DEFAULT`

    - `h5f.CLOSE_WEAK`

    - `h5f.CLOSE_SEMI`

    - `h5f.CLOSE_STRONG`

  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:

    - `h5f.LIBVER_EARLIEST`

    - `h5f.LIBVER_V18`

    - `h5f.LIBVER_V110`

    - `h5f.LIBVER_V112` (HDF5 1.11.4 or later)

    - `h5f.LIBVER_V114` (HDF5 1.13.0 or later)

    - `h5f.LIBVER_LATEST`

  get_mdc_config() → CacheConfig Returns an object that stores all the information about the meta-data cache configuration
  get_meta_block_size() → UINT size

    Get the current minimum size, in bytes, of new metadata block allocations.

  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(threshold, 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.

    block_size

      Chunk size for new memory requests (default 64 KiB)

    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(comm, use_gpfs_hints=0)

    Obsolete.

  set_fapl_ros3(STRING aws_region, STRING secret_id, STRING secret_key)

    Set up the ros3 driver.

  set_fapl_ros3_token(BYTES token="")

    Set session token in the `file access property list`.

  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:

    - `h5f.CLOSE_DEFAULT`

    - `h5f.CLOSE_WEAK`

    - `h5f.CLOSE_SEMI`

    - `h5f.CLOSE_STRONG`

  set_file_image(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:

    - `h5f.LIBVER_EARLIEST`

    - `h5f.LIBVER_V18`

    - `h5f.LIBVER_V110`

    - `h5f.LIBVER_V112` (HDF5 1.11.4 or later)

    - `h5f.LIBVER_V114` (HDF5 1.13.0 or later)

    - `h5f.LIBVER_LATEST`

  set_mdc_config(CacheConfig) → None Returns an object that stores all the information about the meta-data cache configuration
  set_meta_block_size(UINT size)

    Set the current minimum size, in bytes, of new metadata block allocations.

  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:

    - `h5d.FILL_VALUE_UNDEFINED`

    - `h5d.FILL_VALUE_DEFAULT`

    - `h5d.FILL_VALUE_USER_DEFINED`

  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:

    0. STRING name of file (256 chars max)

    1. UINT offset

    2. 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:

    - `h5d.FILL_TIME_ALLOC`

    - `h5d.FILL_TIME_NEVER`

    - `h5d.FILL_TIME_IFSET`

  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:

    0. INT filter code (h5z.FILTER*)

    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_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:

    0. UINT flags (h5z.FLAG*)

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

    2. STRING name of filter (256 chars max)

  get_layout() → INT layout_code

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

    - `h5d.COMPACT`

    - `h5d.CONTIGUOUS`

    - `h5d.CHUNKED`

    - `h5d.VIRTUAL` (If using HDF5 library version 1.10 or later)

  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:

    - `h5d.FILL_TIME_ALLOC`

    - `h5d.FILL_TIME_NEVER`

    - `h5d.FILL_TIME_IFSET`

  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:

      - `h5z.FILTER_DEFLATE`

      - `h5z.FILTER_SHUFFLE`

      - `h5z.FILTER_FLETCHER32`

      - `h5z.FILTER_SZIP`

    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:

    - `h5d.COMPACT`

    - `h5d.CONTIGUOUS`

    - `h5d.CHUNKED`

    - `h5d.VIRTUAL` (If using HDF5 library version 1.10 or later)

  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:

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

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

    2. `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(xfer_mode)

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

## Link creation

class h5py.h5p.PropLCID

  Bases: `PropCreateID`

  Link creation property list

  get_char_encoding() → INT encoding

    Get the character encoding for link names. Legal values are:

    - `h5t.CSET_ASCII`

    - `h5t.CSET_UTF8`

  get_create_intermediate_group() → BOOL

    Determine if missing intermediate groups are automatically created.

  set_char_encoding(INT encoding)

    Set the character encoding for link names. Legal values are:

    - `h5t.CSET_ASCII`

    - `h5t.CSET_UTF8`

  set_create_intermediate_group(BOOL create)

    Set whether missing intermediate groups are automatically created.

## Link access

class h5py.h5p.PropLAID

  Bases: `PropInstanceID`

  Link access property list

  get_elink_acc_flags() → UINT

    Retrieves the external link traversal file access flag from the specified `link access property list`.

  get_elink_fapl() → PropFAID fapl

    Get the `file access property list` used when opening external files.

  get_elink_prefix() → STRING prefix

    Get the external link prefix

  get_nlinks() → UINT

    Get the maximum traversal depth for soft links

  set_elink_acc_flags(UNIT flags)

    Sets the external link traversal file access flag in a `link access property list`.

  set_elink_fapl(PropFAID fapl)

    Set the `file access property list` used when opening external files.

  set_elink_prefix(STRING prefix)

    Set the external link prefix.

  set_nlinks(UINT nlinks)

    Set the maximum traversal depth for soft links

## Group creation

class h5py.h5p.PropGCID

  Bases: `PropOCID`

  Group creation property list

  get_link_creation_order() → UINT flags

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

  set_link_creation_order(UINT flags)

    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.LINK_CREATE

h5py.h5p.LINK_ACCESS

h5py.h5p.GROUP_CREATE

h5py.h5p.OBJECT_CREATE

### Order tracking flags

h5py.h5p.CRT_ORDER_TRACKED

h5py.h5p.CRT_ORDER_INDEXED