From 99597c4d12e358174275945d97e504c0318a3783 Mon Sep 17 00:00:00 2001 From: Senthil Kumaran Date: Wed, 25 Jun 2014 01:12:03 -0700 Subject: [PATCH] Correct the quopri module documentation. Mention the correct types of the parameters on encodestring and decodestring. Patch by Petri Lehtinen. --- Doc/library/quopri.rst | 32 ++++++++++++++++---------------- Lib/quopri.py | 14 ++++++-------- 2 files changed, 22 insertions(+), 24 deletions(-) diff --git a/Doc/library/quopri.rst b/Doc/library/quopri.rst index 755811adfd8..3a74cf8511b 100644 --- a/Doc/library/quopri.rst +++ b/Doc/library/quopri.rst @@ -24,9 +24,8 @@ 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 - `. *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 + `. 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". @@ -34,27 +33,28 @@ sending a graphics file. .. 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 - `. *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 `. *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 index e5bd010d5ba..46c2a4c7287 100755 --- 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: