diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 15b88f87b76..3adb6331038 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -325,11 +325,15 @@ be finalized; only the internally used file object will be closed. See the returned by :meth:`getmembers`. -.. method:: TarFile.list(verbose=True) +.. method:: TarFile.list(verbose=True, *, members=None) Print a table of contents to ``sys.stdout``. If *verbose* is :const:`False`, only the names of the members are printed. If it is :const:`True`, output - similar to that of :program:`ls -l` is produced. + similar to that of :program:`ls -l` is produced. If optional *members* is + given, it must be a subset of the list returned by :meth:`getmembers`. + + .. versionchanged:: 3.5 + Added the *members* parameter. .. method:: TarFile.next() diff --git a/Lib/tarfile.py b/Lib/tarfile.py index 9e291c2a584..4b4e0d35e14 100755 --- a/Lib/tarfile.py +++ b/Lib/tarfile.py @@ -1842,14 +1842,17 @@ class TarFile(object): tarinfo.devminor = os.minor(statres.st_rdev) return tarinfo - def list(self, verbose=True): + def list(self, verbose=True, *, members=None): """Print a table of contents to sys.stdout. If `verbose' is False, only the names of the members are printed. If it is True, an `ls -l'-like - output is produced. + output is produced. `members' is optional and must be a subset of the + list returned by getmembers(). """ self._check() - for tarinfo in self: + if members is None: + members = self + for tarinfo in members: if verbose: _safe_print(stat.filemode(tarinfo.mode)) _safe_print("%s/%s" % (tarinfo.uname or tarinfo.uid, diff --git a/Lib/test/test_tarfile.py b/Lib/test/test_tarfile.py index e527e403fa6..810b76be532 100644 --- a/Lib/test/test_tarfile.py +++ b/Lib/test/test_tarfile.py @@ -285,6 +285,18 @@ class ListTest(ReadTest, unittest.TestCase): self.assertIn(b'pax' + (b'/123' * 125) + b'/longlink link to pax' + (b'/123' * 125) + b'/longname', out) + def test_list_members(self): + tio = io.TextIOWrapper(io.BytesIO(), 'ascii', newline='\n') + def members(tar): + for tarinfo in tar.getmembers(): + if 'reg' in tarinfo.name: + yield tarinfo + with support.swap_attr(sys, 'stdout', tio): + self.tar.list(verbose=False, members=members(self.tar)) + out = tio.detach().getvalue() + self.assertIn(b'ustar/regtype', out) + self.assertNotIn(b'ustar/conttype', out) + class GzipListTest(GzipTest, ListTest): pass diff --git a/Misc/NEWS b/Misc/NEWS index e6e09edea6d..5ac80b822ac 100644 --- a/Misc/NEWS +++ b/Misc/NEWS @@ -124,6 +124,8 @@ Core and Builtins Library ------- +- Issue #21549: Added the "members" parameter to TarFile.list(). + - Issue #19628: Allow compileall recursion depth to be specified with a -r option.