bpo-32695: Add docs and tests for compresslevel and preset in tarfile

Doc/library/tarfile.rst

@@ -102,6 +102,10 @@ 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'``, ``'x:xz'``, :func:`tarfile.open` accepts the keyword
+   argument *preset* to specify the compression level of the file. The default
+   is :class:`PRESET_DEFAULT <lzma.LZMACompressor>`.
+
    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

@@ -1582,15 +1582,29 @@ 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/2018-01-28-12-27-26.bpo-32695.85YqWW.rst

@@ -0,0 +1,2 @@
+The compresslevel and preset keywords for tarfile.open are now both documented
+and tested.