From 93cbb46e964fc077047ee39691ebb325092b4e5d Mon Sep 17 00:00:00 2001 From: "Gregory P. Smith" Date: Mon, 6 Apr 2026 11:13:28 -0700 Subject: [PATCH] gh-73613: clarify padding= docs in for base64 & binascii modules Based on mayeut's comment in https://github.com/python/cpython/pull/147974#discussion_r3038498019. --- Doc/library/base64.rst | 13 +++++++++---- Doc/library/binascii.rst | 7 +++++-- 2 files changed, 14 insertions(+), 6 deletions(-) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index 6e6e5d603e37b1..40edd60abead84 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 4f2edb7eff8a8f..de5e5766779baa 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.