Thanks to visit codestin.com
Credit goes to github.com

Skip to content

Commit b7deff1

Browse files
bitdancerbitdancer
committed
#9124: mailbox now accepts binary input and uses binary internally
Although this patch contains API changes and is rather weighty for an RC phase, the mailbox module was essentially unusable without the patch since it would produce UnicodeErrors when handling non-ascii input at arbitrary and somewhat mysterious places, and any non-trivial amount of email processing will encounter messages with non-ascii bytes. The release manager approved the patch application. The changes allow binary input, and reject non-ASCII string input early with a useful message instead of failing mysteriously later. Binary is used internally for reading and writing the mailbox files. StringIO and Text file input are deprecated. Initial patch by Victor Stinner, validated and expanded by R. David Murray.
1 parent b02f7c0 commit b7deff1

4 files changed

Lines changed: 388 additions & 141 deletions

File tree

‎Doc/library/mailbox.rst‎

Lines changed: 28 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -81,13 +81,16 @@ Maildir, mbox, MH, Babyl, and MMDF.
8181
it.
8282

8383
Parameter *message* may be a :class:`Message` instance, an
84-
:class:`email.Message.Message` instance, a string, or a file-like object
85-
(which should be open in text mode). If *message* is an instance of the
84+
:class:`email.Message.Message` instance, a string, a byte string, or a
85+
file-like object (which should be open in binary mode). If *message* is
86+
an instance of the
8687
appropriate format-specific :class:`Message` subclass (e.g., if it's an
8788
:class:`mboxMessage` instance and this is an :class:`mbox` instance), its
8889
format-specific information is used. Otherwise, reasonable defaults for
8990
format-specific information are used.
9091

92+
.. versionchanged:: 3.2 support for binary input
93+
9194

9295
.. method:: remove(key)
9396
__delitem__(key)
@@ -108,8 +111,9 @@ Maildir, mbox, MH, Babyl, and MMDF.
108111
:exc:`KeyError` exception if no message already corresponds to *key*.
109112

110113
As with :meth:`add`, parameter *message* may be a :class:`Message`
111-
instance, an :class:`email.Message.Message` instance, a string, or a
112-
file-like object (which should be open in text mode). If *message* is an
114+
instance, an :class:`email.Message.Message` instance, a string, a byte
115+
string, or a file-like object (which should be open in binary mode). If
116+
*message* is an
113117
instance of the appropriate format-specific :class:`Message` subclass
114118
(e.g., if it's an :class:`mboxMessage` instance and this is an
115119
:class:`mbox` instance), its format-specific information is
@@ -171,10 +175,20 @@ Maildir, mbox, MH, Babyl, and MMDF.
171175
raise a :exc:`KeyError` exception if no such message exists.
172176

173177

178+
.. method:: get_bytes(key)
179+
180+
Return a byte representation of the message corresponding to *key*, or
181+
raise a :exc:`KeyError` exception if no such message exists.
182+
183+
.. versionadded:: 3.2
184+
185+
174186
.. method:: get_string(key)
175187

176188
Return a string representation of the message corresponding to *key*, or
177-
raise a :exc:`KeyError` exception if no such message exists.
189+
raise a :exc:`KeyError` exception if no such message exists. The
190+
message is processed through :class:`email.message.Message` to
191+
convert it to a 7bit clean representation.
178192

179193

180194
.. method:: get_file(key)
@@ -184,9 +198,11 @@ Maildir, mbox, MH, Babyl, and MMDF.
184198
file-like object behaves as if open in binary mode. This file should be
185199
closed once it is no longer needed.
186200

187-
.. versionadded:: 3.2
188-
The file-like object supports the context manager protocol, so that
189-
you can use a :keyword:`with` statement to automatically close it.
201+
.. versionchanged:: 3.2
202+
The file object really is a binary file; previously it was incorrectly
203+
returned in text mode. Also, the file-like object now supports the
204+
context manager protocol: you can use a :keyword:`with` statement to
205+
automatically close it.
190206

191207
.. note::
192208

@@ -746,9 +762,11 @@ Maildir, mbox, MH, Babyl, and MMDF.
746762
If *message* is omitted, the new instance is created in a default, empty state.
747763
If *message* is an :class:`email.Message.Message` instance, its contents are
748764
copied; furthermore, any format-specific information is converted insofar as
749-
possible if *message* is a :class:`Message` instance. If *message* is a string
765+
possible if *message* is a :class:`Message` instance. If *message* is a string,
766+
a byte string,
750767
or a file, it should contain an :rfc:`2822`\ -compliant message, which is read
751-
and parsed.
768+
and parsed. Files should be open in binary mode, but text mode files
769+
are accepted for backward compatibility.
752770

753771
The format-specific state and behaviors offered by subclasses vary, but in
754772
general it is only the properties that are not specific to a particular

0 commit comments

Comments
 (0)