TST/DOC/BUG: Accommodate OpenPyXL incompatibility

*   Detect whether a compatible version is installed
*   Skip openpyxl unit tests instead of failing
*   Inhibit registration of `openpyxl` engine in `ExcelWriter`
*   Raise `UserWarning`
*   Document limitation as a known issue
*   Resolve issue #7169

Author: neirbowj

README.md

@@ -114,7 +114,8 @@ pip install pandas
   - [xlrd/xlwt](http://www.python-excel.org/)
      - Excel reading (xlrd) and writing (xlwt)
   - [openpyxl](http://packages.python.org/openpyxl/)
-     - openpyxl version 1.6.1 or higher, for writing .xlsx files
+     - openpyxl version 1.6.1 or higher, but lower than 2.0.0, for
+       writing .xlsx files
      - xlrd >= 0.9.0
   - [XlsxWriter](https://pypi.python.org/pypi/XlsxWriter)
      - Alternative Excel writer.

doc/source/install.rst

@@ -97,7 +97,7 @@ Optional Dependencies
   * `statsmodels <http://statsmodels.sourceforge.net/>`__
      * Needed for parts of :mod:`pandas.stats`
   * `openpyxl <http://packages.python.org/openpyxl/>`__, `xlrd/xlwt <http://www.python-excel.org/>`__
-     * openpyxl version 1.6.1 or higher
+     * openpyxl version 1.6.1 or higher, but lower than 2.0.0
      * Needed for Excel I/O
   * `XlsxWriter <https://pypi.python.org/pypi/XlsxWriter>`__
      * Alternative Excel writer.

doc/source/v0.14.0.txt

@@ -31,6 +31,8 @@ users upgrade to this version.
 
 - :ref:`Deprecations <whatsnew_0140.deprecations>`
 
+- :ref:`Known Issues <whatsnew_0140.knownissues>`
+
 - :ref:`Bug Fixes <release.bug_fixes-0.14.0>`
 
 .. warning::
@@ -630,6 +632,14 @@ Deprecations
   in a future release. You can use the future behavior now by passing ``return_type='axes'``
   to boxplot.
 
+.. _whatsnew_0140.knownissues:
+
+Known Issues
+~~~~~~~~~~~~
+
+- OpenPyXL 2.0.0 breaks backwards compatibility (:issue:`7196`)
+
+
 .. _whatsnew_0140.enhancements:
 
 Enhancements

pandas/compat/openpyxl_compat.py

@@ -0,0 +1,26 @@
+"""
+Detect incompatible version of OpenPyXL
+
+GH7169
+"""
+
+from distutils.version import LooseVersion
+
+start_ver = '1.6.1'
+stop_ver = '2.0.0'
+
+def is_compat():
+    """
+    Detect whether the installed version of openpyxl is supported
+    Returns True/False if openpyxl is installed, None otherwise
+    """
+    try:
+        import openpyxl
+    except ImportError:
+        return None
+
+    ver = LooseVersion(openpyxl.__version__)
+    if ver < LooseVersion(start_ver) or LooseVersion(stop_ver) <= ver:
+        return False
+
+    return True

pandas/io/excel.py

@@ -16,6 +16,7 @@
 from pandas.core import config
 from pandas.core.common import pprint_thing
 import pandas.compat as compat
+import pandas.compat.openpyxl_compat as openpyxl_compat
 import pandas.core.common as com
 from warnings import warn
 from distutils.version import LooseVersion
@@ -617,7 +618,12 @@ def _convert_to_style(cls, style_dict):
 
         return xls_style
 
-register_writer(_OpenpyxlWriter)
+
+if openpyxl_compat.is_compat():
+    register_writer(_OpenpyxlWriter)
+else:
+    warn('Installed openpyxl is not supported at this time. Use >={} and <{}.'
+            .format(openpyxl_compat.start_ver, openpyxl_compat.stop_ver))
 
 
 class _XlwtWriter(ExcelWriter):

pandas/io/tests/test_excel.py

@@ -1,6 +1,6 @@
 # pylint: disable=E1101
 
-from pandas.compat import u, range, map
+from pandas.compat import u, range, map, openpyxl_compat
 from datetime import datetime, date, time
 import os
 from distutils.version import LooseVersion
@@ -45,6 +45,10 @@ def _skip_if_no_openpyxl():
     except ImportError:
         raise nose.SkipTest('openpyxl not installed, skipping')
 
+    if not openpyxl_compat.is_compat():
+        raise nose.SkipTest('need %s <= openpyxl < %s, skipping' %
+                (openpyxl_compat.start_ver, openpyxl_compat.stop_ver))
+
 
 def _skip_if_no_xlsxwriter():
     try: