#7475: add (un)transform method to bytes/bytearray and str, add back codecs that can be used with them from Python 2.

2 files changed, 84 insertions, 0 deletions

diff --git a/Doc/library/codecs.rst b/Doc/library/codecs.rst
index dcfc46f..5416d3b 100644
--- a/Doc/library/codecs.rst
+++ b/Doc/library/codecs.rst
@@ -1165,6 +1165,46 @@ particular, the following variants typically exist:
 |                    |         | operand                   |
 +--------------------+---------+---------------------------+
 
+The following codecs provide bytes-to-bytes mappings.  They can be used with
+:meth:`bytes.transform` and :meth:`bytes.untransform`.
+
++--------------------+---------------------------+---------------------------+
+| Codec              | Aliases                   | Purpose                   |
++====================+===========================+===========================+
+| base64_codec       | base64, base-64           | Convert operand to MIME   |
+|                    |                           | base64                    |
++--------------------+---------------------------+---------------------------+
+| bz2_codec          | bz2                       | Compress the operand      |
+|                    |                           | using bz2                 |
++--------------------+---------------------------+---------------------------+
+| hex_codec          | hex                       | Convert operand to        |
+|                    |                           | hexadecimal               |
+|                    |                           | representation, with two  |
+|                    |                           | digits per byte           |
++--------------------+---------------------------+---------------------------+
+| quopri_codec       | quopri, quoted-printable, | Convert operand to MIME   |
+|                    | quotedprintable           | quoted printable          |
++--------------------+---------------------------+---------------------------+
+| uu_codec           | uu                        | Convert the operand using |
+|                    |                           | uuencode                  |
++--------------------+---------------------------+---------------------------+
+| zlib_codec         | zip, zlib                 | Compress the operand      |
+|                    |                           | using gzip                |
++--------------------+---------------------------+---------------------------+
+
+The following codecs provide string-to-string mappings.  They can be used with
+:meth:`str.transform` and :meth:`str.untransform`.
+
++--------------------+---------------------------+---------------------------+
+| Codec              | Aliases                   | Purpose                   |
++====================+===========================+===========================+
+| rot_13             | rot13                     | Returns the Caesar-cypher |
+|                    |                           | encryption of the operand |
++--------------------+---------------------------+---------------------------+
+
+.. versionadded:: 3.2
+   bytes-to-bytes and string-to-string codecs.
+
 
 :mod:`encodings.idna` --- Internationalized Domain Names in Applications
 ------------------------------------------------------------------------
diff --git a/Doc/library/stdtypes.rst b/Doc/library/stdtypes.rst
index b2931ae..6ebf2a0 100644
--- a/Doc/library/stdtypes.rst
+++ b/Doc/library/stdtypes.rst
@@ -1352,6 +1352,19 @@ functions based on regular expressions.
         "They're Bill's Friends."
 
 
+.. method:: str.transform(encoding, errors='strict')
+
+   Return an encoded version of the string.  In contrast to :meth:`encode`, this
+   method works with codecs that provide string-to-string mappings, and not
+   string-to-bytes mappings.  :meth:`transform` therefore returns a string
+   object.
+
+   The codecs that can be used with this method are listed in
+   :ref:`standard-encodings`.
+
+   .. versionadded:: 3.2
+
+
 .. method:: str.translate(map)
 
    Return a copy of the *s* where all characters have been mapped through the
@@ -1369,6 +1382,14 @@ functions based on regular expressions.
       example).
 
 
+.. method:: str.untransform(encoding, errors='strict')
+
+   Return a decoded version of the string.  This provides the reverse operation
+   of :meth:`transform`.
+
+   .. versionadded:: 3.2
+
+
 .. method:: str.upper()
 
    Return a copy of the string converted to uppercase.
@@ -1800,6 +1821,20 @@ The bytes and bytearray types have an additional class method:
 The maketrans and translate methods differ in semantics from the versions
 available on strings:
 
+.. method:: bytes.transform(encoding, errors='strict')
+            bytearray.transform(encoding, errors='strict')
+
+   Return an encoded version of the bytes object.  In contrast to
+   :meth:`encode`, this method works with codecs that provide bytes-to-bytes
+   mappings, and not string-to-bytes mappings.  :meth:`transform` therefore
+   returns a bytes or bytearray object.
+
+   The codecs that can be used with this method are listed in
+   :ref:`standard-encodings`.
+
+   .. versionadded:: 3.2
+
+
 .. method:: bytes.translate(table[, delete])
             bytearray.translate(table[, delete])
 
@@ -1817,6 +1852,15 @@ available on strings:
       b'rd ths shrt txt'
 
 
+.. method:: bytes.untransform(encoding, errors='strict')
+            bytearray.untransform(encoding, errors='strict')
+
+   Return an decoded version of the bytes object.  This provides the reverse
+   operation of :meth:`transform`.
+
+   .. versionadded:: 3.2
+
+
 .. staticmethod:: bytes.maketrans(from, to)
                   bytearray.maketrans(from, to)