8000 gh-132983: Add documentation for compression.zstd by emmatyping · Pull Request #133911 · python/cpython · GitHub
[go: up one dir, main page]

Skip to content

gh-132983: Add documentation for compression.zstd #133911

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.

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

Merged
merged 23 commits into from
May 21, 2025
Merged
Changes from 1 commit
Commits
Show all changes
23 commits
Select commit Hold shift + click to select a range
49d9c30
Add documentation for compression.zstd
emmatyping May 12, 2025
62ef4dc
Add examples
emmatyping May 12, 2025
0b154b1
Fix camelcase name references
emmatyping May 12, 2025
63f963f
CParameter->CompressionParameter
emmatyping May 12, 2025
cfe0590
Apply suggestions from AA-Turner
emmatyping May 12, 2025
5115b4c
Apply suggestions from reviewers
emmatyping May 12, 2025
4ab7fd7
Apply suggestions from reviewers
emmatyping May 12, 2025
5eb5efc
Apply suggestions from reviewers
emmatyping May 14, 2025
987bd27
Don't reference self when referring to items
emmatyping May 14, 2025
615ed7f
Updates to respond to review
emmatyping May 14, 2025
0f7bc05
Remove outdated paragraph
emmatyping May 15, 2025
44173f3
Remove Zstandard dictionary after ZstdDict
emmatyping May 16, 2025
8bd5500
Rewrite introduction to compression package to be more timeless
emmatyping May 18, 2025
24f3761
Remove content_size_flag
emmatyping May 18, 2025
d04ce4f
Merge branch 'zstd-docs' of github.com:emmatyping/cpython into zstd-docs
emmatyping May 18, 2025
e61e9a1
Apply suggestions from Sumana and Stan
emmatyping May 19, 2025
1149832
Remove ref to Meta and clean up mode usage
emmatyping May 20, 2025
71ed7c3
Apply suggestions from vadmium
emmatyping May 20, 2025
2f895dd
Many updates to respond to review
emmatyping May 20, 2025
f25e6e7
Add examples to (De)compressionParameter
emmatyping May 20, 2025
9ff6320
Add reference to zstd manual and blurb on algorithm
emmatyping May 20, 2025
daa9df1
Expand on the connection between level and compression_level
emmatyping May 21, 2025
b3fd3cd
Resolve review suggestions
emmatyping May 21, 2025
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
Prev Previous commit
Next Next commit
Apply suggestions from reviewers
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
  • Loading branch information
emmatyping and StanFromIreland authored May 12, 2025
commit 4ab7fd78fca0ab1929df22903301167f24364227
28 changes: 14 additions & 14 deletions Doc/library/compression.zstd.rst
Original file line number Diff line number Diff line change
Expand Up @@ -11,10 +11,10 @@

--------------

This module provides classes and convenience functions for compressing and
decompressing data using the Zstandard (or "zstd") compression algorithm. Also
included is a file interface supporting reading and writing contents of ``.zst``
files created from the :program:`zstd` utility, as well as raw zstd compressed
This module provides classes and functions for compressing and
decompressing data using the Zstandard (or *zstd*) compression algorithm. Also
included is a file interface that supports reading and writing the contents of ``.zst`` files.
files created by the :program:`zstd` utility, as well as raw zstd compressed
streams.

The :mod:`compression.zstd` module contains:
Expand Down Expand Up @@ -51,33 +51,33 @@ Reading and writing compressed files
in which case the named file is opened, or it can be an existing file object
to read from or write to.

The mode argument can be either 'r' for reading (default), 'w' for
overwriting, 'a' for appending, or 'x' for exclusive creation. These can
equivalently be given as 'rb', 'wb', 'ab', and 'xb' respectively. You may
also open in text mode with 'rt', 'wt', 'at', and 'xt' respectively.
The mode argument can be either ``'r'`` for reading (default), ``'w'`` for
overwriting, 'a' for appending, or ``'x'`` for exclusive creation. These can
equivalently be given as ``'rb'``, ``'wb'``, ``'ab'``, and ``'xb'`` respectively. You may
also open in text mode with ``'rt'``, ``'wt'``, ``'at'``, and ``'xt'`` respectively.

When opening a file for reading, the *options* argument can be a dictionary
providing advanced decompression parameters, see
providing advanced decompression parameters; see
:class:`DecompressionParameter` for detailed information about supported
parameters. The *zstd_dict* argument is a :class:`ZstdDict` instance to be
used during decompression. When opening a file for reading, the *level*
argument should not be used.

When opening a file for writing, the *options* argument can be a dictionary
providing advanced decompression parameters, see
providing advanced decompression parameters; see
:class:`CompressionParameter` for detailed information about supported
parameters. The *level* argument is the compression level to use when
writing compressed data. Only one of *level* or *options* may be passed. The
*zstd_dict* argument is a :class:`ZstdDict` instance to be used during
compression.

For binary mode, this function is equivalent to the :class:`ZstdFile`
In binary mode, this function is equivalent to the :class:`ZstdFile`
constructor: ``ZstdFile(file, mode, ...)``. In this case, the
*encoding*, *errors* and *newline* parameters must not be provided.
*encoding*, *errors*, and *newline* parameters must not be provided.

For text mode, a :class:`ZstdFile` object is created, and wrapped in an
In text mode, a :class:`ZstdFile` object is created, and wrapped in an
:class:`io.TextIOWrapper` instance with the specified encoding, error handling
behavior, and line ending(s).
behavior, and line endings.


.. class:: ZstdFile(file, /, mode='r', *, level=None, options=None, zstd_dict=None)
Expand Down
Loading
0