bootstrap ci for 3.0.x

.cirrus.yml

@@ -3,16 +3,14 @@
 #   - https://cirrus-ci.org/guide/writing-tasks/#environment-variables
 #   - https://cirrus-ci.org/guide/tips-and-tricks/#sharing-configuration-between-tasks
 #   - https://cirrus-ci.org/guide/linux/
-#   - https://cirrus-ci.org/guide/macOS/
-#   - https://cirrus-ci.org/guide/windows/
 #   - https://hub.docker.com/_/gcc/
 #   - https://hub.docker.com/_/python/
 
 #
 # Global defaults.
 #
 container:
-  image: python:3.8
+  image: gcc:latest
   cpu: 2
   memory: 4G
 
@@ -38,10 +36,12 @@ env:
   NOX_CACHE_BUILD: "0"
   # Increment the build number to force new pip cache upload.
   PIP_CACHE_BUILD: "0"
-  # Pip package to be upgraded/installed.
+  # Pip packages to be upgraded/installed.
   PIP_CACHE_PACKAGES: "pip setuptools wheel nox"
+  # Conda packages to be installed.
+  CONDA_CACHE_PACKAGES: "nox pip"
   # Git commit hash for iris test data.
-  IRIS_TEST_DATA_REF: "fffb9b14b9cb472c5eb2ebb7fd19acb7f6414a30"
+  IRIS_TEST_DATA_VERSION: "2.0.0"
   # Base directory for the iris-test-data.
   IRIS_TEST_DATA_DIR: ${HOME}/iris-test-data
 
@@ -52,54 +52,75 @@ env:
 linux_task_template: &LINUX_TASK_TEMPLATE
   auto_cancellation: true
   env:
-    IRIS_REPO_DIR: ${CIRRUS_WORKING_DIR}
     PATH: ${HOME}/miniconda/bin:${PATH}
     SITE_CFG: ${CIRRUS_WORKING_DIR}/lib/iris/etc/site.cfg
   conda_cache:
     folder: ${HOME}/miniconda
     fingerprint_script:
       - wget --quiet https://repo.continuum.io/miniconda/Miniconda3-latest-Linux-x86_64.sh -O miniconda.sh
       - echo "${CIRRUS_OS} $(sha256sum miniconda.sh)"
+      - echo "${CONDA_CACHE_PACKAGES}"
       - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${CONDA_CACHE_BUILD}"
+      - uname -r
     populate_script:
+      - export CONDA_OVERRIDE_LINUX="$(uname -r | cut -d'+' -f1)"
       - bash miniconda.sh -b -p ${HOME}/miniconda
       - conda config --set always_yes yes --set changeps1 no
       - conda config --set show_channel_urls True
       - conda config --add channels conda-forge
       - conda update --quiet --name base conda
-      - conda install --quiet --name base nox pip
+      - conda install --quiet --name base ${CONDA_CACHE_PACKAGES}
   cartopy_cache:
     folder: ${HOME}/.local/share/cartopy
     fingerprint_script:
       - echo "${CIRRUS_OS}"
       - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${CARTOPY_CACHE_BUILD}"
   nox_cache:
     folder: ${CIRRUS_WORKING_DIR}/.nox
+    reupload_on_changes: true
     fingerprint_script:
       - echo "${CIRRUS_TASK_NAME}"
-      - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${NOX_CACHE_BUILD}"
-      - sha256sum ${CIRRUS_WORKING_DIR}/requirements/ci/py$(echo ${PY_VER} | tr -d ".").yml
+      - echo "${NOX_CACHE_BUILD}"
 
 
 #
-# YAML alias for compute credits
+# YAML alias for compute credits.
 #
 compute_credits_template: &CREDITS_TEMPLATE
