Docs: Add bz2 usage examples

[bsolomon1124]

• 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

[pitrou]

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

[gpshead]

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]

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:

• the lone >>> could probably be removed, per https://devguide.python.org/documenting/#showing-code-examples
• I'm noticing that the bytestring data has a trailing space. Could probably be removed, but I'll hold off for a second here..

[bsolomon1124]

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

[gpshead]

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.

[gpshead]

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.

[miss-islington]

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

[bedevere-bot]

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

[gpshead]

Thanks for the documentation improvement, always appreciated!

[bsolomon1124]

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