Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
serhiy-storchaka wants to merge 1 commit into
base: main
Choose a base branch
from
Open

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

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
79 changes: 69 additions & 10 deletions Doc/library/base64.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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`.
Expand All @@ -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`.
Expand All @@ -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`.
Expand All @@ -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
Expand Down Expand Up @@ -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
Expand All @@ -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:

Expand Down
38 changes: 31 additions & 7 deletions Doc/library/binascii.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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.

Expand Down Expand Up @@ -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.
Expand All @@ -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.

Expand All @@ -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)
Expand Down Expand Up @@ -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.
Expand Down
31 changes: 19 additions & 12 deletions Doc/whatsnew/3.15.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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:`146431`.)

* 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:`146431`.)


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`
Expand All @@ -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:`146431`.)


calendar
Expand Down
Loading
Loading