Merge pull request #92 from CSHS-CWRA/new-config-idea

Configuration subsystem refactoring
CSHS-CWRA · Apr 30, 2021 · 0f91952 · 0f91952
2 parents 9354e1b + ec89633
commit 0f91952
Show file tree

Hide file tree

Showing 123 changed files with 4,892 additions and 89,529 deletions.
diff --git a/.cruft.json b/.cruft.json
@@ -10,7 +10,7 @@
             "project_slug": "ravenpy",
             "project_short_description": "A Python wrapper to setup and run the hydrologic modelling framework Raven.",
             "pypi_username": "CSHS-CWRA",
-            "version": "0.4.2",
+            "version": "0.5.0",
             "use_pytest": "y",
             "use_pypi_deployment_with_travis": "y",
             "add_pyup_badge": "y",

diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml
@@ -21,7 +21,7 @@ repos:
     -   id: debug-statements
         language_version: python3
 -   repo: https://github.com/ambv/black
-    rev: 21.4b0
+    rev: 21.4b1
     hooks:
     -   id: black
         language_version: python3

diff --git a/HISTORY.rst b/HISTORY.rst
@@ -2,12 +2,22 @@
 History
 =======
 
+0.5.0
+-----
+
+* Refactoring of the RV config subsystem
+  * The config is fully encapsulated into its own class: `ravenpy.config.rvs.Config`
+  * The emulator RV templates are inline in their emulator classes
+* The emulators have their own submodule: `ravenpy.models.emulators`
+* The "importers" have been renamed to "extractors" and they have their own submodule: `ravenpy.extractors`
+
 0.4.2
 -----
-* Update to RavenC revision 318 to fix OPENDAP access for StationForcing commands
-* Fix grid_weights set to None by default
-* Pass nc_index to ObservationData command
-* Expose more cleanly RavenC errors and warnings
+
+* Update to RavenC revision 318 to fix OPENDAP access for StationForcing commands.
+* Fix grid_weights set to None by default.
+* Pass nc_index to ObservationData command.
+* Expose more cleanly RavenC errors and warnings.
 
 0.4.1
 -----

diff --git a/Makefile b/Makefile
@@ -65,8 +65,8 @@ coverage: ## check code coverage quickly with the default Python
 
 docs: ## generate Sphinx HTML documentation, including API docs
 	# Warning: as the sphinx-apidoc is NOT being run on the RTD server the workaround we have
-	# is to commit the (currently 5) rst files it generates.
-	sphinx-apidoc -o docs/ ravenpy
+	# is to commit the (currently 8) rst files it generates.
+	sphinx-apidoc -d 10 -o docs/ ravenpy
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
 	$(BROWSER) docs/_build/html/index.html

diff --git a/docs/conf.py b/docs/conf.py
@@ -44,6 +44,14 @@
 autosummary_generate = True
 nbsphinx_execute = "auto"
 
