gh-132983: Add documentation for compression.zstd #133911
Open
+801
−1
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
11 tasks
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
|
cc @python/proofreaders, I think the text here could benefit from a close reading, Stan has already noted several English grammar/syntax points. |
Are there any active members, out of curiosity? I do not know of any nor have seen any around.
I will go through it again later. |
|
|
||
| -------------- | ||
|
|
||
| This module provides classes and convenience functions for compressing and |
There was a problem hiding this comment.
Suggested change
| This module provides classes and convenience functions for compressing and | |
| This module provides classes and functions for compressing and |
Unnecessary and awkward
| 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 |
There was a problem hiding this comment.
Suggested change
| files created from the :program:`zstd` utility, as well as raw zstd compressed | |
| files created with the :program:`zstd` utility, as well as raw zstd compressed |
Suggested change
| files created from the :program:`zstd` utility, as well as raw zstd compressed | |
| files created by the :program:`zstd` utility, as well as raw zstd compressed |
Grammar
| -------------- | ||
|
|
||
| This module provides classes and convenience functions for compressing and | ||
| decompressing data using the Zstandard (or "zstd") compression algorithm. Also |
There was a problem hiding this comment.
Suggested change
| decompressing data using the Zstandard (or "zstd") compression algorithm. Also | |
| decompressing data using the Zstandard (or *zstd*) compression algorithm. Also |
Italics are more fitting here
|
|
||
| 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`` |
There was a problem hiding this comment.
Suggested change
| included is a file interface supporting reading and writing contents of ``.zst`` | |
| included is a file interface that supports reading and writing the contents of ``.zst`` files. |
| :class:`Strategy` classes for setting advanced (de)compression parameters. | ||
|
|
||
|
|
||
| .. exception:: ZstdError |
There was a problem hiding this comment.
This should get a little introduction like other modules.
"This module provides the following exception: "
Or something along those lines.
| argument should not be used. | ||
|
|
||
| When opening a file for writing, the *options* argument can be a dictionary | ||
| providing advanced decompression parameters, see |
There was a problem hiding this comment.
Suggested change
| providing advanced decompression parameters, see | |
| providing advanced decompression parameters; see |
| *zstd_dict* argument is a :class:`ZstdDict` instance to be used during | ||
| compression. | ||
|
|
||
| For binary mode, this function is equivalent to the :class:`ZstdFile` |
There was a problem hiding this comment.
Suggested change
| 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. | ||
|
|
||
| For text mode, a :class:`ZstdFile` object is created, and wrapped in an |
There was a problem hiding this comment.
Suggested change
| 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 |
|
|
||
| For 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). |
There was a problem hiding this comment.
Suggested change
| behavior, and line ending(s). | |
| behavior, and line endings. |
Unnecessary IMO
|
|
||
| For 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. |
There was a problem hiding this comment.
Suggested change
| *encoding*, *errors* and *newline* parameters must not be provided. | |
| *encoding*, *errors*, and *newline* parameters must not be provided. |
🙋 I at least look at all pings to the group. Will usually weigh in if I have time, and as long as no one else has beaten me to what I'd have to say. |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
This PR adds docs for the
compressionandcompression.zstdmodules.📚 Documentation preview 📚: https://cpython-previews--133911.org.readthedocs.build/