From f2ba1a4226bf9502f15c51c8aae5047b62b2c197 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 19 May 2025 17:31:25 -0400 Subject: [PATCH 1/9] add additional docs on base-85, refactor --- Doc/library/base64.rst | 52 ++++++++++++++++++++++++++++++++---------- 1 file changed, 40 insertions(+), 12 deletions(-) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index 834ab2536e6c14..55edfdd7ab581e 100644 --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -14,15 +14,9 @@ -------------- This module provides functions for encoding binary data to printable -ASCII characters and decoding such encodings back to binary data. -It provides encoding and decoding functions for the encodings specified in -:rfc:`4648`, which defines the Base16, Base32, and Base64 algorithms, -and for the de-facto standard Ascii85 and Base85 encodings. - -The :rfc:`4648` encodings are suitable for encoding binary data so that it can be -safely sent by email, used as parts of URLs, or included as part of an HTTP -POST request. The encoding algorithm is not the same as the -:program:`uuencode` program. +ASCII characters and decoding such encodings back to binary data, +such as :ref:`those specified in RFC 4648 ` and +:ref:`Base-85 encodings `. There are two interfaces provided by this module. The modern interface supports encoding :term:`bytes-like objects ` to ASCII @@ -30,7 +24,7 @@ supports encoding :term:`bytes-like objects ` to ASCII strings containing ASCII to :class:`bytes`. Both base-64 alphabets defined in :rfc:`4648` (normal, and URL- and filesystem-safe) are supported. -The legacy interface does not support decoding from strings, but it does +The :ref:`legacy interface ` does not support decoding from strings, but it does provide functions for encoding and decoding to and from :term:`file objects `. It only supports the Base64 standard alphabet, and it adds newlines every 76 characters as per :rfc:`2045`. Note that if you are looking @@ -46,7 +40,16 @@ package instead. Any :term:`bytes-like objects ` are now accepted by all encoding and decoding functions in this module. Ascii85/Base85 support added. -The modern interface provides: + +.. _base_64_rfc_4648: + +RFC 4648 Encodings +^^^^^^^^^^^^^^^^^^ + +The :rfc:`4648` encodings are suitable for encoding binary data so that it can be +safely sent by email, used as parts of URLs, or included as part of an HTTP +POST request. The encoding algorithm is not the same as the +:program:`uuencode` program. .. function:: b64encode(s, altchars=None) @@ -181,6 +184,28 @@ The modern interface provides: incorrectly padded or if there are non-alphabet characters present in the input. +.. _base_64_base_85: + +Base 85 Encodings +^^^^^^^^^^^^^^^^^ + +Base-85 encoding is not formally specified. Base-85 encoding is a de facto standard +originating from the ASCII Base-85 Strings encoding defined by the +`PostScript Language `_. + +The Ascii85 and Base85 functions in this module are two implementations of +the de facto standard. Which function you should use depends on how the other +software you use implements the Base-85 encoding. + +The two functions present in this module provide options +to configure the encoding in the following ways: + +* Whether to include enclosing `<~` and `~>` markers +* Whether to include newline characters +* The set of ASCII characters used for encoding +* Handling of null bytes + +Refer to the documentation of the individual functions for more information. .. function:: a85encode(b, *, foldspaces=False, wrapcol=0, pad=False, adobe=False) @@ -262,7 +287,10 @@ The modern interface provides: .. versionadded:: 3.13 -The legacy interface: +.. _base_64_legacy: + +Legacy Interface +^^^^^^^^^^^^^^^^ .. function:: decode(input, output) From 670c08599449cf3b2d544696b1c09ca9c549c6d6 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 19 May 2025 17:44:18 -0400 Subject: [PATCH 2/9] pre-commit --- Doc/library/base64.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index 55edfdd7ab581e..200dd00fa98e69 100644 --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -191,7 +191,7 @@ Base 85 Encodings Base-85 encoding is not formally specified. Base-85 encoding is a de facto standard originating from the ASCII Base-85 Strings encoding defined by the -`PostScript Language `_. +`PostScript Language `_. The Ascii85 and Base85 functions in this module are two implementations of the de facto standard. Which function you should use depends on how the other From b3218df2037af38271c0ca07973b87f2a2d48288 Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 19 May 2025 17:46:23 -0400 Subject: [PATCH 3/9] pre-commit --- Doc/library/base64.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index 200dd00fa98e69..acb2eb0239fdc3 100644 --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -200,7 +200,7 @@ software you use implements the Base-85 encoding. The two functions present in this module provide options to configure the encoding in the following ways: -* Whether to include enclosing `<~` and `~>` markers +* Whether to include enclosing ``<~`` and ``~>`` markers * Whether to include newline characters * The set of ASCII characters used for encoding * Handling of null bytes From e03d1d97bceb1b4b315c8f2773228dacf26cd74f Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 19 May 2025 17:49:05 -0400 Subject: [PATCH 4/9] fix indentation --- Doc/library/base64.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index acb2eb0239fdc3..216900d694812e 100644 --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -44,7 +44,7 @@ package instead. .. _base_64_rfc_4648: RFC 4648 Encodings -^^^^^^^^^^^^^^^^^^ +------------------ The :rfc:`4648` encodings are suitable for encoding binary data so that it can be safely sent by email, used as parts of URLs, or included as part of an HTTP @@ -187,7 +187,7 @@ POST request. The encoding algorithm is not the same as the .. _base_64_base_85: Base 85 Encodings -^^^^^^^^^^^^^^^^^ +----------------- Base-85 encoding is not formally specified. Base-85 encoding is a de facto standard originating from the ASCII Base-85 Strings encoding defined by the @@ -290,7 +290,7 @@ Refer to the documentation of the individual functions for more information. .. _base_64_legacy: Legacy Interface -^^^^^^^^^^^^^^^^ +---------------- .. function:: decode(input, output) From f1424f72f02c4c099f3b9de6e6e170815e701fae Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 19 May 2025 18:04:22 -0400 Subject: [PATCH 5/9] edits --- Doc/library/base64.rst | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index 216900d694812e..c2a37be338991c 100644 --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -189,16 +189,14 @@ POST request. The encoding algorithm is not the same as the Base 85 Encodings ----------------- -Base-85 encoding is not formally specified. Base-85 encoding is a de facto standard -originating from the ASCII Base-85 Strings encoding defined by the -`PostScript Language `_. +Base-85 encoding is not formally specified. Base-85 encoding is a de facto standard, +and different systems perform the encoding differently. The Ascii85 and Base85 functions in this module are two implementations of the de facto standard. Which function you should use depends on how the other software you use implements the Base-85 encoding. -The two functions present in this module provide options -to configure the encoding in the following ways: +The two functions present in this module differ in how they handle the following: * Whether to include enclosing ``<~`` and ``~>`` markers * Whether to include newline characters From e39b5a530d0e58c2e85245a5fea19e1a262672fe Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 19 May 2025 18:21:40 -0400 Subject: [PATCH 6/9] fix base 85 inconsistencies --- Doc/library/base64.rst | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index c2a37be338991c..5dbb80a37352fb 100644 --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -16,7 +16,7 @@ This module provides functions for encoding binary data to printable ASCII characters and decoding such encodings back to binary data, such as :ref:`those specified in RFC 4648 ` and -:ref:`Base-85 encodings `. +:ref:`Base85 encodings `. There are two interfaces provided by this module. The modern interface supports encoding :term:`bytes-like objects ` to ASCII @@ -186,15 +186,15 @@ POST request. The encoding algorithm is not the same as the .. _base_64_base_85: -Base 85 Encodings +Base85 Encodings ----------------- -Base-85 encoding is not formally specified. Base-85 encoding is a de facto standard, +Base85 encoding is not formally specified. Base85 encoding is a de facto standard, and different systems perform the encoding differently. The Ascii85 and Base85 functions in this module are two implementations of the de facto standard. Which function you should use depends on how the other -software you use implements the Base-85 encoding. +software you use implements the Base85 encoding. The two functions present in this module differ in how they handle the following: From fe7323bb736baa2308a99bd532e8a637badc980a Mon Sep 17 00:00:00 2001 From: Aleksander Binion Date: Mon, 19 May 2025 18:27:41 -0400 Subject: [PATCH 7/9] use func --- Doc/library/base64.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index 5dbb80a37352fb..9c2328d390bc7c 100644 --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -192,7 +192,7 @@ Base85 Encodings Base85 encoding is not formally specified. Base85 encoding is a de facto standard, and different systems perform the encoding differently. -The Ascii85 and Base85 functions in this module are two implementations of +The :func:`a85encode` and :func:`b85encode` functions in this module are two implementations of the de facto standard. Which function you should use depends on how the other software you use implements the Base85 encoding. From 3f8726d7e8f048418086d209cbb25dab3be8937c Mon Sep 17 00:00:00 2001 From: Alek Binion Date: Mon, 19 May 2025 19:47:32 -0400 Subject: [PATCH 8/9] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/library/base64.rst | 26 +++++++++++++------------- 1 file changed, 13 insertions(+), 13 deletions(-) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index 9c2328d390bc7c..86854f50ad6975 100644 --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -14,9 +14,10 @@ -------------- This module provides functions for encoding binary data to printable -ASCII characters and decoding such encodings back to binary data, -such as :ref:`those specified in RFC 4648 ` and -:ref:`Base85 encodings `. +ASCII characters and decoding such encodings back to binary data. +This includes the :ref:`encodings specified in ` +:rfc:`4648` (Base64, Base32 and Base16) +and the non-standard :ref:`Base85 encodings `. There are two interfaces provided by this module. The modern interface supports encoding :term:`bytes-like objects ` to ASCII @@ -24,7 +25,7 @@ supports encoding :term:`bytes-like objects ` to ASCII strings containing ASCII to :class:`bytes`. Both base-64 alphabets defined in :rfc:`4648` (normal, and URL- and filesystem-safe) are supported. -The :ref:`legacy interface ` does not support decoding from strings, but it does +The :ref:`legacy interface ` does not support decoding from strings, but it does provide functions for encoding and decoding to and from :term:`file objects `. It only supports the Base64 standard alphabet, and it adds newlines every 76 characters as per :rfc:`2045`. Note that if you are looking @@ -41,15 +42,14 @@ package instead. encoding and decoding functions in this module. Ascii85/Base85 support added. -.. _base_64_rfc_4648: +.. _base64-rfc-4648: RFC 4648 Encodings ------------------ The :rfc:`4648` encodings are suitable for encoding binary data so that it can be safely sent by email, used as parts of URLs, or included as part of an HTTP -POST request. The encoding algorithm is not the same as the -:program:`uuencode` program. +POST request. .. function:: b64encode(s, altchars=None) @@ -184,17 +184,17 @@ POST request. The encoding algorithm is not the same as the incorrectly padded or if there are non-alphabet characters present in the input. -.. _base_64_base_85: +.. _base64-base-85: Base85 Encodings ----------------- -Base85 encoding is not formally specified. Base85 encoding is a de facto standard, -and different systems perform the encoding differently. +Base85 encoding is not formally specified but rather a de facto standard, +thus different systems perform the encoding differently. The :func:`a85encode` and :func:`b85encode` functions in this module are two implementations of -the de facto standard. Which function you should use depends on how the other -software you use implements the Base85 encoding. +the de facto standard. You should call the function with the Base85 +implementation used by the software you intend to work with. The two functions present in this module differ in how they handle the following: @@ -285,7 +285,7 @@ Refer to the documentation of the individual functions for more information. .. versionadded:: 3.13 -.. _base_64_legacy: +.. _base64-legacy: Legacy Interface ---------------- From 713d5c19e3d23dd5cb16ae39cf2bd163668cdf7f Mon Sep 17 00:00:00 2001 From: "C.A.M. Gerlach" Date: Mon, 19 May 2025 18:50:58 -0500 Subject: [PATCH 9/9] Fix RST ref error --- Doc/library/base64.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst index 86854f50ad6975..529a7242443820 100644 --- a/Doc/library/base64.rst +++ b/Doc/library/base64.rst @@ -25,7 +25,7 @@ supports encoding :term:`bytes-like objects ` to ASCII strings containing ASCII to :class:`bytes`. Both base-64 alphabets defined in :rfc:`4648` (normal, and URL- and filesystem-safe) are supported. -The :ref:`legacy interface ` does not support decoding from strings, but it does +The :ref:`legacy interface ` does not support decoding from strings, but it does provide functions for encoding and decoding to and from :term:`file objects `. It only supports the Base64 standard alphabet, and it adds newlines every 76 characters as per :rfc:`2045`. Note that if you are looking