-  # Only use credits for non-DRAFT pull-requests to SciTools/iris master branch by collaborators
-  use_compute_credits: $CIRRUS_REPO_FULL_NAME == 'SciTools/iris' && $CIRRUS_USER_COLLABORATOR == 'true' && $CIRRUS_PR_DRAFT == 'false' && $CIRRUS_BASE_BRANCH == 'master' && $CIRRUS_PR != ''
+  # Only use credits for non-DRAFT pull-requests to a SciTools/iris branch by collaborators
+  use_compute_credits: ${CIRRUS_REPO_FULL_NAME} == "SciTools/iris" && ${CIRRUS_USER_COLLABORATOR} == "true" && ${CIRRUS_PR_DRAFT} == "false" && ${CIRRUS_PR} != ""
+
+
+#
+# YAML alias for the iris-test-data cache.
+#
+iris_test_data_template: &IRIS_TEST_DATA_TEMPLATE
+  data_cache:
+    folder: ${IRIS_TEST_DATA_DIR}
+    fingerprint_script:
+      - echo "iris-test-data v${IRIS_TEST_DATA_VERSION}"
+    populate_script:
+      - wget --quiet https://github.com/SciTools/iris-test-data/archive/v${IRIS_TEST_DATA_VERSION}.zip -O iris-test-data.zip
+      - unzip -q iris-test-data.zip
+      - mv iris-test-data-${IRIS_TEST_DATA_VERSION} ${IRIS_TEST_DATA_DIR}
+
 
 #
 # Linting
 #
 lint_task:
-  only_if: $SKIP_LINT_TASK == ""
+  only_if: ${SKIP_LINT_TASK} == ""
   << : *CREDITS_TEMPLATE
   auto_cancellation: true
+  container:
+    image: python:3.8
+    cpu: 2
+    memory: 4G
   name: "${CIRRUS_OS}: flake8 and black"
   pip_cache:
     folder: ~/.cache/pip
     fingerprint_script:
-      - echo "${CIRRUS_TASK_NAME}"
+      - echo "${CIRRUS_TASK_NAME} py${PYTHON_VERSION}"
       - echo "$(date +%Y).$(expr $(date +%U) / ${CACHE_PERIOD}):${PIP_CACHE_BUILD} ${PIP_CACHE_PACKAGES}"
   lint_script:
     - pip list
@@ -113,7 +134,7 @@ lint_task:
 # Testing Minimal (Linux)
 #
 test_minimal_task:
-  only_if: $SKIP_TEST_MINIMAL_TASK == "" && $SKIP_ALL_TEST_TASKS == ""
+  only_if: ${SKIP_TEST_MINIMAL_TASK} == "" && ${SKIP_ALL_TEST_TASKS} == ""
   << : *CREDITS_TEMPLATE
   matrix:
     env:
@@ -123,22 +144,19 @@ test_minimal_task:
     env:
       PY_VER: 3.8
   name: "${CIRRUS_OS}: py${PY_VER} tests (minimal)"
-  container:
-    image: gcc:latest
-    cpu: 2
-    memory: 4G
   << : *LINUX_TASK_TEMPLATE
   tests_script:
+    - export CONDA_OVERRIDE_LINUX="$(uname -r | cut -d'+' -f1)"
     - echo "[Resources]" > ${SITE_CFG}
     - echo "doc_dir = ${CIRRUS_WORKING_DIR}/docs/iris" >> ${SITE_CFG}
-    - nox --session tests
+    - nox --session tests -- --verbose
 
 
 #
 # Testing Full (Linux)
 #
 test_full_task:
-  only_if: $SKIP_TEST_FULL_TASK == "" && $SKIP_ALL_TEST_TASKS == ""
+  only_if: ${SKIP_TEST_FULL_TASK} == "" && ${SKIP_ALL_TEST_TASKS} == ""
   << : *CREDITS_TEMPLATE
   matrix:
     env:
@@ -152,108 +170,74 @@ test_full_task:
     image: gcc:latest
     cpu: 6
     memory: 8G
-  data_cache:
-    folder: ${IRIS_TEST_DATA_DIR}
-    fingerprint_script:
-      - echo "${IRIS_TEST_DATA_REF}"
-    populate_script:
-      - wget --quiet https://github.com/SciTools/iris-test-data/archive/${IRIS_TEST_DATA_REF}.zip -O iris-test-data.zip
-      - unzip -q iris-test-data.zip
-      - mv iris-test-data-$(echo "${IRIS_TEST_DATA_REF}" | sed "s/^v//") ${IRIS_TEST_DATA_DIR}
+  << : *IRIS_TEST_DATA_TEMPLATE
   << : *LINUX_TASK_TEMPLATE
   tests_script:
