Merge branch 'main' into update-readme

.github/workflows/ci-tests.yml

@@ -36,13 +36,14 @@ jobs:
       matrix:
         os: ["ubuntu-latest"]
         python-version: ["3.11"]
-        session: ["doctest"]
+        session: ["doctest", "linkcheck"]
         iris-source : ["conda-forge"]
         include:
           - os: "ubuntu-latest"
             python-version: "3.11"
             session: "tests"
             iris-source: "conda-forge"
+            coverage: "--coverage"
           - os: "ubuntu-latest"
             python-version: "3.11"
             session: "tests"
@@ -129,3 +130,7 @@ jobs:
           PY_VER: ${{ matrix.python-version }}
         run: |
           nox --session ${{ matrix.session }} -- --test-data-dir ${HOME}/iris-test-data/test_data
+
+      - name: "Upload coverage report"
+        uses: codecov/codecov-action@v4
+        if: ${{ matrix.coverage }}

.gitignore

@@ -1,5 +1,8 @@
 *.py[co]
 
+# setuptools-scm
+_version.py
+
 # Packages
 *.egg
 *.egg-info

.readthedocs.yml

@@ -4,6 +4,19 @@ build:
   os: ubuntu-20.04
   tools:
     python: mambaforge-4.10
+  jobs:
+    post_checkout:
+      # The SciTools/iris-grib repository is shallow i.e., has a .git/shallow,
+      # therefore complete the repository with a full history in order
+      # to allow setuptools-scm to correctly auto-discover the version.
+      - git fetch --unshallow
+      - git fetch --all
+    # Need to stash the local changes that Read the Docs makes so that
+    #  setuptools_scm can generate the correct Iris-grib version.
+    pre_install:
+      - git stash
+    post_install:
+      - git stash pop
 
 conda:
   environment: requirements/readthedocs.yml

docs/conf.py

@@ -105,6 +105,14 @@
 # If true, `todo` and `todoList` produce output, else they produce nothing.
 todo_include_todos = False
 
+# url link checker. Some links registering as faulty, despite being functional.
+# See https://www.sphinx-doc.org/en/1.2/config.html[...]
+# [...]#options-for-the-linkcheck-builder
+
+linkcheck_ignore = [
+    "https://github.com/Scitools/iris-grib/compare"
+    "/c4243ae..5c314e3#diff-cf46b46880cae59e82a91c7ab6bb81ba"
+]
 
 # -- Autodoc ------------------------------------------------------------------
 

docs/index.rst

@@ -214,7 +214,7 @@ Getting Started
 
 To ensure all ``iris-grib`` dependencies, it is sufficient to have installed
 :mod:`Iris <iris>` itself, and
-`ecCodes <https://software.ecmwf.int/wiki/display/ECC/ecCodes+Home>`_ .
+`ecCodes <https://confluence.ecmwf.int/display/ECC/ecCodes+Home>`_ .
 
 The simplest way to install is with
 `conda <https://conda.io/miniconda.html>`_ , using the
@@ -234,7 +234,7 @@ Development sources are hosted at `<https://github.com/SciTools/iris-grib>`_ .
 Releases
 ========
 
-For recent changes, see `Release Notes <ref/release_notes.html>`_ .
+For recent changes, see :ref:`release_notes` .
 
 
 Indices and tables

docs/ref/release_notes.rst

@@ -1,3 +1,5 @@
+.. _release_notes:
+
 Release Notes
 =============
 
@@ -21,6 +23,11 @@ Features
   `(ISSUE#330) <https://github.com/SciTools/iris-grib/issues/330>`_,
   `(PR#402) <https://github.com/SciTools/iris-grib/pull/402>`_
 
+* `@DPeterK <https://github.com/DPeterK>`_ and
+  `@trexfeathers <https://github.com/trexfeathers>`_ added saving support for
+  grid definition template 20 - polar stereographic.
+  `(PR#405) <https://github.com/SciTools/iris-grib/pull/405>`_
+
 Documentation
 ^^^^^^^^^^^^^
 * `@pp-mo <https://github.com/pp-mo>`_ reworked the main docs page to :
@@ -128,7 +135,7 @@ Bugs Fixed
   iris-grib to work with the latest versions of
   `iris <https://scitools-iris.readthedocs.io/en/stable/>`_,
   `cf-units <https://cf-units.readthedocs.io/en/latest/>`_,
