classification
Title: Clarify ResourceWarning documentation
Type: enhancement Stage:
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6, Python 3.4, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, edmorley, ncoghlan
Priority: normal Keywords:

Created on 2018-04-09 22:13 by edmorley, last changed 2018-04-11 13:51 by ncoghlan.

Messages (2)
msg315153 - (view) Author: Ed Morley (edmorley) * Date: 2018-04-09 22:13
The `ResourceWarning` warning has always been ignored by default, since it was added in Python 3.2 in:
https://github.com/python/cpython/commit/08be72d0aa0112118b79d271479598c218adfd23#diff-db4e2b9efea108a38c53e06fa99cdd77R391

However there are several places in the docs where the "ignored by default" aspect is not mentioned even though it is for `DeprecationWarning` and similar - which caused me quite a bit of confusion today.

The docs were partly improved in Python 3.7 onwards by:
https://github.com/python/cpython/commit/9b99747386b690007027c3be2a5d7cfe3d3634f5

...however:
(a) there is still at least one place that still needs updating on master (https://docs.python.org/3.8/library/warnings.html#warning-categories)
(b) it would be good to backport the docs fixes to 3.4/3.5/3.6 (I was looking at the 3.6 docs today)

I'm happy to open PRs to fix this; but filing this issue so I have something to reference.
msg315191 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2018-04-11 13:51
+1 from me for further ResourceWarning docs improvements - my focus when working on PEP 565 was the actual change in how DeprecationWarning was being handled, and the other warnings doc improvements were just a necessary prerequisite for being able to convey that clearly.

The backport to 3.6 may or may not be worthwhile, depending on how much work it proves to be in practice (while those will still be the default online docs for the next couple of months, the 3.7 branch will take their place once 3.7.0 is officially released).

We wouldn't backport docs changes to 3.4 or 3.5, as both of those branches are already in security-fix-only mode.
History
Date User Action Args
2018-04-11 13:51:58ncoghlansetmessages: + msg315191
2018-04-10 14:38:43ned.deilysetnosy: + ncoghlan
2018-04-09 22:13:44edmorleycreate