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

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

h5py.h5f.CLOSE_WEAK

h5py.h5f.CLOSE_SEMI

h5py.h5f.CLOSE_STRONG

### 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