Doc fixes

jklymak · jklymak · commit d25a32115ad4 · 2020-04-20T08:17:49.000-07:00
diff --git a/doc/users/next_whats_new/2020-04-09-datetime-epoch-change.rst b/doc/users/next_whats_new/2020-04-09-datetime-epoch-change.rst
@@ -1,12 +1,12 @@
 Dates now use a modern epoch
 ----------------------------
 
-Matplotlib must convert dates to floating point numbers for plotting, which
-is done as floating point days since an epoch.  Previously, `.dates.date2num`
-used an epoch of ``0000-12-31T00:00:00``, which aside from meaning
-``0001-01-01`` was converted to 1.0, also meant that a modern date was not
-able to preserve microseconds because 2000 years times the 2^(-52) resolution
-of a 64-bit float gives 14 microseconds.
+Matplotlib converts dates to days since an epoch using `.dates.date2num` (via
+`matplotlib.units`).  Previously, an epoch of ``0000-12-31T00:00:00`` was used
+so that ``0001-01-01`` was converted to 1.0.  An epoch so distant in the
+past meant that a modern date was not able to preserve microseconds because
+2000 years times the 2^(-52) resolution of a 64-bit float gives 14
+microseconds.
 
 Here we change the default epoch to the more reasonable UNIX default of
 ``1970-01-01T00:00:00`` which for a modern date has 0.35 microsecond
diff --git a/examples/ticks_and_spines/date_precision_and_epochs.py b/examples/ticks_and_spines/date_precision_and_epochs.py
@@ -25,6 +25,15 @@
 import matplotlib.pyplot as plt
 import matplotlib.dates as mdates
 
+
+def _reset_epoch_for_tutorial():
+    """
+    Users (and downstream libraries) should not use the private method of
+    resetting the epoch.
+    """
+    mdates._reset_epoch_test_example()
+
+
 #############################################################################
 # Datetime
 # --------
@@ -36,7 +45,7 @@
 old_epoch = '0000-12-31T00:00:00'
 new_epoch = '1970-01-01T00:00:00'
 
