gh-146431: Add the wrapcol and ignorechars parameters for more Base XX codec

Add the wrapcol parameter to base64 functions b16encode(), b32encode(),
b32hexencode(), b85encode() and z85encode(), and binascii functions
b2a_base32() and b2a_base85().

Add the ignorechars parameter to base64 functions b16decode(), b32decode(),
b32hexdecode(), b85decode() and z85decode(), and binascii functions
a2b_hex(), unhexlify(), a2b_base32() and a2b_base85().

Author: serhiy-storchaka

Doc/library/base64.rst

@@ -146,13 +146,20 @@ POST request.
       Accepting the ``+`` and ``/`` characters is now deprecated.
 
 
-.. function:: b32encode(s)
+.. function:: b32encode(s, *, wrapcol=0)
 
    Encode the :term:`bytes-like object` *s* using Base32 and return the
    encoded :class:`bytes`.
 
+   If *wrapcol* is non-zero, insert a newline (``b'\n'``) character
+   after at most every *wrapcol* characters.
+   If *wrapcol* is zero (default), do not add any newlines.
+
+   .. versionchanged:: next
+      Added the *wrapcol* parameter.
+
 
-.. function:: b32decode(s, casefold=False, map01=None)
+.. function:: b32decode(s, casefold=False, map01=None, *, ignorechars=b'')
 
    Decode the Base32 encoded :term:`bytes-like object` or ASCII string *s* and
    return the decoded :class:`bytes`.
@@ -168,20 +175,29 @@ POST request.
    digit 0 is always mapped to the letter O).  For security purposes the default is
    ``None``, so that 0 and 1 are not allowed in the input.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+
    A :exc:`binascii.Error` is raised if *s* is
    incorrectly padded or if there are non-alphabet characters present in the
    input.
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
 
-.. function:: b32hexencode(s)
+.. function:: b32hexencode(s, *, wrapcol=0)
 
    Similar to :func:`b32encode` but uses the Extended Hex Alphabet, as defined in
    :rfc:`4648`.
 
    .. versionadded:: 3.10
 
+   .. versionchanged:: next
+      Added the *wrapcol* parameter.
+
 
-.. function:: b32hexdecode(s, casefold=False)
+.. function:: b32hexdecode(s, casefold=False, *, ignorechars=b'')
 
    Similar to :func:`b32decode` but uses the Extended Hex Alphabet, as defined in
    :rfc:`4648`.
@@ -193,14 +209,24 @@ POST request.
 
    .. versionadded:: 3.10
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
 
-.. function:: b16encode(s)
+.. function:: b16encode(s, *, wrapcol=0)
 
    Encode the :term:`bytes-like object` *s* using Base16 and return the
    encoded :class:`bytes`.
 
+   If *wrapcol* is non-zero, insert a newline (``b'\n'``) character
+   after at most every *wrapcol* characters.
+   If *wrapcol* is zero (default), do not add any newlines.
+
+   .. versionchanged:: next
+      Added the *wrapcol* parameter.
 
-.. function:: b16decode(s, casefold=False)
+
+.. function:: b16decode(s, casefold=False, *, ignorechars=b'')
 
    Decode the Base16 encoded :term:`bytes-like object` or ASCII string *s* and
    return the decoded :class:`bytes`.
@@ -209,10 +235,17 @@ POST request.
    lowercase alphabet is acceptable as input.  For security purposes, the default
    is ``False``.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+
    A :exc:`binascii.Error` is raised if *s* is
    incorrectly padded or if there are non-alphabet characters present in the
    input.
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
+
 .. _base64-base-85:
 
 Base85 Encodings
@@ -277,27 +310,40 @@ Refer to the documentation of the individual functions for more information.
    .. versionadded:: 3.4
 
 
-.. function:: b85encode(b, pad=False)
+.. function:: b85encode(b, pad=False, *, wrapcol=0)
 
    Encode the :term:`bytes-like object` *b* using base85 (as used in e.g.
    git-style binary diffs) and return the encoded :class:`bytes`.
 
    If *pad* is true, the input is padded with ``b'\0'`` so its length is a
    multiple of 4 bytes before encoding.
 
+   If *wrapcol* is non-zero, insert a newline (``b'\n'``) character
+   after at most every *wrapcol* characters.
+   If *wrapcol* is zero (default), do not add any newlines.
+
    .. versionadded:: 3.4
 
+   .. versionchanged:: next
+      Added the *wrapcol* parameter.
 
