Refactor all the things

.github/workflows/ci.yaml

@@ -0,0 +1,132 @@
+name: CI
+
+on:
+  push:
+    branches:
+    - main
+    - test
+    tags:
+    - "*"
+  pull_request:
+    branches:
+      - main
+
+permissions:
+  contents: read
+  actions: read
+
+env:
+  PYTHONDONTWRITEBYTECODE: 1
+  FORCE_COLOR: 1
+  PYTHON_VERSION: "3.12"
+
+jobs:
+  test:
+    name: Run tests 🧪
+    runs-on: ubuntu-latest
+    permissions:
+      contents: write
+
+    steps:
+    - name: Checkout repo 🛎️
+      uses: actions/checkout@v6
+      with:
+        persist-credentials: false
+
+    - name: Set up Python 🐍
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+        cache: pip
+
+    - name: Restore testing cache 📥
+      uses: actions/cache@v4
+      with:
+        path: |
+          testing/datasets
+          testing/extractions
+          testing/protocol
+          testing/share
+        key: testing-${{ runner.os }}-${{ env.PYTHON_VERSION }}-${{ hashFiles('isimip_utils/tests/constants.py') }}
+        restore-keys: |
+          testing-${{ runner.os }}-${{ env.PYTHON_VERSION }}-
+
+    - name: Install cdo 🌍
+      run: |
+        sudo apt-get update
+        sudo apt-get install -y cdo netcdf-bin --no-install-recommends
+
+    - name: Install package 📦
+      run: pip install -e .[all]
+
+    - name: Run download script 🌐
+      run: python testing/download.py
+
+    - name: Run setup script 🔧
+      run: python testing/setup.py
+
+    - name: Save testing cache 📤
+      if: always()
+      uses: actions/cache/save@v4
+      with:
+        path: |
+          testing/datasets
+          testing/extractions
+          testing/protocol
+          testing/share
+        key: testing-${{ runner.os }}-${{ env.PYTHON_VERSION }}-${{ hashFiles('isimip_utils/tests/constants.py') }}
+
+    - name: Run pytest 🧪
+      run: pytest --cov=isimip_utils --cov-fail-under=90 --cov-report=term-missing
+
+  build:
+    name: Build distribution 👷
+    needs: test
+    runs-on: ubuntu-latest
+
+    steps:
+    - name: Checkout repo 🛎️
+      uses: actions/checkout@v6
+      with:
+        persist-credentials: false
+
+    - name: Set up Python 🐍
+      uses: actions/setup-python@v6
+      with:
+        python-version: ${{ env.PYTHON_VERSION }}
+        cache: pip
+
+    - name: Install build 🧱
+      run: python3 -m pip install build --user
+
+    - name: Build a binary wheel and a source tarball 🛠️
+      run: python3 -m build
+
+    - name: Store the distribution packages 📤
+      uses: actions/upload-artifact@v5
+      with:
+        name: python-package-distributions
+        path: dist/
+
+  pypi:
+    name: Publish distribution to PyPI 📦
+    if: startsWith(github.ref, 'refs/tags/')
+    needs: build
+    runs-on: ubuntu-latest
+
+    environment:
+      name: pypi
+      url: https://pypi.org/p/isimip-utils
+
+    permissions:
+      id-token: write
+
+    steps:
+    - name: Download the distribution packages 📥
+      uses: actions/download-artifact@v6
+      with:
+        name: python-package-distributions
+        path: dist/
+
+    - name: Publish to PyPI 🚀
+      uses: pypa/gh-action-pypi-publish@release/v1

.gitignore

