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. |
🙋 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. |
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 |
There was a problem hiding this comment.
Hm, the library is called zstd, perhaps we should say "in the zstd library"?
Doc/library/compression.zstd.rst
Outdated
| 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.
There was a problem hiding this comment.
Sorry I think the line numbers have changed and Github does not do a good job at showing enough context for your comment, what were you proposing?
|
|
||
| .. 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".
There was a problem hiding this comment.
Hm, I definitely understand "new" may not be the right word here. I worry if we say "a unified interface to ... compression routines" that people will expect compression to hold some high level compress function that abstracts over the various implementations, which is not the case.
Perhaps
"The compression package contains the canonical compression modules containing interfaces to several different algorithms. 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 compression.* import names are encouraged for use where practical."
|
|
||
| .. 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 |
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>
- Rewrite the digested/undigested dict section - Add a section for exceptions - wrap lines to ~80 chars - clarify that an exception is raised if level is passed to a decompressor - make quotes in docs for open vs ZstdFile consistent - Remove currently and repeated "note"
This PR adds docs for the
compressionandcompression.zstdmodules.📚 Documentation preview 📚: https://cpython-previews--133911.org.readthedocs.build/en/133911/library/compression.zstd.html