gh-132983: Add documentation for compression.zstd by emmatyping · Pull Request #133911 · python/cpython

emmatyping · 2025-05-12T02:47:40Z

This PR adds docs for the compression and compression.zstd modules.

Issue: Implement PEP 784 - Adding Zstandard to the Python standard library #132983

📚 Documentation preview 📚: https://cpython-previews--133911.org.readthedocs.build/en/133911/library/compression.zstd.html

AA-Turner

syntactic review

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

StanFromIreland

Some grammar notes.

Code block directives need a line after.

Please settle on gaps between descriptions for the file, currently it seems random, some parts use two and others one.

Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

AA-Turner · 2025-05-12T19:14:22Z

cc @python/proofreaders, I think the text here could benefit from a close reading, Stan has already noted several English grammar/syntax points.

StanFromIreland · 2025-05-12T19:21:15Z

@python/proofreaders

Are there any active members, out of curiosity? I do not know of any nor have seen any around.

I think the text here could benefit from a close reading

I will go through it again later.

bskinn · 2025-05-12T19:39:17Z

@python/proofreaders
Are there any active members, out of curiosity? I do not know of any nor have seen any around.

🙋

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>

emmatyping · 2025-05-12T20:04:09Z

@StanFromIreland

Please settle on gaps between descriptions for the file, currently it seems random, some parts use two and others one.

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.

mwichmann · 2025-05-12T22:54:53Z

@python/proofreaders
Are there any active members, out of curiosity? I do not know of any nor have seen any around.

There are, but we don't get explicitly called on very often, it seems...

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"

StanFromIreland

Looking pretty good now.

brainwane

I wasn't absolutely thorough in reviewing all the proposed text, but have a few suggestions for clarification. Thanks for the work.

Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Sumana Harihareswara <sh@changeset.nyc>

Co-authored-by: Martin Panter <vadmium@users.noreply.github.com>

- improve argument descriptions - improve clarity about the meaning of parameter value 0s - clarify behavior of compress/flush - many more clarifications/wording improvements

serhiy-storchaka

Besides some nitpicks, LGTM.

serhiy-storchaka · 2025-05-21T10:14:28Z

+ decompression, passing a digested dictionary will reduce the overhead of
+ loading the dictionary.
+
+ .. list-table:: Difference for compression


I think that simple nested item lists would look better here. Maybe not even nested item lists, just an item lists with two or three paragraphs in every item.

Sorry, I'm not sure I understand what you have in mind, perhaps it can be resolved in a follow-up?

- Use "integer" instead of "int object" - Use > 0 rather than >=1 for nb_workers

miss-islington-app · 2025-05-21T14:18:24Z

Thanks @emmatyping for the PR, and @gpshead for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

) Add documentation for compression & compression.zstd. 🎉 --------- (cherry picked from commit d862b6d) Co-authored-by: Emma Smith <emma@emmatyping.dev> Co-authored-by: Adam Turner <9087854+AA-Turner@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> Co-authored-by: Sumana Harihareswara <sh@changeset.nyc> Co-authored-by: Martin Panter <vadmium@users.noreply.github.com>

bedevere-app · 2025-05-21T14:18:37Z

GH-134425 is a backport of this pull request to the 3.14 branch.

…134425) gh-132983: Add documentation for compression.zstd (GH-133911) Add documentation for compression & compression.zstd. 🎉 --------- (cherry picked from commit d862b6d) Co-authored-by: Emma Smith <emma@emmatyping.dev> Co-authored-by: Adam Turner <9087854+AA-Turner@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> Co-authored-by: Sumana Harihareswara <sh@changeset.nyc> Co-authored-by: Martin Panter <vadmium@users.noreply.github.com>

) Add documentation for compression & compression.zstd. 🎉 --------- Co-authored-by: Adam Turner <9087854+AA-Turner@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> Co-authored-by: Sumana Harihareswara <sh@changeset.nyc> Co-authored-by: Martin Panter <vadmium@users.noreply.github.com>

Add documentation for compression.zstd
49d9c30

bedevere-appBot added docs Documentation in the Doc dir skip news labels May 12, 2025

bedevere-appBot mentioned this pull request May 12, 2025
Implement PEP 784 - Adding Zstandard to the Python standard library #132983
Closed
13 tasks

bedevere-appBot added the awaiting review label May 12, 2025

github-project-automationBot added this to Docs PRs May 12, 2025