@@ -11,4 +11,19 @@ __pycache__/
 /build
 /dist
 /*.egg-info
+
+/.aider*
 /.pytest_cache
+/.ruff_cache
+
+/.coverage
+/htmlcov
+
+/site
+
+/testing/datasets
+/testing/extractions
+/testing/output
+/testing/plots
+/testing/protocol
+/testing/share

.pre-commit-config.yaml

@@ -3,15 +3,21 @@ repos:
     hooks:
       - id: check-hooks-apply
   - repo: https://github.com/pre-commit/pre-commit-hooks
-    rev: v4.4.0
+    rev: v6.0.0
     hooks:
       - id: check-ast
       - id: check-yaml
       - id: end-of-file-fixer
       - id: trailing-whitespace
       - id: debug-statements
+
   - repo: https://github.com/charliermarsh/ruff-pre-commit
-    rev: v0.0.284
+    rev: v0.14.6
     hooks:
       - id: ruff
         args: [--fix, --exit-non-zero-on-fix]
+
+  - repo: https://github.com/crate-ci/typos
+    rev: v1.39.2
+    hooks:
+    - id: typos

CITATION.cff

@@ -0,0 +1,19 @@
+cff-version: 1.2.0
+message: If you use this software in your research, please cite it using the provided Digital Object Identifier (DOI).
+
+title: ISIMIP utils
+abstract: Common functionality for different ISIMIP tools.
+
+authors:
+- family-names: Klar
+  given-names: Jochen
+  orcid: https://orcid.org/0000-0002-5883-4273
+- family-names: Büchner
+  given-names: Matthias
+  orcid: https://orcid.org/0000-0002-1382-7424
+- family-names: Inga
+  given-names: Sauer
+  orcid: https://orcid.org/0000-0002-9302-2131
+
+license: MIT
+repository-code: https://github.com/ISI-MIP/isimip-utils

LICENSE

@@ -1,6 +1,6 @@
 MIT License
 
-Copyright (c) 2022 Potsdam Institute for Climate Impact Research
+Copyright (c) 2022-2026 Potsdam Institute for Climate Impact Research
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

README.md

@@ -1,48 +1,85 @@
 ISIMIP utils
 ============
 
-[![Latest release](https://shields.io/github/v/release/ISI-MIP/isimip-utils)](https://github.com/ISI-MIP/isimip-utils/releases)
-[![PyPI Release](https://img.shields.io/pypi/v/isimip-utils)](https://pypi.org/project/isimip-utils/)
-[![Python Version](https://img.shields.io/badge/python->=3.8-blue)](https://www.python.org/)
-[![License](https://img.shields.io/badge/license-MIT-green)](https://github.com/ISI-MIP/django-datacite/blob/master/LICENSE)
+[![Python Version](https://img.shields.io/badge/python->=3.11-blue)](https://www.python.org/)
+[![License](https://img.shields.io/github/license/ISI-MIP/isimip-utils?style=flat)](https://github.com/rdmorganiser/isimip-utils/blob/main/LICENSE)
+[![CI status](https://github.com/ISI-MIP/isimip-utils/actions/workflows/ci.yml/badge.svg)](https://github.com/ISI-MIP/isimip-utils/actions/workflows/ci.yml)
+[![Coverage status](https://coveralls.io/repos/ISI-MIP/isimip-utils/badge.svg?branch=main&service=github)](https://coveralls.io/github/ISI-MIP/isimip-utils?branch=main)
+[![Latest release](https://img.shields.io/pypi/v/isimip-utils.svg?style=flat)](https://pypi.python.org/pypi/isimip-utils/)
 
-This package contains common functionality for different ISIMIP tools, namely:
 
-* https://github.com/ISI-MIP/isimip-publisher
-* https://github.com/ISI-MIP/isimip-qa
-* https://github.com/ISI-MIP/isimip-qc
+[ISIMIP](https://isimip.org) offers a framework for consistently projecting the impacts
+of climate change across affected sectors and spatial scales. An international network
+of climate-impact modellers contribute to a comprehensive and consistent picture of the
+world under different climate-change scenarios.
 
-It comprises of:
+This package contains various utility methods for use in custom scripts as well
+as in different ISIMIP tools:
 
-* `isimip_utils.checksum`: Functions to compute the SHA-512 checksum of a file.
-* `isimip_utils.config`: A settings class to combine input from `argparse`, the environment (via `python-dotenv`) and config files.
-* `isimip_utils.exceptions`: Custom exceptions for ISIMIP tools.
-* `isimip_utils.fetch`: Functions to fetch files from the machine-actionable ISIMIP protocols.
-* `isimip_utils.netcdf`: Functions to open and read NetCDF files.
-* `isimip_utils.patterns`: Functions to match the file names and extract the ISIMIP specifiers.
-* `isimip_utils.utils`: Additional utility functions.
+* [ISIMIP quality control](https://github.com/ISI-MIP/isimip-qc)
+* [ISIMIP quality assurance](https://github.com/ISI-MIP/isimip-qa)
+* [ISIMIP publisher](https://github.com/ISI-MIP/isimip-publisher)
+
+
+The different methods are described are [documented here](docs/index.md).
 
 
 Setup
-=====
+-----
 
-Working on the package requires a running Python3 on your system. Installing those prerequisites is covered [here](https://github.com/ISI-MIP/isimip-utils/blob/master/docs/releases.md).
+Using the package requires a running Python 3 on your system. The installation for different systems is covered
+[here](docs/releases.md).
 
-The package itself can be installed via pip:
+Unless you already use an environment manager (e.g. `conda` or `uv`), it is highly recommended to use a
+[virtual environment](https://docs.python.org/3/library/venv.html), which can be created using:
 
-```
-pip install isimip-utils
+```bash
+python3 -m venv env
+source env/bin/activate  # needs to be invoked in every new terminal session
 ```
 
-The package can also be installed directly from GitHub:
+The package itself can be installed via `pip`:
 
-```
-pip install git+https://github.com/ISI-MIP/isimip-utils
+```bash
+pip install isimip-utils
 ```
 
 For a development setup, the repo should be cloned and installed in *editable* mode:
 
-```
+```bash
 git clone git@github.com:ISI-MIP/isimip-utils
 pip install -e isimip-utils
 ```
+
+
+Usage
+-----
+
+Once installed, the modules can be used like any other Python library, e.g. in order to create a ISIMIP
+compliant NetCDF file, you can use:
+
+```python
+from isimip_utils.xarray import init_dataset, write_dataset
+
+time = np.arrange(0, 365, dtype=np.float64)
+var = np.ones((365, 360, 720), dtype=np.float32)
+
+attrs={
+    'global': {
+        'contact': 'mail@example.com'
+    },
+    'var': {
+        'standard_name': 'var',
+        'long_name': 'Variable',
+        'units': '1',
+    }
+}
+
+# create an xarray.Dataset
+ds = init_dataset(time=time, var=var, attrs=attrs)
+
+# write the dataset as NetCDF file
+write_dataset(ds, 'output.nc')
+```
+
+Please also note our [examples page](examples.md) and the [API reference](api.md).

docs/api/checksum.md

@@ -0,0 +1,3 @@
+# isimip_utils.checksum
+
+::: isimip_utils.checksum

docs/api/cli.md

@@ -0,0 +1,3 @@
+# isimip_utils.cli
+
+::: isimip_utils.cli

docs/api/config.md

@@ -0,0 +1,3 @@
+# isimip_utils.config
+
+::: isimip_utils.config

docs/api/exceptions.md

@@ -0,0 +1,3 @@
+# isimip_utils.exceptions
+
+::: isimip_utils.exceptions

docs/api/extractions.md

@@ -0,0 +1,3 @@
+# isimip_utils.extractions
+
+::: isimip_utils.extractions

docs/api/fetch.md

@@ -0,0 +1,3 @@
+# isimip_utils.fetch
+
+::: isimip_utils.fetch

docs/api/files.md

@@ -0,0 +1,3 @@
+# isimip_utils.files
+
+::: isimip_utils.files

docs/api/netcdf.md

@@ -0,0 +1,3 @@
+# isimip_utils.netcdf
+
+::: isimip_utils.netcdf

docs/api/pandas.md

@@ -0,0 +1,3 @@
+# isimip_utils.pandas
+
+::: isimip_utils.pandas

docs/api/parameters.md

@@ -0,0 +1,3 @@
+# isimip_utils.parameters
+
+::: isimip_utils.parameters

docs/api/patterns.md

@@ -0,0 +1,3 @@
+# isimip_utils.patterns
+
+::: isimip_utils.patterns

docs/api/plot.md

@@ -0,0 +1,3 @@
+# isimip_utils.plot
+
+::: isimip_utils.plot

docs/api/protocol.md

@@ -0,0 +1,3 @@
+# isimip_utils.protocol
+
+::: isimip_utils.protocol

docs/api/utils.md

@@ -0,0 +1,3 @@
+# isimip_utils.utils
+
+::: isimip_utils.utils

docs/api/xarray.md

@@ -0,0 +1,3 @@
+# isimip_utils.xarray
+
+::: isimip_utils.xarray

docs/examples.md

@@ -0,0 +1,2 @@
+Examples
+========