Add a new warning gategory, ResourceWarning, as discussed on python-dev. It is silent by default,

except when configured --with-pydebug.

Emit this warning from the GC shutdown procedure, rather than just printing to stderr.

3 files changed, 22 insertions, 11 deletions

diff --git a/Doc/library/exceptions.rst b/Doc/library/exceptions.rst
index 49b5b93..9d77698 100644
--- a/Doc/library/exceptions.rst
+++ b/Doc/library/exceptions.rst
@@ -410,10 +410,20 @@ module for more information.
 
    Base class for warnings related to Unicode.
 
+
 .. exception:: BytesWarning
 
    Base class for warnings related to :class:`bytes` and :class:`buffer`.
 
+
+.. exception:: ResourceWarning
+
+   Base class for warnings related to resource usage.
+
+   .. versionadded:: 3.2
+
+
+
 Exception hierarchy
 -------------------
 
diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst
index ae615eb..0281bb7 100644
--- a/Doc/library/gc.rst
+++ b/Doc/library/gc.rst
@@ -174,17 +174,15 @@ value but should not rebind it):
    with :meth:`__del__` methods, and *garbage* can be examined in that case to
    verify that no such cycles are being created.
 
-   If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added to
-   this list rather than freed.
+   If :const:`DEBUG_SAVEALL` is set, then all unreachable objects will be added
+   to this list rather than freed.
 
    .. versionchanged:: 3.2
-      If this list is non-empty at interpreter shutdown, a warning message
-      gets printed.
+      If this list is non-empty at interpreter shutdown, a
+      :exc:`ResourceWarning` is emitted, which is silent by default.  If
+      :const:`DEBUG_UNCOLLECTABLE` is set, in addition all uncollectable objects
+      are printed.
 
-   ::
-
-       gc: 2 uncollectable objects at shutdown:
-             Use gc.set_debug(gc.DEBUG_UNCOLLECTABLE) to list them.
 
 The following constants are provided for use with :func:`set_debug`:
 
@@ -203,12 +201,12 @@ The following constants are provided for use with :func:`set_debug`:
 .. data:: DEBUG_UNCOLLECTABLE
 
    Print information of uncollectable objects found (objects which are not
-   reachable but cannot be freed by the collector).  These objects will be added to
-   the ``garbage`` list.
+   reachable but cannot be freed by the collector).  These objects will be added
+   to the ``garbage`` list.
 
    .. versionchanged:: 3.2
       Also print the contents of the :data:`garbage` list at interpreter
-      shutdown (rather than just its length), if it isn't empty.
+      shutdown, if it isn't empty.
 
 .. data:: DEBUG_SAVEALL
 
diff --git a/Doc/library/warnings.rst b/Doc/library/warnings.rst
index 309fec5..64689ad 100644
--- a/Doc/library/warnings.rst
+++ b/Doc/library/warnings.rst
@@ -82,6 +82,9 @@ following warnings category classes are currently defined:
 | :exc:`BytesWarning`              | Base category for warnings related to         |
 |                                  | :class:`bytes` and :class:`buffer`.           |
 +----------------------------------+-----------------------------------------------+
+| :exc:`ResourceWarning`           | Base category for warnings related to         |
+|                                  | resource usage.                               |
++----------------------------------+-----------------------------------------------+
 
 
 While these are technically built-in exceptions, they are documented here,