+    - export CONDA_OVERRIDE_LINUX="$(uname -r | cut -d'+' -f1)"
     - echo "[Resources]" > ${SITE_CFG}
     - echo "test_data_dir = ${IRIS_TEST_DATA_DIR}/test_data" >> ${SITE_CFG}
     - echo "doc_dir = ${CIRRUS_WORKING_DIR}/docs/iris" >> ${SITE_CFG}
-    - nox --session tests
+    - nox --session tests -- --verbose
 
 
 #
 # Testing Documentation Gallery (Linux)
 #
 gallery_task:
-  only_if: $SKIP_GALLERY_TASK == "" && $SKIP_ALL_DOC_TASKS == ""
+  only_if: ${SKIP_GALLERY_TASK} == "" && ${SKIP_ALL_DOC_TASKS} == ""
   << : *CREDITS_TEMPLATE
-  matrix:
-    env:
-      PY_VER: 3.8
+  env:
+    PY_VER: 3.8
   name: "${CIRRUS_OS}: py${PY_VER} doc tests (gallery)"
-  container:
-    image: gcc:latest
-    cpu: 2
-    memory: 4G
-  data_cache:
-    folder: ${IRIS_TEST_DATA_DIR}
-    fingerprint_script:
-      - echo "${IRIS_TEST_DATA_REF}"
-    populate_script:
-      - wget --quiet https://github.com/SciTools/iris-test-data/archive/${IRIS_TEST_DATA_REF}.zip -O iris-test-data.zip
-      - unzip -q iris-test-data.zip
-      - mv iris-test-data-$(echo "${IRIS_TEST_DATA_REF}" | sed "s/^v//") ${IRIS_TEST_DATA_DIR}
+  << : *IRIS_TEST_DATA_TEMPLATE
   << : *LINUX_TASK_TEMPLATE
   tests_script:
+    - export CONDA_OVERRIDE_LINUX="$(uname -r | cut -d'+' -f1)"
     - echo "[Resources]" > ${SITE_CFG}
     - echo "test_data_dir = ${IRIS_TEST_DATA_DIR}/test_data" >> ${SITE_CFG}
     - echo "doc_dir = ${CIRRUS_WORKING_DIR}/docs/iris" >> ${SITE_CFG}
-    - nox --session gallery
+    - nox --session gallery -- --verbose
 
 
 #
 # Testing Documentation (Linux)
 #
 doctest_task:
-  only_if: $SKIP_DOCTEST_TASK == "" && $SKIP_ALL_DOC_TASKS == ""
+  only_if: ${SKIP_DOCTEST_TASK} == "" && ${SKIP_ALL_DOC_TASKS} == ""
   << : *CREDITS_TEMPLATE
-  matrix:
-    env:
-      PY_VER: 3.8
-  name: "${CIRRUS_OS}: py${PY_VER} doc tests"
-  container:
-    image: gcc:latest
-    cpu: 2
-    memory: 4G
   env:
+    PY_VER: 3.8
     MPL_RC_DIR: ${HOME}/.config/matplotlib
     MPL_RC_FILE: ${HOME}/.config/matplotlib/matplotlibrc
-  data_cache:
-    folder: ${IRIS_TEST_DATA_DIR}
-    fingerprint_script:
-      - echo "${IRIS_TEST_DATA_REF}"
-    populate_script:
-      - wget --quiet https://github.com/SciTools/iris-test-data/archive/${IRIS_TEST_DATA_REF}.zip -O iris-test-data.zip
-      - unzip -q iris-test-data.zip
-      - mv iris-test-data-$(echo "${IRIS_TEST_DATA_REF}" | sed "s/^v//") ${IRIS_TEST_DATA_DIR}
+  name: "${CIRRUS_OS}: py${PY_VER} doc tests"
+  << : *IRIS_TEST_DATA_TEMPLATE
   << : *LINUX_TASK_TEMPLATE
   tests_script:
+    - export CONDA_OVERRIDE_LINUX="$(uname -r | cut -d'+' -f1)"
     - echo "[Resources]" > ${SITE_CFG}
     - echo "test_data_dir = ${IRIS_TEST_DATA_DIR}/test_data" >> ${SITE_CFG}
     - echo "doc_dir = ${CIRRUS_WORKING_DIR}/docs/iris" >> ${SITE_CFG}
     - mkdir -p ${MPL_RC_DIR}
     - echo "backend : agg" > ${MPL_RC_FILE}
     - echo "image.cmap : viridis" >> ${MPL_RC_FILE}
