ch5mpy.File

class ch5mpy.File(*args, **kwargs)[source]

A subclass of h5py.File that implements pickling.

Create a new Group object by binding to a low-level GroupID.

Attributes

`File.attrs`	Attributes attached to this object
`File.driver`	Low-level HDF5 file driver used to open file
`File.file`	Return a File instance associated with this object
`File.file_info`
`File.filename`	File name on disk
`File.id`	Low-level identifier appropriate for this object
`File.libver`	low, high)
`File.meta_block_size`	Meta block size (in bytes)
`File.mode`	Python mode used to open file
`File.name`	Return the full name of this object.
`File.parent`	Return the parent group of this object.
`File.ref`	An (opaque) HDF5 reference to this object
`File.regionref`	Create a region reference (Datasets only).
`File.swmr_mode`	Controls single-writer multiple-reader mode
`File.userblock_size`	User block size (in bytes)

Methods

`File.__init__`	Create a new Group object by binding to a low-level GroupID.
`File.build_virtual_dataset`	Assemble a virtual dataset in this group.
`File.clear`
`File.close`	Close the file.
`File.copy`	Copy an object or group.
`File.create_dataset`	Create and return a new Dataset.
`File.create_dataset_like`	Create a dataset similar to other.
`File.create_group`	Create and return a new subgroup.
`File.create_virtual_dataset`	Create a new virtual dataset in this group.
`File.flush`	Tell the HDF5 library to flush its buffers.
`File.get`	Retrieve an item or other information.
`File.items`	Get a view object on member items
`File.keys`	Get a view object on member names
`File.move`	Move a link to a new location in the file.
`File.pop`	If key is not found, d is returned if given, otherwise KeyError is raised.
`File.popitem`	as a 2-tuple; but raise KeyError if D is empty.
`File.require_dataset`	Open a dataset, creating it if it doesn't exist.
`File.require_group`	Return a group, creating it if it doesn't exist.
`File.setdefault`
`File.update`	If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v
`File.values`	Get a view object on member objects
`File.visit`	Recursively visit all names in this group and subgroups (HDF5 1.8).
`File.visititems`	Recursively visit names and objects in this group (HDF5 1.8).

Parameters:

args (Any) –
kwargs (Any) –

Return type:

File

Attributes

File.attrs

File.driver

Low-level HDF5 file driver used to open file

File.file

File.file_info

File.filename

File name on disk

File.id

Low-level identifier appropriate for this object

File.libver

low, high)

Type:

