h5grove reference

content module

Create a content object

h5grove provides the create_content that is a h5py wrapper to get a desired h5py entity. The function handles support link resolution and dataset decompression using hdf5plugin

h5grove.content.create_content(h5file, path, resolve_links=LinkResolution.ONLY_VALID)

Factory function to get entity content from a HDF5 file. This handles external/soft link resolution and dataset decompression.

Parameters:

  • h5file (h5py.File) – An open HDF5 file containing the entity

  • path (str | None) – Path to the entity in the file.

  • resolve_links (LinkResolution) – Tells which external and soft links should be resolved. Defaults to resolving only valid links.

Raises:

  • h5grove.utils.PathError – If the path cannot be found in the file

  • h5grove.utils.LinkError – If a link cannot be resolved when resolve_links is set to LinkResolution.ALL.

  • TypeError – If encountering an unsupported h5py entity

Content object reference

The Content objects returned by create_content hold information to design endpoints.

The Content objects returned by create_content expose the relevant information of the entity through methods:

  • attributes: Only for non-link entities. The dict of attributes.

  • metadata: For all entities. Information on the entities. Includes attribute metadata for non-link entities.

  • data: Only for datasets. Data contained in a dataset or a slice of dataset.

  • data_stats: Only for datasets. Statistics computed on the data of the dataset or a slice of it.

These methods are directly plugged to the endpoints from the example implementations so you can take a look at the endpoints API for more information.

class h5grove.content.ExternalLinkContent(path, link)
Parameters:

  • path (str) –

  • link (h5py.ExternalLink) –

kind = 'external_link'
metadata(depth=None)

External link metadata

Return type:

ExternalLinkMetadata

property name: str

Entity name (last path segment)

property path: str

Path in the file

property target_file: str

The target file of the link

property target_path: str

The target path of the link (in the target file)

class h5grove.content.SoftLinkContent(path, link)
Parameters:

  • path (str) –

  • link (h5py.SoftLink) –

kind = 'soft_link'
metadata(depth=None)

Soft link metadata

Return type:

SoftLinkMetadata

property name: str

Entity name (last path segment)

property path: str

Path in the file

property target_path: str

The target path of the link

class h5grove.content.DatasetContent(path, h5py_entity)
attributes(attr_keys=None)

Attributes of the h5py entity. Can be filtered by keys.

Parameters:

attr_keys (Sequence[str] | None) –

Return type:

dict[str, AttributeMetadata]

data(selection=None, flatten=False, dtype='origin')

Dataset data.

Parameters:
data_stats(selection=None)

Statistics on the data. Providing a selection will compute stats only on the selected slice.

Parameters:

selection (Selection | None) – NumPy-like indexing to define a selection as a slice

Return type:

Stats

kind = 'dataset'
metadata(depth=None)

Dataset metadata

Return type:

DatasetMetadata

property name: str

Entity name (last path segment)

property path: str

Path in the file

class h5grove.content.GroupContent(path, h5py_entity, h5file)
attributes(attr_keys=None)

Attributes of the h5py entity. Can be filtered by keys.

Parameters:

attr_keys (Sequence[str] | None) –

Return type:

dict[str, AttributeMetadata]

kind = 'group'
metadata(depth=1)

Metadata of the group. Recursively includes child metadata if depth > 0.

Parameters:

  • depth (int) – The level of child metadata resolution.

  • depth –

Return type:

GroupMetadata

property name: str

Entity name (last path segment)

property path: str

Path in the file

encoders module

The encoders module contain functions that encode data and provide the appropriate headers to build request responses. The module provides a JSON encoder using orjson, a binary encoder for NumPy arrays and other encoders to serve NumPy arrays as downloadable files.

General

h5grove.encoders.encode(content, encoding='json')

Encode content in given encoding.

Warning: Not all encodings supports all types of content.

Parameters:

  • content (Any) – Content to encode

  • encoding (str | None) –

    • json (default)

    • bin: nD array/scalars in bytes

    • csv: nD arrays in downloadable csv files

    • npy: nD arrays in downloadable npy files

    • tiff: 2D arrays in downloadable TIFF files

Returns:

A Response object containing content and headers

Raises:

QueryArgumentError – If encoding is not among the ones above.

Return type:

Response

class h5grove.encoders.Response(content, headers)
Parameters:

  • content (bytes) –

  • headers (dict[str, str]) –

content: bytes

Encoded content as bytes

headers: dict[str, str]

Associated headers

General

h5grove.encoders.orjson_default(o)

Converts Python objects to JSON-serializable objects.

Raises:

TypeError – if the object is not supported.

Parameters:

o (Any) –

Return type:

list | float | str | None

h5grove.encoders.orjson_encode(content, default=None)

Encode in JSON using orjson.

Param:

content: Content to encode

Parameters:
Return type:

bytes

Binary

h5grove.encoders.bin_encode(array)

Convert array to bytes.

Parameters:

array (ndarray) – Data to convert

Return type:

bytes

File formats

h5grove.encoders.csv_encode(data)

Encodes a NumPy array in CSV.

Param:

data: NumPy array to encode

Parameters:

data (ndarray) –

Return type:

bytes

h5grove.encoders.npy_encode(data)

Encodes a NumPy array in NPY.

Param:

data: NumPy array to encode

Parameters:

data (ndarray) –

Return type:

bytes

h5grove.encoders.tiff_encode(data)

Encodes a NumPy array in TIFF. The data should be 2D.

Param:

data: NumPy array to encode

Parameters:

data (ndarray) –

Return type:

bytes