Merge branch 'master' into spell_check_framework

* master:
  Correct links in docs (SciTools#3781)
  [PI-3478] Merge cube arithmetic feature branch (SciTools#3785)

.flake8

@@ -15,6 +15,8 @@ ignore =
     E402,
     # E501: line too long
     E501,
+    # E731: do not assign a lambda expression, use a def
+    E731,
     # W503: line break before binary operator
     W503,
     # W504: line break after binary operator
@@ -38,3 +40,7 @@ exclude =
     # ignore third-party files
     #
     gitwash_dumper.py,
+    #
+    # convenience imports
+    #
+    lib/iris/common/__init__.py

ci/requirements/readthedocs.yml

@@ -23,6 +23,7 @@ dependencies:
   - netcdf4
   - numpy>=1.14
   - scipy
+  - python-xxhash
 
 # Dependencies needed to run the iris tests
 #------------------------------------------

docs/iris/src/userguide/cube_maths.rst

@@ -60,6 +60,10 @@ but with the data representing their difference:
          Scalar coordinates:
               forecast_reference_time: 1859-09-01 06:00:00
               height: 1.5 m
+         Attributes:
+              Conventions: CF-1.5
+              Model scenario: E1
+              source: Data from Met Office Unified Model 6.05
 
 
 .. note::

docs/iris/src/whatsnew/2.3.rst

@@ -243,21 +243,19 @@ Documentation
 =============
 
 * Adopted a
-  `new colour logo for Iris <../_static/Iris7_1_trim_full.png>`_
+  `new colour logo for Iris <https://github.com/SciTools/iris/blob/master/docs/iris/src/_static/Iris7_1_trim_100.png>`_
 
 * Added a gallery example showing how to concatenate NEMO ocean model data,
   see :ref:`sphx_glr_generated_gallery_oceanography_plot_load_nemo.py`.
 
-* Added an example in the
-  `Loading Iris Cubes: Constraining on Time <../userguide/loading_iris_cubes
-  .html#constraining-on-time>`_
-  User guide section, demonstrating how to load data within a specified date
+* Added an example for loading Iris cubes for :ref:`using-time-constraints`
+  in the user guide, demonstrating how to load data within a specified date
   range.
 
-* Added notes to the :func:`iris.load` documentation, and the user guide
-  `Loading Iris Cubes <../userguide/loading_iris_cubes.html>`_
-  chapter, emphasizing that the *order* of the cubes returned by an iris load
-  operation is effectively random and unstable, and should not be relied on.
+* Added notes to the :func:`iris.load` documentation, and the userguide
+  :ref:`loading_iris_cubes` chapter, emphasizing that the *order* of the cubes
+  returned by an iris load operation is effectively random and unstable, and
+  should not be relied on.
 
 * Fixed references in the documentation of
   :func:`iris.util.find_discontiguities` to a non existent

lib/iris/_concatenate.py

@@ -68,7 +68,7 @@ class _CoordMetaData(
     Args:
 
     * defn:
-        The :class:`iris.coords.CoordDefn` metadata that represents a
+        The :class:`iris.common.CoordMetadata` metadata that represents a
         coordinate.
 
     * dims:
@@ -85,7 +85,7 @@ class _CoordMetaData(
 
     """
 
-    def __new__(cls, coord, dims):
+    def __new__(mcs, coord, dims):
         """
         Create a new :class:`_CoordMetaData` instance.
 
@@ -101,7 +101,7 @@ def __new__(cls, coord, dims):
             The new class instance.
 
         """
-        defn = coord._as_defn()
+        defn = coord.metadata
         points_dtype = coord.points.dtype
         bounds_dtype = coord.bounds.dtype if coord.bounds is not None else None
         kwargs = {}
@@ -120,7 +120,7 @@ def __new__(cls, coord, dims):
                 order = _DECREASING
             kwargs["order"] = order
         metadata = super().__new__(
-            cls, defn, dims, points_dtype, bounds_dtype, kwargs
+            mcs, defn, dims, points_dtype, bounds_dtype, kwargs
         )
         return metadata
 
@@ -194,7 +194,7 @@ def __new__(cls, ancil, dims):
             The new class instance.
 
         """
-        defn = ancil._as_defn()
+        defn = ancil.metadata
         metadata = super().__new__(cls, defn, dims)
         return metadata
 
@@ -403,11 +403,11 @@ def __init__(self, cube):
         axes = dict(T=0, Z=1, Y=2, X=3)
 
         # Coordinate sort function - by guessed coordinate axis, then
-        # by coordinate definition, then by dimensions, in ascending order.
+        # by coordinate name, then by dimensions, in ascending order.
         def key_func(coord):
             return (
                 axes.get(guess_coord_axis(coord), len(axes) + 1),
-                coord._as_defn(),
+                coord.name(),
                 cube.coord_dims(coord),
             )
 
@@ -422,7 +422,7 @@ def key_func(coord):
                 self.scalar_coords.append(coord)
 
         def meta_key_func(dm):
-            return (dm._as_defn(), dm.cube_dims(cube))
+            return (dm.metadata, dm.cube_dims(cube))
 
         for cm in sorted(cube.cell_measures(), key=meta_key_func):
             dims = cube.cell_measure_dims(cm)
@@ -990,6 +990,9 @@ def _build_aux_coordinates(self):
                             points, bounds=bnds, **kwargs
                         )
                     except ValueError:
+                        # Ensure to remove the "circular" kwarg, which may be
+                        # present in the defn of a DimCoord being demoted.
+                        _ = kwargs.pop("circular", None)
                         coord = iris.coords.AuxCoord(
                             points, bounds=bnds, **kwargs
                         )

lib/iris/_constraints.py

@@ -131,7 +131,7 @@ def _coordless_match(self, cube):
         if self._name:
             # Require to also check against cube.name() for the fallback
             # "unknown" default case, when there is no name metadata available.
-            match = self._name in cube.names or self._name == cube.name()
+            match = self._name in cube._names or self._name == cube.name()
         if match and self._cube_func:
             match = self._cube_func(cube)
         return match

lib/iris/_merge.py

@@ -22,8 +22,9 @@
     is_lazy_data,
     multidim_lazy_stack,
 )
-import iris.cube
 import iris.coords
+from iris.common import CoordMetadata, CubeMetadata
+import iris.cube
 import iris.exceptions
 import iris.util
 
@@ -115,7 +116,7 @@ class _ScalarCoordPayload(
     Args:
 
     * defns:
-        A list of scalar coordinate definitions :class:`iris.coords.CoordDefn`
+        A list of scalar coordinate metadata :class:`iris.common.CoordMetadata`
         belonging to a :class:`iris.cube.Cube`.
 
     * values:
@@ -1478,9 +1479,7 @@ def axis_and_name(name):
                         )
                     else:
                         bounds = None
-                    kwargs = dict(
-                        zip(iris.coords.CoordDefn._fields, defns[name])
-                    )
+                    kwargs = dict(zip(CoordMetadata._fields, defns[name]))
                     kwargs.update(metadata[name].kwargs)
 
                     def name_in_independents():
@@ -1560,7 +1559,7 @@ def name_in_independents():
                     if bounds is not None:
                         bounds[index] = name_value.bound
 
-                kwargs = dict(zip(iris.coords.CoordDefn._fields, defns[name]))
+                kwargs = dict(zip(CoordMetadata._fields, defns[name]))
                 self._aux_templates.append(
                     _Template(dims, points, bounds, kwargs)
                 )
@@ -1594,7 +1593,7 @@ def _get_cube(self, data):
             (deepcopy(coord), dims)
             for coord, dims in self._aux_coords_and_dims
         ]
-        kwargs = dict(zip(iris.cube.CubeMetadata._fields, signature.defn))
+        kwargs = dict(zip(CubeMetadata._fields, signature.defn))
 
         cms_and_dims = [
             (deepcopy(cm), dims) for cm, dims in self._cell_measures_and_dims
@@ -1794,7 +1793,7 @@ def _extract_coord_payload(self, cube):
 
         # Coordinate sort function.
         # NB. This makes use of two properties which don't end up in
-        # the CoordDefn used by scalar_defns: `coord.points.dtype` and
+        # the metadata used by scalar_defns: `coord.points.dtype` and
         # `type(coord)`.
         def key_func(coord):
             points_dtype = coord.dtype
@@ -1805,14 +1804,14 @@ def key_func(coord):
                 axis_dict.get(
                     iris.util.guess_coord_axis(coord), len(axis_dict) + 1
                 ),
-                coord._as_defn(),
+                coord.metadata,
             )
 
         # Order the coordinates by hints, axis, and definition.
         for coord in sorted(coords, key=key_func):
             if not cube.coord_dims(coord) and coord.shape == (1,):
                 # Extract the scalar coordinate data and metadata.
-                scalar_defns.append(coord._as_defn())
+                scalar_defns.append(coord.metadata)
                 # Because we know there's a single Cell in the
                 # coordinate, it's quicker to roll our own than use
                 # Coord.cell().
@@ -1844,14 +1843,14 @@ def key_func(coord):
 
         factory_defns = []
         for factory in sorted(
-            cube.aux_factories, key=lambda factory: factory._as_defn()
+            cube.aux_factories, key=lambda factory: factory.metadata
         ):
             dependency_defns = []
             dependencies = factory.dependencies
             for key in sorted(dependencies):
                 coord = dependencies[key]
                 if coord is not None:
-                    dependency_defns.append((key, coord._as_defn()))
+                    dependency_defns.append((key, coord.metadata))
             factory_defn = _FactoryDefn(type(factory), dependency_defns)
             factory_defns.append(factory_defn)
 

lib/iris/analysis/__init__.py

@@ -319,7 +319,7 @@ def _dimensional_metadata_comparison(*cubes, object_get=None):
                         eq = (
                             other_coord is coord
                             or other_coord.name() == coord.name()
-                            and other_coord._as_defn() == coord._as_defn()
+                            and other_coord.metadata == coord.metadata
                         )
                         if eq:
                             coord_to_add_to_group = other_coord