Define Iris 2.4

.travis.yml

@@ -112,11 +112,15 @@ install:
 
   - python setup.py --quiet install
 
-  # JUST FOR NOW : Install latest version of iris-grib.
+  # Install latest version of iris-grib.
+  # ONLY for Python 3, as Iris grib tests now require iris-grib >= v0.15.
   # TODO : remove when iris doesn't do an integration test requiring iris-grib.
-  - if [[ "${TEST_MINIMAL}" != true && ${PYTHON_VERSION} == 2* ]]; then
-        conda install --quiet -n ${ENV_NAME} python-ecmwf_grib;
-        pip install git+https://github.com/SciTools/iris-grib.git@v0.11.0;
+  # test against the latest version of python-eccodes.
+  # Conda-forge versioning is out of order (0.9.* is later than 2.12.*).
+  - >
+    if [[ "${TEST_MINIMAL}" != true && "${PYTHON_VERSION}" == 3* ]]; then
+        conda install --quiet -n ${ENV_NAME} python-eccodes">=0.9.1, <2";
+        conda install --quiet -n ${ENV_NAME} --no-deps iris-grib;
     fi
 
 script:
@@ -127,11 +131,11 @@ script:
   - >
     if [[ ${TEST_TARGET} == 'default' ]]; then
       export IRIS_REPO_DIR=${INSTALL_DIR};
-      python -m iris.tests.runner --default-tests --system-tests --print-failed-images;
+      python -m iris.tests.runner --default-tests --system-tests;
     fi
 
   - if [[ ${TEST_TARGET} == 'example' ]]; then
-      python -m iris.tests.runner --example-tests --print-failed-images;
+      python -m iris.tests.runner --example-tests;
     fi
 
   # A call to check "whatsnew" contributions are valid, because the Iris test
@@ -164,12 +168,18 @@ script:
     fi
 
   # Split the organisation out of the slug. See https://stackoverflow.com/a/5257398/741316 for description.
