gh-134837: Correct and improve base85 documentation for base64 and binascii modules

[dhdaines]

As noted in the issue there are a few clarifications needed in the "Base85 Encodings" section of the base64 module documentation. Namely:

• Base85 is not a de facto standard, but three actual standards, including one actual April Fool's joke (really!)
• The behaviour of adobe=True was not fully specified, particularly that it raises ValueError on unterminated input
• The behaviour of pad=True was not correctly described - the input is always padded, the question is whether this padding is retained in the output encoding.

Also note that pad=True is required by the ZeroMQ standard, but perhaps ZeroMQ is tolerant of Z85 encoded data that isn't a multiple of 5 bytes.

• Issue: Clarify base64.a85(en,de)code documentation for Adobe mode #134837

---

📚 Documentation preview 📚: https://cpython-previews--145843.org.readthedocs.build/

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[github-actions]

This PR is stale because it has been open for 30 days with no activity.

[dhdaines]

Hello! Is there anything that needs to be done to get this PR reviewed?

[sergey-miryanov]

сс @serhiy-storchaka Could you please take a look?

[serhiy-storchaka]

In general, LGTM. Thank you @dhdaines for your contribution.

Please look also at binascii.rst. It also contains documentation for Base85 related functions, mostly copied from base64.rst.

And since you updated documentation for some parameters, I think that docstrings for base64 and binascii functions also may need updates. Docstrings should not be as verbose as the main documentation, but they should be consistent with it.

[dhdaines]

Please look also at binascii.rst. It also contains documentation for Base85 related functions, mostly copied from base64.rst.

Good, yes, I will make sure that they are in agreement.

And since you updated documentation for some parameters, I think that docstrings for base64 and binascii functions also may need updates. Docstrings should not be as verbose as the main documentation, but they should be consistent with it.

Oh! Thanks for the reminder - I will update the relevant docstrings, since the whole reason for this PR is that some functions didn't behave as documented.

[read-the-docs-community]

Documentation build overview

📚 cpython-previews | 🛠️ Build #32661268 | 📁 Comparing 2dd732b against main (f5fb491)

  🔍 Preview build  

14 files changed · ± 14 modified

± Modified

• deprecations/index.html
• deprecations/pending-removal-in-3.16.html
• library/base64.html
• library/binascii.html
• library/mimetypes.html
• library/sys.html
• using/cmdline.html
• whatsnew/3.12.html
• whatsnew/3.13.html
• whatsnew/3.14.html
• and 4 more...

[dhdaines]

Everything should be good now! I've updated the docstrings for both base64 and binascii, as well as the documentation for binascii.

[serhiy-storchaka]

LGTM. 👍 I have only one question.

[miss-islington-app]

Thanks @dhdaines for the PR, and @serhiy-storchaka for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14, 3.15.
🐍🍒⛏🤖

[miss-islington-app]

Sorry, @dhdaines and @serhiy-storchaka, I could not cleanly backport this to 3.14 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker e667d62f114b54dcba17bdfad3835b9c91fda348 3.14

[bedevere-app]

GH-149742 is a backport of this pull request to the 3.15 branch.

[bedevere-app]

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