add warns context manger that mimics raises

Author: Joan Massich

doc/developers_utils.rst

@@ -96,3 +96,45 @@ same information as the deprecation warning as explained above. Use the
 On the top of all the functionality provided by scikit-learn. Imbalance-learn
 provides :func:`deprecate_parameter`: which is used to deprecate a sampler's
 parameter (attribute) by another one.
+
+Warning management when testing
+===============================
+
+If using Python 2.7 or above, you may use this function as a
+context manager::
+
+    >>> import warnings
+    >>> from imblearn.utils.testing import warns
+    >>> with warns(RuntimeWarning):
+    ...    warnings.warn("my runtime warning", RuntimeWarning)
+
+    >>> with warns(RuntimeWarning):
+    ...    pass
+    Traceback (most recent call last):
+      ...
+    Failed: DID NOT WARN. No warnings of type (<class 'RuntimeWarning'>,) was emitted. The list of emitted warnings is: [].
+
+    >>> with warns(RuntimeWarning):
+    ...    warnings.warn(UserWarning)
+    Traceback (most recent call last):
+      ...
+    Failed: DID NOT WARN. No warnings of type (<class 'RuntimeWarning'>,) was emitted. The list of emitted warnings is: [UserWarning(<class 'UserWarning'>,)].
+
+
+
+In the context manager form you may use the keyword argument ``match`` to assert
+that the exception matches a text or regex::
+
+    >>> import warnings
+    >>> from imblearn.utils.testing import warns
+    >>> with warns(UserWarning, match='must be 0 or None'):
+    ...     warnings.warn("value must be 0 or None", UserWarning)
+
+    >>> with warns(UserWarning, match=r'must be \d+$'):
+    ...     warnings.warn("value must be 42", UserWarning)
+
+    >>> with warns(UserWarning, match=r'must be \d+$'):
+    ...     warnings.warn("this is not here", UserWarning)
+    Traceback (most recent call last):
+      ...
+    AssertionError: 'must be \d+$' pattern not found in ['this is not here']

imblearn/utils/testing.py

@@ -14,6 +14,11 @@
 
 from sklearn.base import BaseEstimator
 
+from pytest import warns as _warns
+from contextlib import contextmanager
+from re import compile
+
+
 # meta-estimators need another estimator to be instantiated.
 META_ESTIMATORS = []
 # estimators that there is no way to default-construct sensibly
@@ -120,3 +125,25 @@ def is_abstract(c):
     # itemgetter is used to ensure the sort does not extend to the 2nd item of
     # the tuple
     return sorted(set(estimators), key=itemgetter(0))
+
+
+@contextmanager
+def warns(expected_warning, match=None):
+    """
+    Assert that a code block/function call warns ``expected_warning``
+    and raise a failure exception otherwise.
+
+    """
+    with _warns(expected_warning) as record:
+        yield
+
+    if match is not None:
+        for each in record:
+            if compile(match).search(str(each.message)) is not None:
+                break
+        else:
+            msg = "'{}' pattern not found in {}".format(
+                match, '{}'.format([str(r.message) for r in record]))
+            assert False, msg
+    else:
+        pass

imblearn/utils/tests/test_testing.py

@@ -8,6 +8,8 @@
 from imblearn.base import SamplerMixin
 from imblearn.utils.testing import all_estimators
 
+from imblearn.utils.testing import warns
+
 
 def test_all_estimators():
     # check if the filtering is working with a list or a single string
@@ -23,3 +25,26 @@ def test_all_estimators():
     type_filter = 'rnd'
     with raises(ValueError, match="Parameter type_filter must be 'sampler'"):
         all_estimators(type_filter=type_filter)
+
+
+def test_warns():
+    import warnings
+
+    with warns(UserWarning, match=r'must be \d+$'):
+        warnings.warn("value must be 42", UserWarning)
+
+    with raises(AssertionError, match='pattern not found'):
+        with warns(UserWarning, match=r'must be \d+$'):
+            warnings.warn("this is not here", UserWarning)
+
+    with warns(UserWarning, match=r'aaa'):
+        warnings.warn("cccccccccc", UserWarning)
+        warnings.warn("bbbbbbbbbb", UserWarning)
+        warnings.warn("aaaaaaaaaa", UserWarning)
+
+    a, b, c = ('aaa', 'bbbbbbbbbb', 'cccccccccc')
+    expected_msg = "'{}' pattern not found in \['{}', '{}'\]".format(a, b, c)
+    with raises(AssertionError, match=expected_msg):
+        with warns(UserWarning, match=r'aaa'):
+            warnings.warn("bbbbbbbbbb", UserWarning)
+            warnings.warn("cccccccccc", UserWarning)