github-project-automationBot moved this to Todo in Docs PRs May 12, 2025

emmatyping requested review from AA-Turner and gpshead May 12, 2025 02:48

emmatyping added 3 commits May 11, 2025 19:57

Add examples
62ef4dc

Fix camelcase name references
0b154b1

CParameter->CompressionParameter
63f963f

emmatyping added the needs backport to 3.14 bugs and security fixes label May 12, 2025

AA-Turner reviewed May 12, 2025
View reviewed changes

Apply suggestions from AA-Turner
cfe0590
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

StanFromIreland reviewed May 12, 2025
View reviewed changes

Apply suggestions from reviewers
5115b4c
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

StanFromIreland reviewed May 12, 2025
View reviewed changes

Apply suggestions from reviewers
4ab7fd7
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

StanFromIreland reviewed May 12, 2025
View reviewed changes

Comment threadDoc/library/compression.zstd.rst Outdated

mwichmann reviewed May 12, 2025
View reviewed changes

hugovk reviewed May 13, 2025
View reviewed changes

emmatypingand others added 3 commits May 13, 2025 18:40

Apply suggestions from reviewers
5eb5efc
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com>

Don't reference self when referring to items
987bd27
Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

StanFromIreland reviewed May 18, 2025
View reviewed changes

Comment threadDoc/library/compression.zstd.rst
Comment threadDoc/library/compression.zstd.rst Outdated
Comment threadDoc/library/compression.zstd.rst Outdated
Comment threadDoc/library/compression.zstd.rst Outdated

brainwane reviewed May 19, 2025
View reviewed changes

Comment threadDoc/library/compression.zstd.rst Outdated
Comment threadDoc/library/compression.zstd.rst Outdated
Comment threadDoc/library/compression.zstd.rst Outdated
Comment threadDoc/library/compression.zstd.rst Outdated

Apply suggestions from Sumana and Stan
e61e9a1
Co-authored-by: Stan Ulbrych <89152624+StanFromIreland@users.noreply.github.com> Co-authored-by: Sumana Harihareswara <sh@changeset.nyc>

StanFromIreland mentioned this pull request May 19, 2025
gh-132983: Add zstd version info to test.pythoninfo#134230
Merged

vadmium reviewed May 20, 2025
View reviewed changes

emmatypingand others added 5 commits May 20, 2025 12:01

Remove ref to Meta and clean up mode usage
1149832

Apply suggestions from vadmium
71ed7c3
Co-authored-by: Martin Panter <vadmium@users.noreply.github.com>

Many updates to respond to review
2f895dd
- improve argument descriptions - improve clarity about the meaning of parameter value 0s - clarify behavior of compress/flush - many more clarifications/wording improvements

Add examples to (De)compressionParameter
f25e6e7

Add reference to zstd manual and blurb on algorithm
9ff6320

serhiy-storchaka approved these changes May 21, 2025
View reviewed changes

bedevere-appBot added awaiting merge and removed awaiting review labels May 21, 2025

emmatyping added 2 commits May 21, 2025 09:59

Expand on the connection between level and compression_level
daa9df1

Resolve review suggestions
b3fd3cd
- Use "integer" instead of "int object" - Use > 0 rather than >=1 for nb_workers

hugovk approved these changes May 21, 2025
View reviewed changes

gpshead approved these changes May 21, 2025
View reviewed changes

gpshead moved this from Todo to Done in Docs PRs May 21, 2025

gpshead merged commit d862b6d into python:mainMay 21, 2025

bedevere-appBot removed the awaiting merge label May 21, 2025

bedevere-appBot removed the needs backport to 3.14 bugs and security fixes label May 21, 2025

emmatyping deleted the zstd-docs branch May 21, 2025 14:52

Uh oh!

Uh oh!

Conversation

emmatyping commented May 12, 2025• edited by hugovk Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AA-Turner left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

AA-Turner commented May 12, 2025

Uh oh!

StanFromIreland commented May 12, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

bskinn commented May 12, 2025

Uh oh!

emmatyping commented May 12, 2025

Uh oh!

Uh oh!

mwichmann commented May 12, 2025

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

StanFromIreland left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

brainwane left a comment

Choose a reason for hiding this comment

Uh oh!

emmatyping commented May 12, 2025•
edited by hugovk
Loading

emmatypingMay 21, 2025•
edited
Loading