File format version bounds (2-tuple

File.meta_block_size

Meta block size (in bytes)

File.mode

File.name

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

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

File.ref

An (opaque) HDF5 reference to this object

File.regionref

Create a region reference (Datasets only).

The syntax is regionref[<slices>]. For example, dset.regionref[…] creates a region reference in which the whole dataset is selected.

Can also be used to determine the shape of the referenced dataset (via .shape property), or the shape of the selection (via the .selection property).

File.swmr_mode

Controls single-writer multiple-reader mode

File.userblock_size

User block size (in bytes)

Methods

File.__init__(*args, **kwargs)[source]

Create a new Group object by binding to a low-level GroupID.

Parameters:

args (Any) –

kwargs (Any) –
File.build_virtual_dataset(name, shape, dtype, maxshape=None, fillvalue=None)
Assemble a virtual dataset in this group.

This is used as a context manager:
with f.build_virtual_dataset('virt', (10, 1000), np.uint32) as layout:
    layout[0] = h5py.VirtualSource('foo.h5', 'data', (1000,))
name
(str) Name of the new dataset

shape
(tuple) Shape of the dataset

dtype
A numpy dtype for data read from the virtual dataset

maxshape
(tuple, optional) Maximum dimensions if the dataset can grow. Use None for unlimited dimensions.

fillvalue
The value used where no data is available.
File.clear() → None. Remove all items from D.

File.close()[source]

Close the file. All open objects become invalid
File.copy(source, dest, name=None, shallow=False, expand_soft=False, expand_external=False, expand_refs=False, without_attrs=False)
Copy an object or group.

The source can be a path, Group, Dataset, or Datatype object. The destination can be either a path or a Group object. The source and destinations need not be in the same file.

If the source is a Group object, all objects contained in that group will be copied recursively.

When the destination is a Group object, by default the target will be created in that group with its current name (basename of obj.name). You can override that by setting “name” to a string.

There are various options which all default to “False”:

shallow: copy only immediate members of a group.

expand_soft: expand soft links into new objects.

expand_external: expand external links into new objects.

expand_refs: copy objects that are pointed to by references.

without_attrs: copy object without copying attributes.

Example
>>> f = File('myfile.hdf5', 'w')
>>> f.create_group("MyGroup")
>>> list(f.keys())
['MyGroup']
>>> f.copy('MyGroup', 'MyCopy')
>>> list(f.keys())
['MyGroup', 'MyCopy']
File.create_dataset(name, shape=None, dtype=None, data=None, **kwds)

Create and return a new Dataset.

Parameters:

name (Optional[str]) – Name of the dataset (absolute or relative). Provide None to make an anonymous dataset.

shape (Union[int, tuple, tuple[Optional[int], ...], None] (default: None)) – Dataset shape. Use “()” for scalar datasets. Required if “data” isn’t provided.

dtype (Union[dtype[Any], None, type[Any], _SupportsDType[dtype[Any]], str, tuple[Any, int], tuple[Any, Union[SupportsIndex, Sequence[SupportsIndex]]], list[Any], _DTypeDict, tuple[Any, Any]] (default: None)) – Numpy dtype or string. If omitted, dtype(‘f’) will be used. Required if “data” isn’t provided; otherwise, overrides data array’s dtype.

data (Optional[Collection[Any]] (default: None)) – Provide data to initialize the dataset. If used, you can omit shape and dtype arguments.

kwds (Any) – other arguments to pass to the dataset creation function.

Return type:

Dataset[Any]

File.create_dataset_like(name, other, **kwupdate)

Create a dataset similar to other.

name
Name of the dataset (absolute or relative). Provide None to make an anonymous dataset.

other
The dataset which the new dataset should mimic. All properties, such as shape, dtype, chunking, … will be taken from it, but no data or attributes are being copied.

Any dataset keywords (see create_dataset) may be provided, including shape and dtype, in which case the provided values take precedence over those from other.

File.create_group(name, track_order=None, overwrite=False)

Create and return a new subgroup.

Parameters:

name (str) – may be absolute or relative. Fails if the target name already exists.

track_order (Optional[bool] (default: None)) – Track dataset/group/attribute creation order under this group if True. If None use global default h5.get_config().track_order.

overwrite (bool (default: False)) – overwrite group if it already exists ?

Return type:

Group

File.create_virtual_dataset(name, layout, fillvalue=None)

Create a new virtual dataset in this group.

See virtual datasets in the docs for more information.

name
(str) Name of the new dataset

layout
(VirtualLayout) Defines the sources for the virtual dataset

fillvalue
The value to use where there is no data.

File.flush()[source]

Tell the HDF5 library to flush its buffers.
File.get(name, default=None, getclass=False, getlink=False)
Retrieve an item or other information.

Return type:

Any

Parameters:

name (str) –

default (Any | None) –

getclass (bool) –

getlink (bool) –

“name” given only:
Return the item, or “default” if it doesn’t exist

“getclass” is True:
Return the class of object (Group, Dataset, etc.), or “default” if nothing with that name exists

“getlink” is True:
Return HardLink, SoftLink or ExternalLink instances. Return “default” if nothing with that name exists.

“getlink” and “getclass” are True:
Return HardLink, SoftLink and ExternalLink classes. Return “default” if nothing with that name exists.

Example:
>>> cls = group.get('foo', getclass=True)
>>> if cls == SoftLink:
File.items()

Get a view object on member items

Return type:

ItemsViewHDF5[str, Union[Group, Dataset[Any]]]

File.keys()

Get a view object on member names

File.move(source, dest)

Move a link to a new location in the file.

If “source” is a hard link, this effectively renames the object. If “source” is a soft or external link, the link itself is moved, with its value unmodified.

File.pop(k[, d]) → v, remove specified key and return the corresponding value.

If key is not found, d is returned if given, otherwise KeyError is raised.

File.popitem() → (k, v), remove and return some (key, value) pair

as a 2-tuple; but raise KeyError if D is empty.

File.require_dataset(name, shape, dtype, exact=False, **kwds)

Open a dataset, creating it if it doesn’t exist.

If keyword “exact” is False (default), an existing dataset must have the same shape and a conversion-compatible dtype to be returned. If True, the shape and dtype must match exactly.

If keyword “maxshape” is given, the maxshape and dtype must match instead.

If any of the keywords “rdcc_nslots”, “rdcc_nbytes”, or “rdcc_w0” are given, they will be used to configure the dataset’s chunk cache.

Other dataset keywords (see create_dataset) may be provided, but are only used if a new dataset is to be created.

Raises TypeError if an incompatible object already exists, or if the shape, maxshape or dtype don’t match according to the above rules.

File.require_group(name)

Return a group, creating it if it doesn’t exist.

TypeError is raised if something with that name already exists that isn’t a group.

Return type:

Group

Parameters:

name (str) –

File.setdefault(k[, d]) → D.get(k,d), also set D[k]=d if k not in D

File.update([E, ]**F) → None. Update D from mapping/iterable E and F.

If E present and has a .keys() method, does: for k in E: D[k] = E[k] If E present and lacks .keys() method, does: for (k, v) in E: D[k] = v In either case, this is followed by: for k, v in F.items(): D[k] = v

File.values()

Get a view object on member objects

Return type:

ValuesViewHDF5[Union[Group, Dataset[Any]]]
File.visit(func)
Recursively visit all names in this group and subgroups (HDF5 1.8).

You supply a callable (function, method or callable object); it will be called exactly once for each link in this group and every group below it. Your callable must conform to the signature:

func(<member name>) => <None or return value>

Returning None continues iteration, returning anything else stops and immediately returns that value from the visit method. No particular order of iteration within groups is guaranteed.

Example:
>>> # List the entire contents of the file
>>> f = File("foo.hdf5")
>>> list_of_names = []
>>> f.visit(list_of_names.append)
File.visititems(func)

Recursively visit names and objects in this group (HDF5 1.8).

You supply a callable (function, method or callable object); it will be called exactly once for each link in this group and every group below it. Your callable must conform to the signature:

func(<member name>, <object>) => <None or return value>

Returning None continues iteration, returning anything else stops and immediately returns that value from the visit method. No particular order of iteration within groups is guaranteed.

Example:

# Get a list of all datasets in the file >>> mylist = [] >>> def func(name, obj): … if isinstance(obj, Dataset): … mylist.append(name) … >>> f = File(‘foo.hdf5’) >>> f.visititems(func)