gh-73613: clarify padding= docs in for base64 & binascii modules (GH-148183)

Based on mayeut's comment in https://github.com/python/cpython/pull/147974#discussion_r3038498019.

diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst
index 6e6e5d603e37b17a2519ad2608057c58c8d6c618..40edd60abead84950293345a041d846b16a70b66 100644 (file)
--- a/Doc/library/base64.rst
+++ b/Doc/library/base64.rst
@@ -85,8 +85,11 @@ POST request.
 
    If *padded* is true, the last group of 4 base 64 alphabet characters must
    be padded with the '=' character.
-   If *padded* is false, the '=' character is treated as other non-alphabet
-   characters (depending on the value of *validate* and *ignorechars*).
+   If *padded* is false, padding is neither required nor recognized:
+   the '=' character is not treated as padding but as a non-alphabet
+   character, which means it is silently discarded when *validate* is false,
+   or causes an :exc:`~binascii.Error` when *validate* is true unless
+   b'=' is included in *ignorechars*.
 
    A :exc:`binascii.Error` exception is raised
    if *s* is incorrectly padded.
@@ -194,8 +197,10 @@ POST request.
 
    If *padded* is true, the last group of 8 base 32 alphabet characters must
    be padded with the '=' character.
-   If *padded* is false, the '=' character is treated as other non-alphabet
-   characters (depending on the value of *ignorechars*).
+   If *padded* is false, padding is neither required nor recognized:
+   the '=' character is not treated as padding but as a non-alphabet
+   character, which means it raises an :exc:`~binascii.Error` unless
+   b'=' is included in *ignorechars*.
 
    *ignorechars* should be a :term:`bytes-like object` containing characters
    to ignore from the input.

diff --git a/Doc/library/binascii.rst b/Doc/library/binascii.rst
index 4f2edb7eff8a8f3c11d0452840043fdd95363719..de5e5766779baaaeaa030d6f9215f4cc57205816 100644 (file)
--- a/Doc/library/binascii.rst
+++ b/Doc/library/binascii.rst
@@ -59,8 +59,11 @@ The :mod:`!binascii` module defines the following functions:
 
    If *padded* is true, the last group of 4 base 64 alphabet characters must
    be padded with the '=' character.
-   If *padded* is false, the '=' character is treated as other non-alphabet
-   characters (depending on the value of *strict_mode* and *ignorechars*).
+   If *padded* is false, padding is neither required nor recognized:
+   the '=' character is not treated as padding but as a non-alphabet
+   character, which means it is silently discarded when *strict_mode* is false,
+   or causes an :exc:`~binascii.Error` when *strict_mode* is true unless
+   b'=' is included in *ignorechars*.
 
    If *ignorechars* is specified, it should be a :term:`bytes-like object`
    containing characters to ignore from the input when *strict_mode* is true.