Metadata-Version: 2.4
Name: dhis2eo
Version: 1.2.1
Summary: DHIS2 Earth Observation Toolkit
Author: DHIS2
License-Expression: BSD-3-Clause
Project-URL: Repository, https://github.com/dhis2/dhis2eo
Project-URL: Documentation, https://github.com/dhis2/dhis2eo#readme
Keywords: dhis2,hisp,climate,earth-observation,geospatial,xarray
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Intended Audience :: Science/Research
Classifier: Topic :: Scientific/Engineering :: GIS
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: earthkit-data[cds,geopandas,geotiff,netcdf,projection]==0.16.*
Requires-Dist: ecmwf-datastores-client==0.4.*
Requires-Dist: xarray<2026,>=2025.6
Requires-Dist: rioxarray==0.19.*
Requires-Dist: pandas<3,>=2.3
Requires-Dist: geopandas<2,>=1.1
Requires-Dist: numpy<3,>=2.2
Requires-Dist: zarr<4,>=3.1
Requires-Dist: aiohttp<4,>=3.13
Requires-Dist: requests<3,>=2.32
Provides-Extra: dev
Requires-Dist: build<2,>=1.2; extra == "dev"
Requires-Dist: pytest<9,>=8.0; extra == "dev"
Requires-Dist: ruff==0.14.*; extra == "dev"
Dynamic: license-file

# dhis2eo

[![Test status](https://github.com/dhis2/dhis2eo/actions/workflows/tests.yml/badge.svg)](https://github.com/dhis2/dhis2eo/actions/workflows/tests.yml)
[![Latest version](https://img.shields.io/github/v/release/dhis2/dhis2eo)](https://github.com/dhis2/dhis2eo/releases)

Dhis2eo is a small, focused Python library for DHIS2 users who want to integrate earth observation and climate data into their workflows. It provides lightweight helpers and tools bridging the Python geoscience and DHIS2 ecosystems.

---

## What is dhis2eo?

The purpose of dhis2eo is to help DHIS2 users incorporate earth observation and climate data into their workflows without adding unnecessary complexity. It focuses on the intersection of DHIS2 and geoscience rather than trying to be a full earth observation library.

Key points about dhis2eo:

- **Integration with earth observation tools**:
  Dhis2eo is a thin utility layer that connects DHIS2 workflows with climate data sources and geospatial libraries like **xarray** and **earthkit**. It provides helpers for common climate and earth observation tasks while avoiding the overhead of a full-featured earth observation or geospatial library.

- **Generic functionality across local and national contexts**:
  Dhis2eo is designed to provide generic solutions for DHIS2 users worldwide, while also allowing users to extract and work with data relevant to specific country contexts.

- **Data translation for DHIS2**:
  Dhis2eo supports translating between DHIS2 and earth observation domains, including conversion of data formats and values. It is not meant for general interaction with DHIS2; for that, use the separately maintained [dhis2-python-client](https://github.com/dhis2/dhis2-python-client).

## Design philosophy

More generally, dhis2eo as a library is meant to be:
- Easy to read
- Easy to run
- Easy to maintain
- Easy to integrate into other projects

This leads to a few guiding principles:

- **Fewer things over more things**:
  Every new function, dependency, or tool has a long-term cost.

- **Core libraries over wrappers**:
  If something can be done directly with xarray, earthkit, or standard Python, we usually prefer that over adding a dhis2eo wrapper.

- **Keep it simple**:
  Code should be short, easy to read, debug, and explain to someone new to the project.

- **Lightweight Python tooling**:
  The project is designed to be easy for developers to install, test, and run, with minimal extra dependencies and broad support across operating systems and Python versions.

These principles help keep the project approachable and durable over time.

---

## Installation

Install the latest released version from PyPI:

```bash
pip install dhis2eo
```

To test unreleased changes directly from GitHub:

```bash
pip install git+https://github.com/dhis2/dhis2eo
```

For contributors (to get linting and testing tools):

```bash
pip install -e ".[dev]"
```

## Running tests

Tests are written with pytest and can be run directly:

```bash
pytest -v
```

To avoid unnecessary computation and server load, tests for the `data` integrations are marked with `@pytest.mark.integration` and are skipped by default. To run them manually: 

```bash
pytest -v -m integration
```

## Code formatting

Code style and linting are handled by ruff and can be run directly:

```bash
ruff check .
ruff format .
```

## Contributing

Contributions are welcome, whether they are bug fixes, improvements, or new features.

When contributing, please try to align with the design philosophy above. In particular, we aim to keep:

- The public API small
- Dependencies minimal
- Tooling simple and standard
