Skip to content

Docs: Add bz2 usage examples#13258

Merged
gpshead merged 9 commits into
python:masterfrom
bsolomon1124:docs-bz2-examples
May 13, 2019
Merged

Docs: Add bz2 usage examples#13258
gpshead merged 9 commits into
python:masterfrom
bsolomon1124:docs-bz2-examples

Conversation

@bsolomon1124

@bsolomon1124 bsolomon1124 commented May 12, 2019

Copy link
Copy Markdown
Contributor
  • Adds an "Examples of usage" section inspired by the one
    found in the gzip docs
  • Corrects the descriptions for compresslevel and data:
    • compresslevel must be an int, not any number. For
      instance, passing a float will raise TypeError
    • Note that data must be bytes-like

@bedevere-bot bedevere-bot added docs Documentation in the Doc dir awaiting review labels May 12, 2019
@csabella csabella requested a review from pitrou May 12, 2019 09:36
pitrou
pitrou reviewed May 12, 2019
View reviewed changes

@pitrou pitrou left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM generally. I'll let someone else review the grammar.

Comment thread Doc/library/bz2.rst Outdated
@bsolomon1124
Docs: Add bz2 usage examples
25bce3d 
- Adds an "Examples of usage" section inspired by the one
  found in the gzip docs
- Corrects the descriptions for ``compresslevel`` and ``data``:
    - ``compresslevel`` must be an `int`, not any number.  For
      instance, passing a float will raise ``TypeError``
    - Notes that `data` must be bytes-like
@gpshead gpshead self-assigned this May 13, 2019
@gpshead

gpshead commented May 13, 2019

Copy link
Copy Markdown
Member

i made an edit that I believe will fix the failing doctest. otherwise this looks good to me. waiting on CI now. as this is just a documentation improvement, no issue or news entry necessary.

@bsolomon1124

bsolomon1124 commented May 13, 2019 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Thanks for having a look @gpshead - two thoughts/questions:

  1. Why might the 502 (bytes written) output make doctests fail? Would this number vary by platform or something like that?
  2. One example that I can be self-critical of is the one with gen_data(): because the data is very random, the compression ratio is actually < 1. (I.e. compression ratio will be much higher for non-random-looking data.) Do you think that this deserves some type of rewrite to a more realistic scenario, or does it still get the point across?

Also:

@bsolomon1124

bsolomon1124 commented May 13, 2019 •
edited
Loading

Copy link
Copy Markdown
Contributor Author

Looks like the build is failing because a "`" is used inside a function docstring. News to me that that wasn't allowed.

Screen Shot 2019-05-12 at 10 01 00 PM

@gpshead

gpshead commented May 13, 2019

Copy link
Copy Markdown
Member

Why might the 502 (bytes written) output make doctests fail?

It was in the wrong place as ... 502 as if it were be entered as a line of code in the interactive session rather than 502 as the result. I could've left it there, but it was an irrelevant detail and would need updating if the data string above were ever changed.

btw, i removed the extra ``s. i just obey whatever sphinx says for this sort of thing.

@bsolomon1124
Remove trailing space from bytestring
8d5a83e 
This modifies the compression ratio by a hair.
@gpshead

gpshead commented May 13, 2019

Copy link
Copy Markdown
Member

One example that I can be self-critical of is the one with gen_data(): because the data is very random, the compression ratio is actually < 1. (I.e. compression ratio will be much higher for non-random-looking data.) Do you think that this deserves some type of rewrite to a more realistic scenario, or does it still get the point across?

heh, true. compressing random data is rather pointless. how about just changing that to yield something else. Even if it just yields chunks of b'z' * chunksize that'd be fine.

@bsolomon1124
Use 'nonrandom' data in compression example
c9475e9 
Compressing random data (low compression ratio) is a
less realistic and less useful example.
@bsolomon1124
Remove empty prompt
1a10b20 
Per https://devguide.python.org/documenting/.
@gpshead gpshead merged commit be6939f into python:master May 13, 2019
@miss-islington

miss-islington commented May 13, 2019

Copy link
Copy Markdown
Contributor

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

miss-islington pushed a commit to miss-islington/cpython that referenced this pull request May 13, 2019
@bsolomon1124 @miss-islington
Docs: Add bz2 usage examples (pythonGH-13258)
7248a03 
* Docs: Add bz2 usage examples

- Adds an "Examples of usage" section inspired by the one
  found in the gzip docs
- Corrects the descriptions for ``compresslevel`` and ``data``:
    - ``compresslevel`` must be an `int`, not any number.  For
      instance, passing a float will raise ``TypeError``
    - Notes that `data` must be bytes-like
(cherry picked from commit be6939f)

Co-authored-by: Brad <brad.solomon.1124@gmail.com>
@bedevere-bot

bedevere-bot commented May 13, 2019

Copy link
Copy Markdown

GH-13294 is a backport of this pull request to the 3.7 branch.

@gpshead

gpshead commented May 13, 2019

Copy link
Copy Markdown
Member

Thanks for the documentation improvement, always appreciated!

@bsolomon1124

bsolomon1124 commented May 13, 2019

Copy link
Copy Markdown
Contributor Author

@gpshead appreciate your guidance. It was a positive experience as my first CPython PR.

@bsolomon1124 bsolomon1124 deleted the docs-bz2-examples branch May 13, 2019 18:30
miss-islington added a commit that referenced this pull request May 13, 2019
@miss-islington @bsolomon1124
Docs: Add bz2 usage examples (GH-13258)
ee9b5ce 
* Docs: Add bz2 usage examples

- Adds an "Examples of usage" section inspired by the one
  found in the gzip docs
- Corrects the descriptions for ``compresslevel`` and ``data``:
    - ``compresslevel`` must be an `int`, not any number.  For
      instance, passing a float will raise ``TypeError``
    - Notes that `data` must be bytes-like
(cherry picked from commit be6939f)

Co-authored-by: Brad <brad.solomon.1124@gmail.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@pitrou pitrou pitrou left review comments

Assignees

@gpshead gpshead

Labels

docs Documentation in the Doc dir skip issue skip news

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

6 participants

@bsolomon1124 @gpshead @miss-islington @bedevere-bot @pitrou @the-knights-who-say-ni