ENH: Show versions and system info for debugging (#557)

Author: hayesall

doc/whats_new/v0.5.rst

@@ -23,6 +23,10 @@ Enhancement
 - Add Parallelisation for SMOTEENN and SMOTETomek.
   :issue:`547` by :user:`Michael Hsieh <Microsheep>`.
 
+- Add :class:`imblearn.utils._show_versions`. Updated the contribution guide
+  and issue template showing how to print system and dependency information
+  from the command line. :issue:`557` by :user:`Alexander L. Hayes <batflyer>`.
+
 Maintenance
 ...........
 

imblearn/__init__.py

@@ -44,6 +44,7 @@
 
 from .base import FunctionSampler
 from ._version import __version__
+from .utils._show_versions import show_versions
 
 __all__ = ['combine', 'ensemble', 'exceptions', 'keras', 'metrics',
            'over_sampling', 'tensorflow', 'under_sampling',

imblearn/utils/_show_versions.py

@@ -0,0 +1,109 @@
+"""
+Utility method which prints system info to help with debugging,
+and filing issues on GitHub.
+Adapted from :func:`sklearn.show_versions`,
+which was adapted from :func:`pandas.show_versions`
+"""
+
+# Author: Alexander L. Hayes <hayesall@iu.edu>
+# License: MIT
+
+import sys
+import importlib
+
+
+def _get_deps_info():
+    """Overview of the installed version of main dependencies
+    Returns
+    -------
+    deps_info: dict
+        version information on relevant Python libraries
+    """
+    deps = [
+        "pip",
+        "setuptools",
+        "imblearn",
+        "sklearn",
+        "numpy",
+        "scipy",
+        "Cython",
+        "pandas",
+        "keras",
+        "tensorflow",
+    ]
+
+    def get_version(module):
+        return module.__version__
+
+    deps_info = {}
+
+    for modname in deps:
+        try:
+            if modname in sys.modules:
+                mod = sys.modules[modname]
+            else:
+                mod = importlib.import_module(modname)
+            ver = get_version(mod)
+            deps_info[modname] = ver
+        except ImportError:
+            deps_info[modname] = None
+
+    return deps_info
+
+
+def show_versions(github=False):
+    """Print debugging information.
+    Parameters
+    ----------
+    github : bool,
+        If true, wrap system info with GitHub markup.
+    """
+
+    from sklearn.utils._show_versions import (
+        _get_sys_info,
+        _get_blas_info,
+    )
+
+    _sys_info = _get_sys_info()
+    _blas_info = _get_blas_info()
+    _deps_info = _get_deps_info()
+    _github_markup = (
+        "<details>"
+        "<summary>System, BLAS, and Dependencies</summary>\n\n"
+        "**System Information**\n\n"
+        "{0}\n"
+        "**BLAS**\n\n"
+        "{1}\n"
+        "**Python Dependencies**\n\n"
+        "{2}\n"
+        "</details>"
+    )
+
+    if github:
+
+        _sys_markup = ""
+        _blas_markup = ""
+        _deps_markup = ""
+
+        for k, stat in _sys_info.items():
+            _sys_markup += "* {k:<10}: `{stat}`\n".format(k=k, stat=stat)
+        for k, stat in _blas_info.items():
+            _blas_markup += "* {k:<10}: `{stat}`\n".format(k=k, stat=stat)
+        for k, stat in _deps_info.items():
+            _deps_markup += "* {k:<10}: `{stat}`\n".format(k=k, stat=stat)
+
+        print(_github_markup.format(_sys_markup, _blas_markup, _deps_markup))
+
+    else:
+
+        print("\nSystem:")
+        for k, stat in _sys_info.items():
+            print("{k:>11}: {stat}".format(k=k, stat=stat))
+
+        print("\nBLAS:")
+        for k, stat in _blas_info.items():
+            print("{k:>11}: {stat}".format(k=k, stat=stat))
+
+        print("\nPython dependencies:")
+        for k, stat in _deps_info.items():
+            print("{k:>11}: {stat}".format(k=k, stat=stat))

imblearn/utils/tests/test_show_versions.py

@@ -0,0 +1,65 @@
+"""Test for the show_versions helper. Based on the sklearn tests."""
+# Author: Alexander L. Hayes <hayesall@iu.edu>
+# License: MIT
+
+from imblearn.utils._show_versions import _get_deps_info
+from imblearn.utils._show_versions import show_versions
+
+
+def test_get_deps_info():
+    _deps_info = _get_deps_info()
+    assert "pip" in _deps_info
+    assert "setuptools" in _deps_info
+    assert "imblearn" in _deps_info
+    assert "sklearn" in _deps_info
+    assert "numpy" in _deps_info
+    assert "scipy" in _deps_info
+    assert "Cython" in _deps_info
+    assert "pandas" in _deps_info
+
+
+def test_show_versions_default(capsys):
+    show_versions()
+    out, err = capsys.readouterr()
+    assert "python" in out
+    assert "executable" in out
+    assert "machine" in out
+    assert "macros" in out
+    assert "lib_dirs" in out
+    assert "cblas_libs" in out
+    assert "pip" in out
+    assert "setuptools" in out
+    assert "imblearn" in out
+    assert "sklearn" in out
+    assert "numpy" in out
+    assert "scipy" in out
+    assert "Cython" in out
+    assert "pandas" in out
+    assert "keras" in out
+    assert "tensorflow" in out
+
+
+def test_show_versions_github(capsys):
+    show_versions(github=True)
+    out, err = capsys.readouterr()
+    assert "<details><summary>System, BLAS, and Dependencies</summary>" in out
+    assert "**System Information**" in out
+    assert "* python" in out
+    assert "* executable" in out
+    assert "* machine" in out
+    assert "**BLAS**" in out
+    assert "* macros" in out
+    assert "* lib_dirs" in out
+    assert "* cblas_libs" in out
+    assert "**Python Dependencies**" in out
+    assert "* pip" in out
+    assert "* setuptools" in out
+    assert "* imblearn" in out
+    assert "* sklearn" in out
+    assert "* numpy" in out
+    assert "* scipy" in out
+    assert "* Cython" in out
+    assert "* pandas" in out
+    assert "* keras" in out
+    assert "* tensorflow" in out
+    assert "</details>" in out