Integration in an existing application

h5grove endpoints (see API here) can be added to existing FastAPI, Flask or Tornado applications.

FastAPI

The module fastapi_utils contains utilities dedicated to FastAPI backends. It provides a APIRouter that can be included in an existing FastAPI application:

from fastapi import FastAPI
from h5grove.fastapi_utils import router, settings

app = FastAPI()

...

# Configure base directory from which the HDF5 files will be served
settings.base_dir = os.path.abspath(options.basedir)

app.include_router(router)

fastapi_utils reference

Helpers for usage with FastAPI

async h5grove.fastapi_utils.get_attr(file=Depends(add_base_path), path='/', attr_keys=Query(None))

/attr/ endpoint handler

Parameters:

  • file (str) –

  • path (str) –

  • attr_keys (list[str] | None) –

async h5grove.fastapi_utils.get_data(file=Depends(add_base_path), path='/', dtype='origin', format='json', flatten=False, selection=None)

/data/ endpoint handler

Parameters:

  • file (str) –

  • path (str) –

  • dtype (str) –

  • format (str) –

  • flatten (bool) –

async h5grove.fastapi_utils.get_meta(file=Depends(add_base_path), path='/', resolve_links='only_valid')

/meta/ endpoint handler

Parameters:

  • file (str) –

  • path (str) –

  • resolve_links (str) –

async h5grove.fastapi_utils.get_root()

/ endpoint handler to check server status

async h5grove.fastapi_utils.get_stats(file=Depends(add_base_path), path='/', selection=None)

/stats/ endpoint handler

Parameters:

  • file (str) –

  • path (str) –

h5grove.fastapi_utils.router = <fastapi.routing.APIRouter object>

FastAPI router with h5grove endpoints.

The directory from which files are served can be defined in settings.

Parameters:

  • scope (Scope) –

  • receive (Receive) –

  • send (Send) –

Return type:

None

h5grove.fastapi_utils.settings = Settings(base_dir=None)

Settings where base_dir can be defined

Flask

The module flask_utils contains utilities dedicated to Flask backends. It provides a Blueprint that can be registered to an existing Flask application:

from flask import Flask
from h5grove.flask_utils import BLUEPRINT

app = Flask(__name__)

...

# Configure base directory from which the HDF5 files will be served
app.config["H5_BASE_DIR"] = os.path.abspath(options.basedir)

app.register_blueprint(BLUEPRINT)

flask_utils reference

Helpers for usage with Flask

h5grove.flask_utils.BLUEPRINT = <Blueprint 'h5grove'>

Blueprint of h5grove endpoints.

It relies on H5_BASE_DIR being defined in the app config.

h5grove.flask_utils.URL_RULES = {'/': <function root_route>, '/attr/': <function attr_route>, '/data/': <function data_route>, '/meta/': <function meta_route>, '/paths/': <function paths_route>, '/stats/': <function stats_route>}

Mapping of Flask URL endpoints to handlers

h5grove.flask_utils.attr_route()

/attr/ endpoint handler

h5grove.flask_utils.data_route()

/data/ endpoint handler

h5grove.flask_utils.meta_route()

/meta/ endpoint handler

h5grove.flask_utils.root_route()

/ endpoint handler to check server status

h5grove.flask_utils.stats_route()

/stats/ endpoint handler

Tornado

The module tornado_utils contains utilities dedicated to Tornado backends. It provides a get_handlers function to construct handlers that can be passed directly to a Tornado application:

import tornado.web
from h5grove.tornado_utils import get_handlers

# The base directory from which the HDF5 files will be served is passed as argument of the function
h5grove_handlers = get_handlers(base_dir, allow_origin="*")

# On construction
app = tornado.web.Application(h5grove_handlers)

# Or using `add_handlers`
app.add_handlers(h5grove_handlers)

tornado_utils reference

Helpers for usage with Tornado

class h5grove.tornado_utils.AttributeHandler(application, request, **kwargs)

/attr/ endpoint handler

Parameters:

  • application (Application) –

  • request (HTTPServerRequest) –

  • kwargs (Any) –

class h5grove.tornado_utils.BaseHandler(application, request, **kwargs)

Base class for h5grove handlers

Parameters:

  • application (Application) –

  • request (HTTPServerRequest) –

  • kwargs (Any) –

initialize(base_dir, allow_origin=None)
Parameters:

  • base_dir (str) –

  • allow_origin (str | None) –

Return type:

None

prepare()

Called at the beginning of a request before get/post/etc.

Override this method to perform common initialization regardless of the request method.

Asynchronous support: Use async def or decorate this method with .gen.coroutine to make it asynchronous. If this method returns an Awaitable execution will not proceed until the Awaitable is done.

New in version 3.1: Asynchronous support.

write_error(status_code, **kwargs)

Override to implement custom error pages.

write_error may call write, render, set_header, etc to produce output as usual.

If this error was caused by an uncaught exception (including HTTPError), an exc_info triple will be available as kwargs["exc_info"]. Note that this exception may not be the “current” exception for purposes of methods like sys.exc_info() or traceback.format_exc.

Parameters:

  • status_code (int) –

  • kwargs (Any) –

Return type:

None

class h5grove.tornado_utils.DataHandler(application, request, **kwargs)

/data/ endpoint handler

Parameters:

  • application (Application) –

  • request (HTTPServerRequest) –

  • kwargs (Any) –

class h5grove.tornado_utils.MetadataHandler(application, request, **kwargs)

/meta/ endpoint handler

Parameters:

  • application (Application) –

  • request (HTTPServerRequest) –

  • kwargs (Any) –

class h5grove.tornado_utils.RootHandler(application, request, **kwargs)

/ endpoint handler to check server status

Parameters:

  • application (Application) –

  • request (HTTPServerRequest) –

  • kwargs (Any) –

class h5grove.tornado_utils.StatisticsHandler(application, request, **kwargs)

/stats/ endpoint handler

Parameters:

  • application (Application) –

  • request (HTTPServerRequest) –

  • kwargs (Any) –

h5grove.tornado_utils.get_handlers(base_dir, allow_origin=None)

Build h5grove handlers (/, /attr/, /data/, /meta/ and /stats/).

Parameters:

  • base_dir (str | None) – Base directory from which the HDF5 files will be served

  • allow_origin (str | None) – Allowed origins for CORS

Return type:

List[Tuple[str, BaseHandler, dict]]