-  - ORG=(${TRAVIS_REPO_SLUG//\// })
+  # NOTE: a *separate* "export" command appears to be necessary here : A command of the
+  #   form "export ORG=.." failed to define ORG for the following command (?!)
+  - >
+    ORG=$(echo ${TRAVIS_REPO_SLUG} | cut -d/ -f1);
+    export ORG
+
+  - echo "Travis job context ORG=${ORG}; TRAVIS_EVENT_TYPE=${TRAVIS_EVENT_TYPE}; PUSH_BUILT_DOCS=${PUSH_BUILT_DOCS}"
 
   # When we merge a change to SciTools/iris, we can push docs to github pages.
   # At present, only the Python 3.7 "doctest" job does this.
   # Results appear at https://scitools-docs.github.io/iris/<<branchname>>/index.html
-  - if [[ ${ORG} == "SciTools" && ${TRAVIS_EVENT_TYPE} == 'push' && ${PUSH_BUILT_DOCS} == 'true' ]]; then
+  - if [[ "${ORG}" == 'SciTools' && "${TRAVIS_EVENT_TYPE}" == 'push' && "${PUSH_BUILT_DOCS}" == 'true' ]]; then
       cd ${INSTALL_DIR};
       pip install doctr;
       doctr deploy --deploy-repo SciTools-docs/iris --built-docs docs/iris/build/html

docs/iris/example_code/Meteorology/COP_maps.py

@@ -103,15 +103,15 @@ def main():
 
         # Add the first subplot showing the E1 scenario
         plt.subplot(121)
-        plt.title('HadGEM2 E1 Scenario',  fontsize=10)
+        plt.title('HadGEM2 E1 Scenario', fontsize=10)
         iplt.contourf(delta_e1, levels, colors=colors, extend='both')
         plt.gca().coastlines()
         # get the current axes' subplot for use later on
         plt1_ax = plt.gca()
 
         # Add the second subplot showing the A1B scenario
         plt.subplot(122)
-        plt.title('HadGEM2 A1B-Image Scenario',  fontsize=10)
+        plt.title('HadGEM2 A1B-Image Scenario', fontsize=10)
         contour_result = iplt.contourf(delta_a1b, levels, colors=colors,
                                        extend='both')
         plt.gca().coastlines()
@@ -131,8 +131,7 @@ def main():
         width = left - first_plot_left + width
 
         # Add axes to the figure, to place the colour bar
-        colorbar_axes = fig.add_axes([first_plot_left, bottom + 0.07,
-                                      width, 0.03])
+        colorbar_axes = fig.add_axes([first_plot_left, 0.18, width, 0.03])
 
         # Add the colour bar
         cbar = plt.colorbar(contour_result, colorbar_axes,

docs/iris/src/_templates/index.html

@@ -134,7 +134,7 @@
         <span class="linkdescr">extra information on specific technical issues</span></p>
     </li>
     <li>
-        <p class="biglink"><a class="biglink" href="whatsnew/2.3.html">What's new in Iris 2.3?</a><br/>
+        <p class="biglink"><a class="biglink" href="whatsnew/2.4.html">What's new in Iris 2.4?</a><br/>
         <span class="linkdescr">recent changes in Iris's capabilities</span></p>
     </li>
 	</ul>

docs/iris/src/_templates/layout.html

@@ -37,7 +37,7 @@
     </a>
     <div class="strapline">
       <h1>
-          Iris <span class="version">v2.3</span>
+          Iris <span class="version">v2.4</span>
       </h1>
       <p>
          A powerful, format-agnostic, community-driven Python library for analysing and

docs/iris/src/conf.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2010 - 2018, Met Office
+# (C) British Crown Copyright 2010 - 2020, Met Office
 #
 # This file is part of Iris.
 #
@@ -64,7 +64,6 @@
               'sphinx.ext.imgmath',
               'sphinx.ext.intersphinx',
               'matplotlib.sphinxext.mathmpl',
-              'matplotlib.sphinxext.only_directives',
               'matplotlib.sphinxext.plot_directive',
 
               # better class documentation

docs/iris/src/userguide/cube_maths.rst

@@ -205,12 +205,12 @@ Finally, the cube we have created needs to be given a suitable name::
 The result could now be plotted using the guidance provided in the 
 :doc:`plotting_a_cube` section.
 
-.. htmlonly::
+.. only:: html
 
     A very similar example to this can be found in 
     :doc:`/examples/Meteorology/deriving_phenomena`.
 
-.. latexonly::
+.. only:: latex
 
     A very similar example to this can be found in the examples section, 
     with the title "Deriving Exner Pressure and Air Temperature".

docs/iris/src/userguide/index.rst

@@ -13,7 +13,7 @@ fully before experimenting with your own data files.
 Much of the content has supplementary links to the reference documentation; you will not need to follow these
 links in order to understand the guide but they may serve as a useful reference for future exploration.
 
-.. htmlonly::
+.. only:: html
 
    Since later pages depend on earlier ones, try reading this user guide sequentially using the ``next`` and ``previous`` links.
 

docs/iris/src/userguide/loading_iris_cubes.rst

@@ -166,18 +166,36 @@ As we have seen, loading the following file creates several Cubes::
     cubes = iris.load(filename)
 
 Specifying a name as a constraint argument to :py:func:`iris.load` will mean 
-only cubes with a matching :meth:`name <iris.cube.Cube.name>` 
+only cubes with matching :meth:`name <iris.cube.Cube.names>`
 will be returned::
 
     filename = iris.sample_data_path('uk_hires.pp')
-    cubes = iris.load(filename, 'specific_humidity')
+    cubes = iris.load(filename, 'surface_altitude')
 
-To constrain the load to multiple distinct constraints, a list of constraints 
+Note that, the provided name will match against either the standard name,
+long name, NetCDF variable name or STASH metadata of a cube. Therefore, the
+previous example using the ``surface_altitude`` standard name constraint can
+also be achieved using the STASH value of ``m01s00i033``::
+
+    filename = iris.sample_data_path('uk_hires.pp')
+    cubes = iris.load(filename, 'm01s00i033')
+
+If further specific name constraint control is required i.e., to constrain
+against a combination of standard name, long name, NetCDF variable name and/or
+STASH metadata, consider using the :class:`iris.NameConstraint`. For example,
+to constrain against both a standard name of ``surface_altitude`` **and** a STASH
+of ``m01s00i033``::
+
+    filename = iris.sample_data_path('uk_hires.pp')
+    constraint = iris.NameConstraint(standard_name='surface_altitude', STASH='m01s00i033')
+    cubes = iris.load(filename, constraint)
+
+To constrain the load to multiple distinct constraints, a list of constraints
 can be provided.  This is equivalent to running load once for each constraint 
 but is likely to be more efficient::
 
     filename = iris.sample_data_path('uk_hires.pp')
-    cubes = iris.load(filename, ['air_potential_temperature', 'specific_humidity'])
+    cubes = iris.load(filename, ['air_potential_temperature', 'surface_altitude'])
 
 The :class:`iris.Constraint` class can be used to restrict coordinate values 
 on load. For example, to constrain the load to match 

docs/iris/src/whatsnew/2.4.rst

@@ -0,0 +1,49 @@
+What's New in Iris 2.4.0
+************************
+
+:Release: 2.4.0
+:Date: 2020-01-15
+
+This document explains the new/changed features of Iris in version 2.4.0
+(:doc:`View all changes <index>`.)
+
+
+Iris 2.4.0 Features
+===================
+
+.. admonition:: Last python 2 version of Iris
+
+    Iris 2.4 is a final extra release of Iris 2, which back-ports specific desired features from
+    Iris 3 (not yet released).
+
+    The purpose of this is both to support early adoption of certain newer features,
+    and to provide a final release for Python 2.
+
+    The next release of Iris will be version 3.0 : a major-version release which
+    introduces breaking API and behavioural changes, and only supports Python 3.
+
+* :class:`iris.coord_systems.Geostationary` can now accept creation arguments of
+  `false_easting=None` or `false_northing=None`, equivalent to values of 0.
+  Previously these kwargs could be omitted, but could not be set to `None`.
+  This also enables loading of netcdf data on a Geostationary grid, where either of these
+  keys is not present as a grid-mapping variable property : Previously, loading any
+  such data caused an exception.
+* The area weights used when performing area weighted regridding with :class:`iris.analysis.AreaWeighted`
+  are now cached.
+  This allows a significant speedup when regridding multiple similar cubes, by repeatedly using
+  a `'regridder' object <../iris/iris/analysis.html?highlight=regridder#iris.analysis.AreaWeighted.regridder>`_
+  which you created first.
+* Name constraint matching against cubes during loading or extracting has been relaxed from strictly matching
+  against the :meth:`~iris.cube.Cube.name`, to matching against either the
+  ``standard_name``, ``long_name``, NetCDF ``var_name``, or ``STASH`` attributes metadata of a cube.
+* Cubes and coordinates now have a new ``names`` property that contains a tuple of the
+  ``standard_name``, ``long_name``, NetCDF ``var_name``, and ``STASH`` attributes metadata.
+* The :class:`~iris.NameConstraint` provides richer name constraint matching when loading or extracting
+  against cubes, by supporting a constraint against any combination of
+  ``standard_name``, ``long_name``, NetCDF ``var_name`` and ``STASH``
+  from the attributes dictionary of a :class:`~iris.cube.Cube`.
+
+
+Iris 2.4.0 Dependency Updates
+=============================
+* Iris is now able to use the latest version of matplotlib.

docs/iris/src/whatsnew/index.rst

@@ -9,6 +9,7 @@ Iris versions.
 .. toctree::
    :maxdepth: 2
 
+   2.4.rst
    2.3.rst
    2.2.rst
    2.1.rst

lib/iris/__init__.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2010 - 2019, Met Office
+# (C) British Crown Copyright 2010 - 2020, Met Office
 #
 # This file is part of Iris.
 #
@@ -121,17 +121,29 @@ def callback(cube, field, filename):
 
 
 # Iris revision.
-__version__ = '2.3.0'
+__version__ = '2.4.0rc0'
 
 # Restrict the names imported when using "from iris import *"
-__all__ = ['load', 'load_cube', 'load_cubes', 'load_raw',
-           'save', 'Constraint', 'AttributeConstraint', 'sample_data_path',
-           'site_configuration', 'Future', 'FUTURE',
-           'IrisDeprecation']
+__all__ = [
+    "load",
+    "load_cube",
+    "load_cubes",
+    "load_raw",
+    "save",
+    "Constraint",
+    "AttributeConstraint",
+    "NameConstraint",
+    "sample_data_path",
+    "site_configuration",
+    "Future",
+    "FUTURE",
+    "IrisDeprecation",
+]
 
 
 Constraint = iris._constraints.Constraint
 AttributeConstraint = iris._constraints.AttributeConstraint
+NameConstraint = iris._constraints.NameConstraint
 
 
 class Future(threading.local):