-.. function:: b85decode(b)
+
+.. function:: b85decode(b, *, ignorechars=b'')
 
    Decode the base85-encoded :term:`bytes-like object` or ASCII string *b* and
    return the decoded :class:`bytes`.  Padding is implicitly removed, if
    necessary.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+
    .. versionadded:: 3.4
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
 
-.. function:: z85encode(s, pad=False)
+.. function:: z85encode(s, pad=False, *, wrapcol=0)
 
    Encode the :term:`bytes-like object` *s* using Z85 (as used in ZeroMQ)
    and return the encoded :class:`bytes`.  See `Z85  specification
@@ -306,20 +352,33 @@ Refer to the documentation of the individual functions for more information.
    If *pad* is true, the input is padded with ``b'\0'`` so its length is a
    multiple of 4 bytes before encoding.
 
+   If *wrapcol* is non-zero, insert a newline (``b'\n'``) character
+   after at most every *wrapcol* characters.
+   If *wrapcol* is zero (default), do not add any newlines.
+
    .. versionadded:: 3.13
 
    .. versionchanged:: 3.15
       The *pad* parameter was added.
 
+   .. versionchanged:: next
+      Added the *wrapcol* parameter.
+
 
-.. function:: z85decode(s)
+.. function:: z85decode(s, *, ignorechars=b'')
 
    Decode the Z85-encoded :term:`bytes-like object` or ASCII string *s* and
    return the decoded :class:`bytes`.  See `Z85  specification
    <https://rfc.zeromq.org/spec/32/>`_ for more information.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+
    .. versionadded:: 3.13
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
 
 .. _base64-legacy:
 

Doc/library/binascii.rst

@@ -101,7 +101,7 @@ The :mod:`!binascii` module defines the following functions:
       Added the *alphabet* and *wrapcol* parameters.
 
 
-.. function:: a2b_ascii85(string, /, *, foldspaces=False, adobe=False, ignorechars=b"")
+.. function:: a2b_ascii85(string, /, *, foldspaces=False, adobe=False, ignorechars=b'')
 
    Convert Ascii85 data back to binary and return the binary data.
 
@@ -151,7 +151,7 @@ The :mod:`!binascii` module defines the following functions:
    .. versionadded:: 3.15
 
 
-.. function:: a2b_base85(string, /, *, alphabet=BASE85_ALPHABET)
+.. function:: a2b_base85(string, /, *, alphabet=BASE85_ALPHABET, ignorechars=b'')
 
    Convert Base85 data back to binary and return the binary data.
    More than one line may be passed at a time.
@@ -164,26 +164,33 @@ The :mod:`!binascii` module defines the following functions:
    Optional *alphabet* must be a :class:`bytes` object of length 85 which
    specifies an alternative alphabet.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+
    Invalid Base85 data will raise :exc:`binascii.Error`.
 
    .. versionadded:: 3.15
 
 
-.. function:: b2a_base85(data, /, *, alphabet=BASE85_ALPHABET, pad=False)
+.. function:: b2a_base85(data, /, *, alphabet=BASE85_ALPHABET, wrapcol=0, pad=False)
 
    Convert binary data to a line of ASCII characters in Base85 coding.
    The return value is the converted line.
 
    Optional *alphabet* must be a :term:`bytes-like object` of length 85 which
    specifies an alternative alphabet.
 
+   If *wrapcol* is non-zero, insert a newline (``b'\n'``) character
+   after at most every *wrapcol* characters.
+   If *wrapcol* is zero (default), do not insert any newlines.
+
    If *pad* is true, the input is padded with ``b'\0'`` so its length is a
    multiple of 4 bytes before encoding.
 
    .. versionadded:: 3.15
 
 
-.. function:: a2b_base32(string, /, *, alphabet=BASE32_ALPHABET)
+.. function:: a2b_base32(string, /, *, alphabet=BASE32_ALPHABET, ignorechars=b'')
 
    Convert base32 data back to binary and return the binary data.
 
@@ -201,18 +208,28 @@ The :mod:`!binascii` module defines the following functions:
    Optional *alphabet* must be a :class:`bytes` object of length 32 which
    specifies an alternative alphabet.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+   If *ignorechars* contains the pad character ``'='``,  the pad characters
+   presented before the end of the encoded data and the excess pad characters
+   will be ignored.
+
    Invalid base32 data will raise :exc:`binascii.Error`.
 
    .. versionadded:: next
 
