merge from 3.4

orsenthil · orsenthil · commit b057970f0d4e · 2014-06-25T01:13:19.000-07:00
issue15588 - Correct the quopri module documentation. Mention the correct types
of the parameters on encodestring and decodestring.

Patch by Petri Lehtinen.
diff --git a/Doc/library/quopri.rst b/Doc/library/quopri.rst
@@ -24,37 +24,37 @@ sending a graphics file.
 .. function:: decode(input, output, header=False)
 
    Decode the contents of the *input* file and write the resulting decoded binary
-   data to the *output* file. *input* and *output* must be :term:`file objects
-   <file object>`.  *input* will be read until ``input.readline()`` returns an
-   empty string. If the optional argument *header* is present and true, underscore
+   data to the *output* file. *input* and *output* must be :term:`binary file objects
+   <file object>`.  If the optional argument *header* is present and true, underscore
    will be decoded as space. This is used to decode "Q"-encoded headers as
    described in :rfc:`1522`: "MIME (Multipurpose Internet Mail Extensions)
    Part Two: Message Header Extensions for Non-ASCII Text".
 
 
 .. function:: encode(input, output, quotetabs, header=False)
 
-   Encode the contents of the *input* file and write the resulting quoted-printable
-   data to the *output* file. *input* and *output* must be :term:`file objects
-   <file object>`.  *input* will be read until ``input.readline()`` returns an
-   empty string. *quotetabs* is a flag which controls whether to encode embedded
-   spaces and tabs; when true it encodes such embedded whitespace, and when
-   false it leaves them unencoded.  Note that spaces and tabs appearing at the
-   end of lines are always encoded, as per :rfc:`1521`.  *header* is a flag
-   which controls if spaces are encoded as underscores as per :rfc:`1522`.
+   Encode the contents of the *input* file and write the resulting quoted-
+   printable data to the *output* file. *input* and *output* must be
+   :term:`binary file objects <file object>`. *quotetabs*, a flag which controls
+   whether to encode embedded spaces and tabs must be provideda and when true it
+   encodes such embedded whitespace, and when false it leaves them unencoded.
+   Note that spaces and tabs appearing at the end of lines are always encoded,
+   as per :rfc:`1521`.  *header* is a flag which controls if spaces are encoded
+   as underscores as per :rfc:`1522`.
 
 
 .. function:: decodestring(s, header=False)
 
-   Like :func:`decode`, except that it accepts a source string and returns the
-   corresponding decoded string.
+   Like :func:`decode`, except that it accepts a source :class:`bytes` and
+   returns the corresponding decoded :class:`bytes`.
 
 
 .. function:: encodestring(s, quotetabs=False, header=False)
 
-   Like :func:`encode`, except that it accepts a source string and returns the
-   corresponding encoded string.  *quotetabs* and *header* are optional
-   (defaulting to ``False``), and are passed straight through to :func:`encode`.
+   Like :func:`encode`, except that it accepts a source :class:`bytes` and
+   returns the corresponding encoded :class:`bytes`. By default, it sends a
+   False value to *quotetabs* parameter of the :func:`encode` function.
+
 
 
 .. seealso::
diff --git a/Lib/quopri.py b/Lib/quopri.py
@@ -44,13 +44,11 @@ def quote(c):
 def encode(input, output, quotetabs, header=False):
     """Read 'input', apply quoted-printable encoding, and write to 'output'.
 
-    'input' and 'output' are files with readline() and write() methods.
-    The 'quotetabs' flag indicates whether embedded tabs and spaces should be
-    quoted.  Note that line-ending tabs and spaces are always encoded, as per
-    RFC 1521.
-    The 'header' flag indicates whether we are encoding spaces as _ as per
-    RFC 1522.
-    """
+    'input' and 'output' are binary file objects. The 'quotetabs' flag
+    indicates whether embedded tabs and spaces should be quoted. Note that
+    line-ending tabs and spaces are always encoded, as per RFC 1521.
+    The 'header' flag indicates whether we are encoding spaces as _ as per RFC
+    1522."""
 
     if b2a_qp is not None:
         data = input.read()
@@ -118,7 +116,7 @@ def encodestring(s, quotetabs=False, header=False):
 
 def decode(input, output, header=False):
     """Read 'input', apply quoted-printable decoding, and write to 'output'.
-    'input' and 'output' are files with readline() and write() methods.
+    'input' and 'output' are binary file objects.
     If 'header' is true, decode underscore as space (per RFC 1522)."""
 
     if a2b_qp is not None:
