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).
There was a problem hiding this comment.
| Meta's zstd library | |
| the Zstandard library |
| 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
There was a problem hiding this comment.
| overwriting, 'a' for appending, or ``'x'`` for exclusive creation. These can | |
| overwriting, ``'a'`` for appending, or ``'x'`` for exclusive creation. These can |
| :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.
There was a problem hiding this comment.
Both are grammatical with slightly different meanings. "Practical" is more direct clearer.
Practicable: "are encouraged for use where [it could generally be done]"
Practical: "are encouraged for use where [it can actually be done]"
| import names are encouraged for use where practicable. | |
| import names are encouraged for use where practical. |
There was a problem hiding this comment.
I suggested practicable as I think it covers the intent more closely, compare Able to be done or put into practice successfully; feasible (“Practicable, Adj., Sense 1.”) with Of, relating to practice or action, as opposed to speculation or theory. (“Practical, Adj., Sense I.1.a.”), both copyright the Oxford English Dictionary. If both Hugo and Mats prefer changing, though, I have no strong objection.
There was a problem hiding this comment.
I certainly won't raise objections if it stays. I've spent years trying to convince myself to use the "simpler" word in docs when there are a couple of choices, is all it was.
| ============================================================================= | ||
|
|
||
| .. module:: compression.zstd | ||
| :synopsis: Low level interface to compression and decompression routines in |
There was a problem hiding this comment.
| :synopsis: Low level interface to compression and decompression routines in | |
| :synopsis: Low-level interface to compression and decompression routines in |
|
|
||
| .. module:: compression.zstd | ||
| :synopsis: Low level interface to compression and decompression routines in | ||
| Meta's zstd library |
There was a problem hiding this comment.
| Meta's zstd library | |
| the Zstandard library |
| 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.
Both are grammatical with slightly different meanings. "Practical" is more direct clearer.
Practicable: "are encouraged for use where [it could generally be done]"
Practical: "are encouraged for use where [it can actually be done]"
| import names are encouraged for use where practicable. | |
| import names are encouraged for use where practical. |
| 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.
| overwriting, 'a' for appending, or ``'x'`` for exclusive creation. These can | |
| overwriting, ``'a'`` for appending, or ``'x'`` for exclusive creation. These can |
| The *mode* argument can be either ``"r"`` for reading (default), ``"w"`` for | ||
| overwriting, ``"x"`` for exclusive creation, or ``"a"`` for appending. These | ||
| can equivalently be given as ``"rb"``, ``"wb"``, ``"xb"`` and ``"ab"`` | ||
| respectively. | ||
|
|
||
| If *file* is a file object (rather than an actual file name), a mode of | ||
| ``"w"`` does not truncate the file, and is instead equivalent to ``"a"``. |
There was a problem hiding this comment.
Single quotes were used for open, be consistent one way or the other.
| internally, for use in later calls to :meth:`~.decompress`. | ||
| The returned data should be concatenated with the output of any previous | ||
| calls to :meth:`~.decompress`. |
There was a problem hiding this comment.
| internally, for use in later calls to :meth:`~.decompress`. | |
| The returned data should be concatenated with the output of any previous | |
| calls to :meth:`~.decompress`. | |
| internally, for use in later calls to :meth:`!decompress`. | |
| The returned data should be concatenated with the output of any previous | |
| calls to :meth:`!decompress`. |
|
|
||
| .. note:: | ||
|
|
||
| The meaning of ``0`` for :attr:`ZstdDict.dict_id` is different from |
There was a problem hiding this comment.
| The meaning of ``0`` for :attr:`ZstdDict.dict_id` is different from | |
| The meaning of ``0`` for :attr:`!ZstdDict.dict_id` is different from |
| Minimum size of searched matches. Larger values increase compression and | ||
| decompression speed, but decrease ratio. Note that Zstandard can still | ||
| find matches of smaller size, it just tweaks its search algorithm to look | ||
| for this size and larger. Note that currently, for all strategies |
There was a problem hiding this comment.
Everything in these (versioned) docs should be "currently", no need to say so unless it's changing.
| for this size and larger. Note that currently, for all strategies | |
| for this size and larger. Note that for all strategies |
| Metadata related to a Zstandard frame. There are currently two attributes | ||
| containing metadata related to Zstandard frames. |
There was a problem hiding this comment.
| Metadata related to a Zstandard frame. There are currently two attributes | |
| containing metadata related to Zstandard frames. | |
| Metadata related to a Zstandard frame. There are two attributes | |
| containing metadata related to Zstandard frames. |
Fine to leave a count, but these are often things forgotten when adding a new one :)
| Metadata related to a Zstandard frame. There are currently two attributes | |
| containing metadata related to Zstandard frames. | |
| Metadata related to a Zstandard frame. Here are the attributes | |
| containing metadata related to Zstandard frames. |
Or perhaps remove altogether:
| Metadata related to a Zstandard frame. There are currently two attributes | |
| containing metadata related to Zstandard frames. | |
| Metadata related to a Zstandard frame. |
|
|
||
| .. attribute:: COMPRESSION_LEVEL_DEFAULT | ||
|
|
||
| The default compression level for Zstandard, currently '3'. |
There was a problem hiding this comment.
| The default compression level for Zstandard, currently '3'. | |
| The default compression level for Zstandard: '3'. |
There was a problem hiding this comment.
| The default compression level for Zstandard, currently '3'. | |
| The default compression level for Zstandard: ``'3'``. |
Since it is the return value, unless it is an integer than this is much better:
| The default compression level for Zstandard, currently '3'. | |
| The default compression level for Zstandard: ``3``. |
This PR adds docs for the
compressionandcompression.zstdmodules.📚 Documentation preview 📚: https://cpython-previews--133911.org.readthedocs.build/en/133911/library/compression.zstd.html