Filters

A column’s storage pipeline, mirroring HDF5’s chunk filter pipeline. The filters and storage chapter covers usage and the hdf5plugin ecosystem.

class h5col.FilterPipeline(filters: Iterable[Any] = ())

An ordered, immutable sequence of Filter entries.

Accepts Filter instances and hdf5plugin filter objects, adapting the latter automatically.

Raises:

FilterError – If an entry is neither a Filter nor an hdf5plugin filter.

apply(dcpl: Any) → None

Add every filter, in order, to an HDF5 dataset-creation property list.

to_h5py_kwargs() → dict[str, Any]

Map the pipeline to h5py high-level create_dataset keyword arguments.

h5py’s high-level dataset API is the only creation path that sets fill values correctly for every dtype (its low-level set_fill_value is broken for fixed-length strings), so column creation goes through it. The builtin shuffle/fletcher32 filters map to their boolean keywords and the single remaining compressor maps to compression / compression_opts.

Raises FilterError if the pipeline needs more than one compressor filter, which the high-level API cannot express (combine them into a Blosc/Blosc2 meta-compressor, or drive the low-level DCPL via apply()).

class h5col.Filter(plugin_id: int, cd_values: tuple[int, ...] = (), optional: bool = False, name: str = '')

One entry of a filter pipeline.

Parameters:

• plugin_id (int) – The registered HDF5 filter plugin identifier. A filter plugin is the piece of software that connects the HDF5 library to the code that actually filters a chunk’s bytes.

• cd_values (tuple[int, ...]) – Client data (the filter’s unsigned-int parameters), in order.

• optional (bool) – If True, HDF5 may skip the filter for a chunk it cannot process instead of failing the write (the H5Z_FLAG_OPTIONAL flag).

• name (str) – Human-readable label (informational only).

property flags: int

The HDF5 filter flags for this entry.

h5col.Deflate(level: int = 4) → Filter

The built-in deflate compression filter (HDF5’s H5Z_FILTER_DEFLATE).

Parameters:

level – Compression level, 0–9 (default 4).

Raises:

FilterError – If level is outside 0–9.

h5col.Shuffle() → Filter

The built-in byte-shuffle filter.

h5col.Fletcher32() → Filter

The built-in Fletcher-32 checksum filter.

h5col.from_hdf5plugin(obj: Any) → Filter

Adapt an hdf5plugin filter instance to a Filter.

hdf5plugin filter objects behave like mappings of h5py create_dataset keyword arguments (compression = filter id, compression_opts = client data) and expose a filter_id attribute.

Raises:

FilterError – If obj cannot be interpreted as an hdf5plugin filter or carries no filter id.