bpo-32695: Docs and tests for compresslevel and preset kwargs in tarfile (GH-21470)

Co-Authored-By: Bo Bayles <bbayles@gmail.com> (cherry picked from commit eb2d4a6) Co-authored-by: Zackery Spytz <zspytz@gmail.com>

Author: miss-islington

Doc/library/tarfile.rst

@@ -102,6 +102,9 @@ Some facts and figures:
  ``'x:bz2'``, :func:`tarfile.open` accepts the keyword argument
  *compresslevel* (default ``9``) to specify the compression level of the file.
 
+ For modes ``'w:xz'`` and ``'x:xz'``, :func:`tarfile.open` accepts the
+ keyword argument *preset* to specify the compression level of the file.
+
  For special purposes, there is a second format for *mode*:
  ``'filemode|[compression]'``. :func:`tarfile.open` will return a :class:`TarFile`
  object that processes its data as a stream of blocks. No random seeking will

Lib/test/test_tarfile.py

@@ -1706,15 +1706,30 @@ def test_create_taropen_pathlike_name(self):
 
 
 class GzipCreateTest(GzipTest, CreateTest):
- pass
+
+ def test_create_with_compresslevel(self):
+ with tarfile.open(tmpname, self.mode, compresslevel=1) as tobj:
+ tobj.add(self.file_path)
+ with tarfile.open(tmpname, 'r:gz', compresslevel=1) as tobj:
+ pass
 
 
 class Bz2CreateTest(Bz2Test, CreateTest):
- pass
+
+ def test_create_with_compresslevel(self):
+ with tarfile.open(tmpname, self.mode, compresslevel=1) as tobj:
+ tobj.add(self.file_path)
+ with tarfile.open(tmpname, 'r:bz2', compresslevel=1) as tobj:
+ pass
 
 
 class LzmaCreateTest(LzmaTest, CreateTest):
- pass
+
+ # Unlike gz and bz2, xz uses the preset keyword instead of compresslevel.
+ # It does not allow for preset to be specified when reading.
+ def test_create_with_preset(self):
+ with tarfile.open(tmpname, self.mode, preset=1) as tobj:
+ tobj.add(self.file_path)
 
 
 class CreateWithXModeTest(CreateTest):

Misc/NEWS.d/next/Library/2020-07-13-23-46-59.bpo-32695.tTqqXe.rst

@@ -0,0 +1,2 @@
+The *compresslevel* and *preset* keyword arguments of :func:`tarfile.open`
+are now both documented and tested.