DEPR: deprecate options.display.mpl_style

Closes #11783    Deprecates
pd.options.display.mpl_style in favor of matplotlib's style sheets.

Author: Tom Augspurger <tom.w.augspurger@gmail.com>

Closes #12190 from TomAugspurger/depr-mpl and squashes the following commits:

1c1b99e [Tom Augspurger] DEPR: deprecate options.display.mpl_style

doc/source/10min.rst

@@ -11,10 +11,7 @@
    np.random.seed(123456)
    np.set_printoptions(precision=4, suppress=True)
    import matplotlib
-   try:
-      matplotlib.style.use('ggplot')
-   except AttributeError:
-      pd.options.display.mpl_style = 'default'
+   matplotlib.style.use('ggplot')
    pd.options.display.max_rows = 15
 
    #### portions of this were borrowed from the

doc/source/computation.rst

@@ -8,10 +8,7 @@
    np.set_printoptions(precision=4, suppress=True)
    import pandas as pd
    import matplotlib
-   try:
-      matplotlib.style.use('ggplot')
-   except AttributeError:
-      pd.options.display.mpl_style = 'default'
+   matplotlib.style.use('ggplot')
    import matplotlib.pyplot as plt
    plt.close('all')
    pd.options.display.max_rows=15

doc/source/cookbook.rst

@@ -19,10 +19,7 @@
    pd.options.display.max_rows=15
 
    import matplotlib
-   try:
-      matplotlib.style.use('ggplot')
-   except AttributeError:
-      pd.options.display.mpl_style = 'default'
+   matplotlib.style.use('ggplot')
 
    np.set_printoptions(precision=4, suppress=True)
 

doc/source/faq.rst

@@ -14,10 +14,7 @@ Frequently Asked Questions (FAQ)
    import pandas as pd
    pd.options.display.max_rows = 15
    import matplotlib
-   try:
-      matplotlib.style.use('ggplot')
-   except AttributeError:
-      pd.options.display.mpl_style = 'default'
+   matplotlib.style.use('ggplot')
    import matplotlib.pyplot as plt
    plt.close('all')
 

doc/source/groupby.rst

@@ -10,10 +10,7 @@
    import pandas as pd
    pd.options.display.max_rows = 15
    import matplotlib
-   try:
-      matplotlib.style.use('ggplot')
-   except AttributeError:
-      pd.options.display.mpl_style = 'default'
+   matplotlib.style.use('ggplot')
    import matplotlib.pyplot as plt
    plt.close('all')
 

doc/source/missing_data.rst

@@ -7,10 +7,7 @@
    import pandas as pd
    pd.options.display.max_rows=15
    import matplotlib
-   try:
-      matplotlib.style.use('ggplot')
-   except AttributeError:
-      pd.options.display.mpl_style = 'default'
+   matplotlib.style.use('ggplot')
    import matplotlib.pyplot as plt
 
 .. _missing_data:

doc/source/options.rst

@@ -361,12 +361,6 @@ display.max_seq_items      100          when pretty-printing a long sequence,
 display.memory_usage       True         This specifies if the memory usage of
                                         a DataFrame should be displayed when the
                                         df.info() method is invoked.
-display.mpl_style          None         Setting this to 'default' will modify
-                                        the rcParams used by matplotlib
-                                        to give plots a more pleasing visual
-                                        style by default. Setting this to
-                                        None/False restores the values to
-                                        their initial value.
 display.multi_sparse       True         "Sparsify" MultiIndex display (don't
                                         display repeated elements in outer
                                         levels within groups)

doc/source/whatsnew/v0.18.0.txt

@@ -840,6 +840,15 @@ Deprecations
 - ``pandas.stats.ols``, ``pandas.stats.plm`` and ``pandas.stats.var`` routines are deprecated and will be removed in a future version (:issue:`6077`)
 - show a ``FutureWarning`` rather than a ``DeprecationWarning`` on using long-time deprecated syntax in ``HDFStore.select``, where the ``where`` clause is not a string-like (:issue:`12027`)
 
+- The ``pandas.options.display.mpl_style`` configuration has been deprecated
+  and will be removed in a future version of pandas. This functionality
+  is better handled by matplotlib's `style sheets`_ (:issue:`11783`).
+
+
+
+
+.. _style sheets: http://matplotlib.org/users/style_sheets.html
+
 .. _whatsnew_0180.prior_deprecations:
 
 Removal of prior version deprecations/changes

pandas/core/config_init.py

@@ -9,6 +9,7 @@
 module is imported, register them here rather then in the module.
 
 """
+import warnings
 
 import pandas.core.config as cf
 from pandas.core.config import (is_int, is_bool, is_text, is_instance_factory,
@@ -222,6 +223,11 @@
     Setting this to None/False restores the values to their initial value.
 """
 
+pc_mpl_style_deprecation_warning = """
+mpl_style had been deprecated and will be removed in a future version.
+Use `matplotlib.pyplot.style.use` instead.
+"""
+
 pc_memory_usage_doc = """
 : bool, string or None
     This specifies if the memory usage of a DataFrame should be displayed when
@@ -246,6 +252,9 @@
 
 
 def mpl_style_cb(key):
+    warnings.warn(pc_mpl_style_deprecation_warning, FutureWarning,
+                  stacklevel=4)
+
     import sys
     from pandas.tools.plotting import mpl_stylesheet
     global style_backup

pandas/tests/test_graphics.py

@@ -3774,9 +3774,15 @@ def test_df_grid_settings(self):
             plotting._dataframe_kinds, kws={'x': 'a', 'y': 'b'})
 
     def test_option_mpl_style(self):
-        set_option('display.mpl_style', 'default')
-        set_option('display.mpl_style', None)
-        set_option('display.mpl_style', False)
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            set_option('display.mpl_style', 'default')
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            set_option('display.mpl_style', None)
+        with tm.assert_produces_warning(FutureWarning,
+                                        check_stacklevel=False):
+            set_option('display.mpl_style', False)
 
         with tm.assertRaises(ValueError):
             set_option('display.mpl_style', 'default2')