From: Gregory P. Smith <68491+gpshead@users.noreply.github.com>
Date: Mon, 6 Apr 2026 23:45:13 +0000 (-0700)
Subject: gh-73613: clarify padding= docs in for base64 & binascii modules (GH-148183)
X-Git-Tag: v3.15.0a8~10
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=bac4fee745569ef7f9bbe465c1c7f66856854af2;p=thirdparty%2FPython%2Fcpython.git

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 6e6e5d603e37..40edd60abead 100644
--- 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 4f2edb7eff8a..de5e5766779b 100644
--- 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.