File Objects

Opening & creating files

HDF5 files work generally like standard Python file objects. They support standard modes like r/w/a, and should be closed when they are no longer in use. However, there is obviously no concept of “text” vs “binary” mode.

>>> f = h5py.File('myfile.hdf5','r')

The file name may be a byte string or unicode string. Valid modes are:

r Readonly, file must exist
r+ Read/write, file must exist
w Create file, truncate if exists
w- Create file, fail if exists
a Read/write if exists, create otherwise (default)

File drivers

HDF5 ships with a variety of different low-level drivers, which map the logical HDF5 address space to different storage mechanisms. You can specify which driver you want to use when the file is opened:

>>> f = h5py.File('myfile.hdf5', driver=<driver name>, <driver_kwds>)

For example, the HDF5 “core” driver can be used to create a purely in-memory HDF5 file, optionally written out to disk when it is closed. Here’s a list of supported drivers and their options:

None
Strongly recommended. Use the standard HDF5 driver appropriate for the current platform. On UNIX, this is the H5FD_SEC2 driver; on Windows, it is H5FD_WINDOWS.
‘sec2’
Unbuffered, optimized I/O using standard POSIX functions.
‘stdio’
Buffered I/O using functions from stdio.h.
‘core’

Memory-map the entire file; all operations are performed in memory and written back out when the file is closed. Keywords:

backing_store: If True (default), save changes to a real file
when closing. If False, the file exists purely in memory and is discarded when closed.
block_size: Increment (in bytes) by which memory is extended.
Default is 64k.
‘family’

Store the file on disk as a series of fixed-length chunks. Useful if the file system doesn’t allow large files. Note: the filename you provide must contain a printf-style integer format code (e.g. %d”), which will be replaced by the file sequence number. Keywords:

memb_size: Maximum file size (default is 2**31-1).

Version Bounding

HDF5 has been evolving for many years now. By default, the library will write objects in the most compatible fashion possible, so that older versions will still be able to read files generated by modern programs. However, there can be performance advantages if you are willing to forgo a certain level of backwards compatibility. By using the “libver” option to File, you can specify the minimum and maximum sophistication of these structures:

>>> f = h5py.File('name.hdf5', libver='earliest') # most compatible
>>> f = h5py.File('name.hdf5', libver='latest')   # most modern

Here “latest” means that HDF5 will always use the newest version of these structures without particular concern for backwards compatibility. The “earliest” option means that HDF5 will make a best effort to be backwards compatible.

The default is “earliest”.

Reference

In addition to the properties and methods defined here, File objects inherit the full API of Group objects; in this case, the group in question is the root group (/) of the file.

Note

Please note that unlike Python file objects, the attribute File.name does not refer to the file name on disk. File.name gives the HDF5 name of the root group, “/”. To access the on-disk name, use File.filename.

class h5py.File(name, mode=None, driver=None, libver=None, **kwds)

Represents an HDF5 file.

__init__(name, mode=None, driver=None, libver=None, **kwds)

Create a new file object.

See the h5py user guide for a detailed explanation of the options.

name
Name of the file on disk. Note: for files created with the ‘core’ driver, HDF5 still requires this be non-empty.
driver
Name of the driver to use. Legal values are None (default, recommended), ‘core’, ‘sec2’ (UNIX), ‘stdio’.
libver
Library version bounds. Currently only the strings ‘earliest’ and ‘latest’ are defined.
Additional keywords
Passed on to the selected file driver.

File properties

filename

File name on disk

mode

Python mode used to open file

driver

Low-level HDF5 file driver used to open file

libver

File format version bounds (2-tuple: low, high)

File methods

close()

Close the file. All open objects become invalid

flush()

Tell the HDF5 library to flush its buffers.

Properties common to all HDF5 objects:

file

Return a File instance associated with this object

parent

Return the parent group of this object.

This is always equivalent to obj.file[posixpath.dirname(obj.name)]. ValueError if this object is anonymous.

name

Return the full name of this object. None if anonymous.

id

Low-level identifier appropriate for this object

ref

An (opaque) HDF5 reference to this object

attrs

Attributes attached to this object

Table Of Contents

Previous topic

High-Level Reference

Next topic

Group Objects

This Page