Netcdf separate loadsave

docs/src/whatsnew/latest.rst

@@ -222,6 +222,10 @@ This document explains the changes made to Iris for this release
    bin in the system PATH.
    (:pull:`4794`)
 
+#. `@pp-mo`_ split the module :mod:`iris.fileformats.netcdf` into separate
+   :mod:`~iris.fileformats.netcdf.loader` and :mod:`~iris.fileformats.netcdf.saver`
+   submodules, just to make the code easier to handle.
+
 
 .. comment
     Whatsnew author names (@github name) in alphabetical order. Note that,

lib/iris/experimental/ugrid/load.py

@@ -8,8 +8,7 @@
 Extensions to Iris' NetCDF loading to allow the construction of
 :class:`~iris.experimental.ugrid.mesh.Mesh`\\ es from UGRID data in the file.
 
-Eventual destination: :mod:`iris.fileformats.netcdf` (plan to split that module
-into ``load`` and ``save`` in future).
+Eventual destination: :mod:`iris.fileformats.netcdf`.
 
 """
 from contextlib import contextmanager
@@ -19,8 +18,8 @@
 
 from ...config import get_logger
 from ...coords import AuxCoord
-from ...fileformats import netcdf
 from ...fileformats._nc_load_rules.helpers import get_attr_units, get_names
+from ...fileformats.netcdf import loader as nc_loader
 from ...io import decode_uri, expand_filespecs
 from ...util import guess_coord_axis
 from .cf import (
@@ -202,7 +201,7 @@ def load_meshes(uris, var_name=None):
             else:
                 handling_format_spec = FORMAT_AGENT.get_spec(source, None)
 
-            if handling_format_spec.handler == netcdf.load_cubes:
+            if handling_format_spec.handler == nc_loader.load_cubes:
                 valid_sources.append(source)
             else:
                 message = f"Ignoring non-NetCDF file: {source}"
@@ -239,7 +238,7 @@ def _build_aux_coord(coord_var, file_path):
     assert isinstance(coord_var, CFUGridAuxiliaryCoordinateVariable)
     attributes = {}
     attr_units = get_attr_units(coord_var, attributes)
-    points_data = netcdf._get_cf_var_data(coord_var, file_path)
+    points_data = nc_loader._get_cf_var_data(coord_var, file_path)
 
     # Bounds will not be loaded:
     # Bounds may be present, but the UGRID conventions state this would
@@ -293,7 +292,7 @@ def _build_connectivity(connectivity_var, file_path, element_dims):
     assert isinstance(connectivity_var, CFUGridConnectivityVariable)
     attributes = {}
     attr_units = get_attr_units(connectivity_var, attributes)
-    indices_data = netcdf._get_cf_var_data(connectivity_var, file_path)
+    indices_data = nc_loader._get_cf_var_data(connectivity_var, file_path)
 
     cf_role = connectivity_var.cf_role
     start_index = connectivity_var.start_index
@@ -462,7 +461,7 @@ def _build_mesh(cf, mesh_var, file_path):
     )
     mesh_elements = filter(None, mesh_elements)
     for iris_object in mesh_elements:
-        netcdf._add_unused_attributes(
+        nc_loader._add_unused_attributes(
             iris_object, cf.cf_group[iris_object.var_name]
         )
 

lib/iris/experimental/ugrid/save.py

@@ -8,8 +8,7 @@
 Extensions to Iris' NetCDF saving to allow
 :class:`~iris.experimental.ugrid.mesh.Mesh` saving in UGRID format.
 
-Eventual destination: :mod:`iris.fileformats.netcdf` (plan to split that module
-into ``load`` and ``save`` in future).
+Eventual destination: :mod:`iris.fileformats.netcdf`.
 
 """
 from collections.abc import Iterable

lib/iris/fileformats/_nc_load_rules/helpers.py

@@ -31,9 +31,9 @@
 import iris.fileformats.netcdf
 from iris.fileformats.netcdf import (
     UnknownCellMethodWarning,
-    _get_cf_var_data,
     parse_cell_methods,
 )
+from iris.fileformats.netcdf.loader import _get_cf_var_data
 import iris.std_names
 import iris.util
 

lib/iris/fileformats/netcdf/__init__.py

@@ -0,0 +1,49 @@
+# Copyright Iris contributors
+#
+# This file is part of Iris and is released under the LGPL license.
+# See COPYING and COPYING.LESSER in the root of the repository for full
+# licensing details.
+"""
+Module to support the loading and saving of NetCDF files, also using the CF conventions
+for metadata interpretation.
+
+See : `NetCDF User's Guide <https://docs.unidata.ucar.edu/nug/current/>`_
+and `netCDF4 python module <https://github.com/Unidata/netcdf4-python>`_.
+
+Also : `CF Conventions <https://cfconventions.org/>`_.
+
+"""
+import iris.config
+
+# Note: *must* be done before importing from submodules, as they also use this !
+logger = iris.config.get_logger(__name__)
+
+from .loader import DEBUG, NetCDFDataProxy, load_cubes
+from .saver import (
+    CF_CONVENTIONS_VERSION,
+    MESH_ELEMENTS,
+    SPATIO_TEMPORAL_AXES,
+    CFNameCoordMap,
+    Saver,
+    UnknownCellMethodWarning,
+    parse_cell_methods,
+    save,
+)
+
+# Export all public elements from the loader and saver submodules.
+# NOTE: the separation is purely for neatness and developer convenience; from
+# the user point of view, it is still all one module.
+__all__ = (
+    "CFNameCoordMap",
+    "CF_CONVENTIONS_VERSION",
+    "DEBUG",
+    "MESH_ELEMENTS",
+    "NetCDFDataProxy",
+    "SPATIO_TEMPORAL_AXES",
+    "Saver",
+    "UnknownCellMethodWarning",
+    "load_cubes",
+    "logger",
+    "parse_cell_methods",
+    "save",
+)