-    - nox --session doctest
+    - nox --session doctest -- --verbose
 
 
 #
 # Testing Documentation Link Check (Linux)
 #
 linkcheck_task:
-  only_if: $SKIP_LINKCHECK_TASK == "" && $SKIP_ALL_DOC_TASKS == ""
+  only_if: ${SKIP_LINKCHECK_TASK} == "" && ${SKIP_ALL_DOC_TASKS} == ""
   << : *CREDITS_TEMPLATE
-  matrix:
-    env:
-      PY_VER: 3.8
-  name: "${CIRRUS_OS}: py${PY_VER} doc link check"
-  container:
-    image: gcc:latest
-    cpu: 2
-    memory: 4G
   env:
+    PY_VER: 3.8
     MPL_RC_DIR: ${HOME}/.config/matplotlib
     MPL_RC_FILE: ${HOME}/.config/matplotlib/matplotlibrc
+  name: "${CIRRUS_OS}: py${PY_VER} doc link check"
   << : *LINUX_TASK_TEMPLATE
   tests_script:
+    - export CONDA_OVERRIDE_LINUX="$(uname -r | cut -d'+' -f1)"
     - mkdir -p ${MPL_RC_DIR}
     - echo "backend : agg" > ${MPL_RC_FILE}
     - echo "image.cmap : viridis" >> ${MPL_RC_FILE}
-    - nox --session linkcheck
+    - nox --session linkcheck -- --verbose

docs/iris/src/developers_guide/contributing_code_formatting.rst

@@ -39,7 +39,7 @@ linted according to our ``.flake8`` configuration file. Note that,
 for each ``.pre-commit-config.yaml`` git hook.
 
 Additionally, you may wish to enable ``black`` for your preferred
-`editor/IDE <https://black.readthedocs.io/en/stable/editor_integration.html#editor-integration>`_.
+`editor/IDE <https://black.readthedocs.io/en/stable/integrations/editors.html>`_.
 
 With the ``pre-commit`` configured, the output of performing a ``git commit``
 will look similar to::

lib/iris/coord_categorisation.py

@@ -93,7 +93,7 @@ def vectorised_fn(*args):
 # Private "helper" function
 def _pt_date(coord, time):
     """
-    Return the date of a time-coordinate point.
+    Return the datetime of a time-coordinate point.
 
     Args:
 
@@ -103,14 +103,11 @@ def _pt_date(coord, time):
         value of a coordinate point
 
     Returns:
-        datetime.date
+        cftime.datetime
     """
     # NOTE: All of the currently defined categorisation functions are
     # calendar operations on Time coordinates.
-    #  - All these currently depend on Unit::num2date, which is deprecated (!!)
-    #  - We will want to do better, when we sort out our own Calendars.
-    #  - For now, just make sure these all call through this one function.
-    return coord.units.num2date(time)
+    return coord.units.num2date(time, only_use_cftime_datetimes=True)
 
 
 # --------------------------------------------

lib/iris/fileformats/netcdf.py

@@ -1043,7 +1043,7 @@ def write(
             dtype(i.e. 'i2', 'short', 'u4') or a dict of packing parameters as
             described below. This provides support for netCDF data packing as
             described in
-            http://www.unidata.ucar.edu/software/netcdf/docs/BestPractices.html#bp_Packed-Data-Values
+            https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/best_practices.html#bp_Packed-Data-Values
             If this argument is a type (or type string), appropriate values of
             scale_factor and add_offset will be automatically calculated based
             on `cube.data` and possible masking. For more control, pass a dict
@@ -2589,7 +2589,7 @@ def save(
         (i.e. 'i2', 'short', 'u4') or a dict of packing parameters as described
         below or an iterable of such types, strings, or dicts.
         This provides support for netCDF data packing as described in
-        http://www.unidata.ucar.edu/software/netcdf/docs/BestPractices.html#bp_Packed-Data-Values
+        https://www.unidata.ucar.edu/software/netcdf/documentation/NUG/best_practices.html#bp_Packed-Data-Values
         If this argument is a type (or type string), appropriate values of
         scale_factor and add_offset will be automatically calculated based
         on `cube.data` and possible masking. For more control, pass a dict with