gh-86608: Improve and restructure tarfile examples (GH-121771)
Add an example on how to write a tarfile to stdout; general improvements.
(cherry picked from commit cc81b4e501)
Co-authored-by: Dominic H <dom@dominic.sk>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
gh-135252: Document Zstandard integration across zipfile, shutil, and tarfile (GH-135311)
Document Zstandard integration across zipfile, shutil, and tarfile
(cherry picked from commit 938a5d7e62)
Co-authored-by: Emma Smith <emma@emmatyping.dev>
* gh-133005: Support `tarfile.open(mode="w|xz", preset=...)`
Support passing the `preset` option to `tarfile.open` when the file
is open with `mode="w|xz"`. This aligns the behavior with `"w:xz"`
mode.
* Also raise an error for `compresslevel` or `preset` with wrong mode
Raise an error if `compresslevel` or `preset` argument is specified
for stream mode with incorrect compression. This should reduce the risk
of mistakes and align the stream modes with regular modes, that raise
an implicit TypeError on unsupported arguments.
* Apply suggestions from code review
Co-authored-by: Brian Schubert <brianm.schubert@gmail.com>
Co-authored-by: Tomas R <tomas.roun8@gmail.com>
Co-authored-by: Scott Odle <scott@sjodle.com>
Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
Co-authored-by: Petr Viktorin <encukou@gmail.com>
* Add name and mode attributes for compressed and archived file-like objects
in modules bz2, lzma, tarfile and zipfile.
* Change the value of the mode attribute of GzipFile from integer (1 or 2)
to string ('rb' or 'wb').
* Change the value of the mode attribute of ZipExtFile from 'r' to 'rb'.
Tarfile.addfile now throws an ValueError when the user passes
in a non-zero size tarinfo but does not provide a fileobj,
instead of writing an incomplete entry.
The syntax used in the current docs (a / before any args) is invalid.
I think the right approach is for the arguments to arbitrary
filter functions to be treated as positional-only, meaning that users
can supply filter functions with any names for the argument. tarfile.py
only calls the filter function with positional arguments.
`tarfile` already accepts a compressionlevel argument for creating
files. This patch adds the same for stream-based tarfile usage.
The default is 9, the value that was previously hard-coded.
The issue being resolved is shown in the 3.10 docs (if you select docs for older versions you won't see a visual glitch).
The newer sphinx version that produces the 3.10 docs doesn't treat the backslash to escape things in some situations it previously did.
Add :noindex: to duplicated documentation to fix "duplicate object
description" errors.
For example, fix this Sphinx 3 issue:
Doc/library/configparser.rst:1146: WARNING: duplicate object
description of configparser.ConfigParser.optionxform, other instance
in library/configparser, use :noindex: for one of them
Before
```
content.txt is 42 bytes in size and isa regular file.
folder is 420 bytes in size and isa directory.
magic is 4200 bytes in size and issomething else.
```
After:
```
content.txt is 42 bytes in size and is a regular file.
folder is 420 bytes in size and is a directory.
magic is 4200 bytes in size and is something else.
```
Automerge-Triggered-By: @orsenthil
* The Windows-specific binary notice was probably a Python 2 thing
* Make it more obvious gettarinfo() is based on stat(), and that non-ordinary
files may need special care
* The file name must be text; suggest dummy arcname as a workaround
* Indicate TarInfo may be used directly, not just via gettarinfo()
