[Python-checkins] bpo-33487: improve BZ2File Deprecation and documentation. (GH-6785)

[Gregory P. Smith]

https://github.com/python/cpython/commit/ffa198c642f9c67b84ef192bf0f7016c4249e570
commit: ffa198c642f9c67b84ef192bf0f7016c4249e570
branch: master
author: Matthias Bussonnier <bussonniermatthias at gmail.com>
committer: Gregory P. Smith <greg at krypto.org>
date: 2018-09-10T18:15:56-07:00
summary:

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.

files:
A Misc/NEWS.d/next/Documentation/2018-05-13-14-44-30.bpo-33487.iLDzFb.rst
M Doc/library/bz2.rst
M Lib/bz2.py

diff --git a/Doc/library/bz2.rst b/Doc/library/bz2.rst
index d5f622515a40..946cc67dd301 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 3924aaed1678..3ab099147190 100644
--- a/Lib/bz2.py
+++ b/Lib/bz2.py
@@ -24,6 +24,8 @@
 # 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 @@ def __init__(self, filename, mode="r", buffering=None, compresslevel=9):
         '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 @@ def __init__(self, filename, mode="r", buffering=None, compresslevel=9):
         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 000000000000..0439d983d1bc
--- /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.