Skip to content

gh-136858: Adds an example of writing a tarfile using stdin #137510

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 1 commit into
base: main
Choose a base branch
from
Open

gh-136858: Adds an example of writing a tarfile using stdin #137510

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
34 changes: 29 additions & 5 deletions Doc/library/tarfile.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -104,7 +104,7 @@ Some facts and figures:
| ``'w'`` or | Open for uncompressed writing. |
| ``'w:'`` | |
+------------------+---------------------------------------------+
| ``'w:gz'`` | Open for gzip compressed writing. |
| ``'w:gz'`` | Open for gzip-compressed writing. |
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Why are you hyphenating these? The following line has bzip2 compressed without hyphens.

+------------------+---------------------------------------------+
| ``'w:bz2'`` | Open for bzip2 compressed writing. |
+------------------+---------------------------------------------+
Expand Down Expand Up @@ -159,7 +159,7 @@ Some facts and figures:
| ``'r|'`` | Open a *stream* of uncompressed tar blocks |
| | for reading. |
+-------------+--------------------------------------------+
| ``'r|gz'`` | Open a gzip compressed *stream* for |
| ``'r|gz'`` | Open a gzip-compressed *stream* for |
| | reading. |
+-------------+--------------------------------------------+
| ``'r|bz2'`` | Open a bzip2 compressed *stream* for |
Expand All @@ -173,7 +173,7 @@ Some facts and figures:
+-------------+--------------------------------------------+
| ``'w|'`` | Open an uncompressed *stream* for writing. |
+-------------+--------------------------------------------+
| ``'w|gz'`` | Open a gzip compressed *stream* for |
| ``'w|gz'`` | Open a gzip-compressed *stream* for |
| | writing. |
+-------------+--------------------------------------------+
| ``'w|bz2'`` | Open a bzip2 compressed *stream* for |
Expand Down Expand Up @@ -1367,6 +1367,12 @@ How to extract an entire tar archive to the current working directory::
tar.extractall(filter='data')
tar.close()

The same example using the :keyword:`with` statement::
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

You could replace the example with the with statement. We don't need an additional example.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We should drop it as well in the "Writing examples" section.


import tarfile
with tarfile.open("sample.tar.gz") as tar:
tar.extractall(filter='data')

How to extract a subset of a tar archive with :meth:`TarFile.extractall` using
a generator function instead of a list::

Expand All @@ -1382,7 +1388,7 @@ a generator function instead of a list::
tar.extractall(members=py_files(tar))
tar.close()

How to read a gzip compressed tar archive and display some member information::
How to read a gzip-compressed tar archive and display some member information::

import tarfile
tar = tarfile.open("sample.tar.gz", "r:gz")
Expand All @@ -1396,6 +1402,15 @@ How to read a gzip compressed tar archive and display some member information::
print("something else.")
tar.close()

How to extract a gzip-compressed tar archive from standard input using
:data:`sys.stdin.buffer <sys.stdin>` as the *fileobj* parameter
in :meth:`TarFile.open` into the current working directory::

import sys
import tarfile
with tarfile.open(fileobj=sys.stdin.buffer, mode="r:gz") as tar:
tar.extractall(filter="data")

Writing examples
~~~~~~~~~~~~~~~~

Expand All @@ -1414,9 +1429,18 @@ The same example using the :keyword:`with` statement::
for name in ["foo", "bar", "quux"]:
tar.add(name)

How to create a gzip-compressed tar archive from a list of filenames
read from the standard input using :data:`sys.stdin <sys.stdin>`::

import sys
import tarfile
with tarfile.open("sample.tar.gz", mode="w|gz") as tar:
for filename in sys.stdin:
tar.add(filename.strip())

How to create and write an archive to stdout using
:data:`sys.stdout.buffer <sys.stdout>` in the *fileobj* parameter
in :meth:`TarFile.add`::
in :meth:`TarFile.open`::
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This demonstrates .add not open.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

add does not have a fileobj parameter.


import sys
import tarfile
Expand Down
Loading