Code qa refresh

.pre-commit-config.yaml

@@ -13,6 +13,7 @@ files: |
     (?x)(
         benchmarks\/.+\.py|
         docs\/.+\.py|
+        docs\/.+\.rst|
         lib\/.+\.py|
         noxfile\.py|
         pyproject\.toml|
@@ -50,14 +51,11 @@ repos:
         # Duplicates Ruff W291 but also works on non-Python files.
     -   id: trailing-whitespace
 
--   repo: https://github.com/astral-sh/ruff-pre-commit
-    rev: "v0.7.3"
+-   repo: https://github.com/adamchainz/blacken-docs
+    rev: 1.19.1
     hooks:
-    -   id: ruff
-        types: [file, python]
-        args: [--fix, --show-fixes]
-    -   id: ruff-format
-        types: [file, python]
+    -   id: blacken-docs
+        types: [file, rst]
 
 -   repo: https://github.com/codespell-project/codespell
     rev: "v2.3.0"
@@ -66,29 +64,33 @@ repos:
         types_or: [asciidoc, python, markdown, rst]
         additional_dependencies: [tomli]
 
--   repo: https://github.com/adamchainz/blacken-docs
-    rev: 1.19.1
+-   repo: https://github.com/pre-commit/mirrors-mypy
+    rev: 'v1.13.0'
     hooks:
-    -   id: blacken-docs
-        types: [file, rst]
+    -   id: mypy
+        exclude: 'noxfile\.py|docs/conf\.py'
 
--   repo: https://github.com/aio-libs/sort-all
-    rev: v1.3.0
+-   repo: https://github.com/numpy/numpydoc
+    rev: v1.8.0
     hooks:
-    -   id: sort-all
+      - id: numpydoc-validation
+        exclude: "src/iris_grib/tests/|noxfile.py"
         types: [file, python]
 
--   repo: https://github.com/pre-commit/mirrors-mypy
-    rev: 'v1.13.0'
+-   repo: https://github.com/astral-sh/ruff-pre-commit
+    rev: "v0.7.4"
     hooks:
-    -   id: mypy
-        exclude: 'noxfile\.py|docs/conf\.py'
+    -   id: ruff
+        types: [file, python]
+        args: [--fix, --show-fixes]
+    -   id: ruff-format
+        types: [file, python]
 
--   repo: https://github.com/abravalheri/validate-pyproject
-    # More exhaustive than Ruff RUF200.
-    rev: "v0.23"
+-   repo: https://github.com/aio-libs/sort-all
+    rev: v1.3.0
     hooks:
-    - id: validate-pyproject
+    -   id: sort-all
+        types: [file, python]
 
 -   repo: https://github.com/scientific-python/cookie
     rev: 2024.08.19
@@ -97,9 +99,8 @@ repos:
       additional_dependencies: ["repo-review[cli]"]
       args: ["--show=errskip"]
 
-# TODO: pending the addition of numpydoc, including config file(s).
-#-   repo: https://github.com/numpy/numpydoc
-#    rev: v1.7.0
-#    hooks:
-#      - id: numpydoc-validation
-#        types: [file, python]
+-   repo: https://github.com/abravalheri/validate-pyproject
+    # More exhaustive than Ruff RUF200.
+    rev: "v0.23"
+    hooks:
+    - id: validate-pyproject

docs/index.rst

@@ -26,9 +26,10 @@ and ``iris-grib`` installed in your Python environment.
    import iris
    import iris_grib
    import warnings
-   warnings.simplefilter('ignore')
+
+   warnings.simplefilter("ignore")
    cube = iris.load_cube(iris.sample_data_path("rotated_pole.nc"))
-   iris.save(cube, 'testfile.grib', saver='grib2')
+   iris.save(cube, "testfile.grib", saver="grib2")
 
 For example, to load GRIB data :
 
@@ -185,6 +186,7 @@ You can convert Iris cubes to eccodes messages, and modify or filter them before
 
    from iris.coords import DimCoord
    import eccodes
+
    cube_height_2m5 = iris.load_cube(iris.sample_data_path("rotated_pole.nc"))
    cube_height_2m5.add_aux_coord(DimCoord([2.5], standard_name="height", units="m"), ())
 
@@ -255,4 +257,3 @@ See also:
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

docs/ref/iris_grib.rst

@@ -22,4 +22,3 @@ In this module:
 .. autofunction:: iris_grib.save_pairs_from_cube
 
 .. autofunction:: iris_grib.save_messages
-

docs/ref/message/message.rst

@@ -15,4 +15,3 @@ In this module:
 
 .. autoclass:: iris_grib.message.Section
     :members:
-

pyproject.toml

@@ -106,15 +106,31 @@ ignore = [
 
 [tool.mypy]
 # See https://mypy.readthedocs.io/en/stable/config_file.html
-ignore_missing_imports = true
+
+# Extra checks we have chosen to enable.
 warn_unused_configs = true
 warn_unreachable = true
 enable_error_code = ["ignore-without-code", "truthy-bool"]
+
+# Checks we have temporarily *disabled*
+# NOTE:
+#   * Some of these settings are also disabled by "strict = false"
+#   * See "$ mypy --help" for which
+#   * Given these settings, "strict = true" generates no errors
+# TODO: all of these should eventually be removed
+disallow_any_generics = false  # 5 errors
+disallow_subclassing_any = false  # 14 errors
+disallow_untyped_calls = false  # 8 errors
+disallow_untyped_defs = false  # 964 errors
+disallow_incomplete_defs = false  # 3 errors
+check_untyped_defs = false  # 100 errors
+no_implicit_reexport = false  # 134 errors
+
 exclude = [
     'noxfile\.py',
     'docs/conf\.py'
 ]
-strict = false  # Default value, make true when introducing type hinting.
+strict = true  # Default value, make true when introducing type hinting.
 
 [tool.pytest.ini_options]
 # See https://docs.pytest.org/en/stable/reference/customize.html
@@ -190,3 +206,47 @@ known-first-party = ["iris_grib"]
 
 [tool.ruff.lint.pydocstyle]
 convention = "numpy"
+
+[tool.numpydoc_validation]
+checks = [
+    "all",  # Enable all numpydoc validation rules, apart from the following:
+
+    # -> Docstring text (summary) should start in the line immediately
+    #    after the opening quotes (not in the same line, or leaving a
+    #    blank line in between)
+    "GL01",  # Permit summary line on same line as docstring opening quotes.
+
+    # -> Closing quotes should be placed in the line after the last text
+    #    in the docstring (do not close the quotes in the same line as
+    #    the text, or leave a blank line between the last text and the
+    #    quotes)
+    "GL02",  # Permit a blank line before docstring closing quotes.
+
+    # -> Double line break found; please use only one blank line to
+    #    separate sections or paragraphs, and do not leave blank lines
+    #    at the end of docstrings
+    "GL03",  # Ignoring.
+
+    # -> See Also section not found
+    "SA01",  # Not all docstrings require a "See Also" section.
+
+    # -> No extended summary found
+    "ES01",  # Not all docstrings require an "Extended Summary" section.
+
+    # -> No examples section found
+    "EX01",  # Not all docstrings require an "Examples" section.
+
+    # -> No Yields section found
+    "YD01",  # Not all docstrings require a "Yields" section.
+
+    # Record temporarily ignored checks below; will be reviewed at a later date:
+    # TODO: work to remove these at a later date.
+    "GL08",  # *975    The object does not have a docstring
+    "PR01",  # *149    Parameters ... not documented
+    "RT01",  # *9      No Returns section found
+]
+exclude = [
+    '\.__eq__$',
+    '\.__ne__$',
+    '\.__repr__$',
+]

src/iris_grib/__init__.py

@@ -692,8 +692,9 @@ def core_data(self):
 
     def phenomenon_points(self, time_unit):
         """
-        Return the phenomenon time point offset from the epoch time reference
-        measured in the appropriate time units.
+        Return the phenomenon time points.
+
+        As offsets from the epoch time reference, measured in appropriate time units.
 
         """
         time_reference = "%s since epoch" % time_unit
@@ -705,8 +706,9 @@ def phenomenon_points(self, time_unit):
 
     def phenomenon_bounds(self, time_unit):
         """
-        Return the phenomenon time bound offsets from the epoch time reference
-        measured in the appropriate time units.
+        Return the phenomenon time bounds.
+
+        As offsets from the epoch time reference, measured in appropriate time units.
 
         """
         # TODO #576 Investigate when it's valid to get phenomenon_bounds
@@ -762,7 +764,7 @@ def _load_generate(filename):
 
 def load_cubes(filenames, callback=None):
     """
-    Returns an iterator over cubes from the given list of filenames.
+    Return an iterator over cubes from the given list of filenames.
 
     Args:
 
@@ -786,9 +788,21 @@ def load_cubes(filenames, callback=None):
 
 def load_pairs_from_fields(grib_messages):
     """
-    Convert an iterable of GRIB messages into an iterable of
-    (Cube, Grib message) tuples.
+    Convert an GRIB messages into (Cube, Grib message) tuples.
+
+    Parameters
+    ----------
+    grib_messages : iterable on (cube, message)
+        An iterable of :class:`GribMessage`.
 
+    Returns
+    -------
+    iterable of (cube, message)
+        An iterable of (:class:`~iris.Cube`, :class:`GribMessage`),
+        pairing each message with a corresponding generated cube.
+
+    Notes
+    -----
     This capability can be used to filter out fields before they are passed to
     the load pipeline, and amend the cubes once they are created, using
     GRIB metadata conditions.  Where the filtering
@@ -894,6 +908,7 @@ def save_pairs_from_cube(cube):
 def save_messages(messages, target, append=False):
     """
     Save messages to a GRIB2 file.
+
     The messages will be released as part of the save.
 
     Args:

src/iris_grib/_grib1_load_rules.py

@@ -17,7 +17,7 @@
 
 def grib1_convert(grib):
     """
-    Converts a GRIB1 message into the corresponding items of Cube metadata.
+    Convert a GRIB1 message into the corresponding items of Cube metadata.
 
     Args: