spacepy_testing.assertWarns

class spacepy_testing.assertWarns(test, action='always', message='', category=<class 'Warning'>, module='', lineno=0)

Tests that a warning is raised.

Use as a context manager. Code within the context manager block will be executed and, on exit from the block, all warnings issued during execution of the block will be checked to see if the warning specified was issued.

assertWarns requires that the matched warning be issued exactly once within the context manager, or the test function will fail (whether the warning was issued not at all, or multiple times). assertDoesntWarn requires that matched warnings are not issued at all.

All other warnings are issued as normal, although the warning will not be shown (e.g. printed) until the exit of the context manager. If code within the context manager issues an exception, the test for warnings will be skipped (test failure will not be issued), and all warnings shown before the exception propagates up the stack.

The parameters determining which warning to match are for the code referenced in the warning, not necessarily the code being warned. E.g. if code calls a deprecated function, and the deprecated function issues a DeprecationWarning, what is matched may be the code in the deprecated function, not the caller; see the stacklevel parameter to warn() for how this may be changed.

Parameters:

testunittest.TestCase

The test case from which this is being called, almost always self (so the fail() method is available).

action{‘always’, None, ‘default’, ‘error’, ‘ignore’, ‘module’, ‘once’}

Unless None, a warning filter matching the specified warning will be added to the filter before executing the block. ‘always’ (default) is generally recommended to make sure the tested warning will be raised. This filter will be removed on completion of the block.

messagestr, optional

Regular expression to match the start of warning message. Default is to match all.

categorytype, optional

Matches if the warning is an instance of this type or a subclass. Default is the base Warning type (matches all warnings).

modulestr, optional

Regular expression to match the start of the name of the module from which the warning is issued. This is primarily used in setting up the warnings filter; matching the module to determine if the desired warning was issued is based on filename and may not work for modules built into the interpreter. Default is to match all.

linenoint, optional

Line number from which the warning was issued. This is rarely useful since it will change from version to version. Default (0) will match all lines.

See also

warnings.filterwarnings

The action, message, category, module, and lineno parameters are based on the filter specifications.

Examples

This class is primarily useful as part of a test suite, and cannot be easily demonstrated through interactive examples. See the tests of it in test_testing.py and its usage throughout the test suite.

__init__(test, action='always', message='', category=<class 'Warning'>, module='', lineno=0)

Specify whether to record warnings and if an alternative module should be used other than sys.modules[‘warnings’].

For compatibility with Python 3.0, please consider all arguments to be keyword-only.

Methods

Attributes

requireWarning

requireWarning = True

If True, requires that the matching warning be issued (i.e. fail if the warning isn’t issued.) If False, fail if warning is issued.