Merge issue 19548 changes from 3.4

Lib/codecs.py

@@ -347,8 +347,7 @@ class StreamWriter(Codec):
 
         """ Creates a StreamWriter instance.
 
-            stream must be a file-like object open for writing
-            (binary) data.
+            stream must be a file-like object open for writing.
 
             The StreamWriter may use different error handling
             schemes by providing the errors keyword argument. These
@@ -422,8 +421,7 @@ class StreamReader(Codec):
 
         """ Creates a StreamReader instance.
 
-            stream must be a file-like object open for reading
-            (binary) data.
+            stream must be a file-like object open for reading.
 
             The StreamReader may use different error handling
             schemes by providing the errors keyword argument. These
@@ -451,13 +449,12 @@ class StreamReader(Codec):
         """ Decodes data from the stream self.stream and returns the
             resulting object.
 
-            chars indicates the number of characters to read from the
-            stream. read() will never return more than chars
-            characters, but it might return less, if there are not enough
-            characters available.
+            chars indicates the number of decoded code points or bytes to
+            return. read() will never return more data than requested,
+            but it might return less, if there is not enough available.
 
-            size indicates the approximate maximum number of bytes to
-            read from the stream for decoding purposes. The decoder
+            size indicates the approximate maximum number of decoded
+            bytes or code points to read for decoding. The decoder
             can modify this setting as appropriate. The default value
             -1 indicates to read and decode as much as possible.  size
             is intended to prevent having to decode huge files in one
@@ -468,7 +465,7 @@ class StreamReader(Codec):
             will be returned, the rest of the input will be kept until the
             next call to read().
 
-            The method should use a greedy read strategy meaning that
+            The method should use a greedy read strategy, meaning that
             it should read as much data as is allowed within the
             definition of the encoding and the given size, e.g.  if
             optional encoding endings or state markers are available
@@ -603,7 +600,7 @@ class StreamReader(Codec):
     def readlines(self, sizehint=None, keepends=True):
 
         """ Read all lines available on the input stream
-            and return them as list of lines.
+            and return them as a list.
 
             Line breaks are implemented using the codec's decoder
             method and are included in the list entries.
@@ -751,19 +748,18 @@ class StreamReaderWriter:
 
 class StreamRecoder:
 
-    """ StreamRecoder instances provide a frontend - backend
-        view of encoding data.
+    """ StreamRecoder instances translate data from one encoding to another.
 
         They use the complete set of APIs returned by the
         codecs.lookup() function to implement their task.
 
-        Data written to the stream is first decoded into an
-        intermediate format (which is dependent on the given codec
-        combination) and then written to the stream using an instance
-        of the provided Writer class.
+        Data written to the StreamRecoder is first decoded into an
+        intermediate format (depending on the "decode" codec) and then
+        written to the underlying stream using an instance of the provided
+        Writer class.
 
-        In the other direction, data is read from the stream using a
-        Reader instance and then return encoded data to the caller.
+        In the other direction, data is read from the underlying stream using
+        a Reader instance and then encoded and returned to the caller.
 
     """
     # Optional attributes set by the file wrappers below
@@ -775,22 +771,17 @@ class StreamRecoder:
 
         """ Creates a StreamRecoder instance which implements a two-way
             conversion: encode and decode work on the frontend (the
-            input to .read() and output of .write()) while
-            Reader and Writer work on the backend (reading and
-            writing to the stream).
+            data visible to .read() and .write()) while Reader and Writer
+            work on the backend (the data in stream).
 
-            You can use these objects to do transparent direct
-            recodings from e.g. latin-1 to utf-8 and back.
+            You can use these objects to do transparent
+            transcodings from e.g. latin-1 to utf-8 and back.
 
             stream must be a file-like object.
 
-            encode, decode must adhere to the Codec interface, Reader,
+            encode and decode must adhere to the Codec interface; Reader and
             Writer must be factory functions or classes providing the
-            StreamReader, StreamWriter interface resp.
-
-            encode and decode are needed for the frontend translation,
-            Reader and Writer for the backend translation. Unicode is
-            used as intermediate encoding.
+            StreamReader and StreamWriter interfaces resp.
 
             Error handling is done in the same way as defined for the
             StreamWriter/Readers.
@@ -865,7 +856,7 @@ class StreamRecoder:
 
 ### Shortcuts
 
-def open(filename, mode='rb', encoding=None, errors='strict', buffering=1):
+def open(filename, mode='r', encoding=None, errors='strict', buffering=1):
 
     """ Open an encoded file using the given mode and return
         a wrapped version providing transparent encoding/decoding.
@@ -875,10 +866,8 @@ def open(filename, mode='rb', encoding=None, errors='strict', buffering=1):
         codecs. Output is also codec dependent and will usually be
         Unicode as well.
 
-        Files are always opened in binary mode, even if no binary mode
-        was specified. This is done to avoid data loss due to encodings
-        using 8-bit values. The default file mode is 'rb' meaning to
-        open the file in binary read mode.
+        Underlying encoded files are always opened in binary mode.
+        The default file mode is 'r', meaning to open the file in read mode.
 
         encoding specifies the encoding which is to be used for the
         file.
@@ -914,13 +903,13 @@ def EncodedFile(file, data_encoding, file_encoding=None, errors='strict'):
     """ Return a wrapped version of file which provides transparent
         encoding translation.
 
-        Strings written to the wrapped file are interpreted according
-        to the given data_encoding and then written to the original
-        file as string using file_encoding. The intermediate encoding
+        Data written to the wrapped file is decoded according
+        to the given data_encoding and then encoded to the underlying
+        file using file_encoding. The intermediate data type
         will usually be Unicode but depends on the specified codecs.
 
-        Strings are read from the file using file_encoding and then
-        passed back to the caller as string using data_encoding.
+        Bytes read from the file are decoded using file_encoding and then
+        passed back to the caller encoded using data_encoding.
 
         If file_encoding is not given, it defaults to data_encoding.