From 08a5ca9bfcd31a706770580bea3bd5d8074d9139 Mon Sep 17 00:00:00 2001 From: Dominic H Date: Sun, 14 Jul 2024 16:13:10 +0200 Subject: [PATCH 01/10] Add example on how to write a tarfile to stdout --- Doc/library/tarfile.rst | 9 +++++++++ .../2024-07-14-16-12-31.gh-issue-86608.di8ggz.rst | 1 + 2 files changed, 10 insertions(+) create mode 100644 Misc/NEWS.d/next/Documentation/2024-07-14-16-12-31.gh-issue-86608.di8ggz.rst diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 5b624f3533136f..7ff726f2c57af9 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -1346,6 +1346,15 @@ parameter in :meth:`TarFile.add`:: tar.add("foo", filter=reset) tar.close() +How to create and write the archive to stdout using :meth:`sys.stdout.buffer` +in the *fileobj* parameter in :meth:`TarFile.add`:: + + import tarfile + import sys + files = ["foo.txt", "bar.txt", "quux.txt"] + with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar: + for file in files: + tar.add(file) .. _tar-formats: diff --git a/Misc/NEWS.d/next/Documentation/2024-07-14-16-12-31.gh-issue-86608.di8ggz.rst b/Misc/NEWS.d/next/Documentation/2024-07-14-16-12-31.gh-issue-86608.di8ggz.rst new file mode 100644 index 00000000000000..4f9a394429c038 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2024-07-14-16-12-31.gh-issue-86608.di8ggz.rst @@ -0,0 +1 @@ +Add an example on how to write a tarfile to stdout. From b91aa1be93cbd42015a6c4bd4db5152fc2b1be66 Mon Sep 17 00:00:00 2001 From: Dominic H Date: Sun, 14 Jul 2024 16:23:28 +0200 Subject: [PATCH 02/10] Fix sphinx doc warning --- Doc/library/tarfile.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 7ff726f2c57af9..eb5d743b6c397f 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -1346,7 +1346,7 @@ parameter in :meth:`TarFile.add`:: tar.add("foo", filter=reset) tar.close() -How to create and write the archive to stdout using :meth:`sys.stdout.buffer` +How to create and write the archive to stdout using :func:`sys.stdout.buffer` in the *fileobj* parameter in :meth:`TarFile.add`:: import tarfile From b4d66f9157d50ced7d473d3ee8c6d57b3ee06776 Mon Sep 17 00:00:00 2001 From: Dominic H Date: Sun, 14 Jul 2024 16:41:45 +0200 Subject: [PATCH 03/10] Use correct sphinx notation in docs --- Doc/library/tarfile.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index eb5d743b6c397f..524c0522d6819b 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -1346,8 +1346,9 @@ parameter in :meth:`TarFile.add`:: tar.add("foo", filter=reset) tar.close() -How to create and write the archive to stdout using :func:`sys.stdout.buffer` -in the *fileobj* parameter in :meth:`TarFile.add`:: +How to create and write the archive to stdout using +:data:`sys.stdout.buffer ` in the *fileobj* parameter +in :meth:`TarFile.add`:: import tarfile import sys From d1f942b3fa7e8719e408c57ca0216b53f96b2923 Mon Sep 17 00:00:00 2001 From: Dominic H Date: Sun, 14 Jul 2024 22:07:18 +0200 Subject: [PATCH 04/10] Remove trailing space --- Doc/library/tarfile.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 524c0522d6819b..f145118882ff0c 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -1346,7 +1346,7 @@ parameter in :meth:`TarFile.add`:: tar.add("foo", filter=reset) tar.close() -How to create and write the archive to stdout using +How to create and write the archive to stdout using :data:`sys.stdout.buffer ` in the *fileobj* parameter in :meth:`TarFile.add`:: From 84fabe0085638da41bd4b6e989c4eb91cb611bc6 Mon Sep 17 00:00:00 2001 From: Dominic H Date: Sat, 27 Jul 2024 15:12:30 +0100 Subject: [PATCH 05/10] Conform with previous examples --- Doc/library/tarfile.rst | 11 +++++------ 1 file changed, 5 insertions(+), 6 deletions(-) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index f145118882ff0c..81fe0c3e68d273 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -1346,16 +1346,15 @@ parameter in :meth:`TarFile.add`:: tar.add("foo", filter=reset) tar.close() -How to create and write the archive to stdout using +How to create and write an archive to stdout using :data:`sys.stdout.buffer ` in the *fileobj* parameter in :meth:`TarFile.add`:: - import tarfile import sys - files = ["foo.txt", "bar.txt", "quux.txt"] - with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar: - for file in files: - tar.add(file) + import tarfile + with tarfile.open("sample.tar.gz", "w:gz", fileobj=sys.stdout.buffer) as tar: + for name in ["foo", "bar", "quux"]: + tar.add(name) .. _tar-formats: From fa974e67728a7cfcddd0370fe9ec096d1a16a80f Mon Sep 17 00:00:00 2001 From: Dominic H Date: Sun, 20 Jul 2025 13:42:39 +0200 Subject: [PATCH 06/10] Add sections to docs --- Doc/library/tarfile.rst | 46 +++++++++++++++++++++++------------------ 1 file changed, 26 insertions(+), 20 deletions(-) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 81fe0c3e68d273..e2740ccf4725dd 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -1283,6 +1283,9 @@ Command-line options Examples -------- +Reading examples +~~~~~~~~~~~~~~~~~~~ + How to extract an entire tar archive to the current working directory:: import tarfile @@ -1305,21 +1308,6 @@ a generator function instead of a list:: tar.extractall(members=py_files(tar)) tar.close() -How to create an uncompressed tar archive from a list of filenames:: - - import tarfile - tar = tarfile.open("sample.tar", "w") - for name in ["foo", "bar", "quux"]: - tar.add(name) - tar.close() - -The same example using the :keyword:`with` statement:: - - import tarfile - with tarfile.open("sample.tar", "w") as tar: - for name in ["foo", "bar", "quux"]: - tar.add(name) - How to read a gzip compressed tar archive and display some member information:: import tarfile @@ -1334,6 +1322,19 @@ How to read a gzip compressed tar archive and display some member information:: print("something else.") tar.close() +Writing examples +~~~~~~~~~~~~~~~~ + +How to create and write an archive to stdout using +:data:`sys.stdout.buffer ` in the *fileobj* parameter +in :meth:`TarFile.add`:: + + import sys + import tarfile + with tarfile.open("sample.tar.gz", "w:gz", fileobj=sys.stdout.buffer) as tar: + for name in ["foo", "bar", "quux"]: + tar.add(name) + How to create an archive and reset the user information using the *filter* parameter in :meth:`TarFile.add`:: @@ -1346,13 +1347,18 @@ parameter in :meth:`TarFile.add`:: tar.add("foo", filter=reset) tar.close() -How to create and write an archive to stdout using -:data:`sys.stdout.buffer ` in the *fileobj* parameter -in :meth:`TarFile.add`:: +How to create an uncompressed tar archive from a list of filenames:: + + import tarfile + tar = tarfile.open("sample.tar", "w") + for name in ["foo", "bar", "quux"]: + tar.add(name) + tar.close() + +The same example using the :keyword:`with` statement:: - import sys import tarfile - with tarfile.open("sample.tar.gz", "w:gz", fileobj=sys.stdout.buffer) as tar: + with tarfile.open("sample.tar", "w") as tar: for name in ["foo", "bar", "quux"]: tar.add(name) From 4c90c51e3b963e66c50de733316cf75390915007 Mon Sep 17 00:00:00 2001 From: Dominic H Date: Sun, 20 Jul 2025 13:45:43 +0200 Subject: [PATCH 07/10] Remove news blurb --- .../Documentation/2024-07-14-16-12-31.gh-issue-86608.di8ggz.rst | 1 - 1 file changed, 1 deletion(-) delete mode 100644 Misc/NEWS.d/next/Documentation/2024-07-14-16-12-31.gh-issue-86608.di8ggz.rst diff --git a/Misc/NEWS.d/next/Documentation/2024-07-14-16-12-31.gh-issue-86608.di8ggz.rst b/Misc/NEWS.d/next/Documentation/2024-07-14-16-12-31.gh-issue-86608.di8ggz.rst deleted file mode 100644 index 4f9a394429c038..00000000000000 --- a/Misc/NEWS.d/next/Documentation/2024-07-14-16-12-31.gh-issue-86608.di8ggz.rst +++ /dev/null @@ -1 +0,0 @@ -Add an example on how to write a tarfile to stdout. From b2a1f90fcd1921d89d410f6217a8a4549e550355 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 20 Jul 2025 12:49:56 +0100 Subject: [PATCH 08/10] Update Doc/library/tarfile.rst --- Doc/library/tarfile.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index e2740ccf4725dd..748a82aeee3d1d 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -1331,7 +1331,7 @@ in :meth:`TarFile.add`:: import sys import tarfile - with tarfile.open("sample.tar.gz", "w:gz", fileobj=sys.stdout.buffer) as tar: + with tarfile.open("sample.tar.gz", "w|gz", fileobj=sys.stdout.buffer) as tar: for name in ["foo", "bar", "quux"]: tar.add(name) From 9978ce5f50b5d091f6c3d62700824b64b7b295c6 Mon Sep 17 00:00:00 2001 From: Dominic H Date: Sun, 20 Jul 2025 13:57:00 +0200 Subject: [PATCH 09/10] Move writing examples up a little --- Doc/library/tarfile.rst | 30 +++++++++++++++--------------- 1 file changed, 15 insertions(+), 15 deletions(-) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index 748a82aeee3d1d..f03ad7f6a5080e 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -1325,6 +1325,21 @@ How to read a gzip compressed tar archive and display some member information:: Writing examples ~~~~~~~~~~~~~~~~ +How to create an uncompressed tar archive from a list of filenames:: + + import tarfile + tar = tarfile.open("sample.tar", "w") + for name in ["foo", "bar", "quux"]: + tar.add(name) + tar.close() + +The same example using the :keyword:`with` statement:: + + import tarfile + with tarfile.open("sample.tar", "w") as tar: + for name in ["foo", "bar", "quux"]: + tar.add(name) + How to create and write an archive to stdout using :data:`sys.stdout.buffer ` in the *fileobj* parameter in :meth:`TarFile.add`:: @@ -1347,21 +1362,6 @@ parameter in :meth:`TarFile.add`:: tar.add("foo", filter=reset) tar.close() -How to create an uncompressed tar archive from a list of filenames:: - - import tarfile - tar = tarfile.open("sample.tar", "w") - for name in ["foo", "bar", "quux"]: - tar.add(name) - tar.close() - -The same example using the :keyword:`with` statement:: - - import tarfile - with tarfile.open("sample.tar", "w") as tar: - for name in ["foo", "bar", "quux"]: - tar.add(name) - .. _tar-formats: Supported tar formats From 9f0943ffc3459a09590c67772e06917bffdc3ac1 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sun, 20 Jul 2025 14:11:33 +0200 Subject: [PATCH 10/10] whitespace --- Doc/library/tarfile.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/library/tarfile.rst b/Doc/library/tarfile.rst index f03ad7f6a5080e..82d823cc21d47a 100644 --- a/Doc/library/tarfile.rst +++ b/Doc/library/tarfile.rst @@ -1362,6 +1362,7 @@ parameter in :meth:`TarFile.add`:: tar.add("foo", filter=reset) tar.close() + .. _tar-formats: Supported tar formats