Module H5F

Low-level operations on HDF5 file objects.

Functional API

h5py.h5f.open(STRING name, UINT flags=ACC_RDWR, PropFAID fapl=None) → FileID

Open an existing HDF5 file. Keyword “flags” may be:

ACC_RDWR

Open in read-write mode

ACC_RDONLY

Open in readonly mode

Keyword fapl may be a file access property list.

h5py.h5f.create(STRING name, INT flags=ACC_TRUNC, PropFCID fcpl=None, PropFAID fapl=None) → FileID

Create a new HDF5 file. Keyword “flags” may be:

ACC_TRUNC

Truncate an existing file, discarding its data

ACC_EXCL

Fail if a conflicting file exists

To keep the behavior in line with that of Python’s built-in functions, the default is ACC_TRUNC. Be careful!

h5py.h5f.flush(ObjectID obj, INT scope=SCOPE_LOCAL)

Tell the HDF5 library to flush file buffers to disk. “obj” may be the file identifier, or the identifier of any object residing in the file. Keyword “scope” may be:

SCOPE_LOCAL

Flush only the given file

SCOPE_GLOBAL

Flush the entire virtual file

h5py.h5f.is_hdf5(STRING name) → BOOL

Determine if a given file is an HDF5 file. Note this raises an exception if the file doesn’t exist.

h5py.h5f.mount(ObjectID loc, STRING name, FileID fid)

Mount an open file on the group “name” under group loc_id. Note that “name” must already exist.

h5py.h5f.unmount(ObjectID loc, STRING name)

Unmount a file, mounted at “name” under group loc_id.

h5py.h5f.open_file_image(STRING image, INT flags=0) → FileID

Load a new HDF5 file into memory. Keyword “flags” may be:

FILE_IMAGE_OPEN_RW

Specifies opening the file image in read/write mode.

h5py.h5f.get_name(ObjectID obj) → STRING

Determine the name of the file in which the specified object resides.

h5py.h5f.get_obj_count(OBJECT where=OBJ_ALL, types=OBJ_ALL) → INT

Get the number of open objects.

where

Either a FileID instance representing an HDF5 file, or the special constant OBJ_ALL, to count objects in all files.

type

Specify what kinds of object to include. May be one of OBJ*, or any bitwise combination (e.g. OBJ_FILE | OBJ_ATTR).

The special value OBJ_ALL matches all object types, and OBJ_LOCAL will only match objects opened through a specific identifier.

h5py.h5f.get_obj_ids(OBJECT where=OBJ_ALL, types=OBJ_ALL) → LIST

Get a list of identifier instances for open objects.

where

Either a FileID instance representing an HDF5 file, or the special constant OBJ_ALL, to list objects in all files.

type

Specify what kinds of object to include. May be one of OBJ*, or any bitwise combination (e.g. OBJ_FILE | OBJ_ATTR).

The special value OBJ_ALL matches all object types, and OBJ_LOCAL will only match objects opened through a specific identifier.

File objects

class h5py.h5f.FileID

Represents an HDF5 file identifier.

These objects wrap a small portion of the H5F interface; all the H5F functions which can take arbitrary objects in addition to file identifiers are provided as functions in the h5f module.

Properties:

• name: File name on disk

Behavior:

• Hashable: Yes, unique to the file (but not the access mode)

• Equality: Hash comparison

close()

Terminate access through this identifier. Note that depending on what property list settings were used to open the file, the physical file might not be closed until all remaining open identifiers are freed.

get_access_plist() → PropFAID

Retrieve a copy of the file access property list which manages access to this file.

get_create_plist() → PropFCID

Retrieve a copy of the file creation property list used to create this file.

get_file_image() → BYTES

Retrieves a copy of the image of an existing, open file.

Feature requires: 1.8.9

get_filesize() → LONG size

Determine the total size (in bytes) of the HDF5 file, including any user block.

get_freespace() → LONG freespace

Determine the amount of free space in this file. Note that this only tracks free space until the file is closed.

get_intent() → INT

Determine the file’s write intent, either of: - H5F_ACC_RDONLY - H5F_ACC_RDWR

