Merge branch 'main' into create-bounds

Author: davidhassell

Changelog.rst

@@ -9,7 +9,7 @@ version 3.??.?
 version 3.17.0
 --------------
 
-**2025-03-24**
+**2025-04-02**
 
 * Set new minimum version of `dask`: ``2025.2.0``
   (https://github.com/NCAS-CMS/cf-python/issues/849)
@@ -24,10 +24,13 @@ version 3.17.0
 * Fix bug that caused `Data._axes` to be incorrect after a call to
   `cf.Field.collapse`
   (https://github.com/NCAS-CMS/cf-python/issues/857)
+* Fix bug that caused wrong directions from
+  `cf.DimensionCoordinate.direction`
+  (https://github.com/NCAS-CMS/cf-python/issues/859)
 * Changed dependency: ``Python>=3.9.0``
 * Changed dependency: ``numpy>=2.0.0``
-* Changed dependency: ``cfdm>=1.12.0.0, <1.12.1.0``
-* Changed dependency: ``dask>=2025.2.0``
+* Changed dependency: ``cfdm>=1.12.1.0, <1.12.2.0``
+* Changed dependency: ``dask>=2025.2.0, <=2025.3.0``
 * Changed dependency: ``netCDF4>=1.7.2``
 * Changed dependency: ``cftime>=1.6.4``
 * Changed optional dependency: ``esmpy>=8.7.0``

DOCUMENTATION.md renamed to RECIPES.md

@@ -1,3 +1,7 @@
+# Instructions for the cf-python gallery of code recipes
+
+## Environment
+
 * The generation of recipes using Sphinx-Gallery requires `Python<3.12.0` and:
 
   ```txt
@@ -14,6 +18,13 @@
   pip install alabaster==0.7.13
   pip install sphinx==2.4.5
   ```
+  
+* **Note** this is a very old very of Sphinx and some of its plugins etc., which will be updated soon so we
+use the latest, but is necessary for now to maintain certain features. When installing libraries, take
+care not to allow the newest version of Sphinx to be installed by default during the operation.
+
+
+## Notes
 
 * The `.py` files to generate recipes are stored in `docs/source/recipes/`.
 
@@ -51,3 +62,20 @@
       <button data-filter="testfilter">Test</button>
   </div>
   ```
+
+
+## Building for a release
+
+* Since the datasets to use are often very large, it is best to build only new recipes and re-build any
+  which have been updated (usually to replace deprecated keywords or methods, etc.).
+  * To force the prevention of re-builds, move the relevant `docs/source/recipes/plot_*_recipe.py` script(s)
+  out of that directory (or `rm` them, they can be recovered by version control) and they won't be built.
+  Use that to build only recipes that are new or updated.
+  * The HTML files, code and generated notebooks under `_downloads` and generated plots
+     and thumbnail images under  `_images`, for any previously-built recipes, can then be manually copied
+     across from stored archive builds, to create the full recipe listing.
+  * The `index.html` will need to be updated to list the previously-generated recipes, also.
+  * Note that recipes built for the `dev` or `archive` documentation builds will have paths in the
+     recipes HTML files beginning with the relative path `../../` whereas for the `latest` documentation
+     build this needs to be `../` only i.e. is one level up in the tree structure, so if copying anything over
+     note this might need to be updated.

RELEASE.md

@@ -1,8 +1,8 @@
-* Decide the version name to set for the new release, by
+- [ ] Decide the version name to set for the new release, by
   heeding the Versioning Strategy (see
   https://ncas-cms.github.io/cf-python/releases.html#versioning-strategy).
 
-* Set the `NEXTVERSION` version marker across the codebase (added in PRs
+- [ ] Set the `NEXTVERSION` version marker across the codebase (added in PRs
   to mark the next version where the exact number/name is not yet decided)
   by recursively finding all occurences within the `cf` directory and replacing
   them with the upcoming version name `X.Y.Z` (replace `X`, `Y` and `Z`
@@ -14,63 +14,63 @@
   $ find cf/ -type f | xargs sed -i 's/NEXTVERSION/X.Y.Z/g'
   ```
 
-* Change the version and date in `cf/__init__.py` (`__version__` and
+- [ ] Change the version and date in `cf/__init__.py` (`__version__` and
   `__date__` variables)
 
-* Ensure that the requirements on dependencies & their versions are
+- [ ] Ensure that the requirements on dependencies & their versions are
   up-to-date and consistent in both the `requirements.txt` and in
   `docs/source/installation.rst`; and in the `_requires` list and
   `Version` checks in `cf/__init__.py`.
 
-* Make sure that `README.md` is up to date.
+- [ ] Make sure that `README.md` is up to date.
 
-* Make sure that the `long_description` in `setup.py` is up to date.
+- [ ] Make sure that the `long_description` in `setup.py` is up to date.
 
-* Make sure that `Changelog.rst` is up to date (version, date and
+- [ ] Make sure that `Changelog.rst` is up to date (version, date and
   changes).
 
-* Deprecated methods and keyword arguments: Check the code for
+- [ ] Deprecated methods and keyword arguments: Check the code for
   deprecated methods and keyword arguments that can be completely
   removed, i.e. those with a ``removed_at`` version that is at or
   before the version being released. Remove any reference to them in
   the method, class, or fucntion (including, if appropriate, the
   ``@_deprecated_kwarg_check`` decorator), and remove them from the
   relevant documentation ``.rst`` files.
 
-* Check that the documentation API coverage is complete:
+- [ ] Check that the documentation API coverage is complete:
 
   ```bash
   ./check_docs_api_coverage
   ```
 
-  * If it is not complete, add any undocumented attributes, methods,
+  - [ ] If it is not complete, add any undocumented attributes, methods,
     functions and keyword arguments (e.g. as listed in the change log)
     to the `.rst` files in `docs/source/class/`.
 
-* Check external links to the CF conventions are up to date in
+- [ ] Check external links to the CF conventions are up to date in
   `docs/source/tutorial.rst` and `docs/source/field_analysis.rst`
 
-* Create a link to the new documentation in
+- [ ] Create a link to the new documentation in
   `docs/source/releases.rst`, including the release date.
 
-* Test tutorial code:
+- [ ] Test tutorial code:
 
   ```bash
   export PYTHONPATH=$PWD:$PYTHONPATH
   ./test_tutorial_code
   ```
 
-* **Follow all of the steps outlined externally in `DOCUMENTATION.md`**,
+- [ ] **Follow all of the steps outlined externally in [`RECIPES.md`](./RECIPES.md)**,
   notably so that the correct Sphinx-related environment is prepared for
   documentation building.
 
-* Ensure that the [PDF for Cheat Sheet](docs/_downloads/cheatsheet.pdf) 
+- [ ] Ensure that the [PDF for Cheat Sheet](docs/_downloads/cheatsheet.pdf) 
   is updated to include any API changes. The PDF is created using Canva 
   keeping in mind the colours and fonts of the website. The same could 
   be edited using this 
   [link](https://www.canva.com/design/DAFk9_BVfNY/gmQHycBiV_YbTIWMqYxK1g/edit).
 
-* Build a development copy of the documentation using to check API
+- [ ] Build a development copy of the documentation using to check API
   pages for any new methods are present & correct, & that the overall
   formatting has not been adversely affected for comprehension by any
   updates in the latest Sphinx or theme etc. (Do not manually commit
@@ -80,17 +80,17 @@
   ./release_docs dev-scrub
   ```
 
-* Check that no typos or spelling mistakes have been introduced to the
+- [ ] Check that no typos or spelling mistakes have been introduced to the
   documentation:
 
-  * Run a dummy build of the documentation to detect invalid words:
+  - [ ] Run a dummy build of the documentation to detect invalid words:
 
      ```console
      $ cd docs
      $ make spelling build
      ```
 
-  * If there are words raised with 'Spell check' warnings for the dummy
+  - [ ] If there are words raised with 'Spell check' warnings for the dummy
     build, such as:
 
     ```bash
@@ -104,13 +104,13 @@
     `/attribute` or `/function` which will be fixed along with the origin
     docstrings after a 'latest' build) as follows:
 
-    * If there are words that are in fact valid, add the valid words to
+    - [ ] If there are words that are in fact valid, add the valid words to
       the list of false positives for the spelling checker extension,
       `docs/source/spelling_false_positives.txt`.
-    * Correct any words that are not valid in the codebase under `cf` or
+    - [ ] Correct any words that are not valid in the codebase under `cf` or
       in the `docs/source` content files.
 
-  * Note that, in the case there are many words raised as warnings, it
+  - [ ] Note that, in the case there are many words raised as warnings, it
     helps to automate the above steps. The following commands are a means
     to do this processing:
 
@@ -132,58 +132,60 @@
     5. Remove duplicate words and sort alphabetically via:
        `sort -u -o docs/source/spelling_false_positives.txt docs/source/spelling_false_positives.txt`
 
-* Create an archived copy of the documentation:
+- [ ] For major or epoch releases *only* (i.e. not minor, see the versioning strategy at
+  https://ncas-cms.github.io/cf-python/releases.html#versioning-strategy)
+  create an archived copy of the documentation:
 
   ```bash
   ./release_docs archive
   ```
 
-* Update the latest documentation:
+- [ ] Update the latest documentation:
 
   ```bash
   ./release_docs latest
   ```
 
-* Create a source tarball:
+- [ ] Create a source tarball:
 
   ```bash
   python setup.py sdist
   ```
 
-* Test the tarball release using
+- [ ] Test the tarball release using
 
   ```bash
   ./test_release <vn> # E.g. ./test_release 3.14.0
   ```
 
-* Push recent commits using
+- [ ] Push recent commits using
 
   ```bash
   git push origin main
   ```
 
-* Tag the release:
+- [ ] Tag the release:
 
   ```bash
   ./tag <vn> # E.g. ./tag 3.14.0
   ```
 
-* Upload the source tarball to PyPI. Note this requires the `twine`
+- [ ] Upload the source tarball to PyPI. Note this requires the `twine`
   library (which can be installed via `pip`) and relevant project
   privileges on PyPI.
 
   ```bash
   ./upload_to_pypi <vn> # E.g. ./upload_to_pypi 3.14.0
   ```
 
-* Update the GitHub releases page for the new version:
+- [ ] Update the GitHub releases page for the new version:
   https://github.com/NCAS-CMS/cf-python/releases
 
-* Upload the new release to Zenodo: https://zenodo.org/record/3961353
+- [ ] Upload the new release to Zenodo: https://zenodo.org/record/3961353
 
-* Copy the archive docs to https://github.com/NCAS-CMS/cf-python-docs
-
-* Move and commit the previously-generated archived copy of the documentation to https://github.com/NCAS-CMS/cf-python-docs (fork or clone that repo first):
+- [ ] For major or epoch releases *only*, move the archive docs generated earlier to
+  https://github.com/NCAS-CMS/cf-python-docs and commit them (you may have to
+  fork or clone that repo first):
 
   ```bash
   mv docs/<vn>/ ~/cf-python-docs/

cf/__init__.py

@@ -80,7 +80,7 @@
 
 """
 
-__date__ = "2025-03-24"
+__date__ = "2025-04-02"
 __version__ = "3.17.0"
 
 _requires = (
@@ -121,16 +121,16 @@
     raise ImportError(_error0 + str(error1))
 else:
     # Check the version of cfdm
-    _minimum_vn = "1.12.0.0"
-    _maximum_vn = "1.12.1.0"
+    _minimum_vn = "1.12.1.0"
+    _maximum_vn = "1.12.2.0"
     _cfdm_version = Version(cfdm.__version__)
     if _cfdm_version < Version(_minimum_vn) or _cfdm_version >= Version(
         _maximum_vn
     ):
         raise RuntimeError(
             "Bad cfdm version: cf requires "
             f"{_minimum_vn}<=cfdm<{_maximum_vn}. "
-            f"Got {cfdm.__version__} at {cfdm.__file__}"
+            f"Got {_cfdm_version} at {cfdm.__file__}"
         )
 
 __cf_version__ = cfdm.__cf_version__
@@ -202,10 +202,15 @@
     raise ImportError(_error0 + str(error1))
 else:
     _minimum_vn = "2025.2.0"
-    if Version(dask.__version__) < Version(_minimum_vn):
-        raise ValueError(
-            f"Bad dask version: cf requires dask>={_minimum_vn}. "
-            f"Got {dask.__version__} at {dask.__file__}"
+    # Note in this case max is inclusive, change inequalities if this changes
+    _maximum_vn = "2025.3.0"
+    _dask_version = Version(dask.__version__)
+    if _dask_version < Version(_minimum_vn) or _dask_version > Version(
+        _maximum_vn
+    ):
+        raise RuntimeError(
+            "Bad dask version: cf requires "
+            f"{_minimum_vn}<=dask<={_maximum_vn}. Got {_dask_version}."
         )
 
 try:

cf/dimensioncoordinate.py

@@ -131,9 +131,9 @@ def _infer_direction(self):
         """Return True if a coordinate is increasing, otherwise return
         False.
 
-        A dimension coordinate construct is considered to be increasing if
-        its data array values are increasing in index space, or if it has
-        no data nor bounds.
+        A dimension coordinate construct is considered to be
+        increasing if its data array values are not strictly
+        decreasing in index space, or if it has no data nor bounds.
 
         If the direction can not be inferred from the data not bounds then
         the coordinate's units are used.
@@ -168,12 +168,12 @@ def _infer_direction(self):
                 c = data._get_cached_elements()
                 if c:
                     try:
-                        return bool(c.get(0) < c.get(1))
+                        return bool(c.get(0) <= c.get(1))
                     except TypeError:
                         pass
 
                 data = data[:2].compute()
-                return bool(data.item(0) < data.item(1))
+                return bool(data.item(0) <= data.item(1))
 
         # Still here?
         data = self.get_bounds_data(None, _fill_value=False)
@@ -182,12 +182,12 @@ def _infer_direction(self):
             c = data._get_cached_elements()
             if c:
                 try:
-                    return bool(c.get(0) < c.get(1))
+                    return bool(c.get(0) <= c.get(1))
                 except TypeError:
                     pass
 
             b = data[0].compute()
-            return bool(b.item(0) < b.item(1))
+            return bool(b.item(0) <= b.item(1))
 
         # Still here? Then infer the direction from the units.
         return not self.Units.ispressure

cf/test/test_DimensionCoordinate.py

@@ -818,6 +818,30 @@ def test_DimensionCoordinate_anchor(self):
         self.assertEqual(e[0].array, d[0].array - 360)
 
 
+    def test_DimensionCoordinate_direction(self):
+        """Test DimensionCoordinate.direction"""
+        d = self.dim.copy()
+
+        # Test the use case of
+        # https://github.com/NCAS-CMS/cf-python/issues/859
+        #
+        # Create a coordinate with all equal values
+        d.data[...] = d[0].array
+        for i, x in enumerate(d.array):
+            d.bounds.data[i, :] = x
+
+        d._custom["direction"] = None  # Force a re-calculation of direction
+        self.assertTrue(d.direction())
+        d._custom["direction"] = None
+        self.assertTrue(d[0].direction())
+
+        d.del_bounds()
+        d._custom["direction"] = None
+        self.assertTrue(d.direction())
+        d._custom["direction"] = None
+        self.assertTrue(d[0].direction())
+
+
 if __name__ == "__main__":
     print("Run date:", datetime.datetime.now())
     cf.environment()