num2pydate

cf_units/__init__.py

@@ -62,6 +62,7 @@
     "encode_date",
     "encode_time",
     "num2date",
+    "num2pydate",
     "suppress_errors",
 ]
 
@@ -419,7 +420,13 @@ def _discard_microsecond(date):
     return result
 
 
-def num2date(time_value, unit, calendar, only_use_cftime_datetimes=True):
+def num2date(
+    time_value,
+    unit,
+    calendar,
+    only_use_cftime_datetimes=True,
+    only_use_python_datetimes=False,
+):
     """
     Return datetime encoding of numeric time value (resolution of 1 second).
 
@@ -459,6 +466,11 @@ def num2date(time_value, unit, calendar, only_use_cftime_datetimes=True):
         calendar.  If False, returns datetime.datetime instances where
         possible.  Defaults to True.
 
+    * only_use_python_datetimes (bool):
+        If True, will always return datetime.datetime instances where
+        possible, and raise an exception if not.  Ignored if
+        only_use_cftime_datetimes is True.  Defaults to False.
+
     Returns:
         datetime, or numpy.ndarray of datetime object.
 
@@ -486,12 +498,36 @@ def num2date(time_value, unit, calendar, only_use_cftime_datetimes=True):
         unit_string = unit_string.replace("epoch", EPOCH)
     unit_inst = Unit(unit_string, calendar=calendar)
     return unit_inst.num2date(
-        time_value, only_use_cftime_datetimes=only_use_cftime_datetimes
+        time_value,
+        only_use_cftime_datetimes=only_use_cftime_datetimes,
+        only_use_python_datetimes=only_use_python_datetimes,
+    )
+
+
+def num2pydate(time_value, unit, calendar):
+    """
+    Convert time value(s) to python datetime.datetime objects, or raise an
+    exception if this is not possible.  Same as::
+
+        num2date(time_value, unit, calendar,
+                 only_use_cftime_datetimes=False,
+                 only_use_python_datetimes=True)
+
+    """
+    return num2date(
+        time_value,
+        unit,
+        calendar,
+        only_use_cftime_datetimes=False,
+        only_use_python_datetimes=True,
     )
 
 
 def _num2date_to_nearest_second(
-    time_value, unit, only_use_cftime_datetimes=True
+    time_value,
+    unit,
+    only_use_cftime_datetimes=True,
+    only_use_python_datetimes=False,
 ):
     """
     Return datetime encoding of numeric time value with respect to the given
