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.
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 @@
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 @@
.. 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 @@
# Value 2 no longer used
_MODE_WRITE = 3
+_sentinel = object()
+
class BZ2File(_compression.BaseStream):
@@ -36,7 +38,7 @@
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 @@
'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 @@
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.