# OpenAQ Python SDK

The official Python SDK for the OpenAQ API.

[![PyPI - Version](https://img.shields.io/pypi/v/openaq.svg)](https://pypi.org/project/openaq)
[![PyPI - Python Version](https://img.shields.io/pypi/pyversions/openaq.svg)](https://pypi.org/project/openaq)
![Codecov](https://img.shields.io/codecov/c/github/openaq/openaq-python)
![Static Badge](https://img.shields.io/badge/type%20checked-mypy-039dfc)
[![Ruff](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/astral-sh/ruff/main/assets/badge/v2.json)](https://github.com/astral-sh/ruff)
[![slack](https://img.shields.io/badge/Slack-OpenAQ-blue?logo=slack&color=%23198cff
)](https://join.slack.com/t/openaq/shared_invite/zt-yzqlgsva-v6McumTjy2BZnegIK9XCVw)

-----

## Table of Contents

- [Installation](#installation)
- [License](#license)
- [Documentation](#documentation)
- [Development](#development)

## Installation

The OpenAQ Python SDK is available on [PyPI](https://pypi.org/project/openaq/).

```console
pip install openaq
```

## Documentation

Documentation available at [python.openaq.org](https://python.openaq.org)

Information on building documentation site locally can be found in [docs/README.md](./docs/README.md)

## License

The source code is distributed under the terms of the [Apache 2.0](https://www.apache.org/licenses/LICENSE-2.0.txt) license.

## Development

Code is linted using [ruff](https://github.com/astral-sh/ruff).

Codebase can be automatically formatted and linted by running:

```console
hatch run style:fmt
```

style can be checked with:

```console
hatch run style:check
```

[mypy](https://mypy-lang.org/) static type checking:

```console
hatch run types:check
```

Testing uses [pytest](https://docs.pytest.org/en/7.4.x/).

```console
hatch run test:test
```

## Acknowledgements

For many years [py-openaq](https://github.com/dhhagan/py-openaq) by David Hagan
filled the gap for a Python API SDK for the OpenAQ API. Thank you to David for
many years of maintaining py-openaq and for taking the original step to develop
a Python tool for OpenAQ.