Issue #22088: Clarify base-64 alphabets and which characters are discarded
* There are only two base-64 alphabets defined by the RFCs, not three
* Due to the internal translation, plus (+) and slash (/) are never discarded
* standard_ and urlsafe_b64decode() discard characters as well
diff --git a/Lib/base64.py b/Lib/base64.py
index 844907f..38bc61e 100755
--- a/Lib/base64.py
+++ b/Lib/base64.py
@@ -65,8 +65,9 @@
alternative alphabet used instead of the '+' and '/' characters.
The decoded string is returned. A TypeError is raised if s is
- incorrectly padded. Non-base64-alphabet characters are discarded prior
- to the padding check.
+ incorrectly padded. Characters that are neither in the normal base-64
+ alphabet nor the alternative alphabet are discarded prior to the padding
+ check.
"""
if altchars is not None:
s = s.translate(string.maketrans(altchars[:2], '+/'))
@@ -87,9 +88,10 @@
def standard_b64decode(s):
"""Decode a string encoded with the standard Base64 alphabet.
- s is the string to decode. The decoded string is returned. A TypeError
- is raised if the string is incorrectly padded or if there are non-alphabet
- characters present in the string.
+ Argument s is the string to decode. The decoded string is returned. A
+ TypeError is raised if the string is incorrectly padded. Characters that
+ are not in the standard alphabet are discarded prior to the padding
+ check.
"""
return b64decode(s)
@@ -97,19 +99,20 @@
_urlsafe_decode_translation = string.maketrans(b'-_', b'+/')
def urlsafe_b64encode(s):
- """Encode a string using a url-safe Base64 alphabet.
+ """Encode a string using the URL- and filesystem-safe Base64 alphabet.
- s is the string to encode. The encoded string is returned. The alphabet
- uses '-' instead of '+' and '_' instead of '/'.
+ Argument s is the string to encode. The encoded string is returned. The
+ alphabet uses '-' instead of '+' and '_' instead of '/'.
"""
return b64encode(s).translate(_urlsafe_encode_translation)
def urlsafe_b64decode(s):
- """Decode a string encoded with the standard Base64 alphabet.
+ """Decode a string using the URL- and filesystem-safe Base64 alphabet.
- s is the string to decode. The decoded string is returned. A TypeError
- is raised if the string is incorrectly padded or if there are non-alphabet
- characters present in the string.
+ Argument s is the string to decode. The decoded string is returned. A
+ TypeError is raised if the string is incorrectly padded. Characters that
+ are not in the URL-safe base-64 alphabet, and are not a plus '+' or slash
+ '/', are discarded prior to the padding check.
The alphabet uses '-' instead of '+' and '_' instead of '/'.
"""
@@ -267,7 +270,7 @@
a lowercase alphabet is acceptable as input. For security purposes, the
default is False.
- The decoded string is returned. A TypeError is raised if s were
+ The decoded string is returned. A TypeError is raised if s is
incorrectly padded or if there are non-alphabet characters present in the
string.
"""