Internal Design

Welcome to HvPy's design wiki. These pages will be useful for you if you're a developer for HvPy or if you're looking to make changes to it.

Overview

HvPy is a python interface for interacting with Heliovewer's Web API. This means all API calls are done via sending an HTTP request and parsing the response. Since this action is common for all API requests, it is encapsulated by the API core in HvPy. Certain parameters are provided to the core via an instance of HvpyParameters. This instance contains all information necessary to perform the API request. It contains the target URL, the input parameters, and the expected output type. Using this information, the HTTP Requester will be able to perform the request and coerce the result into the desired type.

Input Parameters

In order to handle input validation and to define the parameters for each endpoint, we've chosen to use pydantic to handle definitions for API input parameters.

Every API endpoint has an InputParameters class which inherit HvpyParameters. These classes use pydantic to construct and validate the user's input parameters. These classes are converted into dictionaries via a call to InputParameters.dict() and the resulting dictionary is passed to the requests library to send off the API request.

HvpyParameters defines this dict() function, and defines the interface to be used for all input parameter classes.

Sometimes the output type may change depending on one of the input parameters. To handle this, HvpyParameters defines a function get_output_type() which will return the expected result type. By default, this function will return OutputType.Raw. Subclasses may override this to their desired output type. Options for OutputType follow.

OutputType.Raw

Raw is best used for strings or binary data. The result from the API is given directly to the user. This is expected to be the most common use case.

OutputType.Json

The JSON from the api response will be parsed into a python dictionary representing the json data.

Directory Structure

hvpy
|-- __init__.py             # Exposes API functions and parameter classes
|-- core.py                 # Contains the API Requester which handles all HTTP I/O
|-- io.py                   # Contains the base InputParameters class and OutputType enum
|-- api_groups              # Analogous to the Web API's api groups
    |-- jpeg2000            # Groups JPEG2000 API endpoints together
        |-- get_jp2_image.py  # Contains I/O parameters for getJp2Image
        |-- get_jp2_header.py # Contains I/O parameters for getJp2Header
        |-- etc...
    |-- movies
        |-- queueo_movie.py   # Contains I/O parameters for queueMovie
        |-- etc...
    |-- etc... # See https://api.helioviewer.org/docs/v2/api/index.html for all API groups