diff options
Diffstat (limited to 'numpy/testing/decorators.py')
| -rw-r--r-- | numpy/testing/decorators.py | 205 |
1 files changed, 138 insertions, 67 deletions
diff --git a/numpy/testing/decorators.py b/numpy/testing/decorators.py index e337c35e2..afb52d3ea 100644 --- a/numpy/testing/decorators.py +++ b/numpy/testing/decorators.py @@ -1,79 +1,117 @@ -"""Decorators for labeling test objects +""" +Decorators for labeling and modifying behavior of test objects. Decorators that merely return a modified version of the original -function object are straightforward. Decorators that return a new +function object are straightforward. Decorators that return a new function object need to use -nose.tools.make_decorator(original_function)(decorator) in returning -the decorator, in order to preserve metadata such as function name, -setup and teardown functions and so on - see nose.tools for more -information. +:: + + nose.tools.make_decorator(original_function)(decorator) + +in returning the decorator, in order to preserve meta-data such as +function name, setup and teardown functions and so on - see +``nose.tools`` for more information. """ import warnings import sys def slow(t): - """Labels a test as 'slow'. + """ + Label a test as 'slow'. The exact definition of a slow test is obviously both subjective and hardware-dependent, but in general any individual test that requires more than a second or two should be labeled as slow (the whole suite consits of - thousands of tests, so even a second is significant).""" + thousands of tests, so even a second is significant). + + Parameters + ---------- + t : callable + The test to label as slow. + + Returns + ------- + t : callable + The decorated test `t`. + + Examples + -------- + The `numpy.testing` module includes ``import decorators as dec``. + A test can be decorated as slow like this:: + + from numpy.testing import * + + @dec.slow + def test_big(self): + print 'Big, slow test' + + """ t.slow = True return t def setastest(tf=True): - ''' Signals to nose that this function is or is not a test + """ + Signals to nose that this function is or is not a test. Parameters ---------- tf : bool - If True specifies this is a test, not a test otherwise + If True, specifies that the decorated callable is a test. + If False, specifies that the decorated callable is not a test. + Default is True. + + Notes + ----- + This decorator can't use the nose namespace, because it can be + called from a non-test module. See also ``istest`` and ``nottest`` in + ``nose.tools``. - e.g - >>> from numpy.testing.decorators import setastest - >>> @setastest(False) - ... def func_with_test_in_name(arg1, arg2): pass - ... - >>> + Examples + -------- + `setastest` can be used in the following way:: - This decorator cannot use the nose namespace, because it can be - called from a non-test module. See also istest and nottest in - nose.tools + from numpy.testing.decorators import setastest - ''' + @setastest(False) + def func_with_test_in_name(arg1, arg2): + pass + + """ def set_test(t): t.__test__ = tf return t return set_test def skipif(skip_condition, msg=None): - ''' Make function raise SkipTest exception if skip_condition is true + """ + Make function raise SkipTest exception if a given condition is true. + + If the condition is a callable, it is used at runtime to dynamically + make the decision. This is useful for tests that may require costly + imports, to delay the cost until the test suite is actually executed. Parameters ---------- - skip_condition : bool or callable. - Flag to determine whether to skip test. If the condition is a - callable, it is used at runtime to dynamically make the decision. This - is useful for tests that may require costly imports, to delay the cost - until the test suite is actually executed. - msg : string - Message to give on raising a SkipTest exception - - Returns - ------- - decorator : function - Decorator, which, when applied to a function, causes SkipTest - to be raised when the skip_condition was True, and the function - to be called normally otherwise. + skip_condition : bool or callable + Flag to determine whether to skip the decorated test. + msg : str, optional + Message to give on raising a SkipTest exception. Default is None. + + Returns + ------- + decorator : function + Decorator which, when applied to a function, causes SkipTest + to be raised when `skip_condition` is True, and the function + to be called normally otherwise. Notes ----- - You will see from the code that we had to further decorate the - decorator with the nose.tools.make_decorator function in order to - transmit function name, and various other metadata. - ''' + The decorator itself is decorated with the ``nose.tools.make_decorator`` + function in order to transmit function name, and various other metadata. + + """ def skip_decorator(f): # Local import to avoid a hard nose dependency and only incur the @@ -124,32 +162,35 @@ def skipif(skip_condition, msg=None): def knownfailureif(fail_condition, msg=None): - ''' Make function raise KnownFailureTest exception if fail_condition is true + """ + Make function raise KnownFailureTest exception if given condition is true. + + If the condition is a callable, it is used at runtime to dynamically + make the decision. This is useful for tests that may require costly + imports, to delay the cost until the test suite is actually executed. Parameters ---------- - fail_condition : bool or callable. - Flag to determine whether to mark test as known failure (True) - or not (False). If the condition is a callable, it is used at - runtime to dynamically make the decision. This is useful for - tests that may require costly imports, to delay the cost - until the test suite is actually executed. - msg : string - Message to give on raising a KnownFailureTest exception - - Returns - ------- - decorator : function - Decorator, which, when applied to a function, causes SkipTest - to be raised when the skip_condition was True, and the function - to be called normally otherwise. + fail_condition : bool or callable + Flag to determine whether to mark the decorated test as a known + failure (if True) or not (if False). + msg : str, optional + Message to give on raising a KnownFailureTest exception. + Default is None. + + Returns + ------- + decorator : function + Decorator, which, when applied to a function, causes SkipTest + to be raised when `skip_condition` is True, and the function + to be called normally otherwise. Notes ----- - You will see from the code that we had to further decorate the - decorator with the nose.tools.make_decorator function in order to - transmit function name, and various other metadata. - ''' + The decorator itself is decorated with the ``nose.tools.make_decorator`` + function in order to transmit function name, and various other metadata. + + """ if msg is None: msg = 'Test skipped due to known failure' @@ -177,7 +218,15 @@ def knownfailureif(fail_condition, msg=None): # manager) class WarningMessage(object): - """Holds the result of a single showwarning() call.""" + """ + Holds the result of a single showwarning() call. + + Notes + ----- + `WarningMessage` is copied from the Python 2.6 warnings module, + so it can be used in NumPy with older Python versions. + + """ _WARNING_DETAILS = ("message", "category", "filename", "lineno", "file", "line") @@ -198,6 +247,27 @@ class WarningMessage(object): self.filename, self.lineno, self.line)) class WarningManager: + """ + A context manager that copies and restores the warnings filter upon + exiting the context. + + The 'record' argument specifies whether warnings should be captured by a + custom implementation of ``warnings.showwarning()`` and be appended to a + list returned by the context manager. Otherwise None is returned by the + context manager. The objects appended to the list are arguments whose + attributes mirror the arguments to ``showwarning()``. + + The 'module' argument is to specify an alternative module to the module + named 'warnings' and imported under that name. This argument is only useful + when testing the warnings module itself. + + Notes + ----- + `WarningManager` is a copy of the ``catch_warnings`` context manager + from the Python 2.6 warnings module, with slight modifications. + It is copied so it can be used in NumPy with older Python versions. + + """ def __init__(self, record=False, module=None): self._record = record if module is None: @@ -229,28 +299,29 @@ class WarningManager: self._module.showwarning = self._showwarning def deprecated(conditional=True): - """This decorator can be used to filter Deprecation Warning, to avoid + """ + Filter deprecation warnings while running the test suite. + + This decorator can be used to filter DeprecationWarning's, to avoid printing them during the test suite run, while checking that the test actually raises a DeprecationWarning. Parameters ---------- - conditional : bool or callable. + conditional : bool or callable, optional Flag to determine whether to mark test as deprecated or not. If the condition is a callable, it is used at runtime to dynamically make the - decision. + decision. Default is True. Returns ------- decorator : function - Decorator, which, when applied to a function, causes SkipTest - to be raised when the skip_condition was True, and the function - to be called normally otherwise. + The `deprecated` decorator itself. Notes ----- - .. versionadded:: 1.4.0 + """ def deprecate_decorator(f): # Local import to avoid a hard nose dependency and only incur the |