API: Restore implicit converter registration

ci/check_imports.py

@@ -9,7 +9,6 @@
     'ipython',
     'jinja2'
     'lxml',
-    'matplotlib',
     'numexpr',
     'openpyxl',
     'py',

doc/source/whatsnew/v0.21.1.txt

@@ -7,6 +7,45 @@ This is a minor release from 0.21.1 and includes a number of deprecations, new
 features, enhancements, and performance improvements along with a large number
 of bug fixes. We recommend that all users upgrade to this version.
 
+.. _whatsnew_0211.special:
+
+Restore Matplotlib datetime Converter Registration
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+Pandas implements some matplotlib converters for nicely formatting the axis
+labels on plots with ``datetime`` or ``Period`` values. Prior to pandas 0.21.0,
+these were implicitly registered with matplotlib, as a side effect of
+``import pandas``. In pandas 0.21.0, we required users to explicitly register
+the converter.
+
+.. code-block:: python
+
+   >>> from pandas.tseries import converter
+   >>> converter.register()
+
+This caused problems for some users, so we're temporarily reverting that change;
+pandas will again register the converters on import. Using the converters
+without explicitly registering the formatters will cause a ``FutureWarning``:
+
+.. code-block:: python
+
+   >>> import pandas as pd
+   >>> import matplotlib.pyplot as plt
+   >>> fig, ax = plt.subplots()
+   >>> ax.plot(pd.Series(range(12), index=pd.date_range('2017', periods=12)))
+   FutureWarning: Using an implicitly registered datetime converter for a
+   matplotlib plotting method. The converter was registered by pandas on import.
+   Future versions of pandas will require you to explicitly register matplotlib
+   converters.
+
+   To register the converters:
+           >>> from pandas.tseries import converter
+           >>> converter.register()
+
+As the error message says, you'll need to register the converts if you intend to
+use them with matplotlib plotting functions. Pandas plotting functions, such as
+``Series.plot``, will register them for you. (:issue:`18301`)
+
 .. _whatsnew_0211.enhancements:
 
 New features
@@ -30,7 +69,7 @@ Other Enhancements
 Deprecations
 ~~~~~~~~~~~~
 
--
+- 
 -
 -
 

pandas/plotting/_converter.py

@@ -1,3 +1,4 @@
+import warnings
 from datetime import datetime, timedelta
 import datetime as pydt
 import numpy as np
@@ -45,8 +46,15 @@
 
 MUSEC_PER_DAY = 1e6 * SEC_PER_DAY
 
+_WARN = True
+
+
+def register(warn=False):
+    global _WARN
+
+    if not warn:
+        _WARN = False
 
-def register():
     units.registry[lib.Timestamp] = DatetimeConverter()
     units.registry[Period] = PeriodConverter()
     units.registry[pydt.datetime] = DatetimeConverter()
@@ -55,6 +63,21 @@ def register():
     units.registry[np.datetime64] = DatetimeConverter()
 
 
+def _check_implicitly_registered():
+    global _WARN
+
+    if _WARN:
+        msg = ("Using an implicitly registered datetime converter for a "
+               "matplotlib plotting method. The converter was registered "
+               "by pandas on import. Future versions of pandas will require "
+               "you to explicitly register matplotlib converters.\n\n"
+               "To register the converters:\n\t"
+               ">>> from pandas.tseries import converter\n\t"
+               ">>> converter.register()")
+        warnings.warn(msg, FutureWarning)
+        _WARN = False
+
+
 def _to_ordinalf(tm):
     tot_sec = (tm.hour * 3600 + tm.minute * 60 + tm.second +
                float(tm.microsecond / 1e6))
@@ -190,6 +213,7 @@ class DatetimeConverter(dates.DateConverter):
     @staticmethod
     def convert(values, unit, axis):
         # values might be a 1-d array, or a list-like of arrays.
+        _check_implicitly_registered()
         if is_nested_list_like(values):
             values = [DatetimeConverter._convert_1d(v, unit, axis)
                       for v in values]
@@ -274,6 +298,7 @@ class PandasAutoDateLocator(dates.AutoDateLocator):
 
     def get_locator(self, dmin, dmax):
         'Pick the best locator based on a distance.'
+        _check_implicitly_registered()
         delta = relativedelta(dmax, dmin)
 
         num_days = (delta.years * 12.0 + delta.months) * 31.0 + delta.days
@@ -315,6 +340,7 @@ def get_unit_generic(freq):
 
     def __call__(self):
         # if no data have been set, this will tank with a ValueError
+        _check_implicitly_registered()
         try:
             dmin, dmax = self.viewlim_to_dt()
         except ValueError:
@@ -917,6 +943,8 @@ def _get_default_locs(self, vmin, vmax):
     def __call__(self):
         'Return the locations of the ticks.'
         # axis calls Locator.set_axis inside set_m<xxxx>_formatter
+        _check_implicitly_registered()
+
         vi = tuple(self.axis.get_view_interval())
         if vi != self.plot_obj.view_interval:
             self.plot_obj.date_axis_info = None
@@ -1001,6 +1029,8 @@ def set_locs(self, locs):
         'Sets the locations of the ticks'
         # don't actually use the locs. This is just needed to work with
         # matplotlib. Force to use vmin, vmax
+        _check_implicitly_registered()
+
         self.locs = locs
 
         (vmin, vmax) = vi = tuple(self.axis.get_view_interval())
@@ -1012,6 +1042,8 @@ def set_locs(self, locs):
         self._set_default_format(vmin, vmax)
 
     def __call__(self, x, pos=0):
+        _check_implicitly_registered()
+
         if self.formatdict is None:
             return ''
         else:
