Python Warnings Module
The warnings module provides a way to issue warning messages to users. Warnings are typically issued in situations where it is useful to alert the user of some condition in a program, where that condition (normally) doesn't warrant raising an exception and terminating the program.
Importing the Module
import warningsIssuing Warnings
To issue a warning, use the warn() function.
import warnings
def my_function(x):
if x < 0:
warnings.warn("Argument is negative", UserWarning)
return x * x
my_function(-5)
# Output (to stderr):
# UserWarning: Argument is negative
# warnings.warn("Argument is negative", UserWarning)Warning Categories
There are several built-in exceptions that represent warning categories. This categorization is useful to be able to filter out groups of warnings.
UserWarning: Base class for warnings generated by user code.DeprecationWarning: Base class for warnings about deprecated features.SyntaxWarning: Base class for warnings about dubious syntax.RuntimeWarning: Base class for warnings about dubious runtime behavior.FutureWarning: Base class for warnings about constructs that will change semantically in the future.PendingDeprecationWarning: Base class for warnings about features that will be deprecated in the future.ImportWarning: Base class for warnings about probable mistakes in module imports.UnicodeWarning: Base class for warnings related to Unicode.BytesWarning: Base class for warnings related to bytes and bytearray.ResourceWarning: Base class for warnings related to resource usage.
Filtering Warnings
You can control how warnings are handled using filters.
simplefilter()
The simplefilter() function inserts a simple entry into the list of warnings filters.
import warnings
# Ignore all warnings
warnings.simplefilter('ignore')
warnings.warn("This will not be shown")
# Reset to default
warnings.simplefilter('default')
warnings.warn("This will be shown")Common actions:
"error": Turn warning into exception."ignore": Never print matching warnings."always": Always print matching warnings."default": Print the first occurrence of matching warnings for each location (module + line number) where the warning is issued."module": Print the first occurrence of matching warnings for each module where the warning is issued."once": Print only the first occurrence of matching warnings, regardless of location.
filterwarnings()
For more granular control, use filterwarnings().
# Filter specific category
warnings.filterwarnings('error', category=DeprecationWarning)Testing Warnings
To test that your code issues warnings correctly, use catch_warnings as a context manager.
import warnings
def deprecated_function():
warnings.warn("This is deprecated", DeprecationWarning)
with warnings.catch_warnings(record=True) as w:
# Cause all warnings to always be triggered.
warnings.simplefilter("always")
# Trigger a warning.
deprecated_function()
# Verify some things
assert len(w) == 1
assert issubclass(w[0].category, DeprecationWarning)
assert "deprecated" in str(w[0].message)