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

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

syntactic review

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

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>

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

@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.

@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>

@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.

@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"

Looking pretty good now.

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

Besides some nitpicks, LGTM.

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

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

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

Add documentation for compression.zstd

49d9c30

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

bedevere-app Bot mentioned this pull request May 12, 2025

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

Closed

13 tasks

bedevere-app Bot added the awaiting review label May 12, 2025

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

github-project-automation Bot 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 thread Doc/library/compression.zstd.rst Outdated

mwichmann reviewed May 12, 2025

View reviewed changes

hugovk reviewed May 13, 2025

View reviewed changes

emmatyping and 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 thread Doc/library/compression.zstd.rst

Comment thread Doc/library/compression.zstd.rst Outdated

Comment thread Doc/library/compression.zstd.rst Outdated

Comment thread Doc/library/compression.zstd.rst Outdated

brainwane reviewed May 19, 2025

View reviewed changes

Comment thread Doc/library/compression.zstd.rst Outdated

Comment thread Doc/library/compression.zstd.rst Outdated

Comment thread Doc/library/compression.zstd.rst Outdated

Comment thread Doc/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

emmatyping and 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-app Bot 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:main May 21, 2025

bedevere-app Bot removed the awaiting merge label May 21, 2025

bedevere-app Bot 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

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

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

Uh oh!

Uh oh!

gh-132983: Add documentation for compression.zstd - #133911

gh-132983: Add documentation for compression.zstd#133911gpshead merged 23 commits intopython:mainpython/cpython:mainfrom emmatyping:zstd-docsemmatyping/cpython:zstd-docsCopy head branch name to clipboard

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!

gh-132983: Add documentation for compression.zstd#133911
gpshead merged 23 commits into
python:mainfrom
emmatyping:zstd-docs

emmatyping commented May 12, 2025 •
edited by hugovk
Loading

emmatyping May 21, 2025 •
edited
Loading