gh-101178: Add Ascii85, Base85, and Z85 support to binascii (GH-102753)

Add Ascii85, Base85, and Z85 encoders and decoders to binascii,
replacing the existing pure Python implementations in base64.

This makes the codecs two orders of magnitude faster and consume
two orders of magnitude less memory.

Note that attempting to decode Ascii85 or Base85 data of length 1 mod 5
(after accounting for Ascii85 quirks) now produces an error, as no
encoder would emit such data. This should be the only significant
externally visible difference compared to the old implementation.

Co-authored-by: Serhiy Storchaka <storchaka@gmail.com>

Author: kangtastic

Doc/library/base64.rst

@@ -247,8 +247,9 @@ Refer to the documentation of the individual functions for more information.
    after at most every *wrapcol* characters.
    If *wrapcol* is zero (default), do not insert any newlines.
 
-   *pad* controls whether the input is padded to a multiple of 4
-   before encoding. Note that the ``btoa`` implementation always pads.
+   If *pad* is true, the input is padded with ``b'\0'`` so its length is a
+   multiple of 4 bytes before encoding.
+   Note that the ``btoa`` implementation always pads.
 
    *adobe* controls whether the encoded byte sequence is framed with ``<~``
    and ``~>``, which is used by the Adobe implementation.
@@ -268,8 +269,9 @@ Refer to the documentation of the individual functions for more information.
    *adobe* controls whether the input sequence is in Adobe Ascii85 format
    (i.e. is framed with <~ and ~>).
 
-   *ignorechars* should be a byte string containing characters to ignore
-   from the input. This should only contain whitespace characters, and by
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+   This should only contain whitespace characters, and by
    default contains all whitespace characters in ASCII.
 
    .. versionadded:: 3.4

Doc/library/binascii.rst

@@ -98,6 +98,112 @@ The :mod:`!binascii` module defines the following functions:
       Added the *wrapcol* parameter.
 
 
+.. function:: a2b_ascii85(string, /, *, foldspaces=False, adobe=False, ignorechars=b"")
+
+   Convert Ascii85 data back to binary and return the binary data.
+
+   Valid Ascii85 data contains characters from the Ascii85 alphabet in groups
+   of five (except for the final group, which may have from two to five
+   characters). Each group encodes 32 bits of binary data in the range from
+   ``0`` to ``2 ** 32 - 1``, inclusive. The special character ``z`` is
+   accepted as a short form of the group ``!!!!!``, which encodes four
+   consecutive null bytes.
+
+   *foldspaces* is a flag that specifies whether the 'y' short sequence
+   should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20).
+   This feature is not supported by the "standard" Ascii85 encoding.
+
+   *adobe* controls whether the input sequence is in Adobe Ascii85 format
+   (i.e. is framed with <~ and ~>).
+
+   *ignorechars* should be a :term:`bytes-like object` containing characters
+   to ignore from the input.
+   This should only contain whitespace characters.
+
+   Invalid Ascii85 data will raise :exc:`binascii.Error`.
+
+   .. versionadded:: next
+
+
+.. function:: b2a_ascii85(data, /, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)
+
+   Convert binary data to a formatted sequence of ASCII characters in Ascii85
+   coding. The return value is the converted data.
+
+   *foldspaces* is an optional flag that uses the special short sequence 'y'
+   instead of 4 consecutive spaces (ASCII 0x20) as supported by 'btoa'. This
+   feature is not supported by the "standard" Ascii85 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 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.
+   Note that the ``btoa`` implementation always pads.
+
+   *adobe* controls whether the encoded byte sequence is framed with ``<~``
+   and ``~>``, which is used by the Adobe implementation.
+
+   .. versionadded:: next
+
+
+.. function:: a2b_base85(string, /)
+
+   Convert Base85 data back to binary and return the binary data.
+   More than one line may be passed at a time.
+
+   Valid Base85 data contains characters from the Base85 alphabet in groups
+   of five (except for the final group, which may have from two to five
+   characters). Each group encodes 32 bits of binary data in the range from
+   ``0`` to ``2 ** 32 - 1``, inclusive.
+
+   Invalid Base85 data will raise :exc:`binascii.Error`.
+
+   .. versionadded:: next
+
+
+.. function:: b2a_base85(data, /, *, pad=False)
+
+   Convert binary data to a line of ASCII characters in Base85 coding.
+   The return value is the converted line.
+
+   If *pad* is true, the input is padded with ``b'\0'`` so its length is a
+   multiple of 4 bytes before encoding.
+
+   .. versionadded:: next
+
+
+.. function:: a2b_z85(string, /)
+
+   Convert Z85 data back to binary and return the binary data.
+   More than one line may be passed at a time.
+
+   Valid Z85 data contains characters from the Z85 alphabet in groups
+   of five (except for the final group, which may have from two to five
+   characters). Each group encodes 32 bits of binary data in the range from
+   ``0`` to ``2 ** 32 - 1``, inclusive.
+
+   See `Z85 specification <https://rfc.zeromq.org/spec/32/>`_ for more information.
+
+   Invalid Z85 data will raise :exc:`binascii.Error`.
+
+   .. versionadded:: next
+
+
+.. function:: b2a_z85(data, /, *, pad=False)
+
+   Convert binary data to a line of ASCII characters in Z85 coding.
+   The return value is the converted line.
+
+   If *pad* is true, the input is padded with ``b'\0'`` so its length is a
+   multiple of 4 bytes before encoding.
+
+   See `Z85 specification <https://rfc.zeromq.org/spec/32/>`_ for more information.
+
+   .. versionadded:: next
+
+
 .. function:: a2b_qp(data, header=False)
 
    Convert a block of quoted-printable data back to binary and return the binary