@@ -1042,6 +1074,7 @@ def format_timedelta_ticks(x, pos, n_decimals):
         return s
 
     def __call__(self, x, pos=0):
+        _check_implicitly_registered()
         (vmin, vmax) = tuple(self.axis.get_view_interval())
         n_decimals = int(np.ceil(np.log10(100 * 1e9 / (vmax - vmin))))
         if n_decimals > 9:

pandas/plotting/_core.py

@@ -40,16 +40,16 @@
                                     _get_xlim, _set_ticks_props,
                                     format_date_labels)
 
-_registered = False
-
-
-def _setup():
-    # delay the import of matplotlib until nescessary
-    global _registered
-    if not _registered:
-        from pandas.plotting import _converter
-        _converter.register()
-        _registered = True
+try:
+    # We want to warn if the formatter is called implicitly
+    # by `ax.plot(datetimeindex, another)`
+    # We don't want to warn if
+    # * Series.plot
+    # * User calls `register` explicitly
+    from pandas.plotting import _converter
+    _converter.register(warn=True)
+except ImportError:
+    pass
 
 
 def _get_standard_kind(kind):
@@ -99,7 +99,7 @@ def __init__(self, data, kind=None, by=None, subplots=False, sharex=None,
                  secondary_y=False, colormap=None,
                  table=False, layout=None, **kwds):
 
-        _setup()
+        _converter._WARN = False
         self.data = data
         self.by = by
 
@@ -2059,7 +2059,7 @@ def boxplot_frame(self, column=None, by=None, ax=None, fontsize=None, rot=0,
                   grid=True, figsize=None, layout=None,
                   return_type=None, **kwds):
     import matplotlib.pyplot as plt
-    _setup()
+    _converter.WARN = False
     ax = boxplot(self, column=column, by=by, ax=ax, fontsize=fontsize,
                  grid=grid, rot=rot, figsize=figsize, layout=layout,
                  return_type=return_type, **kwds)
@@ -2155,7 +2155,7 @@ def hist_frame(data, column=None, by=None, grid=True, xlabelsize=None,
     kwds : other plotting keyword arguments
         To be passed to hist function
     """
-    _setup()
+    _converter.WARN = False
     if by is not None:
         axes = grouped_hist(data, column=column, by=by, ax=ax, grid=grid,
                             figsize=figsize, sharex=sharex, sharey=sharey,
@@ -2289,6 +2289,8 @@ def grouped_hist(data, column=None, by=None, ax=None, bins=50, figsize=None,
     -------
     axes: collection of Matplotlib Axes
     """
+    _converter.WARN = False
+
     def plot_group(group, ax):
         ax.hist(group.dropna().values, bins=bins, **kwargs)
 
@@ -2352,7 +2354,6 @@ def boxplot_frame_groupby(grouped, subplots=True, column=None, fontsize=None,
     >>> grouped = df.unstack(level='lvl1').groupby(level=0, axis=1)
     >>> boxplot_frame_groupby(grouped, subplots=False)
     """
-    _setup()
     if subplots is True:
         naxes = len(grouped)
         fig, axes = _subplots(naxes=naxes, squeeze=False,

pandas/tests/plotting/test_converter.py

@@ -2,7 +2,7 @@
 from datetime import datetime, date
 
 import numpy as np
-from pandas import Timestamp, Period, Index
+from pandas import Timestamp, Period, Index, date_range, Series
 from pandas.compat import u
 import pandas.util.testing as tm
 from pandas.tseries.offsets import Second, Milli, Micro, Day
@@ -15,6 +15,37 @@ def test_timtetonum_accepts_unicode():
     assert (converter.time2num("00:01") == converter.time2num(u("00:01")))
 
 
+class TestImplicitRegistration(object):
+
+    def test_warns(self):
+        plt = pytest.importorskip("matplotlib.pyplot")
+        s = Series(range(12), index=date_range('2017', periods=12))
+        _, ax = plt.subplots()
+
+        # Set to the "warning" state, in case this isn't the first test run
+        converter._WARN = True
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False) as w:
+            ax.plot(s.index, s.values)
+            plt.close()
+
+        assert len(w) == 1
+        assert "Using an implicitly registered datetime converter" in str(w[0])
+
+    def test_registering_no_warning(self):
+        plt = pytest.importorskip("matplotlib.pyplot")
+        s = Series(range(12), index=date_range('2017', periods=12))
+        _, ax = plt.subplots()
+
+        # Set to the "no-warn" state, in case this isn't the first test run
+        converter._WARN = True
+        converter.register()
+        with tm.assert_produces_warning(None) as w:
+            ax.plot(s.index, s.values)
+
+        assert len(w) == 0
+
+
 class TestDateTimeConverter(object):
 
     def setup_method(self, method):

pandas/tests/plotting/test_warns.py

@@ -0,0 +1,35 @@
+import pytest
+
+import pandas as pd
+import pandas.util.testing as tm
+
+from pandas.plotting import _converter
+from pandas.tseries import converter
+
+
+plt = pytest.importorskip('matplotlib.pyplot')
+
+
+def test_warns():
+    s = pd.Series(range(12), index=pd.date_range('2017', periods=12))
+    fig, ax = plt.subplots()
+
+    _converter._WARN = True
+    with tm.assert_produces_warning(FutureWarning,
+                                    check_stacklevel=False) as w:
+        ax.plot(s.index, s.values)
+        plt.close()
+
+    assert len(w) == 1
+
+
+def test_registering_no_warning():
+    s = pd.Series(range(12), index=pd.date_range('2017', periods=12))
+    fig, ax = plt.subplots()
+
+    _converter._WARN = True
+    converter.register()
+    with tm.assert_produces_warning(None) as w:
+        ax.plot(s.index, s.values)
+
+    assert len(w) == 0