[Python-checkins] cpython (3.5): #1753718: clarify RFC compliance and bytes/string argument types.
r.david.murray
python-checkins at python.org
Wed Dec 23 21:20:21 EST 2015
https://hg.python.org/cpython/rev/105bf5dd93b8
changeset: 99666:105bf5dd93b8
branch: 3.5
parent: 99664:7995a81236b6
user: R David Murray <rdmurray at bitdance.com>
date: Wed Dec 23 21:17:17 2015 -0500
summary:
#1753718: clarify RFC compliance and bytes/string argument types.
Patch includes contributions by Isobel Hooper, incorporating suggestions from
Paul Winkler. Reviewed by Martin Panter.
In addition to accepting the corrections for the RFC compliance wording, I
went through and corrected all the argument and return types, and made the
pattern of how the arguments and return types are documented consistent.
So, this patch also addresses #20782, though I had forgotten about that issue
and its patch.
files:
Doc/library/base64.rst | 128 ++++++++++++++++------------
1 files changed, 71 insertions(+), 57 deletions(-)
diff --git a/Doc/library/base64.rst b/Doc/library/base64.rst
--- a/Doc/library/base64.rst
+++ b/Doc/library/base64.rst
@@ -21,13 +21,19 @@
POST request. The encoding algorithm is not the same as the
:program:`uuencode` program.
-There are two :rfc:`3548` interfaces provided by this module. The modern
-interface supports encoding and decoding ASCII byte string objects using all
-three :rfc:`3548` defined alphabets (normal, URL-safe, and filesystem-safe).
-Additionally, the decoding functions of the modern interface also accept
-Unicode strings containing only ASCII characters. The legacy interface provides
-for encoding and decoding to and from file-like objects as well as byte
-strings, but only using the Base64 standard alphabet.
+There are two interfaces provided by this module. The modern interface
+supports encoding :term:`bytes-like objects <bytes-like object>` to ASCII
+:class:`bytes`, and decoding :term:`bytes-like objects <bytes-like object>` or
+strings containing ASCII to :class:`bytes`. All three :rfc:`3548` defined
+alphabets (normal, URL-safe, and filesystem-safe) are supported.
+
+The legacy interface does not support decoding from strings, but it does
+provide functions for encoding and decoding to and from :term:`file objects
+<file object>`. It only supports the Base64 standard alphabet, and it adds
+newlines every 76 characters as per :rfc:`2045`. Note that if you are looking
+for :rfc:`2045` support you probably want to be looking at the :mod:`email`
+package instead.
+
.. versionchanged:: 3.3
ASCII-only Unicode strings are now accepted by the decoding functions of
@@ -41,26 +47,26 @@
.. function:: b64encode(s, altchars=None)
- Encode a byte string using Base64.
+ Encode the :term:`bytes-like object` *s* using Base64 and return the encoded
+ :class:`bytes`.
- *s* is the string to encode. Optional *altchars* must be a string of at least
+ Optional *altchars* must be a :term:`bytes-like object` of at least
length 2 (additional characters are ignored) which specifies an alternative
alphabet for the ``+`` and ``/`` characters. This allows an application to e.g.
generate URL or filesystem safe Base64 strings. The default is ``None``, for
which the standard Base64 alphabet is used.
- The encoded byte string is returned.
-
.. function:: b64decode(s, altchars=None, validate=False)
- Decode a Base64 encoded byte string.
+ Decode the Base64 encoded :term:`bytes-like object` or ASCII string
+ *s* and return the decoded :class:`bytes`.
- *s* is the byte string to decode. Optional *altchars* must be a string of
+ Optional *altchars* must be a :term:`bytes-like object` or ASCII string of
at least length 2 (additional characters are ignored) which specifies the
alternative alphabet used instead of the ``+`` and ``/`` characters.
- The decoded string is returned. A :exc:`binascii.Error` exception is raised
+ A :exc:`binascii.Error` exception is raised
if *s* is incorrectly padded.
If *validate* is ``False`` (the default), non-base64-alphabet characters are
@@ -71,38 +77,44 @@
.. function:: standard_b64encode(s)
- Encode byte string *s* using the standard Base64 alphabet.
+ Encode :term:`bytes-like object` *s* using the standard Base64 alphabet
+ and return the encoded :class:`bytes`.
.. function:: standard_b64decode(s)
- Decode byte string *s* using the standard Base64 alphabet.
+ Decode :term:`bytes-like object` or ASCII string *s* using the standard
+ Base64 alphabet and return the decoded :class:`bytes`.
.. function:: urlsafe_b64encode(s)
- Encode byte string *s* using a URL-safe alphabet, which substitutes ``-`` instead of
- ``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet. The result
+ Encode :term:`bytes-like object` *s* using a URL-safe alphabet, which
+ substitutes ``-`` instead of ``+`` and ``_`` instead of ``/`` in the
+ standard Base64 alphabet, and return the encoded :class:`bytes`. The result
can still contain ``=``.
.. function:: urlsafe_b64decode(s)
- Decode byte string *s* using a URL-safe alphabet, which substitutes ``-`` instead of
- ``+`` and ``_`` instead of ``/`` in the standard Base64 alphabet.
+ Decode :term:`bytes-like object` or ASCII string *s* using a URL-safe
+ alphabet, which substitutes ``-`` instead of ``+`` and ``_`` instead of
+ ``/`` in the standard Base64 alphabet, and return the decoded
+ :class:`bytes`.
.. function:: b32encode(s)
- Encode a byte string using Base32. *s* is the string to encode. The encoded string
- is returned.
+ Encode the :term:`bytes-like object` *s* using Base32 and return the
+ encoded :class:`bytes`.
.. function:: b32decode(s, casefold=False, map01=None)
- Decode a Base32 encoded byte string.
+ Decode the Base32 encoded :term:`bytes-like object` or ASCII string *s* and
+ return the decoded :class:`bytes`.
- *s* is the byte string to decode. Optional *casefold* is a flag specifying
+ Optional *casefold* is a flag specifying
whether a lowercase alphabet is acceptable as input. For security purposes,
the default is ``False``.
@@ -113,46 +125,45 @@
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.
- The decoded byte string is returned. A :exc:`binascii.Error` is raised if *s* is
+ A :exc:`binascii.Error` is raised if *s* is
incorrectly padded or if there are non-alphabet characters present in the
- string.
+ input.
.. function:: b16encode(s)
- Encode a byte string using Base16.
-
- *s* is the string to encode. The encoded byte string is returned.
+ Encode the :term:`bytes-like object` *s* using Base16 and return the
+ encoded :class:`bytes`.
.. function:: b16decode(s, casefold=False)
- Decode a Base16 encoded byte string.
+ Decode the Base16 encoded :term:`bytes-like object` or ASCII string *s* and
+ return the decoded :class:`bytes`.
- *s* is the string to decode. Optional *casefold* is a flag specifying whether a
+ Optional *casefold* is a flag specifying whether a
lowercase alphabet is acceptable as input. For security purposes, the default
is ``False``.
- The decoded byte string is returned. A :exc:`TypeError` is raised if *s* were
+ A :exc:`TypeError` is raised if *s* is
incorrectly padded or if there are non-alphabet characters present in the
- string.
+ input.
.. function:: a85encode(s, *, foldspaces=False, wrapcol=0, pad=False, adobe=False)
- Encode a byte string using Ascii85.
-
- *s* is the string to encode. The encoded byte string is returned.
+ Encode the :term:`bytes-like object` *s* using Ascii85 and return the
+ encoded :class:`bytes`.
*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.
- *wrapcol* controls whether the output should have newline (``'\n'``)
+ *wrapcol* controls whether the output should have newline (``b'\n'``)
characters added to it. If this is non-zero, each output line will be
at most this many characters long.
- *pad* controls whether the input string is padded to a multiple of 4
+ *pad* controls whether the input is padded to a multiple of 4
before encoding. Note that the ``btoa`` implementation always pads.
*adobe* controls whether the encoded byte sequence is framed with ``<~``
@@ -163,9 +174,8 @@
.. function:: a85decode(s, *, foldspaces=False, adobe=False, ignorechars=b' \\t\\n\\r\\v')
- Decode an Ascii85 encoded byte string.
-
- *s* is the byte string to decode.
+ Decode the Ascii85 encoded :term:`bytes-like object` or ASCII string *s* and
+ return the decoded :class:`bytes`.
*foldspaces* is a flag that specifies whether the 'y' short sequence
should be accepted as shorthand for 4 consecutive spaces (ASCII 0x20).
@@ -174,7 +184,8 @@
*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
+ *ignorechars* should be a :term:`bytes-like object` or ASCII string
+ containing characters to ignore
from the input. This should only contain whitespace characters, and by
default contains all whitespace characters in ASCII.
@@ -183,18 +194,19 @@
.. function:: b85encode(s, pad=False)
- Encode a byte string using base85, as used in e.g. git-style binary
- diffs.
+ Encode the :term:`bytes-like object` *s* 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 "\\0" so its length is a
- multiple of 4 characters before encoding.
+ If *pad* is true, the input is padded with ``b'\0'`` so its length is a
+ multiple of 4 bytes before encoding.
.. versionadded:: 3.4
.. function:: b85decode(b)
- Decode base85-encoded byte string. Padding is implicitly removed, if
+ Decode the base85-encoded :term:`bytes-like object` or ASCII string *b* and
+ return the decoded :class:`bytes`. Padding is implicitly removed, if
necessary.
.. versionadded:: 3.4
@@ -214,15 +226,15 @@
Decode the contents of the binary *input* file and write the resulting binary
data to the *output* file. *input* and *output* must be :term:`file objects
- <file object>`. *input* will be read until ``input.read()`` returns an empty
- bytes object.
+ <file object>`. *input* will be read until ``input.readline()`` returns an
+ empty bytes object.
.. function:: decodebytes(s)
decodestring(s)
- Decode the byte string *s*, which must contain one or more lines of base64
- encoded data, and return a byte string containing the resulting binary data.
+ Decode the :term:`bytes-like object` *s*, which must contain one or more
+ lines of base64 encoded data, and return the decoded :class:`bytes`.
``decodestring`` is a deprecated alias.
.. versionadded:: 3.1
@@ -233,17 +245,19 @@
Encode the contents of the binary *input* file and write the resulting base64
encoded data to the *output* file. *input* and *output* must be :term:`file
objects <file object>`. *input* will be read until ``input.read()`` returns
- an empty bytes object. :func:`encode` returns the encoded data plus a trailing
- newline character (``b'\n'``).
+ an empty bytes object. :func:`encode` inserts a newline character (``b'\n'``)
+ after every 76 bytes of the output, as well as ensuring that the output
+ always ends with a newline, as per :rfc:`2045` (MIME).
.. function:: encodebytes(s)
encodestring(s)
- Encode the byte string *s*, which can contain arbitrary binary data, and
- return a byte string containing one or more lines of base64-encoded data.
- :func:`encodebytes` returns a string containing one or more lines of
- base64-encoded data always including an extra trailing newline (``b'\n'``).
+ Encode the :term:`bytes-like object` *s*, which can contain arbitrary binary
+ data, and return :class:`bytes` containing the base64-encoded data, with newlines
+ (``b'\n'``) inserted after every 76 bytes of output, and ensuring that
+ there is a trailing newline, as per :rfc:`2045` (MIME).
+
``encodestring`` is a deprecated alias.
--
Repository URL: https://hg.python.org/cpython
More information about the Python-checkins
mailing list