pythongh-134201: Expand explanation of Base85 encodings in base64 docs (python#134288)

biniona · CAM-Gerlach · web-flow · commit 66aaad610377 · 2025-05-19T18:59:06.000-05:00
Explain history of de-facto standard and how to pick between the two Base-85 encoding functions in the base-64 module.

---------

Co-authored-by: C.A.M. Gerlach &lt;CAM.Gerlach@Gerlach.CAM&gt;
diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst
@@ -15,22 +15,17 @@
 
 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
 :class:`bytes`, and decoding :term:`bytes-like objects <bytes-like object>` or
 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)
 
