@@ -158,6 +158,67 @@ ImportWarning can also be enabled explicitly in Python code using::
158158 warnings.simplefilter('default', ImportWarning)
159159
160160
161+ .. _warning-suppress :
162+
163+ Temporarily Suppressing Warnings
164+ --------------------------------
165+
166+ If you are using code that you know will raise a warning, such some deprecated
167+ function, but do not want to see the warning, then suppress the warning using
168+ the :class: `catch_warnings ` context manager::
169+
170+ import warnings
171+
172+ def fxn():
173+ warnings.warn("deprecated", DeprecationWarning)
174+
175+ with warnings.catch_warnings():
176+ warnings.simplefilter("ignore")
177+ fxn()
178+
179+ While within the context manager all warnings will simply be ignored. This
180+ allows you to use known-deprecated code without having to see the warning while
181+ not suppressing the warning for other code that might not be aware of its use
182+ of deprecated code.
183+
184+
185+ .. _warning-testing :
186+
187+ Testing Warnings
188+ ----------------
189+
190+ To test warnings raised by code, use the :class: `catch_warnings ` context
191+ manager. With it you can temporarily mutate the warnings filter to facilitate
192+ your testing. For instance, do the following to capture all raised warnings to
193+ check::
194+
195+ import warnings
196+
197+ def fxn():
198+ warnings.warn("deprecated", DeprecationWarning)
199+
200+ with warnings.catch_warnings(record=True) as w:
201+ # Cause all warnings to always be triggered.
202+ warnings.simplefilter("always")
203+ # Trigger a warning.
204+ fxn()
205+ # Verify some things
206+ assert len(w) == 1
207+ assert isinstance(w[-1].category, DeprecationWarning)
208+ assert "deprecated" in str(w[-1].message)
209+
210+ One can also cause all warnings to be exceptions by using ``error `` instead of
211+ ``always ``. One thing to be aware of is that if a warning has already been
212+ raised because of a ``once ``/``default `` rule, then no matter what filters are
213+ set the warning will not be seen again unless the warnings registry related to
214+ the warning has been cleared.
215+
216+ Once the context manager exits, the warnings filter is restored to its state
217+ when the context was entered. This prevents tests from changing the warnings
218+ filter in unexpected ways between tests and leading to indeterminate test
219+ results.
220+
221+
161222.. _warning-functions :
162223
163224Available Functions
@@ -264,31 +325,22 @@ Available Functions
264325 and calls to :func: `simplefilter `.
265326
266327
267- Available Classes
268- -----------------
269-
270- .. class :: catch_warnings([\*, record=False[, module=None]])
271-
272- A context manager that guards the warnings filter from being permanently
273- mutated. The manager returns an instance of :class: `WarningsRecorder `. The
274- *record * argument specifies whether warnings that would typically be
275- handled by :func: `showwarning ` should instead be recorded by the
276- :class: `WarningsRecorder ` instance. This argument is typically set when
277- testing for expected warnings behavior. The *module * argument may be a
278- module object that is to be used instead of the :mod: `warnings ` module.
279- This argument should only be set when testing the :mod: `warnings ` module
280- or some similar use-case.
328+ Available Context Managers
329+ --------------------------
281330
282- Typical usage of the context manager is like so::
331+ .. class :: catch_warnings([\*, record=False, module=None])
283332
284- def fxn():
285- warn("fxn is deprecated", DeprecationWarning)
286- return "spam spam bacon spam"
333+ A context manager that copies and, upon exit, restores the warnings filter.
334+ If the *record * argument is False (the default) the context manager returns
335+ :class: `None `. If *record * is true, a list is returned that is populated
336+ with objects as seen by a custom :func: `showwarning ` function (which also
337+ suppresses output to ``sys.stdout ``). Each object has attributes with the
338+ same names as the arguments to :func: `showwarning `.
287339
288- # The function 'fxn' is known to raise a DeprecationWarning.
289- with catch_warnings() as w:
290- warnings.filterwarning('ignore', 'fxn is deprecated', DeprecationWarning)
291- fxn() # DeprecationWarning is temporarily suppressed .
340+ The * module * argument takes a module that will be used instead of the
341+ module returned when you import :mod: ` warnings ` whose filter will be
342+ protected. This arguments exists primarily for testing the :mod: ` warnings `
343+ module itself .
292344
293345 .. note ::
294346
@@ -297,19 +349,3 @@ Available Classes
297349
298350 .. versionadded :: 2.6
299351
300-
301- .. class :: WarningsRecorder()
302-
303- A subclass of :class: `list ` that stores all warnings passed to
304- :func: `showwarning ` when returned by a :class: `catch_warnings ` context
305- manager created with its *record * argument set to ``True ``. Each recorded
306- warning is represented by an object whose attributes correspond to the
307- arguments to :func: `showwarning `. As a convenience, a
308- :class: `WarningsRecorder ` instance has the attributes of the last
309- recorded warning set on the :class: `WarningsRecorder ` instance as well.
310-
311- .. method :: reset()
312-
313- Delete all recorded warnings.
314-
315- .. versionadded :: 2.6
0 commit comments