Synchronize code formatters with pre-commit (#1626)

## What kind of change does this PR introduce?

* Updates the pre-commit hook versions.
* `black` is now using year-2024 style conventions. 
* Pins the `dev` recipe-listed code formatters (`black`, `blackdoc`,
`isort`) to match their `pre-commit` equivalents.
* Updates these pinned versions in the `tox.ini`.
* `isort` (currently used in Makefile) has been added to the `dev`
recipe and `environment.yml`
* Set the `environment.yml` to use the `PyPI`-provided `bump-my-version`
package.

### Does this PR introduce a breaking change?

Yes. `black` 24.1.0 introduces several aesthetic changes to the code.
`isort` is now listed as a dependency. Both `black` and `isort` (and
`blackdoc`) are now pinned to prevent `pre-commit` and `tox` formatting
disagreements.

### Other information:

https://github.com/psf/black/releases/tag/24.1.0
callowayproject/bump-my-version#129

.pre-commit-config.yaml

@@ -33,15 +33,15 @@ repos:
       - id: yamllint
         args: [ '--config-file=.yamllint.yaml' ]
   - repo: https://github.com/psf/black-pre-commit-mirror
-    rev: 23.12.1
+    rev: 24.1.0
     hooks:
       - id: black
   - repo: https://github.com/PyCQA/isort
     rev: 5.13.2
     hooks:
       - id: isort
   - repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: v0.1.13
+    rev: v0.1.14
     hooks:
       - id: ruff
   - repo: https://github.com/pylint-dev/pylint
@@ -61,7 +61,7 @@ repos:
       - id: nbqa-pyupgrade
         args: [ '--py38-plus' ]
       - id: nbqa-black
-        additional_dependencies: [ 'black==23.12.1' ]
+        additional_dependencies: [ 'black==24.1.0' ]
       - id: nbqa-isort
   - repo: https://github.com/kynan/nbstripout
     rev: 0.6.1
@@ -73,7 +73,7 @@ repos:
     rev: v0.3.9
     hooks:
       - id: blackdoc
-        additional_dependencies: [ 'black==23.12.1' ]
+        additional_dependencies: [ 'black==24.1.0' ]
         exclude: '(xclim/indices/__init__.py|docs/installation.rst)'
   - repo: https://github.com/gitleaks/gitleaks
     rev: v8.18.1

CHANGES.rst

@@ -26,6 +26,7 @@ Breaking changes
 * `xclim`'s units registry and units formatting are now extended from `cf-xarray`. The exponent sign "^" is now never added in the ``units`` attribute. For example, square meters are given as "m2" instead of "m^2" by xclim, both are still accepted as input. (:issue:`1010`, :pull:`1590`).
 * `yamale` is now listed as a core dependency (was previously listed in the `dev` installation recipe). (:issue:`1595`, :pull:`1596`).
 * Due to a licensing limitation, the calculation of empirical orthogonal function  based on `eofs` (``xclim.sdba.properties.first_eof``) has been removed from `xclim`. (:issue:`1620`, :pull:`1621`).
+* `black` formatting style has been updated to the 2024 stable conventions. `isort` has been added to the `dev` installation recipe. (:pull:`1626`).
 
 Bug fixes
 ^^^^^^^^^
@@ -48,6 +49,7 @@ Internal changes
     * A new GitHub Workflow (``workflow-warning.yml``) has been added to warn maintainers when a forked repository has been used to open a Pull Request that modifies GitHub Workflows.
     * `pylint` has been configured to provide some overhead checks of the `xclim` codebase as well as run as part of `xclim`'s `pre-commit` hooks.
     * Some small adjustments to code organization to address `pylint` errors.
+* `dev` formatting tools (`black`, `blackdoc`, `isort`) are now pinned to their `pre-commit` hook version equivalents in both `pyproject.toml` and `tox.ini`. (:pull:`1626`).
 
 v0.47.0 (2023-12-01)
 --------------------

docs/autodoc_indicator.py

@@ -4,6 +4,7 @@
 
 Based on https://github.com/powerline/powerline/blob/83d855d3d73498c47553afeba212415990d95c54/docs/source/powerline_autodoc.py
 """
+
 from __future__ import annotations
 
 from sphinx.domains.python import PyFunction, PyXRefRole

environment.yml

@@ -29,9 +29,9 @@ dependencies:
   # Extras
   - flox
   # Testing and development dependencies
-  - black >=22.12
-  - blackdoc
-  - bump-my-version
+  - black ==24.1.0
+  - blackdoc ==0.3.9
+#  - bump-my-version  # The conda package is not as up-to-date as the PyPI package.
   - cairosvg
   - codespell
   - coverage
@@ -43,6 +43,7 @@ dependencies:
   - h5netcdf
   - ipykernel
   - ipython
+  - isort ==5.13.2
   - matplotlib
   - mypy
   - nbqa
@@ -69,11 +70,12 @@ dependencies:
   - sphinx-rtd-theme >=1.0
   - sphinxcontrib-bibtex
   - tokenize-rt
-  - tox
+  - tox >=4.0
 #  - tox-conda  # Will be added when a tox@v4.0+ compatible plugin is released.
   - xdoctest
   - yamllint
   - pip
   - pip:
+    - bump-my-version >=0.17.1  # The conda package is not as up-to-date as the PyPI package.
     - flake8-alphabetize
     - sphinxcontrib-svg2pdfconverter

pyproject.toml

@@ -59,16 +59,17 @@ dependencies = [
 [project.optional-dependencies]
 dev = [
   # Dev tools and testing
-  "black >=23.3.0",
-  "blackdoc",
-  "bump-my-version",
+  "black ==24.1.0",
+  "blackdoc ==0.3.9",
+  "bump-my-version >=0.17.1",
   "codespell",
   "coverage[toml]",
   "flake8",
   "flake8-alphabetize",
   "flake8-rst-docstrings",
   "h5netcdf",
   "ipython",
+  "isort ==5.13.2",
   "mypy",
   "nbqa",
   "nbval",
@@ -83,7 +84,7 @@ dev = [
   "pytest-xdist[psutil] >=3.2",
   "ruff >=0.1.0",
   "tokenize-rt",
-  "tox",
+  "tox >=4.0",
   # "tox-conda",  # Will be added when a tox@v4.0+ compatible plugin is released.
   "xdoctest",
   "yamllint",

tests/test_generic.py

@@ -1,4 +1,5 @@
 """Tests for generic indices."""
+
 from __future__ import annotations
 
 import numpy as np

tests/test_land.py

@@ -1,4 +1,5 @@
 """Tests for indicators in `land` realm."""
+
 from __future__ import annotations
 
 import numpy as np

tests/test_stats.py

@@ -1,4 +1,5 @@
 """Tests for statistical indices."""
+
 from __future__ import annotations
 
 import numpy as np

tox.ini

@@ -21,13 +21,15 @@ description = Run code quality compliance tests under {basepython}
 skip_install = True
 extras =
 deps =
+    codespell
     flake8
+    flake8-alphabetize
     flake8-rst-docstrings
-    black[jupyter]
-    blackdoc
-    isort
+    black[jupyter]==24.1.0
+    blackdoc==0.3.9
+    isort==5.13.2
     nbqa
-    ruff
+    ruff>=0.1.0
     yamllint
 commands_pre =
 commands =
@@ -38,6 +40,7 @@ commands =
     nbqa black --check docs
     blackdoc --check --exclude=xclim/indices/__init__.py xclim
     blackdoc --check docs
+    codespell xclim tests docs
     yamllint --config-file=.yamllint.yaml xclim
 commands_post =
 

xclim/__init__.py

@@ -1,4 +1,5 @@
 """Climate indices computation package based on Xarray."""
+
 from __future__ import annotations
 
 try:

xclim/analog.py

@@ -1,4 +1,5 @@
 """Spatial Analogues module."""
+
 # TODO: Hellinger distance
 # TODO: Mahalanobis distance
 # TODO: Comment on "significance" of results.

xclim/cli.py

@@ -3,6 +3,7 @@
 Command Line Interface module
 =============================
 """
+
 from __future__ import annotations
 
 import sys

xclim/core/__init__.py

@@ -1,4 +1,5 @@
 """Core module."""
+
 from __future__ import annotations
 
 from . import missing

xclim/core/bootstrapping.py

@@ -1,4 +1,5 @@
 """Module comprising the bootstrapping algorithm for indicators."""
+
 from __future__ import annotations
 
 import warnings

xclim/core/calendar.py

@@ -4,6 +4,7 @@
 
 Helper function to handle dates, times and different calendars with xarray.
 """
+
 from __future__ import annotations
 
 import datetime as pydt
@@ -1013,12 +1014,14 @@ def resample_doy(doy: xr.DataArray, arr: xr.DataArray | xr.Dataset) -> xr.DataAr
 
 
 def time_bnds(  # noqa: C901
-    time: xr.DataArray
-    | xr.Dataset
-    | CFTimeIndex
-    | pd.DatetimeIndex
-    | DataArrayResample
-    | DatasetResample,
+    time: (
+        xr.DataArray
+        | xr.Dataset
+        | CFTimeIndex
+        | pd.DatetimeIndex
+        | DataArrayResample
+        | DatasetResample
+    ),
     freq: str | None = None,
     precision: str | None = None,
 ):
@@ -1768,9 +1771,11 @@ def stack_periods(
         periods.append(
             slice(
                 strd_slc.start + win_slc.start,
-                (strd_slc.start + win_slc.stop)
-                if win_slc.stop is not None
-                else da.time.size,
+                (
+                    (strd_slc.start + win_slc.stop)
+                    if win_slc.stop is not None
+                    else da.time.size
+                ),
             )
         )
 

xclim/core/cfchecks.py

@@ -4,6 +4,7 @@
 
 Utilities designed to verify the compliance of metadata with the CF-Convention.
 """
+
 from __future__ import annotations
 
 import fnmatch

xclim/core/datachecks.py

@@ -4,6 +4,7 @@
 
 Utilities designed to check the validity of data inputs.
 """
+
 from __future__ import annotations
 
 from typing import Sequence

xclim/core/dataflags.py

@@ -4,6 +4,7 @@
 
 Pseudo-indicators designed to analyse supplied variables for suspicious/erroneous indicator values.
 """
+
 from __future__ import annotations
 
 from decimal import Decimal

xclim/core/formatting.py

@@ -2,6 +2,7 @@
 Formatting Utilities for Indicators
 ===================================
 """
+
 from __future__ import annotations
 
 import datetime as dt

xclim/core/indicator.py

@@ -97,6 +97,7 @@
 to one of those official variables.
 
 """
+
 from __future__ import annotations
 
 import re
@@ -1755,9 +1756,11 @@ def build_indicator_module_from_yaml(  # noqa: C901
     elif translations is not None:
         # A mapping was passed, we read paths is any.
         translations = {
-            lng: read_locale_file(trans, module=module_name, encoding=encoding)
-            if isinstance(trans, (str, Path))
-            else trans
+            lng: (
+                read_locale_file(trans, module=module_name, encoding=encoding)
+                if isinstance(trans, (str, Path))
+                else trans
+            )
             for lng, trans in translations.items()
         }
 

xclim/core/locales.py

@@ -43,6 +43,7 @@
 For xclim-provided translations (for now only French), all indicators must have en entry and the "attrs_mapping"
 entries must match exactly the default formatter. Those default translations are found in the `xclim/locales` folder.
 """
+
 from __future__ import annotations
 
 import json

xclim/core/missing.py

@@ -22,6 +22,7 @@
 To define another missing value algorithm, subclass :py:class:`MissingBase` and decorate it with
 :py:func:`xclim.core.options.register_missing_method`.
 """
+
 from __future__ import annotations
 
 import numpy as np

xclim/core/options.py

@@ -4,6 +4,7 @@
 
 Global or contextual options for xclim, similar to xarray.set_options.
 """
+
 from __future__ import annotations
 
 from inspect import signature

xclim/core/units.py

@@ -5,6 +5,7 @@
 `xclim`'s `pint`-based unit registry is an extension of the registry defined in `cf-xarray`.
 This module defines most unit handling methods.
 """
+
 from __future__ import annotations
 
 import logging
@@ -1091,8 +1092,7 @@ def declare_relative_units(**units_by_name) -> Callable:
     .. code-block:: python
 
         @declare_relative_units(thresh="<da>", thresh2="<da> / [time]")
-        def func(da, thresh, thresh2):
-            ...
+        def func(da, thresh, thresh2): ...
 
     The decorator will check that `thresh` has units compatible with those of da
     and that `thresh2` has units compatible with the time derivative of da.
@@ -1199,8 +1199,7 @@ def declare_units(**units_by_name) -> Callable:
     .. code-block:: python
 
         @declare_units(tas="[temperature]")
-        def func(tas):
-            ...
+        def func(tas): ...
 
     The decorator will check that `tas` has units of temperature (C, K, F).
 

xclim/core/utils.py

@@ -4,6 +4,7 @@
 
 Helper functions for the indices computations, indicator construction and other things.
 """
+
 from __future__ import annotations
 
 import functools
@@ -806,9 +807,9 @@ def adapt_clix_meta_yaml(  # noqa: C901
                             ),
                             "units": param["units"],
                         }
-                        rename_params[
-                            f"{{{name}}}"
-                        ] = f"{{{list(param['data'].keys())[0]}}}"
+                        rename_params[f"{{{name}}}"] = (
+                            f"{{{list(param['data'].keys())[0]}}}"
+                        )
                     else:
                         # Value
                         data["parameters"][name] = f"{param['data']} {param['units']}"

xclim/ensembles/__init__.py

@@ -7,6 +7,7 @@
 In xclim, an "ensemble" is a `Dataset` or a `DataArray` where multiple climate realizations
 or models are concatenated along the `realization` dimension.
 """
+
 from __future__ import annotations
 
 from ._base import create_ensemble, ensemble_mean_std_max_min, ensemble_percentiles