get_mdc_config() → CacheConfig Returns an object that stores all the information about the meta-data cache configuration. This config is created for every file in-memory with the default cache config values, it is not saved to the hdf5 file.

get_mdc_hit_rate() → DOUBLE

Retrieve the cache hit rate

get_mdc_size() → max_size, min_clean_size, cur_size, cur_num_entries[SIZE_T, SIZE_T, SIZE_T, INT]

Obtain current metadata cache size data for specified file.

get_mpi_atomicity() → BOOL

Return atomicity setting for MPI-IO driver.

Feature requires: 1.8.9 and Parallel HDF5

get_page_buffering_stats() -> NAMEDTUPLE PageBufStats(NAMEDTUPLE meta=PageStats, NAMEDTUPLE raw=PageStats)

Retrieve page buffering statistics for the file as the number of metadata and raw data accesses, hits, misses, evictions, and accesses that bypass the page buffer (bypasses).

get_vfd_handle(PropFAID) → INT

Retrieve the file handle used by the virtual file driver.

This may not be supported for all file drivers, and the meaning of the return value may depend on the file driver.

The ‘family’ and ‘multi’ drivers access multiple files, and a file access property list (fapl) can be used to indicate which to access, with H5Pset_family_offset or H5Pset_multi_type.

name

File name on disk (according to h5f.get_name())

reopen() → FileID

Retrieve another identifier for a file (which must still be open). The new identifier is guaranteed to neither be mounted nor contain a mounted file.

reset_mdc_hit_rate_stats()

no return

rests the hit-rate statistics

reset_page_buffering_stats()

Reset page buffer statistics for the file.

set_mdc_config(CacheConfig) → None Sets the meta-data cache configuration for a file. This config is created for every file in-memory with the default config values, it is not saved to the hdf5 file. Any change to the configuration lives until the hdf5 file is closed.

set_mpi_atomicity(BOOL atomicity)

For MPI-IO driver, set to atomic (True), which guarantees sequential I/O semantics, or non-atomic (False), which improves performance.

Default is False.

Feature requires: 1.8.9 and Parallel HDF5

start_swmr_write()

no return

Enables SWMR writing mode for a file.

This function will activate SWMR writing mode for a file associated with file_id. This routine will prepare and ensure the file is safe for SWMR writing as follows:

• Check that the file is opened with write access (H5F_ACC_RDWR).

• Check that the file is opened with the latest library format to ensure data structures with check-summed metadata are used.

• Check that the file is not already marked in SWMR writing mode.

• Enable reading retries for check-summed metadata to remedy possible checksum failures from reading inconsistent metadata on a system that is not atomic.

• Turn off usage of the library’s accumulator to avoid possible ordering problem on a system that is not atomic.

• Perform a flush of the file’s data buffers and metadata to set a consistent state for starting SWMR write operations.

Library objects are groups, datasets, and committed datatypes. For the current implementation, groups and datasets can remain open when activating SWMR writing mode, but not committed datatypes. Attributes attached to objects cannot remain open.

Feature requires: 1.9.178 HDF5

Module constants

File access flags

h5py.h5f.ACC_TRUNC

Create/truncate file

h5py.h5f.ACC_EXCL

Create file if it doesn’t exist; fail otherwise

h5py.h5f.ACC_RDWR

Open in read/write mode

h5py.h5f.ACC_RDONLY

Open in read-only mode

File close strength

h5py.h5f.CLOSE_WEAK

h5py.h5f.CLOSE_SEMI

h5py.h5f.CLOSE_STRONG

h5py.h5f.CLOSE_DEFAULT

File scope

h5py.h5f.SCOPE_LOCAL

h5py.h5f.SCOPE_GLOBAL

Object types

h5py.h5f.OBJ_FILE

h5py.h5f.OBJ_DATASET

h5py.h5f.OBJ_GROUP

h5py.h5f.OBJ_DATATYPE

h5py.h5f.OBJ_ATTR

h5py.h5f.OBJ_ALL

h5py.h5f.OBJ_LOCAL

Library version bounding

h5py.h5f.LIBVER_EARLIEST

h5py.h5f.LIBVER_V18

h5py.h5f.LIBVER_V110

h5py.h5f.LIBVER_LATEST