Merge pull request #21 from hydrologie/indicators

Add xscen functions and move to conda environment

.github/workflows/main.yml

@@ -37,52 +37,68 @@ jobs:
         run: tox -e black
 
   test:
-    name: test-${{ matrix.tox-env }} (Python${{ matrix.python-version }})
+    name: Test with Python${{ matrix.python-version }}
     needs: black
     runs-on: ubuntu-latest
     strategy:
+      fail-fast: false
       matrix:
         include:
-          - tox-env: "py39"
-            python-version: "3.9"
-          - tox-env: "py310"
-            python-version: "3.10"
-          - tox-env: "py311"
-            python-version: "3.11"
+          - python-version: "3.9"
+#            tox-build: "py39"
+          - python-version: "3.10"
+#            tox-build: "py310"
+          - python-version: "3.11"
+#            tox-build: "py311"
+    defaults:
+      run:
+        shell: bash -l {0}
     steps:
       - uses: actions/checkout@v3
-      - name: Set up Python${{ matrix.python-version }}
-        uses: actions/setup-python@v4
+      - name: Setup Conda (Micromamba) with Python ${{ matrix.python-version }}
+        uses: mamba-org/setup-micromamba@v1
         with:
-          python-version: ${{ matrix.python-version }}
-#      - name: Install tox
-#        run: pip install tox
-#      - name: Test with tox
-#        run: tox -e ${{ matrix.tox-env }}
-#        env:
-#          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-#          COVERALLS_FLAG_NAME: run-${{ matrix.tox-env }}
-#          COVERALLS_PARALLEL: true
-#          COVERALLS_SERVICE_NAME: github
-      - name: Install xhydro (no dependencies)
+          cache-downloads: true
+          environment-file: environment.yml
+          create-args: >-
+            coveralls
+            mamba
+            python=${{ matrix.python-version }}
+            pytest
+            pytest-cov
+      - name: Conda and Mamba versions
+        run: |
+          mamba --version
+          echo "micromamba $(micromamba --version)"
+      - name: Install xhydro
+        run: |
+          pip install --editable .
+      - name: Check versions
         run: |
-          python -m pip install -e . --no-dependencies
-      - name: Smoke tests
+          conda list
+          pip check
+      - name: Test with pytest
         run: |
-          python -m pip install pytest
-          pytest
+          pytest --cov xhydro
+      - name: Report coverage
+        run: |
+          coveralls
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COVERALLS_FLAG_NAME: run-Python${{ matrix.python-version }}
+          COVERALLS_PARALLEL: true
+          COVERALLS_SERVICE_NAME: github
 
-# FIXME: Needs the Coveralls Pro webhook
-#  finish:
-#    needs:
-#      - test
-#    runs-on: ubuntu-latest
-#    container: python:3-slim
-#    steps:
-#      - name: Coveralls Finished
-#        run: |
-#          pip install --upgrade coveralls
-#          coveralls --finish
-#        env:
-#          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-#          COVERALLS_SERVICE_NAME: github
+  finish:
+    needs:
+      - test
+    runs-on: ubuntu-latest
+    container: python:3-slim
+    steps:
+      - name: Coveralls Finished
+        run: |
+          pip install --upgrade coveralls
+          coveralls --finish
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          COVERALLS_SERVICE_NAME: github

.readthedocs.yml

@@ -15,15 +15,10 @@ build:
   tools:
     python: "mambaforge-22.9"
   jobs:
+    post_create_environment:
+      - pip install . --no-deps
     pre_build:
       - sphinx-apidoc -o docs/apidoc --private --module-first xhydro
 
 conda:
   environment: environment-dev.yml
-
-python:
-  install:
-    - method: pip
-      path: .
-      extra_requirements:
-        - dev

HISTORY.rst

@@ -13,11 +13,13 @@ Announcements
 
 New features and enhancements
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-* GitHub Workflows for automated testing using `tox` have been added. (:pull:`11`)
+* GitHub Workflows for automated testing using `tox` have been added. (:pull:`11`).
+* Support for various `xscen` functions has been added to compute indicators and various climate change metrics. (:pull:`21`).
 
 Breaking changes
 ^^^^^^^^^^^^^^^^
 * `xHydro` repository has renamed its primary development branch from `master` to `main`. (:pull:`13`).
