H5Grove

4.0.0 · active · verified Fri Apr 17

h5grove is a Python library providing core utilities to serve HDF5 file contents over a REST API. It allows users to browse and extract data from HDF5 files via HTTP requests, with support for various web frameworks like FastAPI, Flask, and Tornado. The library is actively maintained, with a current version of 4.0.0, and releases new versions regularly, often including breaking changes to improve the API or underlying structure.

Common errors

```
ModuleNotFoundError: No module named 'h5grove'
```
cause The h5grove package has not been installed in your current Python environment.

fix Run `pip install h5grove` to install the core library, or `pip install h5grove[fastapi]` (or other backend) for full functionality.
```
404 Not Found when accessing /attr/ or /data/
```
cause From v3.0.0 onwards, h5grove endpoints no longer use trailing slashes.

fix Update your API client requests to remove trailing slashes from all h5grove endpoints (e.g., change `/attr/` to `/attr`, `/data/` to `/data`).
```
TypeError: 'dict' object is not subscriptable when parsing compound dataset metadata for 'members'
```
cause You are using h5grove v4.0.0+ but your client expects the 'members' key for compound dataset metadata to be an object, not an array.

fix Adjust your client-side code to parse the `members` key as an array rather than an object when requesting `/meta` for compound datasets from a v4.0.0+ h5grove server.
```
RuntimeError: Python version 3.9 is not supported by h5grove version 3.0.0. Minimal version is 3.10.
```
cause Your Python environment does not meet the minimum version requirement for the installed h5grove package.

fix Upgrade your Python environment to version 3.10 or newer. Alternatively, downgrade h5grove to a version compatible with your current Python version (e.g., `pip install 'h5grove<3.0.0'` for Python 3.8/3.9 or `h5grove<2.0.0` for Python 3.7).

Warnings

breaking In v4.0.0, the `/meta` endpoint response schema for compound datasets changed. The `members` key is now an array instead of an object to ensure correct field ordering.
Fix: Update client-side parsing logic for `/meta` endpoint responses involving compound datasets to expect `members` as an array.
breaking In v3.0.0, trailing slashes were removed from all endpoints (e.g., `/attr/` is now `/attr`).
Fix: Update all API calls to remove trailing slashes from endpoint paths. Old endpoints with trailing slashes will result in 404 Not Found errors.
breaking Starting from v3.0.0, Python 3.10 or newer is required.
Fix: Ensure your development and deployment environments are using Python 3.10 or a later version. Older Python versions will cause installation or runtime errors.
breaking In v2.0.0, the `type` field in all entities' metadata was renamed to `kind`, and the `dtype` field for dataset/attribute metadata was replaced with a richer `type` object (e.g., `{dtype: '<f8'}` became `{type: {'class': 1, 'dtype': '<f8', 'size': 8, 'order': 0}}`).
Fix: Adjust client-side code that parses metadata responses to use `kind` instead of `type`, and to handle the new structured `type` object instead of a simple `dtype` string.

Install

pip install h5grove Install core library
pip install h5grove[fastapi] uvicorn Install with FastAPI backend and Uvicorn

Imports

create_app
wrong:
```
from h5grove.backends.fastapi import create_app
```
correct:
```
from h5grove.app import create_app
```
create_app is a universal function in h5grove.app to create a server app for a given backend.

H5GroveConfig

from h5grove.config import H5GroveConfig

Quickstart

This quickstart demonstrates setting up a basic h5grove server using FastAPI and Uvicorn. It mounts the h5grove API at the `/h5grove` path. Ensure you have the `h5grove[fastapi]` and `uvicorn` packages installed, and specify an `H5GROVE_HDF5_DIR` environment variable or directly set `H5GroveConfig.hdf5_dir` to point to a directory containing your HDF5 files. This allows the server to discover and serve them.

import os
from fastapi import FastAPI
from h5grove.app import create_app
from h5grove.config import H5GroveConfig

# Configure the base directory for HDF5 files.
# Replace with a path where your .h5 files are located.
# For a runnable example, ensure a '.h5' file exists here.
H5GroveConfig.hdf5_dir = os.environ.get('H5GROVE_HDF5_DIR', '.')

app = FastAPI()
app.mount("/h5grove", create_app())

# To run this app (requires uvicorn):
# 1. pip install h5grove[fastapi] uvicorn
# 2. Save this code as 'main.py'
# 3. Run from terminal: uvicorn main:app --reload --port 8000
# 4. Access API: http://127.0.0.1:8000/h5grove/

view raw JSON →