Use cftime instead of netcdftime (#3016)

* use cftime instead of netcdftime

* fix the docs too

* fix license year

* review actions

* simplify test_pandas

* what's new

* remove cf_units check

docs/iris/src/userguide/interpolation_and_regridding.rst

@@ -47,7 +47,7 @@ The specified coordinate must exist on the cube being interpolated! For example:
 are all examples of valid sample points.
 
 The values for coordinates that correspond to date/times can be supplied as
-datetime.datetime or netcdftime.datetime instances,
+datetime.datetime or cftime.datetime instances,
 e.g. ``[('time', datetime.datetime(2009, 11, 19, 10, 30))]``).
 
 Let's take the air temperature cube we've seen previously:

docs/iris/src/whatsnew/contributions_2.1/newfeature_2018-May-23_cftime.txt

@@ -0,0 +1,2 @@
+Iris updated its time-handling functionality from the netcdf4-python builtin netcdftime to the standalone module cftime.
+cftime is entirely compatible with netcdftime.

lib/iris/analysis/__init__.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2010 - 2017, Met Office
+# (C) British Crown Copyright 2010 - 2018, Met Office
 #
 # This file is part of Iris.
 #
@@ -2181,7 +2181,7 @@ def interpolator(self, cube, coords):
 
             The values for coordinates that correspond to date/times
             may optionally be supplied as datetime.datetime or
-            netcdftime.datetime instances.
+            cftime.datetime instances.
 
             For example, for the callable returned by:
             `Linear().interpolator(cube, ['latitude', 'longitude'])`,
@@ -2364,7 +2364,7 @@ def interpolator(self, cube, coords):
 
             The values for coordinates that correspond to date/times
             may optionally be supplied as datetime.datetime or
-            netcdftime.datetime instances.
+            cftime.datetime instances.
 
             For example, for the callable returned by:
             `Nearest().interpolator(cube, ['latitude', 'longitude'])`,

lib/iris/coord_categorisation.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2010 - 2016, Met Office
+# (C) British Crown Copyright 2010 - 2018, Met Office
 #
 # This file is part of Iris.
 #