+# To ensure that underlined fields (e.g. `_field`) are shown in the docs.
+autodoc_default_options = {
+    "members": True,
+    "undoc-members": True,
+    "private-members": False,
+    "special-members": False,
+}
+
 # To avoid having to install these and burst memory limit on ReadTheDocs.
 autodoc_mock_imports = [
     "affine",
@@ -57,6 +65,8 @@
     "netCDF4",
     "osgeo",
     "geopandas",
+    "holoviews",
+    "hvplot",
     "lxml",
     "owslib",
     "pandas",

diff --git a/docs/modules.rst b/docs/modules.rst
@@ -2,6 +2,6 @@ ravenpy
 =======
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 10
 
    ravenpy
diff --git a/docs/notebooks/RavenPy.ipynb b/docs/notebooks/RavenPy.ipynb
diff --git a/docs/notebooks/Running_Raven_with_CANOPEX_data.ipynb b/docs/notebooks/Running_Raven_with_CANOPEX_data.ipynb
diff --git a/docs/notebooks/climatological_ESP_forecasting.ipynb b/docs/notebooks/climatological_ESP_forecasting.ipynb
diff --git a/docs/notebooks/hydro_routing_product_example.ipynb b/docs/notebooks/hydro_routing_product_example.ipynb
diff --git a/docs/ravenpy.config.rst b/docs/ravenpy.config.rst
@@ -0,0 +1,29 @@
+ravenpy.config package
+======================
+
+Submodules
+----------
+
+ravenpy.config.commands module
+------------------------------
+
+.. automodule:: ravenpy.config.commands
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ravenpy.config.rvs module
+-------------------------
+
+.. automodule:: ravenpy.config.rvs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ravenpy.config
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/ravenpy.extractors.rst b/docs/ravenpy.extractors.rst
@@ -0,0 +1,21 @@
+ravenpy.extractors package
+==========================
+
+Submodules
+----------
+
+ravenpy.extractors.routing\_product module
+------------------------------------------
+
+.. automodule:: ravenpy.extractors.routing_product
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ravenpy.extractors
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/ravenpy.models.emulators.rst b/docs/ravenpy.models.emulators.rst
@@ -0,0 +1,53 @@
+ravenpy.models.emulators package
+================================
+
+Submodules
+----------
+
+ravenpy.models.emulators.blended module
+---------------------------------------
+
+.. automodule:: ravenpy.models.emulators.blended
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ravenpy.models.emulators.gr4jcn module
+--------------------------------------
+
+.. automodule:: ravenpy.models.emulators.gr4jcn
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ravenpy.models.emulators.hbvec module
+-------------------------------------
+
+.. automodule:: ravenpy.models.emulators.hbvec
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ravenpy.models.emulators.hmets module
+-------------------------------------
+
+.. automodule:: ravenpy.models.emulators.hmets
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+ravenpy.models.emulators.mohyse module
+--------------------------------------
+
+.. automodule:: ravenpy.models.emulators.mohyse
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
+Module contents
+---------------
+
+.. automodule:: ravenpy.models.emulators
+   :members:
+   :undoc-members:
+   :show-inheritance:
diff --git a/docs/ravenpy.models.rst b/docs/ravenpy.models.rst
@@ -1,6 +1,14 @@
 ravenpy.models package
 ======================
 
+Subpackages
+-----------
+
+.. toctree::
+   :maxdepth: 10
+
+   ravenpy.models.emulators
+
 Submodules
 ----------
 
@@ -12,30 +20,6 @@ ravenpy.models.base module
    :undoc-members:
    :show-inheritance:
 
-ravenpy.models.commands module
-------------------------------
-
-.. automodule:: ravenpy.models.commands
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-ravenpy.models.emulators module
--------------------------------
-
-.. automodule:: ravenpy.models.emulators
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
-ravenpy.models.importers module
--------------------------------
-
-.. automodule:: ravenpy.models.importers
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 ravenpy.models.multimodel module
 --------------------------------
 
@@ -44,14 +28,6 @@ ravenpy.models.multimodel module
    :undoc-members:
    :show-inheritance:
 
-ravenpy.models.rv module
-------------------------
-
-.. automodule:: ravenpy.models.rv
-   :members:
-   :undoc-members:
-   :show-inheritance:
-
 Module contents
 ---------------
 

diff --git a/docs/ravenpy.rst b/docs/ravenpy.rst
@@ -5,9 +5,11 @@ Subpackages
 -----------
 
 .. toctree::
-   :maxdepth: 4
+   :maxdepth: 10
 
    ravenpy.cli
+   ravenpy.config
+   ravenpy.extractors
    ravenpy.models
    ravenpy.utilities
 

diff --git a/docs/ravenpy.utilities.rst b/docs/ravenpy.utilities.rst
@@ -84,6 +84,14 @@ ravenpy.utilities.mk\_test module
    :undoc-members:
    :show-inheritance:
 
+ravenpy.utilities.nb\_graphs module
+-----------------------------------
+
+.. automodule:: ravenpy.utilities.nb_graphs
+   :members:
+   :undoc-members:
+   :show-inheritance:
+
 ravenpy.utilities.ravenio module
 --------------------------------
 

diff --git a/docs/user_api.rst b/docs/user_api.rst
@@ -2,7 +2,7 @@
 User API
 ========
 
-Base models
+Base Models
 ===========
 
 .. autoclass:: ravenpy.models.base.Raven
@@ -20,30 +20,43 @@ Base models
 Emulators
 =========
 
-.. automodule::  ravenpy.models.emulators
+.. automodule::  ravenpy.models.emulators.blended
    :members:
    :noindex:
 
+.. automodule::  ravenpy.models.emulators.gr4jcn
+   :members:
+   :noindex:
 
-Configuration options
-=====================
+.. automodule::  ravenpy.models.emulators.hbvec
+   :members:
+   :noindex:
 
-.. automodule::  ravenpy.models.rv
+.. automodule::  ravenpy.models.emulators.hmets
    :members:
    :noindex:
 
-.. automodule::  ravenpy.models.commands
+.. automodule::  ravenpy.models.emulators.mohyse
    :members:
    :noindex:
 
+Configuration
+=============
 
-Importers
-=========
+.. automodule::  ravenpy.config.commands
+   :members:
+   :noindex:
 
-.. automodule::  ravenpy.models.importers
+.. automodule::  ravenpy.config.rvs
    :members:
    :noindex:
 
+Extractors
+==========
+
+.. automodule::  ravenpy.extractors.routing_product
+   :members:
+   :noindex:
 
 Utilities
 =========

diff --git a/environment-rtd.yml b/environment-rtd.yml
@@ -15,6 +15,7 @@ dependencies:
   - ipython
   - ipykernel
   - jupyter_client
+  - pydantic
   - sphinx-click
   - sphinx_rtd_theme
   - sphinx-autoapi

diff --git a/environment.yml b/environment.yml
@@ -22,6 +22,7 @@ dependencies:
   - pandas
   - pip
   - proj
+  - pydantic
   - pyparsing
   - pyproj>=3.0.0
   - rasterio

diff --git a/ravenpy/__version__.py b/ravenpy/__version__.py
@@ -6,4 +6,4 @@
 
 __author__ = """David Huard"""
 __email__ = "huard.david@ouranos.ca"
-__version__ = "0.4.2"
+__version__ = "0.5.0"
diff --git a/ravenpy/cli/aggregate_forcings_to_hrus.py b/ravenpy/cli/aggregate_forcings_to_hrus.py
@@ -2,8 +2,8 @@
 
 import click
 
-from ravenpy.models.commands import GridWeightsCommand
-from ravenpy.models.importers import grid_weight_importer_params
+from ravenpy.config.commands import GridWeightsCommand
+from ravenpy.extractors.routing_product import RoutingProductGridWeightExtractor
 
 
 @click.command()
@@ -14,7 +14,7 @@
     "--dim-names",
     nargs=2,
     type=click.Tuple([str, str]),
-    default=grid_weight_importer_params["DIM_NAMES"],
+    default=RoutingProductGridWeightExtractor.DIM_NAMES,
     show_default=True,
     help="Ordered dimension names of longitude (x) and latitude (y) in the NetCDF INPUT_NC_FILE.",
 )