MNT: deprecate epoch2num/num2epoch

jklymak · jklymak · commit b9ec4c838d17 · 2021-02-08T15:21:23.000-08: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
@@ -1744,6 +1744,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.
@@ -1765,6 +1767,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.
