DOCTEST: Suppress deprecation warnings in doctests of deprecated methods

Author: effigies

nibabel/deprecator.py

@@ -7,6 +7,26 @@
 
 _LEADING_WHITE = re.compile(r'^(\s*)')
 
+TESTSETUP = """
+
+.. testsetup::
+
+    >>> import pytest
+    >>> import warnings
+    >>> _suppress_warnings = pytest.deprecated_call()
+    >>> _ = _suppress_warnings.__enter__()
+
+"""
+
+TESTCLEANUP = """
+
+.. testcleanup::
+
+    >>> warnings.warn("Avoid error if no doctests to run...", DeprecationWarning)
+    >>> _ = _suppress_warnings.__exit__(None, None, None)
+
+"""
+
 
 class ExpiredDeprecationError(RuntimeError):
     """ Error for expired deprecation
@@ -25,7 +45,7 @@ def _ensure_cr(text):
     return text.rstrip() + '\n'
 
 
-def _add_dep_doc(old_doc, dep_doc):
+def _add_dep_doc(old_doc, dep_doc, setup='', cleanup=''):
     """ Add deprecation message `dep_doc` to docstring in `old_doc`
 
     Parameters
@@ -56,8 +76,11 @@ def _add_dep_doc(old_doc, dep_doc):
         # nothing following first paragraph, just append message
         return old_doc + '\n' + dep_doc
     indent = _LEADING_WHITE.match(old_lines[next_line]).group()
+    setup_lines = [indent + L for L in setup.splitlines()]
     dep_lines = [indent + L for L in [''] + dep_doc.splitlines() + ['']]
-    return '\n'.join(new_lines + dep_lines + old_lines[next_line:]) + '\n'
+    cleanup_lines = [indent + L for L in cleanup.splitlines()]
+    return '\n'.join(new_lines + dep_lines + setup_lines +
+                     old_lines[next_line:] + cleanup_lines + [''])
 
 
 class Deprecator(object):
@@ -160,7 +183,7 @@ def deprecated_func(*args, **kwargs):
                 return func(*args, **kwargs)
 
             deprecated_func.__doc__ = _add_dep_doc(deprecated_func.__doc__,
-                                                   message)
+                                                   message, TESTSETUP, TESTCLEANUP)
             return deprecated_func
 
         return deprecator

nibabel/tests/test_deprecator.py

@@ -4,11 +4,13 @@
 import sys
 import warnings
 from functools import partial
+from textwrap import indent
 
 import pytest
 
 from nibabel.deprecator import (_ensure_cr, _add_dep_doc,
-                                ExpiredDeprecationError, Deprecator)
+                                ExpiredDeprecationError, Deprecator,
+                                TESTSETUP, TESTCLEANUP)
 
 from ..testing import clear_and_catch_warnings
 
@@ -81,7 +83,9 @@ def test_dep_func(self):
         with pytest.deprecated_call() as w:
             assert func(1, 2) is None
             assert len(w) == 1
-        assert func.__doc__ == 'A docstring\n   \n   foo\n   \n   Some text\n'
+        assert (func.__doc__ ==
+                f'A docstring\n   \n   foo\n   \n{indent(TESTSETUP, "   ", lambda x: True)}'
+                f'   Some text\n{indent(TESTCLEANUP, "   ", lambda x: True)}')
 
         # Try some since and until versions
         func = dec('foo', '1.1')(func_no_doc)
@@ -110,7 +114,8 @@ def test_dep_func(self):
         assert (func.__doc__ ==
                 'A docstring\n   \n   foo\n   \n   * deprecated from version: 1.2\n   '
                 f'* Raises {ExpiredDeprecationError} as of version: 1.8\n   \n'
-                '   Some text\n')
+                f'{indent(TESTSETUP, "   ", lambda x: True)}'
+                f'   Some text\n{indent(TESTCLEANUP, "   ", lambda x: True)}')
         with pytest.raises(ExpiredDeprecationError):
             func()