+* `xHydro` now requires a conda environment to be installed. (:pull:`21`).
 
 Bug fixes
 ^^^^^^^^^

docs/conf.py

@@ -16,12 +16,18 @@
 # directory, add these directories to sys.path here. If the directory is
 # relative to the documentation root, use os.path.abspath to make it
 # absolute, like shown here.
-#
+from pathlib import Path
+
 import os
 import sys
 sys.path.insert(0, os.path.abspath('..'))
+if os.environ.get("READTHEDOCS") and "ESMFMKFILE" not in os.environ:
+    # RTD doesn't activate the env, and esmpy depends on an env var set there
+    # We assume the `os` package is in {ENV}/lib/pythonX.X/os.py
+    # See conda-forge/esmf-feedstock#91 and readthedocs/readthedocs.org#4067
+    os.environ["ESMFMKFILE"] = str(Path(os.__file__).parent.parent / "esmf.mk")
 
-import xhydro
+import xhydro  # noqa
 
 # -- General configuration ---------------------------------------------
 
@@ -35,6 +41,7 @@
     'sphinx.ext.autodoc',
     'sphinx.ext.autosectionlabel',
     'sphinx.ext.extlinks',
+    'sphinx.ext.intersphinx',
     'sphinx.ext.viewcode',
     'sphinx.ext.todo',
     'sphinx_codeautolink',
@@ -53,6 +60,15 @@
     "special-members": False,
 }
 