-  `ecCodes <https://software.ecmwf.int/wiki/display/ECC/ecCodes+Home>`_ and
+  `ecCodes <https://confluence.ecmwf.int/display/ECC>`_ and
   `cartopy <https://scitools.org.uk/cartopy/docs/latest/>`_, including casting
   the usage of :meth:`cf_units.Unit.date2num` as float. setting and setting the
   values of some missing keys using ``gribapi.GRIB_MISSING_LONG``.
@@ -247,15 +254,15 @@ Bugs Fixed
 * `@pp-mo <https://github.com/pp-mo>`_ fixed loading of grid definition
   template 3.90, "Space view perspective or orthographic grid", which was
   **broken since Iris 2.3**.  This now produces data with an iris
-  `Geostationary <https://scitools-iris.readthedocs.io/en/latest/generated/api/iris/coord_systems.html#iris.coord_systems.Geostationary>`_
+  `Geostationary <https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.coord_systems.html#iris.coord_systems.Geostationary>`_
   coordinate system.  Prior to Iris 2.3, what is now the Iris 'Geostationary'
   class was (incorrectly) named "VerticalPerspective" :  When that was
   `corrected in Iris 2.3 <https://github.com/SciTools/iris/pull/3406>`_ , it
   broke the iris-grib loading, since the data was now incorrectly
   assigned the "new-style" Iris
-  `VerticalPerspective <https://scitools-iris.readthedocs.io/en/latest/generated/api/iris/coord_systems.html#iris.coord_systems.VerticalPerspective>`_
+  `VerticalPerspective <https://scitools-iris.readthedocs.io/en/stable/generated/api/iris.coord_systems.html#iris.coord_systems.VerticalPerspective>`_
   coordinate system, equivalent to the Cartopy
-  `NearsidePerspective <https://scitools.org.uk/cartopy/docs/latest/crs/projections.html#nearsideperspective>`_
+  `NearsidePerspective <https://scitools.org.uk/cartopy/docs/latest/reference/projections.html#nearsideperspective>`_
   and Proj
   `"nsper" <https://proj.org/operations/projections/nsper.html>`_ .
   The plotting behaviour of this is now **the same again as before Iris 2.3** :
@@ -264,7 +271,7 @@ Bugs Fixed
 
 * `@pp-mo <https://github.com/pp-mo>`_ fixed a problem where cubes were loading from GRIB 1 with a changed coordinate
   system, since eccodes versions >= 1.19.  This resulted from a change to eccodes, which now returns a different
-  'shapeOfTheEarth' parameter : see `eccodes issue ECC-811 <https://jira.ecmwf.int/browse/ECC-811>`_ .  This resulted
+  'shapeOfTheEarth' parameter.  This resulted
   in a coordinate system with a different earth radius.
   For backwards compatibilty, the earth radius has now been fixed to the same value as previously.
   However, pending further investigation, this value may be technically incorrect and we may
@@ -293,8 +300,7 @@ Bugs Fixed
 * `@pp-mo <https://github.com/pp-mo>`_ fixed a problem that caused very slow
   loading, and possible memory overflows, with Dask versions >= 2.0.
   **This requires Iris >= 2.4**, as a new minimum dependency.
