bpo-33487: improve BZ2File Deprecation and documentation. (GH-6785)

Emit warning when None passed explicitly, list Python version since
deprecation in warning message and docs.

3 files changed, 17 insertions, 6 deletions

diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index d5f6225..946cc67 100644
--- a/Doc/library/bz2.rst
+++ b/Doc/library/bz2.rst
@@ -81,7 +81,7 @@ All of the classes in this module may safely be accessed from multiple threads.
    If *filename* is a file object (rather than an actual file name), a mode of
    ``'w'`` does not truncate the file, and is instead equivalent to ``'a'``.
 
-   The *buffering* argument is ignored. Its use is deprecated.
+   The *buffering* argument is ignored. Its use is deprecated since Python 3.0.
 
    If *mode* is ``'w'`` or ``'a'``, *compresslevel* can be a number between
    ``1`` and ``9`` specifying the level of compression: ``1`` produces the
@@ -109,6 +109,10 @@ All of the classes in this module may safely be accessed from multiple threads.
 
       .. versionadded:: 3.3
 
+
+   .. deprecated:: 3.0
+      The keyword argument *buffering* was deprecated and is now ignored.
+
    .. versionchanged:: 3.1
       Support for the :keyword:`with` statement was added.
 
diff --git a/Lib/bz2.py b/Lib/bz2.py
index 3924aae..3ab0991 100644
--- a/Lib/bz2.py
+++ b/Lib/bz2.py
@@ -24,6 +24,8 @@ _MODE_READ     = 1
 # Value 2 no longer used
 _MODE_WRITE    = 3
 
+_sentinel = object()
+
 
 class BZ2File(_compression.BaseStream):
 
@@ -36,7 +38,7 @@ class BZ2File(_compression.BaseStream):
     returned as bytes, and data to be written should be given as bytes.
     """
 
-    def __init__(self, filename, mode="r", buffering=None, compresslevel=9):
+    def __init__(self, filename, mode="r", buffering=_sentinel, compresslevel=9):
         """Open a bzip2-compressed file.
 
         If filename is a str, bytes, or PathLike object, it gives the
@@ -47,7 +49,7 @@ class BZ2File(_compression.BaseStream):
         'x' for creating exclusively, or 'a' for appending. These can
         equivalently be given as 'rb', 'wb', 'xb', and 'ab'.
 
-        buffering is ignored. Its use is deprecated.
+        buffering is ignored since Python 3.0. Its use is deprecated.
 
         If mode is 'w', 'x' or 'a', compresslevel can be a number between 1
         and 9 specifying the level of compression: 1 produces the least
@@ -63,9 +65,11 @@ class BZ2File(_compression.BaseStream):
         self._closefp = False
         self._mode = _MODE_CLOSED
 
-        if buffering is not None:
-            warnings.warn("Use of 'buffering' argument is deprecated",
-                          DeprecationWarning)
+        if buffering is not _sentinel:
+            warnings.warn("Use of 'buffering' argument is deprecated  and ignored"
+                          "since Python 3.0.",
+                          DeprecationWarning,
+                          stacklevel=2)
 
         if not (1 <= compresslevel <= 9):
             raise ValueError("compresslevel must be between 1 and 9")
diff --git a/Misc/NEWS.d/next/Documentation/2018-05-13-14-44-30.bpo-33487.iLDzFb.rst b/Misc/NEWS.d/next/Documentation/2018-05-13-14-44-30.bpo-33487.iLDzFb.rst
new file mode 100644
index 0000000..0439d98
--- /dev/null
+++ b/Misc/NEWS.d/next/Documentation/2018-05-13-14-44-30.bpo-33487.iLDzFb.rst
@@ -0,0 +1,3 @@
+BZ2file now emit a DeprecationWarning when buffering=None is passed, the
+deprecation message and documentation also now explicitely state it is
+deprecated since 3.0.