+# For styling class attributes
+napoleon_use_ivar = True
+
+# For external documentation links
+intersphinx_mapping = {
+    "xclim": ("https://xclim.readthedocs.io/en/latest/", None),
+    "xscen": ("https://xscen.readthedocs.io/en/latest/", None),
+}
+
 extlinks = {
     "issue": ("https://github.com/hydrologie/xhydro/issues/%s", "GH/%s"),
     "pull": ("https://github.com/hydrologie/xhydro/pull/%s", "PR/%s"),

docs/installation.rst

@@ -2,29 +2,30 @@
 Installation
 ============
 
-
 Stable release
 --------------
-
-To install xHydro, run this command in your terminal:
+Due to the complexity of the install process of some dependencies, we strongly recommend installing `xhydro` in an Anaconda Python environment.
+To create a working environment and install xHydro, copy the `environment.yml` file from the root of the repository and run the following commands:
 
 .. code-block:: console
 
-    $ pip install xhydro
+    $ conda env create -f environment.yml
+    $ conda activate xhydro
+    $ pip install xhydro --no-deps
 
-This is the preferred method to install xHydro, as it will always install the most recent stable release.
+This is the preferred method to install `xHydro`, as it will always install the most recent stable release.
 
-If you don't have `pip`_ installed, this `Python installation guide`_ can guide
-you through the process.
+If for some reason you wish to install the `PyPI` version of `xscen` into an existing Anaconda environment (*not recommended*), only run the last command above.
+
+If you don't have `pip`_ installed, this `Python installation guide`_ can guide you through the process.
 
 .. _pip: https://pip.pypa.io
 .. _Python installation guide: http://docs.python-guide.org/en/latest/starting/installation/
 
-
 From sources
 ------------
-
-The sources for xHydro can be downloaded from the `Github repo`_.
+`xHydro` is still under active development and the latest features might not yet be available on `PyPI`.
+To install the latest development version, you can install `xHydro` directly from the `Github repo`_.
 
 You can either clone the public repository:
 
@@ -38,12 +39,19 @@ Or download the `tarball`_:
 
     $ curl -OJL https://github.com/hydrologie/xhydro/tarball/main
 
-Once you have a copy of the source, you can install it with:
+Once you have a copy of the source, you can create a working environment and install `xHydro` in it:
 
 .. code-block:: console
 
-    $ python setup.py install
+    $ conda env create -f environment.yml
+    $ conda activate xhydro
+    $ pip install . --no-deps
+
+When new changes are made to the `Github repo`_, you can update your local copy using:
+
+.. code-block:: console
 
+    $ git pull origin main
 
 .. _Github repo: https://github.com/hydrologie/xhydro
 .. _tarball: https://github.com/hydrologie/xhydro/tarball/main

environment-dev.yml

@@ -2,9 +2,11 @@ name: xhydro-dev
 channels:
   - conda-forge
 dependencies:
-  - python >=3.9,<3.11
+  - python >=3.9,<3.12
   # Don't forget to sync the changes here with environment.yml!
   # Main packages
+  - xclim >=0.45.0
+  - xscen >=0.7.1
   # Dev
   - bump2version
   - coveralls
@@ -21,12 +23,13 @@ dependencies:
   - pytest-cov
   - sphinx
   - sphinx-autoapi
-  - sphinxcontrib-napoleon
   - sphinx-codeautolink
   - sphinx-copybutton
+  - sphinxcontrib-napoleon
   - pip
   # Testing
-  - tox >=4.0
+  - tox <4.0  # 2022-12-12: tox v4.0 is incompatible with tox-conda plugin
+  - tox-conda >=0.10.2
   # Packaging
   - build
   - wheel

environment.yml

@@ -2,4 +2,6 @@ name: xhydro
 channels:
   - conda-forge
 dependencies:
-  - python >=3.9,<3.11
+  - python >=3.9,<3.12
+  - xclim >=0.45.0
+  - xscen >=0.7.1

setup.cfg

@@ -24,21 +24,22 @@ test = pytest
 
 [tool:pytest]
 collect_ignore = ['setup.py']
-addopts = 
+addopts =
+    --color=yes
 	--verbose
-filterwarnings = 
+filterwarnings =
 	ignore::UserWarning
 
 [flake8]
-exclude = 
+exclude =
 	.git,
 	docs,
 	build,
 	.eggs,
 	docs/conf.py,
 max-line-length = 88
 max-complexity = 12
-ignore = 
+ignore =
 	C901
 	E203
 	E231
@@ -48,9 +49,9 @@ ignore =
 	F403
 	W503
 	W504
-per-file-ignores = 
+per-file-ignores =
 	tests/*:E402
-rst-roles = 
+rst-roles =
 	mod,
 	py:attr,
 	py:attribute,

setup.py

@@ -7,7 +7,7 @@
 with open("README.rst") as readme_file:
     readme = readme_file.read()
 
-requirements = []
+requirements = ["xscen", "xclim>=0.45.0"]
 
 dev_requirements = ["pytest", "pytest-cov"]
 
@@ -18,12 +18,15 @@
     classifiers=[
         "Development Status :: 2 - Pre-Alpha",
         "Intended Audience :: Developers",
+        "Intended Audience :: Science/Research"
         "License :: OSI Approved :: Apache Software License",
         "Natural Language :: English",
         "Programming Language :: Python :: 3",
         "Programming Language :: Python :: 3.9",
         "Programming Language :: Python :: 3.10",
         "Programming Language :: Python :: 3.11",
+        "Topic :: Scientific/Engineering :: Hydrology",
+        "Topic :: Scientific/Engineering :: GIS",
     ],
     description="Hydrological analysis library built with xarray",
     entry_points={
@@ -43,7 +46,7 @@
     extras_require={
         "dev": dev_requirements,
     },
-    url="https://github.com/TC-FF/xhydro",
+    url="https://github.com/hydrologie/xhydro",
     version="0.1.8",
     zip_safe=False,
 )

tests/test_xhydro.py

@@ -7,7 +7,7 @@
 
 import pytest
 
-from xhydro import xhydro
+import xhydro
 
 
 @pytest.fixture

tox.ini

@@ -1,5 +1,5 @@
 [tox]
-min_version = 4.0
+# min_version = 4.0  # removed until tox-conda is updated for use with tox>=4.0
 envlist =
     black
     py{39,310,311}
@@ -21,18 +21,21 @@ allowlist_externals =
     make
 
 [testenv:docs]
-extras =
-    docs
+description = Run Build of xscen Documentation
+conda_deps =
+conda_env = environment-dev.yml
 commands =
-    make --directory=docs clean html
+    make docs
 allowlist_externals =
     make
 
 [testenv]
+description = Run tests with pytest under {basepython}
 setenv =
-    PYTEST_ADDOPTS = "--color=yes"
+    PYTEST_ADDOPTS = "--color=yes --verbose"
     PYTHONPATH = {toxinidir}
 passenv =
+    COVERALLS_*
     GITHUB_*
 extras =
     dev