https://github.com/python/cpython/commit/e20f05f53fe6a54435923105329c9de24a10fd2e
commit: e20f05f53fe6a54435923105329c9de24a10fd2e
branch: 3.14
author: Miss Islington (bot) <31488909+miss-isling...@users.noreply.github.com>
committer: CAM-Gerlach <cam.gerl...@gerlach.cam>
date: 2025-05-20T00:05:26Z
summary:
[3.14] gh-134201: Expand explanation of Base85 encodings in base64 docs
(GH-134288) (#134298)
gh-134201: Expand explanation of Base85 encodings in base64 docs (GH-134288)
Explain history of de-facto standard and how to pick between the two Base-85
encoding functions in the base-64 module.
---------
(cherry picked from commit 66aaad61037785639aec393be7618cb54b1372dc)
Co-authored-by: Alek Binion <aleksander.bin...@gmail.com>
Co-authored-by: C.A.M. Gerlach <cam.gerl...@gerlach.cam>
files:
M Doc/library/base64.rst
diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst
index 834ab2536e6c14..529a7242443820 100644
--- a/Doc/library/base64.rst
+++ b/Doc/library/base64.rst
@@ -15,14 +15,9 @@
This module provides functions for encoding binary data to printable
ASCII characters and decoding such encodings back to binary data.
-It provides encoding and decoding functions for the encodings specified in
-:rfc:`4648`, which defines the Base16, Base32, and Base64 algorithms,
-and for the de-facto standard Ascii85 and Base85 encodings.
-
-The :rfc:`4648` encodings are suitable for encoding binary data so that it can
be
-safely sent by email, used as parts of URLs, or included as part of an HTTP
-POST request. The encoding algorithm is not the same as the
-:program:`uuencode` program.
+This includes the :ref:`encodings specified in <base64-rfc-4648>`
+:rfc:`4648` (Base64, Base32 and Base16)
+and the non-standard :ref:`Base85 encodings <base64-base-85>`.
There are two interfaces provided by this module. The modern interface
supports encoding :term:`bytes-like objects <bytes-like object>` to ASCII
@@ -30,7 +25,7 @@ supports encoding :term:`bytes-like objects <bytes-like
object>` to ASCII
strings containing ASCII to :class:`bytes`. Both base-64 alphabets
defined in :rfc:`4648` (normal, and URL- and filesystem-safe) are supported.
-The legacy interface does not support decoding from strings, but it does
+The :ref:`legacy interface <base64-legacy>` does not support decoding from
strings, but it does
provide functions for encoding and decoding to and from :term:`file objects
<file object>`. It only supports the Base64 standard alphabet, and it adds
newlines every 76 characters as per :rfc:`2045`. Note that if you are looking
@@ -46,7 +41,15 @@ package instead.
Any :term:`bytes-like objects <bytes-like object>` are now accepted by all
encoding and decoding functions in this module. Ascii85/Base85 support
added.
-The modern interface provides:
+
+.. _base64-rfc-4648:
+
+RFC 4648 Encodings
+------------------
+
+The :rfc:`4648` encodings are suitable for encoding binary data so that it can
be
+safely sent by email, used as parts of URLs, or included as part of an HTTP
+POST request.
.. function:: b64encode(s, altchars=None)
@@ -181,6 +184,26 @@ The modern interface provides:
incorrectly padded or if there are non-alphabet characters present in the
input.
+.. _base64-base-85:
+
+Base85 Encodings
+-----------------
+
+Base85 encoding is not formally specified but rather a de facto standard,
+thus different systems perform the encoding differently.
+
+The :func:`a85encode` and :func:`b85encode` functions in this module are two
implementations of
+the de facto standard. You should call the function with the Base85
+implementation used by the software you intend to work with.
+
+The two functions present in this module differ in how they handle the
following:
+
+* Whether to include enclosing ``<~`` and ``~>`` markers
+* Whether to include newline characters
+* The set of ASCII characters used for encoding
+* Handling of null bytes
+
+Refer to the documentation of the individual functions for more information.
.. function:: a85encode(b, *, foldspaces=False, wrapcol=0, pad=False,
adobe=False)
@@ -262,7 +285,10 @@ The modern interface provides:
.. versionadded:: 3.13
-The legacy interface:
+.. _base64-legacy:
+
+Legacy Interface
+----------------
.. function:: decode(input, output)
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3/lists/python-checkins.python.org/
Member address: arch...@mail-archive.com