-  ( This problem was shared with UM file access in Iris : see
-  https://scitools.org.uk/iris/docs/v2.4.0/whatsnew/2.4.html#bugs-fixed ).
+  ( This problem was shared with UM file access in Iris, fixed in Iris 2.4.
   `(PR#190) <https://github.com/SciTools/iris-grib/pull/190>`_
 
 * `@trexfeathers <https://github.com/trexfeathers>`_ fixed all the tests to
@@ -451,7 +457,7 @@ What's new in iris-grib v0.12
 :Date: 25 Oct 2017
 
 Updated to work with
-`ecCodes <https://software.ecmwf.int/wiki/display/ECC/ecCodes+Home>`_ as its
+`ecCodes <https://confluence.ecmwf.int/display/ECC>`_ as its
 interface to GRIB files.
 This is ECMWF's replacement for the older GRIB-API, which is now deprecated.
 

iris_grib/__init__.py

@@ -5,7 +5,7 @@
 """
 Conversion of cubes to/from GRIB.
 
-See: `ECMWF GRIB API <https://software.ecmwf.int/wiki/display/GRIB/Home>`_.
+See: `ECMWF GRIB API <https://confluence.ecmwf.int/display/MTG2US/Migration+to+Grib+2+-+User+Space+Home>`_.
 
 """
 
@@ -30,7 +30,10 @@
 from .message import GribMessage
 
 
-__version__ = "0.20.dev0"
+try:
+    from ._version import version as __version__
+except ModuleNotFoundError:
+    __version__ = "unknown"
 
 __all__ = [
     "load_cubes",
@@ -410,8 +413,11 @@ def _compute_extra_keys(self):
             else:
                 raise TranslationError("Unhandled projectionCentreFlag")
 
+            # Always load PolarStereographic - never Stereographic.
+            #  Stereographic is a CF/Iris concept and not something described
+            #  in GRIB.
             # Note: I think the grib api defaults LaDInDegrees to 60 for grib1.
-            self.extra_keys["_coord_system"] = coord_systems.Stereographic(
+            self.extra_keys["_coord_system"] = coord_systems.PolarStereographic(
                 pole_lat,
                 self.orientationOfTheGridInDegrees,
                 0,

iris_grib/_load_convert.py

@@ -225,40 +225,6 @@ def _hindcast_fix(forecast_time):
     return forecast_time
 
 
-def fixup_float32_from_int32(value):
-    """
-    Workaround for use when reading an IEEE 32-bit floating-point value
-    which the ECMWF GRIB API has erroneously treated as a 4-byte signed
-    integer.
-
-    """
-    # Convert from two's complement to sign-and-magnitude.
-    # NB. The bit patterns 0x00000000 and 0x80000000 will both be
-    # returned by the ECMWF GRIB API as an integer 0. Because they
-    # correspond to positive and negative zero respectively it is safe
-    # to treat an integer 0 as a positive zero.
-    if value < 0:
-        value = 0x80000000 - value
-    value_as_uint32 = np.array(value, dtype="u4")
-    value_as_float32 = value_as_uint32.view(dtype="f4")
-    return float(value_as_float32)
-
-
-def fixup_int32_from_uint32(value):
-    """
-    Workaround for use when reading a signed, 4-byte integer which the
-    ECMWF GRIB API has erroneously treated as an unsigned, 4-byte
-    integer.
-
-    NB. This workaround is safe to use with values which are already
-    treated as signed, 4-byte integers.
-
-    """
-    if value >= 0x80000000:
-        value = 0x80000000 - value
-    return value
-
-
 ###############################################################################
 #
 # Identification Section 1
@@ -846,21 +812,16 @@ def grid_definition_template_12(section, metadata):
     lat = section["latitudeOfReferencePoint"] * _GRID_ACCURACY_IN_DEGREES
     lon = section["longitudeOfReferencePoint"] * _GRID_ACCURACY_IN_DEGREES
     scale = section["scaleFactorAtReferencePoint"]
-    # Catch bug in ECMWF GRIB API (present at 1.12.1) where the scale
-    # is treated as a signed, 4-byte integer.
-    if isinstance(scale, int):
-        scale = fixup_float32_from_int32(scale)
     CM_TO_M = 0.01
     easting = section["XR"] * CM_TO_M
     northing = section["YR"] * CM_TO_M
     cs = icoord_systems.TransverseMercator(lat, lon, easting, northing, scale, geog_cs)
 
-    # Deal with bug in ECMWF GRIB API (present at 1.12.1) where these
-    # values are treated as unsigned, 4-byte integers.
-    x1 = fixup_int32_from_uint32(section["X1"])
-    y1 = fixup_int32_from_uint32(section["Y1"])
-    x2 = fixup_int32_from_uint32(section["X2"])
-    y2 = fixup_int32_from_uint32(section["Y2"])
+    # Fetch grid extents
+    x1 = section["X1"]
+    y1 = section["Y1"]
+    x2 = section["X2"]
+    y2 = section["Y2"]
 
     # Rather unhelpfully this grid definition template seems to be
     # overspecified, and thus open to inconsistency. But for determining
@@ -951,7 +912,10 @@ def grid_definition_template_20(section, metadata):
         central_lat = 90.0
     central_lon = section["orientationOfTheGrid"] * _GRID_ACCURACY_IN_DEGREES
     true_scale_lat = section["LaD"] * _GRID_ACCURACY_IN_DEGREES
-    cs = icoord_systems.Stereographic(
+    # Always load PolarStereographic - never Stereographic.
+    #  Stereographic is a CF/Iris concept and not something described
+    #  in GRIB.
+    cs = icoord_systems.PolarStereographic(
         central_lat=central_lat,
         central_lon=central_lon,
         true_scale_lat=true_scale_lat,