gh-132983: Add documentation for compression.zstd #133911
Conversation
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. |
| :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.
🙋 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. |
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
I use one for items within a class, two for at the module level, but that's probably too complicated and I should probably just choose two lines. |
| 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 |
There was a problem hiding this comment.
| 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 | |
| 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 |
I may have introduced that one in a suggestion, this also needs to be wrapped I presume. (It would be handy if github provided a ruler in their diff viewer.)
There was a problem hiding this comment.
"files, files" doesn't seem a comfortable sequence.
There are, but we don't get explicitly called on very often, it seems... |
|
|
||
| .. module:: compression.zstd | ||
| :synopsis: Low level interface to compression and decompression routines in | ||
| Meta's zstd library |
There was a problem hiding this comment.
Wouldn't call out Meta here. The reference manual for the zstd itself doesn't mention a company name. On the other hand, it might not be a bad idea to reference that manual somewhere (https://facebook.github.io/zstd/zstd_manual.html).
| 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 |
There was a problem hiding this comment.
"files, files" doesn't seem a comfortable sequence.
| 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 |
There was a problem hiding this comment.
markup on append mode is inconsistent
| :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. |
There was a problem hiding this comment.
This may end up being an implementation question: if it "should not be used", does that mean it's ignored for reading (if so, perhaps say so)? Or does it cause problems if specified?
| When opening a file for reading, the *options* argument can be a dictionary | ||
| providing advanced decompression parameters, see | ||
| :class:`DecompressionParameter` for detailed information about supported | ||
| parameters. The *zstd_dict* argument is a :class:`ZstdDict` instance to be |
There was a problem hiding this comment.
Couldn't lines 59-62, 66-69, 102-105 and 109-112 be combined into a single clause, leaving only the specifics for reading and writing as unique? At the very least, four of these clauses in a short space seems a lot, two may be okay.
|
|
||
| .. attention:: | ||
|
|
||
| The :mod:`!compression` package is the new location for the data compression |
There was a problem hiding this comment.
"New" always seems such a temporal term. I'm just spitballing here, but how about something like: "The compression package provides a unified interface to several data compression routines. Some of these have historically been available as separate modules; those will continue to be available under their original names for compatibility reasons, and will not be removed without a deprecation cycle".
| The :mod:`!compression` package is the new location for the data compression | ||
| modules in the standard library, listed below. The existing modules are not | ||
| deprecated and will not be removed before Python 3.19. The new ``compression.*`` | ||
| import names are encouraged for use where practicable. |
There was a problem hiding this comment.
practicable is grammatically correct, no? I think it’s fine.
This PR adds docs for the
compressionandcompression.zstdmodules.📚 Documentation preview 📚: https://cpython-previews--133911.org.readthedocs.build/en/133911/library/compression.zstd.html