@@ -507,6 +543,11 @@ def _num2date_to_nearest_second(
         calendar.  If False, returns datetime.datetime instances where
         possible.  Defaults to True.
 
+    * only_use_python_datetimes (bool):
+        If True, will always return datetime.datetime instances where
+        possible, and raise an exception if not.  Ignored if
+        only_use_cftime_datetimes is True.  Defaults to False.
+
     Returns:
         datetime, or numpy.ndarray of datetime object.
 
@@ -533,6 +574,7 @@ def _num2date_to_nearest_second(
         units=cftime_unit,
         calendar=unit.calendar,
         only_use_cftime_datetimes=only_use_cftime_datetimes,
+        only_use_python_datetimes=only_use_python_datetimes,
     )
     dates = cftime.num2date(time_values, **num2date_kwargs)
     try:
@@ -1933,7 +1975,12 @@ def date2num(self, date):
         date = _discard_microsecond(date)
         return cftime.date2num(date, self.cftime_unit, self.calendar)
 
-    def num2date(self, time_value, only_use_cftime_datetimes=True):
+    def num2date(
+        self,
+        time_value,
+        only_use_cftime_datetimes=True,
+        only_use_python_datetimes=False,
+    ):
         """
         Returns a datetime-like object calculated from the numeric time
         value using the current calendar and the unit time reference.
@@ -1965,6 +2012,11 @@ def num2date(self, time_value, only_use_cftime_datetimes=True):
             calendar.  If False, returns datetime.datetime instances where
             possible.  Defaults to True.
 
+        * only_use_python_datetimes (bool):
+            If True, will always return datetime.datetime instances where
+            possible, and raise an exception if not.  Ignored if
+            only_use_cftime_datetimes is True.  Defaults to False.
+
         Returns:
             datetime, or numpy.ndarray of datetime object.
 
@@ -1985,4 +2037,20 @@ def num2date(self, time_value, only_use_cftime_datetimes=True):
             time_value,
             self,
             only_use_cftime_datetimes=only_use_cftime_datetimes,
+            only_use_python_datetimes=only_use_python_datetimes,
+        )
+
+    def num2pydate(self, time_value):
+        """
+        Convert time value(s) to python datetime.datetime objects, or raise an
+        exception if this is not possible.  Same as::
+
+            unit.num2date(time_value, only_use_cftime_datetimes=False,
+                          only_use_python_datetimes=True)
+
+        """
+        return self.num2date(
+            time_value,
+            only_use_cftime_datetimes=False,
+            only_use_python_datetimes=True,
         )

cf_units/tests/integration/test__num2date_to_nearest_second.py

@@ -252,6 +252,18 @@ def test_fractional_second_360_day(self):
 
         self.check_timedelta(nums, units, expected)
 
+    def test_pydatetime_wrong_calendar(self):
+        unit = cf_units.Unit("days since 1970-01-01", calendar="360_day")
+        with self.assertRaisesRegex(
+            ValueError, "illegal calendar or reference date"
+        ):
+            _num2date_to_nearest_second(
+                1,
+                unit,
+                only_use_cftime_datetimes=False,
+                only_use_python_datetimes=True,
+            )
+
     # 365 day Calendar tests
 
     def test_simple_365_day(self):

cf_units/tests/integration/test_num2date.py

@@ -0,0 +1,28 @@
+# Copyright cf-units contributors
+#
+# This file is part of cf-units and is released under the LGPL license.
+# See COPYING and COPYING.LESSER in the root of the repository for full
+# licensing details.
+"""Test function :func:`cf_units.num2date`."""
+
+import unittest
+
+from cf_units import num2date
+
+
+class Test(unittest.TestCase):
+    def test_num2date_wrong_calendar(self):
+        with self.assertRaisesRegex(
+            ValueError, "illegal calendar or reference date"
+        ):
+            num2date(
+                1,
+                "days since 1970-01-01",
+                calendar="360_day",
+                only_use_cftime_datetimes=False,
+                only_use_python_datetimes=True,
+            )
+
+
+if __name__ == "__main__":
+    unittest.main()

cf_units/tests/integration/test_num2pydate.py

@@ -0,0 +1,29 @@
+# Copyright cf-units contributors
+#
+# This file is part of cf-units and is released under the LGPL license.
+# See COPYING and COPYING.LESSER in the root of the repository for full
+# licensing details.
+"""Test function :func:`cf_units.num2pydate`."""
+
+import datetime
+import unittest
+
+from cf_units import num2pydate
+
+
+class Test(unittest.TestCase):
+    def test_num2pydate_simple(self):
+        result = num2pydate(1, "days since 1970-01-01", calendar="standard")
+        expected = datetime.datetime(1970, 1, 2)
+        self.assertEqual(result, expected)
+        self.assertIsInstance(result, datetime.datetime)
+
+    def test_num2pydate_wrong_calendar(self):
+        with self.assertRaisesRegex(
+            ValueError, "illegal calendar or reference date"
+        ):
+            num2pydate(1, "days since 1970-01-01", calendar="360_day")
+
+
+if __name__ == "__main__":
+    unittest.main()

cf_units/tests/test_unit.py

@@ -964,13 +964,44 @@ def test_num2date_py_datetime_type(self):
         self.assertEqual(str(res), "2010-11-02 13:00:00")
         self.assertIsInstance(res, datetime.datetime)
 
+    def test_num2date_wrong_calendar(self):
+        u = Unit(
+            "hours since 2010-11-02 12:00:00", calendar=unit.CALENDAR_360_DAY
+        )
+        with self.assertRaisesRegex(
+            ValueError, "illegal calendar or reference date"
+        ):
+            u.num2date(
+                1,
+                only_use_cftime_datetimes=False,
+                only_use_python_datetimes=True,
+            )
+
     def test_date2num(self):
         u = Unit(
             "hours since 2010-11-02 12:00:00", calendar=unit.CALENDAR_STANDARD
         )
         d = datetime.datetime(2010, 11, 2, 13, 0, 0)
         self.assertEqual(str(u.num2date(u.date2num(d))), "2010-11-02 13:00:00")
 
+    def test_num2pydate_simple(self):
+        u = Unit(
+            "hours since 2010-11-02 12:00:00", calendar=unit.CALENDAR_STANDARD
+        )
+        result = u.num2pydate(1)
+        expected = datetime.datetime(2010, 11, 2, 13)
+        self.assertEqual(result, expected)
+        self.assertIsInstance(result, datetime.datetime)
+
+    def test_num2pydate_wrong_calendar(self):
+        u = Unit(
+            "hours since 2010-11-02 12:00:00", calendar=unit.CALENDAR_360_DAY
+        )
+        with self.assertRaisesRegex(
+            ValueError, "illegal calendar or reference date"
+        ):
+            u.num2pydate(1)
+
 
 class Test_as_unit(unittest.TestCase):
     def test_already_unit(self):

doc/source/utilities.rst

@@ -13,6 +13,7 @@ These are documented below.
 
 .. autofunction:: date2num
 .. autofunction:: num2date
+.. autofunction:: num2pydate
 
 .. autodata:: CALENDARS
 .. autodata:: CALENDAR_ALIASES