@@ -173,7 +173,7 @@ def add_day_of_year(cube, coord, name='day_of_year'):
     (1..366 in leap years).
 
     """
-    # Note: netcdftime.datetime objects return a normal tuple from timetuple(),
+    # Note: cftime.datetime objects return a normal tuple from timetuple(),
     # unlike datetime.datetime objects that return a namedtuple.
     # Index the time tuple (element 7 is day of year) instead of using named
     # element tm_yday.

lib/iris/coords.py

@@ -32,7 +32,7 @@
 import warnings
 import zlib
 
-import netcdftime
+import cftime
 import numpy as np
 import numpy.ma as ma
 
@@ -267,13 +267,13 @@ def __common_cmp__(self, other, operator_method):
                                    operator.ge, operator.le):
             raise ValueError("Unexpected operator_method")
 
-        # Prevent silent errors resulting from missing netcdftime
+        # Prevent silent errors resulting from missing cftime
         # behaviour.
-        if (isinstance(other, netcdftime.datetime) or
-                (isinstance(self.point, netcdftime.datetime) and
+        if (isinstance(other, cftime.datetime) or
+                (isinstance(self.point, cftime.datetime) and
                  not isinstance(other, iris.time.PartialDateTime))):
             raise TypeError('Cannot determine the order of '
-                            'netcdftime.datetime objects')
+                            'cftime.datetime objects')
 
         if isinstance(other, Cell):
             # Cell vs Cell comparison for providing a strict sort order
@@ -336,7 +336,7 @@ def __common_cmp__(self, other, operator_method):
                 else:
                     me = max(self.bound)
 
-            # Work around to handle netcdftime.datetime comparison, which
+            # Work around to handle cftime.datetime comparison, which
             # doesn't return NotImplemented on failure in some versions of the
             # library
             try:
@@ -1127,7 +1127,7 @@ def cell(self, index):
             If `iris.FUTURE.cell_datetime_objects` is True, then this
             method will return Cell objects whose `points` and `bounds`
             attributes contain either datetime.datetime instances or
-            netcdftime.datetime instances (depending on the calendar).
+            cftime.datetime instances (depending on the calendar).
 
         .. deprecated:: 2.0.0
 

lib/iris/cube.py

@@ -3640,7 +3640,7 @@ def interpolate(self, sample_points, scheme, collapse_scalar=True):
             A sequence of (coordinate, points) pairs over which to
             interpolate. The values for coordinates that correspond to
             dates or times may optionally be supplied as datetime.datetime or
-            netcdftime.datetime instances.
+            cftime.datetime instances.
         * scheme:
             The type of interpolation to use to interpolate from this
             :class:`~iris.cube.Cube` to the given sample points. The

lib/iris/fileformats/nimrod_load_rules.py

@@ -23,7 +23,7 @@
 import warnings
 
 import cf_units
-import netcdftime
+import cftime
 import numpy as np
 
 import iris
@@ -76,9 +76,9 @@ def units(cube, field):
 
 def time(cube, field):
     """Add a time coord to the cube."""
-    valid_date = netcdftime.datetime(field.vt_year, field.vt_month,
-                                     field.vt_day, field.vt_hour,
-                                     field.vt_minute, field.vt_second)
+    valid_date = cftime.datetime(field.vt_year, field.vt_month,
+                                 field.vt_day, field.vt_hour,
+                                 field.vt_minute, field.vt_second)
     point = TIME_UNIT.date2num(valid_date)
 
     bounds = None
@@ -97,9 +97,9 @@ def time(cube, field):
 def reference_time(cube, field):
     """Add a 'reference time' to the cube, if present in the field."""
     if field.dt_year != field.int_mdi:
-        data_date = netcdftime.datetime(field.dt_year, field.dt_month,
-                                        field.dt_day, field.dt_hour,
-                                        field.dt_minute)
+        data_date = cftime.datetime(field.dt_year, field.dt_month,
+                                    field.dt_day, field.dt_hour,
+                                    field.dt_minute)
 
         ref_time_coord = DimCoord(TIME_UNIT.date2num(data_date),
                                   standard_name='forecast_reference_time',

lib/iris/fileformats/pp.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2010 - 2017, Met Office
+# (C) British Crown Copyright 2010 - 2018, Met Office
 #
 # This file is part of Iris.
 #
@@ -35,7 +35,7 @@
 import cf_units
 import numpy as np
 import numpy.ma as ma
-import netcdftime
+import cftime
 
 from iris._deprecation import warn_deprecated
 from iris._lazy_data import as_concrete_data, as_lazy_data, is_lazy_data
@@ -1425,8 +1425,8 @@ class PPField2(PPField):
 
     def _get_t1(self):
         if not hasattr(self, '_t1'):
-            self._t1 = netcdftime.datetime(self.lbyr, self.lbmon, self.lbdat,
-                                           self.lbhr, self.lbmin)
+            self._t1 = cftime.datetime(self.lbyr, self.lbmon, self.lbdat,
+                                       self.lbhr, self.lbmin)
         return self._t1
 
     def _set_t1(self, dt):
@@ -1440,14 +1440,14 @@ def _set_t1(self, dt):
             delattr(self, '_t1')
 
     t1 = property(_get_t1, _set_t1, None,
-                  "A netcdftime.datetime object consisting of the lbyr, lbmon,"
+                  "A cftime.datetime object consisting of the lbyr, lbmon,"
                   " lbdat, lbhr, and lbmin attributes.")
 
     def _get_t2(self):
         if not hasattr(self, '_t2'):
-            self._t2 = netcdftime.datetime(self.lbyrd, self.lbmond,
-                                           self.lbdatd, self.lbhrd,
-                                           self.lbmind)
+            self._t2 = cftime.datetime(self.lbyrd, self.lbmond,
+                                       self.lbdatd, self.lbhrd,
+                                       self.lbmind)
         return self._t2
 
     def _set_t2(self, dt):
@@ -1461,7 +1461,7 @@ def _set_t2(self, dt):
             delattr(self, '_t2')
 
     t2 = property(_get_t2, _set_t2, None,
-                  "A netcdftime.datetime object consisting of the lbyrd, "
+                  "A cftime.datetime object consisting of the lbyrd, "
                   "lbmond, lbdatd, lbhrd, and lbmind attributes.")
 
 
@@ -1478,8 +1478,8 @@ class PPField3(PPField):
 
     def _get_t1(self):
         if not hasattr(self, '_t1'):
-            self._t1 = netcdftime.datetime(self.lbyr, self.lbmon, self.lbdat,
-                                           self.lbhr, self.lbmin, self.lbsec)
+            self._t1 = cftime.datetime(self.lbyr, self.lbmon, self.lbdat,
+                                       self.lbhr, self.lbmin, self.lbsec)
         return self._t1
 
     def _set_t1(self, dt):
@@ -1493,14 +1493,14 @@ def _set_t1(self, dt):
             delattr(self, '_t1')
 
     t1 = property(_get_t1, _set_t1, None,
-                  "A netcdftime.datetime object consisting of the lbyr, lbmon,"
+                  "A cftime.datetime object consisting of the lbyr, lbmon,"
                   " lbdat, lbhr, lbmin, and lbsec attributes.")
 
     def _get_t2(self):
         if not hasattr(self, '_t2'):
-            self._t2 = netcdftime.datetime(self.lbyrd, self.lbmond,
-                                           self.lbdatd, self.lbhrd,
-                                           self.lbmind, self.lbsecd)
+            self._t2 = cftime.datetime(self.lbyrd, self.lbmond,
+                                       self.lbdatd, self.lbhrd,
+                                       self.lbmind, self.lbsecd)
         return self._t2
 
     def _set_t2(self, dt):
@@ -1514,7 +1514,7 @@ def _set_t2(self, dt):
             delattr(self, '_t2')
 
     t2 = property(_get_t2, _set_t2, None,
-                  "A netcdftime.datetime object consisting of the lbyrd, "
+                  "A cftime.datetime object consisting of the lbyrd, "
                   "lbmond, lbdatd, lbhrd, lbmind, and lbsecd attributes.")
 
 

lib/iris/fileformats/pp_load_rules.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2013 - 2017, Met Office
+# (C) British Crown Copyright 2013 - 2018, Met Office
 #
 # This file is part of Iris.
 #
@@ -295,7 +295,7 @@ def _collapse_degenerate_points_and_bounds(points, bounds=None, rtol=1.0e-7):
     All dimensions are tested, and if degenerate are reduced to length 1.
 
     Value equivalence is controlled by a tolerance, to avoid problems with
-    numbers from netcdftime.date2num, which has limited precision because of
+    numbers from cftime.date2num, which has limited precision because of
     the way it calculates with floats of days.
 
     Args:

lib/iris/fileformats/pp_save_rules.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2017, Met Office
+# (C) British Crown Copyright 2017 - 2018, Met Office
 #
 # This file is part of Iris.
 #
@@ -32,7 +32,7 @@
                                     scalar_coord,
                                     vector_coord)
 from iris.util import is_regular, regular_step
-import netcdftime
+import cftime
 
 
 def _basic_coord_system_rules(cube, pp):
@@ -129,7 +129,7 @@ def _general_time_rules(cube, pp):
         pp.lbtim.ia = 0
         pp.lbtim.ib = 0
         pp.t1 = time_coord.units.num2date(time_coord.points[0])
-        pp.t2 = netcdftime.datetime(0, 0, 0)
+        pp.t2 = cftime.datetime(0, 0, 0)
 
     # Forecast.
     if (time_coord is not None and
@@ -252,10 +252,10 @@ def _general_time_rules(cube, pp):
         pp.t1 = time_coord.units.num2date(time_coord.bounds[0, 0])
         pp.t2 = time_coord.units.num2date(time_coord.bounds[0, 1])
         if pp.t1.month == 12:
-            pp.t1 = netcdftime.datetime(pp.t1.year)
+            pp.t1 = cftime.datetime(pp.t1.year)
         else:
-            pp.t1 = netcdftime.datetime(pp.t1.year-1, 12, 1, 0, 0, 0)
-        pp.t2 = netcdftime.datetime(pp.t2.year, 3, 1, 0, 0, 0)
+            pp.t1 = cftime.datetime(pp.t1.year-1, 12, 1, 0, 0, 0)
+        pp.t2 = cftime.datetime(pp.t2.year, 3, 1, 0, 0, 0)
         _conditional_warning(
             time_coord.bounds[0, 0] != time_coord.units.date2num(pp.t1),
             "modified t1 for climatological seasonal mean")
@@ -278,8 +278,8 @@ def _general_time_rules(cube, pp):
         # TODO: wut?
         pp.t1 = time_coord.units.num2date(time_coord.bounds[0, 0])
         pp.t2 = time_coord.units.num2date(time_coord.bounds[0, 1])
-        pp.t1 = netcdftime.datetime(pp.t1.year, 3, 1, 0, 0, 0)
-        pp.t2 = netcdftime.datetime(pp.t2.year, 6, 1, 0, 0, 0)
+        pp.t1 = cftime.datetime(pp.t1.year, 3, 1, 0, 0, 0)
+        pp.t2 = cftime.datetime(pp.t2.year, 6, 1, 0, 0, 0)
         _conditional_warning(
             time_coord.bounds[0, 0] != time_coord.units.date2num(pp.t1),
             "modified t1 for climatological seasonal mean")
@@ -302,8 +302,8 @@ def _general_time_rules(cube, pp):
         # TODO: wut?
         pp.t1 = time_coord.units.num2date(time_coord.bounds[0, 0])
         pp.t2 = time_coord.units.num2date(time_coord.bounds[0, 1])
-        pp.t1 = netcdftime.datetime(pp.t1.year, 6, 1, 0, 0, 0)
-        pp.t2 = netcdftime.datetime(pp.t2.year, 9, 1, 0, 0, 0)
+        pp.t1 = cftime.datetime(pp.t1.year, 6, 1, 0, 0, 0)
+        pp.t2 = cftime.datetime(pp.t2.year, 9, 1, 0, 0, 0)
         _conditional_warning(
             time_coord.bounds[0, 0] != time_coord.units.date2num(pp.t1),
             "modified t1 for climatological seasonal mean")
@@ -326,8 +326,8 @@ def _general_time_rules(cube, pp):
         # TODO: wut?
         pp.t1 = time_coord.units.num2date(time_coord.bounds[0, 0])
         pp.t2 = time_coord.units.num2date(time_coord.bounds[0, 1])
-        pp.t1 = netcdftime.datetime(pp.t1.year, 9, 1, 0, 0, 0)
-        pp.t2 = netcdftime.datetime(pp.t2.year, 12, 1, 0, 0, 0)
+        pp.t1 = cftime.datetime(pp.t1.year, 9, 1, 0, 0, 0)
+        pp.t2 = cftime.datetime(pp.t2.year, 12, 1, 0, 0, 0)
         _conditional_warning(
             time_coord.bounds[0, 0] != time_coord.units.date2num(pp.t1),
             "modified t1 for climatological seasonal mean")

lib/iris/fileformats/um/_fast_load_structured_fields.py

@@ -1,4 +1,4 @@
-# (C) British Crown Copyright 2014 - 2017, Met Office
+# (C) British Crown Copyright 2014 - 2018, Met Office
 #
 # This file is part of Iris.
 #
@@ -28,7 +28,7 @@
 
 import itertools
 
-from netCDF4 import netcdftime
+import cftime
 import numpy as np
 
 from iris._lazy_data import as_lazy_data, multidim_lazy_stack
@@ -217,8 +217,8 @@ def _calculate_structure(self):
                 arr_shape = arr.shape[:-1]
                 extra_length = arr.shape[-1]
                 # Flatten out the array apart from the last dimension,
-                # convert to netcdftime objects, then reshape back.
-                arr = np.array([netcdftime.datetime(*args)
+                # convert to cftime objects, then reshape back.
+                arr = np.array([cftime.datetime(*args)
                                 for args in arr.reshape(-1, extra_length)]
                                ).reshape(arr_shape)
                 vector_element_arrays_and_dims[name] = (arr, dims)

lib/iris/pandas.py

@@ -28,7 +28,7 @@
 
 import cf_units
 from cf_units import Unit
-import netcdftime
+import cftime
 import numpy as np
 import numpy.ma as ma
 import pandas
@@ -59,7 +59,7 @@ def _add_iris_coord(cube, name, points, dim, calendar=None):
 
     # Convert datetime objects to Iris' current datetime representation.
     if points.dtype == object:
-        dt_types = (datetime.datetime, netcdftime.datetime)
+        dt_types = (datetime.datetime, cftime.datetime)
         if all([isinstance(i, dt_types) for i in points]):
             units = Unit("hours since epoch", calendar=calendar)
             points = units.date2num(points)

lib/iris/plot.py

@@ -37,8 +37,8 @@
 import matplotlib.pyplot as plt
 from matplotlib.offsetbox import AnchoredText
 import matplotlib.ticker as mpl_ticker
+import cftime
 import matplotlib.transforms as mpl_transforms
-import netcdftime
 import numpy as np
 import numpy.ma as ma
 
@@ -434,7 +434,7 @@ def _fixup_dates(coord, values):
                 raise IrisError(msg)
 
             r = [nc_time_axis.CalendarDateTime(
-                 netcdftime.datetime(*date), coord.units.calendar)
+                 cftime.datetime(*date), coord.units.calendar)
                  for date in dates]
         values = np.empty(len(r), dtype=object)
         values[:] = r