Doc/whatsnew/3.15.rst

@@ -491,6 +491,14 @@ base64
 binascii
 --------
 
+* Added functions for Ascii85, Base85, and Z85 encoding:
+
+  - :func:`~binascii.b2a_ascii85` and :func:`~binascii.a2b_ascii85`
+  - :func:`~binascii.b2a_base85` and :func:`~binascii.a2b_base85`
+  - :func:`~binascii.b2a_z85` and :func:`~binascii.a2b_z85`
+
+  (Contributed by James Seo and Serhiy Storchaka in :gh:`101178`.)
+
 * Added the *wrapcol* parameter in :func:`~binascii.b2a_base64`.
   (Contributed by Serhiy Storchaka in :gh:`143214`.)
 
@@ -1059,6 +1067,11 @@ base64 & binascii
   faster thanks to simple CPU pipelining optimizations.
   (Contributed by Gregory P. Smith and Serhiy Storchaka in :gh:`143262`.)
 
+* Implementation for Ascii85, Base85, and Z85 encoding has been rewritten in C.
+  Encoding and decoding is now two orders of magnitude faster and consumes
+  two orders of magnitude less memory.
+  (Contributed by James Seo and Serhiy Storchaka in :gh:`101178`.)
+
 csv
 ---
 

Include/internal/pycore_global_objects_fini_generated.h

@@ -297,6 +297,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(aclose)
         STRUCT_FOR_ID(add)
         STRUCT_FOR_ID(add_done_callback)
+        STRUCT_FOR_ID(adobe)
         STRUCT_FOR_ID(after_in_child)
         STRUCT_FOR_ID(after_in_parent)
         STRUCT_FOR_ID(alias)
@@ -492,6 +493,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(flags)
         STRUCT_FOR_ID(flush)
         STRUCT_FOR_ID(fold)
+        STRUCT_FOR_ID(foldspaces)
         STRUCT_FOR_ID(follow_symlinks)
         STRUCT_FOR_ID(format)
         STRUCT_FOR_ID(format_spec)
@@ -691,6 +693,7 @@ struct _Py_global_strings {
         STRUCT_FOR_ID(outpath)
         STRUCT_FOR_ID(overlapped)
         STRUCT_FOR_ID(owner)
+        STRUCT_FOR_ID(pad)
         STRUCT_FOR_ID(pages)
         STRUCT_FOR_ID(parameter)
         STRUCT_FOR_ID(parent)