-.. function:: b2a_base32(data, /, *, alphabet=BASE32_ALPHABET)
+.. function:: b2a_base32(data, /, *, alphabet=BASE32_ALPHABET, wrapcol=0)
 
    Convert binary data to a line of ASCII characters in base32 coding,
    as specified in :rfc:`4648`. The return value is the converted line.
 
    Optional *alphabet* must be a :term:`bytes-like object` of length 32 which
    specifies an alternative alphabet.
 
+   If *wrapcol* is non-zero, insert a newline (``b'\n'``) character
+   after at most every *wrapcol* characters.
+   If *wrapcol* is zero (default), do not insert any newlines.
+
    .. versionadded:: next
 
 .. function:: a2b_qp(data, header=False)
@@ -288,18 +305,25 @@ The :mod:`!binascii` module defines the following functions:
    .. versionchanged:: 3.8
       The *sep* and *bytes_per_sep* parameters were added.
 
-.. function:: a2b_hex(hexstr)
-              unhexlify(hexstr)
+.. function:: a2b_hex(hexstr, *, ignorechars=b'')
+              unhexlify(hexstr, *, ignorechars=b'')
 
    Return the binary data represented by the hexadecimal string *hexstr*.  This
    function is the inverse of :func:`b2a_hex`. *hexstr* must contain an even number
    of hexadecimal digits (which can be upper or lower case), otherwise an
    :exc:`Error` exception is raised.
 
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+
    Similar functionality (accepting only text string arguments, but more
    liberal towards whitespace) is also accessible using the
    :meth:`bytes.fromhex` class method.
 
+   .. versionchanged:: next
+      Added the *ignorechars* parameter.
+
+
 .. exception:: Error
 
    Exception raised on errors. These are usually programming errors.

Doc/whatsnew/3.15.rst

@@ -635,16 +635,28 @@ base64
 * Added the *pad* parameter in :func:`~base64.z85encode`.
   (Contributed by Hauke Dämpfling in :gh:`143103`.)
 
-* Added the *wrapcol* parameter in :func:`~base64.b64encode`.
-  (Contributed by Serhiy Storchaka in :gh:`143214`.)
+* Added the *wrapcol* parameter in :func:`~base64.b16encode`,
+  :func:`~base64.b32encode`, :func:`~base64.b32hexencode`,
+  :func:`~base64.b64encode`, :func:`~base64.b85encode`, and
+  :func:`~base64.z85encode`.
+  (Contributed by Serhiy Storchaka in :gh:`143214` and :gh:`xxxxxx`.)
 
-* Added the *ignorechars* parameter in :func:`~base64.b64decode`.
-  (Contributed by Serhiy Storchaka in :gh:`144001`.)
+* Added the *ignorechars* parameter in :func:`~base64.b16decode`,
+  :func:`~base64.b32decode`,  :func:`~base64.b32hexdecode`,
+  :func:`~base64.b64decode`, :func:`~base64.b85decode`, and
+  :func:`~base64.z85decode`.
+  (Contributed by Serhiy Storchaka in :gh:`144001` and :gh:`xxxxxx`.)
 
 
 binascii
 --------
 
+* Added functions for Base32 encoding:
+
+  - :func:`~binascii.b2a_base32` and :func:`~binascii.a2b_base32`
+
+  (Contributed by James Seo in :gh:`146192`.)
+
 * Added functions for Ascii85, Base85, and Z85 encoding:
 
   - :func:`~binascii.b2a_ascii85` and :func:`~binascii.a2b_ascii85`
@@ -659,14 +671,9 @@ binascii
   :func:`~binascii.a2b_base64`.
   (Contributed by Serhiy Storchaka in :gh:`145980`.)
 
-* Added the *ignorechars* parameter in :func:`~binascii.a2b_base64`.
-  (Contributed by Serhiy Storchaka in :gh:`144001`.)
-
-* Added functions for Base32 encoding:
-
-  - :func:`~binascii.b2a_base32` and :func:`~binascii.a2b_base32`
-
-  (Contributed by James Seo in :gh:`146192`.)
+* Added the *ignorechars* parameter in :func:`~binascii.a2b_hex`,
+  :func:`~binascii.unhexlify`, and :func:`~binascii.a2b_base64`.
+  (Contributed by Serhiy Storchaka in :gh:`144001` and :gh:`xxxxxx`.)
 
 
 calendar