-mdates._reset_epoch()  # Don't do this.  Just being done for this tutorial.
+_reset_epoch_for_tutorial()  # Don't do this.  Just for this tutorial.
 mdates.set_epoch(old_epoch)  # old epoch (pre MPL 3.3)
 
 date1 = datetime.datetime(2000, 1, 1, 0, 10, 0, 12,
@@ -59,27 +68,20 @@
 
 #############################################################################
 # If a user wants to use modern dates at microsecond precision, they
-# can change the epoch.  However, note that calling `.set_epoch` yields an
-# error here.  That is because mixing epochs in a script is confusing, so
-# we attach a sentinel that doesn't let it be changed after any dates
-# code has been run.  In order to run `~.set_epoch` it must be called before
-# any date code has been executed (i.e. near the top of a script).
+# can change the epoch using `~.set_epoch`.  However, the epoch has to be
+# set before any date operations to prevent confusion between different
+# epochs. Trying to change the epoch later will raise a `RuntimeError`.
 
 try:
     mdates.set_epoch(new_epoch)  # this is the new MPL 3.3 default.
 except RuntimeError as e:
     print('RuntimeError:', str(e))
 
 #############################################################################
-# For this tutorial, we reset the sentinel using a private method.
-#
-# .. warning::
-#
-#    Users (and downstream libraries) should avoid using the private
-#    method of resetting sentinel.
-#
+# For this tutorial, we reset the sentinel using a private method, but users
+# should just set the epoch once, if at all.
 
-mdates._reset_epoch()  # Don't do this.  Just being done for this tutorial.
+_reset_epoch_for_tutorial()  # Just being done for this tutorial.
 mdates.set_epoch(new_epoch)
 
 date1 = datetime.datetime(2020, 1, 1, 0, 10, 0, 12,
@@ -98,7 +100,7 @@
 # only converted back to datetime objects, which have microsecond resolution,
 # and years that only span 0000 to 9999.
 
-mdates._reset_epoch()  # Don't do this.  Just being done for this tutorial.
+_reset_epoch_for_tutorial()  # Don't do this.  Just for this tutorial.
 mdates.set_epoch(new_epoch)
 
 date1 = np.datetime64('2000-01-01T00:10:00.000012')
@@ -114,7 +116,7 @@
 # This all of course has an effect on plotting.  With the old default epoch
 # the times were rounded, leading to jumps in the data:
 
-mdates._reset_epoch()  # Don't do this.  Just being done for this tutorial.
+_reset_epoch_for_tutorial()  # Don't do this.  Just for this tutorial.
 mdates.set_epoch(old_epoch)
 
 x = np.arange('2000-01-01T00:00:00.0', '2000-01-01T00:00:00.000100',
@@ -129,7 +131,7 @@
 #############################################################################
 # For a more recent epoch, the plot is smooth:
 
-mdates._reset_epoch()  # Don't do this.  Just being done for this tutorial.
+_reset_epoch_for_tutorial()  # Don't do this.  Just for this tutorial.
 mdates.set_epoch(new_epoch)
 
 fig, ax = plt.subplots(constrained_layout=True)
@@ -138,7 +140,7 @@
 plt.setp(ax.xaxis.get_majorticklabels(), rotation=40)
 plt.show()
 
-mdates._reset_epoch()  # Don't do this.  Just being done for this tutorial.
+_reset_epoch_for_tutorial()  # Don't do this.  Just for this tutorial.
 
 #############################################################################
 # ------------
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -225,10 +225,8 @@ def _get_rc_timezone():
 _epoch_used = False
 
 
-def _reset_epoch():
-    """
-    Reset the Matplotlib date epoch to its rcParams value.
-    """
+def _reset_epoch_test_example():
+    """Reset the Matplotlib date epoch to its rcParams value."""
     global _epoch
     global _epoch_used
 
@@ -238,23 +236,28 @@ def _reset_epoch():
 
 def set_epoch(epoch):
     """
-    Set the epoch (origin for dates) for datetime calculations.  The
-    default epoch is '1970-01-01T00:00:00'. The `.date2num` method returns
-    floating point days from the epoch, and dates that are too far
-    from the epoch will experience floating point round off errors.
-
-    This must be called before any dates are converted (i.e. right after
-    import of `.matplotlib.dates`) or a RuntimeError will be raised.
-
-    See :doc:`/gallery/ticks_and_spines/date_precision_and_epochs` for a
-    discussion.
+    Set the epoch (origin for dates) for datetime calculations.
 
     Parameters
     ----------
     epoch : str
         valid UTC date parsable by `numpy.datetime64` (do not include
         timezone).
 
+    The default epoch is :rc:`dates.epoch`, and users should not need to
+    change this.
+
+    If microsecond accuracy is desired, the date being plotted needs to be
+    within approximately 70 years of the epoch. Matplotlib internally
+    represents dates as days since the epoch, so floating point dynamic
+    range needs to be within a factor fo 2^52.
+
+    `~dates.set_epoch` must be called before any dates are converted
+    (i.e. near the import section) or a RuntimeError will be raised.
+
+    See :doc:`/gallery/ticks_and_spines/date_precision_and_epochs` for a
+    discussion.
+
     """
     global _epoch
     global _epoch_used
@@ -265,17 +268,20 @@ def set_epoch(epoch):
 
 def get_epoch():
     """
-    Get the epoch currently used by `.dates`.
+    Get the epoch used by `.dates`.
 
     Returns
     -------
     epoch: str
+        String for the epoch (parsable by `numpy.datetime64`)
     """
     global _epoch
     global _epoch_used
 
     if _epoch is None:
         _epoch = matplotlib.rcParams['date.epoch']
+    # if get_epoch is called, then set_epoch can no longer be called.
+    # _epoch_used is the latch for checking this.
     _epoch_used = True
     return _epoch
 
diff --git a/lib/matplotlib/mpl-data/stylelib/classic.mplstyle b/lib/matplotlib/mpl-data/stylelib/classic.mplstyle
@@ -229,7 +229,7 @@ date.autoformatter.hour   : %H:%M:%S
 date.autoformatter.minute : %H:%M:%S.%f
 date.autoformatter.second : %H:%M:%S.%f
 date.autoformatter.microsecond : %H:%M:%S.%f
-date.epoch :                     0000-12-31T00:00:00  # old epoch
+date.epoch                : 0000-12-31T00:00:00  # old epoch
 
 ### TICKS
 # see http://matplotlib.org/api/axis_api.html#matplotlib.axis.Tick
diff --git a/lib/matplotlib/tests/test_dates.py b/lib/matplotlib/tests/test_dates.py
@@ -161,10 +161,10 @@ def test_too_many_date_ticks(caplog):
 
 def _new_epoch_decorator(thefunc):
     def wrapper():
-        mdates._reset_epoch()
+        mdates._reset_epoch_test_example()
         mdates.set_epoch('2000-01-01')
         thefunc()
-        mdates._reset_epoch()
+        mdates._reset_epoch_test_example()
     return wrapper
 
 
@@ -938,20 +938,20 @@ def test_change_epoch():
         mdates.set_epoch('1970-01-01')
 
     # use private method to clear the epoch and allow it to be set...
-    mdates._reset_epoch()
+    mdates._reset_epoch_test_example()
     mdates.set_epoch('1970-01-01')
     dt = (date - np.datetime64('1970-01-01')).astype('datetime64[D]')
     dt = dt.astype('int')
     np.testing.assert_equal(mdates.date2num(date), float(dt))
 
-    mdates._reset_epoch()
+    mdates._reset_epoch_test_example()
     mdates.set_epoch('0000-12-31')
     np.testing.assert_equal(mdates.date2num(date), 730120.0)
 
-    mdates._reset_epoch()
+    mdates._reset_epoch_test_example()
     mdates.set_epoch('1970-01-01T01:00:00')
     np.testing.assert_allclose(mdates.date2num(date), dt - 1./24.)
-    mdates._reset_epoch()
+    mdates._reset_epoch_test_example()
     mdates.set_epoch('1970-01-01T00:00:00')
     np.testing.assert_allclose(
         mdates.date2num(np.datetime64('1970-01-01T12:00:00')),
