dates: improve documentation related to use of Gregorian calendar

efiring · efiring · commit 90600d87d950 · 2010-06-07T23:39:24.000Z
svn path=/trunk/matplotlib/; revision=8396
diff --git a/lib/matplotlib/dates.py b/lib/matplotlib/dates.py
@@ -9,6 +9,23 @@
 :func:`num2date` and :func:`drange` are used to facilitate easy
 conversion to and from :mod:`datetime` and numeric ranges.
 
+.. note::
+   Like Python's datetime, mpl uses the Gregorian calendar for
+   all conversions between dates and floating point numbers.
+   This practice is not universal, and calendar differences can
+   cause confusing differences between what Python and mpl
+   give as the number of days since 0001-01-01 and what other
+   software and databases yield.  For example, the
+   `US Naval Observatory <http://www.usno.navy.mil/USNO/astronomical-applications/data-services/jul-date>`_
+   uses a calendar that switches from Julian to Gregorian in
+   October, 1582.  Hence, using their calculator, the number of
+   days between 0001-01-01 and 2006-04-01 is 732403, whereas using
+   the Gregorian calendar via the datetime module we find::
+
+     In [31]:date(2006,4,1).toordinal() - date(1,1,1).toordinal()
+     Out[31]:732401
+
+
 A wide range of specific and general purpose date tick locators and
 formatters are provided in this module.  See
 :mod:`matplotlib.ticker` for general information on tick locators
@@ -233,8 +250,11 @@ def date2num(d):
     *d* is either a :class:`datetime` instance or a sequence of datetimes.
 
     Return value is a floating point number (or sequence of floats)
-    which gives one plus the number of days (fraction part represents hours,
-    minutes, seconds) since 0001-01-01 00:00:00 UTC.
+    which gives the number of days (fraction part represents hours,
+    minutes, seconds) since 0001-01-01 00:00:00 UTC, *plus* *one*.
+    The addition of one here is a historical artifact.  Also, note
+    that the Gregorian calendar is assumed; this is not universal
+    practice.  For details, see the module docstring.
     """
     if not cbook.iterable(d): return _to_ordinalf(d)
     else: return np.asarray([_to_ordinalf(val) for val in d])
@@ -252,9 +272,12 @@ def num2julian(n):
 
 def num2date(x, tz=None):
     """
-    *x* is a float value which gives one plus the number of days
+    *x* is a float value which gives the number of days
     (fraction part represents hours, minutes, seconds) since
-    0001-01-01 00:00:00 UTC.
+    0001-01-01 00:00:00 UTC *plus* *one*.
+    The addition of one here is a historical artifact.  Also, note
+    that the Gregorian calendar is assumed; this is not universal
+    practice.  For details, see the module docstring.
 
     Return value is a :class:`datetime` instance in timezone *tz* (default to
     rcparams TZ value).
