MNT: deprecate epoch2num/num2epoch

jklymak · jklymak · commit 669e1ccd680d · 2021-05-10T15:27:00.000-07:00
diff --git a/doc/api/next_api_changes/deprecations/19483-JMK.rst b/doc/api/next_api_changes/deprecations/19483-JMK.rst
@@ -0,0 +1,7 @@
+``epoch2num`` and ``num2epoch`` are deprecated
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+These methods convert from unix timestamps to matplotlib floats, but are not
+useed internally to matplotlib, and should not be needed by endusers.
+To convert a unix timestamp to datetime, simply use
+`datetime.datetime.utcfromtimestamp`, or to use numpy datetime64
+``dt = np.datetim64(e*1e6, 'us')``.  
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -1729,6 +1729,8 @@ def _get_interval(self):
         return self._interval
 
 
+@_api.deprecated("3.5",
+                 alternative="mdates.date2num(datetime.utcfromtimestamp(e))")
 def epoch2num(e):
     """
     Convert UNIX time to days since Matplotlib epoch.
@@ -1750,6 +1752,7 @@ def epoch2num(e):
     return (dt + np.asarray(e)) / SEC_PER_DAY
 
 
+@_api.deprecated("3.5", alternative="mdates.num2date(e).timestamp()")
 def num2epoch(d):
     """
     Convert days since Matplotlib epoch to UNIX time.
diff --git a/lib/matplotlib/tests/test_dates.py b/lib/matplotlib/tests/test_dates.py
@@ -11,6 +11,7 @@
 import matplotlib.pyplot as plt
 from matplotlib.testing.decorators import image_comparison
 import matplotlib.ticker as mticker
+import matplotlib._api as _api
 
 
 def test_date_numpyx():
@@ -1078,18 +1079,6 @@ def test_change_interval_multiples():
     assert ax.get_xticklabels()[1].get_text() == 'Feb 01 2020'
 
 
-def test_epoch2num():
-    mdates._reset_epoch_test_example()
-    mdates.set_epoch('0000-12-31')
-    assert mdates.epoch2num(86400) == 719164.0
-    assert mdates.num2epoch(719165.0) == 86400 * 2
-    # set back to the default
-    mdates._reset_epoch_test_example()
-    mdates.set_epoch('1970-01-01T00:00:00')
-    assert mdates.epoch2num(86400) == 1.0
-    assert mdates.num2epoch(2.0) == 86400 * 2
-
-
 def test_julian2num():
     mdates._reset_epoch_test_example()
     mdates.set_epoch('0000-12-31')
@@ -1102,3 +1091,16 @@ def test_julian2num():
     mdates.set_epoch('1970-01-01T00:00:00')
     assert mdates.julian2num(2440588.5) == 1.0
     assert mdates.num2julian(2.0) == 2440589.5
+
+
+def test_epoch2num():
+    with _api.suppress_matplotlib_deprecation_warning():
+        mdates._reset_epoch_test_example()
+        mdates.set_epoch('0000-12-31')
+        assert mdates.epoch2num(86400) == 719164.0
+        assert mdates.num2epoch(719165.0) == 86400 * 2
+        # set back to the default
+        mdates._reset_epoch_test_example()
+        mdates.set_epoch('1970-01-01T00:00:00')
+        assert mdates.epoch2num(86400) == 1.0
+        assert mdates.num2epoch(2.0) == 86400 * 2
