Metadata-Version: 2.4
Name: hapiclient
Version: 0.3.2
Summary: Client for Heliophysics API servers
Author-email: Bob Weigel <rweigel@gmu.edu>
License: Copyright 2019- R.S. Weigel
        
        Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
        
        1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
        
        2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
        
        3. Neither the name of the copyright holder nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.
        
        THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
Project-URL: Homepage, http://pypi.python.org/pypi/hapiclient/
Requires-Python: >=3.5
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: joblib
Requires-Dist: urllib3
Requires-Dist: numpy>=1.14.3; python_version >= "3.6"
Requires-Dist: pandas>=0.23; python_version >= "3.6"
Requires-Dist: isodate>=0.6.0; python_version >= "3.6"
Requires-Dist: numpy<1.17; python_version == "3.5"
Requires-Dist: pandas<1.0; python_version == "3.5"
Requires-Dist: isodate<0.7.0,>=0.6.0; python_version == "3.5"
Requires-Dist: kiwisolver<=1.2; python_version == "3.6"
Provides-Extra: dev
Requires-Dist: deepdiff; extra == "dev"
Requires-Dist: pytest; python_version >= "3.6" and extra == "dev"
Requires-Dist: pytest<5.0.0; python_version == "3.5" and extra == "dev"
Dynamic: license-file

[![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). See also
* 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).
* [PyHC Summer School tutorials](https://github.com/hapi-server/tutorial-python)

# 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

```python
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.
