Metadata-Version: 2.4
Name: hapiclient
Version: 0.2.7
Summary: Interface to Heliophysics data server API
Home-page: http://pypi.python.org/pypi/hapiclient/
Author: Bob Weigel
Author-email: rweigel@gmu.edu
License: LICENSE.txt
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: urllib3
Requires-Dist: joblib
Requires-Dist: isodate>=0.6.0
Requires-Dist: pandas>=0.23
Requires-Dist: numpy>=1.14.3
Dynamic: author
Dynamic: author-email
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: license
Dynamic: license-file
Dynamic: requires-dist
Dynamic: summary

[![DOI](https://zenodo.org/badge/93170857.svg)](https://zenodo.org/badge/latestdoi/93170857)
[![Build Status](https://app.travis-ci.com/hapi-server/client-python.svg?branch=master)](https://app.travis-ci.com/hapi-server/client-python)

**HAPI Client for Python**

Basic usage examples for various HAPI servers are given in [hapi_demo.py](https://github.com/hapi-server/client-python/blob/master/hapi_demo.py) and the Examples section of a Jupyter Notebook hosted on Google Colab: [![Open In Colab](https://colab.research.google.com/assets/colab-badge.svg)](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb#examples).

# Installation

```bash
pip install hapiclient --upgrade
# or
pip install 'git+https://github.com/hapi-server/client-python' --upgrade
```

The optional [hapiplot package](https://github.com/hapi-server/plot-python) provides basic preview plotting capabilities of data from a HAPI server. The [Plotting section](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb#plotting) of the `hapiclient` Jupyter Notebook shows how to plot the output of `hapiclient` using many other plotting libraries.

To install `hapiplot`, use

```bash
python -m pip install hapiplot --upgrade
# or
python -m pip install 'git+https://github.com/hapi-server/plot-python' --upgrade
```

See the [Appendix](#appendix) for a fail-safe installation method.

# Basic Example

```python
# Get Dst index from CDAWeb HAPI server
from hapiclient import hapi

# See http://hapi-server.org/servers/ for a list of
# other HAPI servers and datasets.
server     = 'https://cdaweb.gsfc.nasa.gov/hapi'
dataset    = 'OMNI2_H0_MRG1HR'
start      = '2003-09-01T00:00:00'
stop       = '2003-12-01T00:00:00'
parameters = 'DST1800'
opts       = {'logging': True}
# See misc/hapi_logging_demo.py for example of using conventional Python logging.

# Get data
data, meta = hapi(server, dataset, parameters, start, stop, **opts)
print(meta)
print(data)

# Plot all parameters
from hapiplot import hapiplot
hapiplot(data, meta)
```

# Documentation

Basic usage examples for various HAPI servers are given in [hapi_demo.py](https://github.com/hapi-server/client-python/blob/master/hapi_demo.py>) and the [Examples section](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb#examples) of a Jupyter Notebook hosted on Google Colab.

See http://hapi-server.org/servers/ for a list of HAPI servers and datasets.

All of the features are extensively demonstrated in [hapi_demo.ipynb](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb#data-model), a Jupyter Notebook that can be viewed an executed on Google Colab.

# Metadata Model

See also the examples in the [Metadata Model section](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb) of the `hapiclient` Jupyter Notebook.

The HAPI client metadata model is intentionally minimal and closely follows that of the [HAPI metadata model](https://github.com/hapi-server/data-specification). We expect that another library will be developed that allows high-level search and grouping of information from HAPI servers. See also [issue #106](https://github.com/hapi-server/data-specification/issues/106).

# Data Model and Time Format

See also the examples in the [Data Model section](https://colab.research.google.com/github/hapi-server/client-python-notebooks/blob/master/hapi_demo.ipynb) of the `hapiclient` Jupyter Notebook. The examples include 

1. Fast and well-tested conversion from ISO 8601 timestamp strings to Python `datetime` objects
2. Putting the content of `data` in a Pandas `DataFrame` object
3. Creating an Astropy NDArray

A request for data of the form
```
data, meta = hapi(server, dataset, parameters, start, stop)
```

returns the [Numpy N-D array](https://docs.scipy.org/doc/numpy-1.15.1/user/quickstart.html) `data` and a Python dictionary `meta` from a HAPI-compliant data server `server`. The structure of `data` and `meta` mirrors the structure of a response from a HAPI server.

The HAPI client data model is intentionally basic. There is an ongoing discussion of a data model for Heliophysics data among the [PyHC community](https://heliopython.org/). When this data model is complete, a function that converts `data` and `meta` to that data model will be included in the `hapiclient` package.

# Development and Testing

## Testing Python versions available with tox-env

As of 2026-04-14, Python 3.8+ is available with tox-env.

```bash
git clone https://github.com/hapi-server/client-python
cd client-python; python -m pip install -e .

# Run a specific test on current Python version (default is log_level=INFO
# for hapiclient logger and test logger when executed this way).
python test/test_hapi_data_requests.py

# Run a specific test on a specific Python version with all logging
tox -e py311 -- test/test_hapi_data_requests.py
# Set log level for test logger
tox -e py311 -- test/test_hapi_data_requests.py --log-level=INFO

# Run a specific test on all Python versions set by tox.ini `envlist`
tox -- test/test_hapi_data_requests.py

# Run all tests in ./test
tox

# Run long-running tests
tox -e long-test

# Run long-running tests on a specific Python version
tox -e long-test --override testenv:long-test.basepython=python3.11
```

## Testing Python versions available with Anaconda

As of 2026-04-14, Python 3.5+ is available with Anaconda.

```bash
git clone https://github.com/hapi-server/client-python
cd client-python; python -m pip install -e .
```

or, create an isolated Anaconda installation (downloads and installs latest Miniconda3) using

``` bash
make install PYTHON=python3.6
# Execute command displayed to activate isolated environment
```

The command `pip install -e .` creates symlinks so that the local package is
used instead of an installed package. You may need to execute `python -m pip uninstall hapiclient` to ensure the local package is used. To check the version installed, use `python -m pip list | grep hapiclient`.

To run tests before a commit, execute

```bash
make repository-test
```

To run an individual unit test in a Python session, use, e.g.,

```bash
cd test; python test_hapitime_reformat.py
```

# Contact

Submit bug reports and feature requests on the [repository issue
tracker](https://github.com/hapi-server/client-python/issues>).

Before submitting a pull request, please post an issue with the proposed changes for discussion prior to developing the pull request.
