summaryrefslogtreecommitdiffstats
path: root/Doc/library/mailbox.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Doc/library/mailbox.rst')
-rw-r--r--Doc/library/mailbox.rst50
1 files changed, 36 insertions, 14 deletions
diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst
index 7409af5..ff8cfea 100644
--- a/Doc/library/mailbox.rst
+++ b/Doc/library/mailbox.rst
@@ -81,13 +81,16 @@ Maildir, mbox, MH, Babyl, and MMDF.
it.
Parameter *message* may be a :class:`Message` instance, an
- :class:`email.Message.Message` instance, a string, or a file-like object
- (which should be open in text mode). If *message* is an instance of the
+ :class:`email.Message.Message` instance, a string, a byte string, or a
+ file-like object (which should be open in binary mode). If *message* is
+ an instance of the
appropriate format-specific :class:`Message` subclass (e.g., if it's an
:class:`mboxMessage` instance and this is an :class:`mbox` instance), its
format-specific information is used. Otherwise, reasonable defaults for
format-specific information are used.
+ .. versionchanged:: 3.2 support for binary input
+
.. method:: remove(key)
__delitem__(key)
@@ -108,8 +111,9 @@ Maildir, mbox, MH, Babyl, and MMDF.
:exc:`KeyError` exception if no message already corresponds to *key*.
As with :meth:`add`, parameter *message* may be a :class:`Message`
- instance, an :class:`email.Message.Message` instance, a string, or a
- file-like object (which should be open in text mode). If *message* is an
+ instance, an :class:`email.Message.Message` instance, a string, a byte
+ string, or a file-like object (which should be open in binary mode). If
+ *message* is an
instance of the appropriate format-specific :class:`Message` subclass
(e.g., if it's an :class:`mboxMessage` instance and this is an
:class:`mbox` instance), its format-specific information is
@@ -171,24 +175,40 @@ Maildir, mbox, MH, Babyl, and MMDF.
raise a :exc:`KeyError` exception if no such message exists.
+ .. method:: get_bytes(key)
+
+ Return a byte representation of the message corresponding to *key*, or
+ raise a :exc:`KeyError` exception if no such message exists.
+
+ .. versionadded:: 3.2
+
+
.. method:: get_string(key)
Return a string representation of the message corresponding to *key*, or
- raise a :exc:`KeyError` exception if no such message exists.
+ raise a :exc:`KeyError` exception if no such message exists. The
+ message is processed through :class:`email.message.Message` to
+ convert it to a 7bit clean representation.
.. method:: get_file(key)
Return a file-like representation of the message corresponding to *key*,
- or raise a :exc:`KeyError` exception if no such message exists. The
- file-like object behaves as if open in binary mode. This file should be
+ or raise a :exc:`KeyError` exception if no such message exists. The
+ file-like object behaves as if open in binary mode. This file should be
closed once it is no longer needed.
+ .. versionchanged:: 3.2
+ The file object really is a binary file; previously it was incorrectly
+ returned in text mode. Also, the file-like object now supports the
+ context manager protocol: you can use a :keyword:`with` statement to
+ automatically close it.
+
.. note::
Unlike other representations of messages, file-like representations are
not necessarily independent of the :class:`Mailbox` instance that
- created them or of the underlying mailbox. More specific documentation
+ created them or of the underlying mailbox. More specific documentation
is provided by each subclass.
@@ -452,7 +472,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
unlock()
Three locking mechanisms are used---dot locking and, if available, the
- :cfunc:`flock` and :cfunc:`lockf` system calls.
+ :c:func:`flock` and :c:func:`lockf` system calls.
.. seealso::
@@ -566,7 +586,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
unlock()
Three locking mechanisms are used---dot locking and, if available, the
- :cfunc:`flock` and :cfunc:`lockf` system calls. For MH mailboxes, locking
+ :c:func:`flock` and :c:func:`lockf` system calls. For MH mailboxes, locking
the mailbox means locking the :file:`.mh_sequences` file and, only for the
duration of any operations that affect them, locking individual message
files.
@@ -664,7 +684,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
unlock()
Three locking mechanisms are used---dot locking and, if available, the
- :cfunc:`flock` and :cfunc:`lockf` system calls.
+ :c:func:`flock` and :c:func:`lockf` system calls.
.. seealso::
@@ -715,7 +735,7 @@ Maildir, mbox, MH, Babyl, and MMDF.
unlock()
Three locking mechanisms are used---dot locking and, if available, the
- :cfunc:`flock` and :cfunc:`lockf` system calls.
+ :c:func:`flock` and :c:func:`lockf` system calls.
.. seealso::
@@ -742,9 +762,11 @@ Maildir, mbox, MH, Babyl, and MMDF.
If *message* is omitted, the new instance is created in a default, empty state.
If *message* is an :class:`email.Message.Message` instance, its contents are
copied; furthermore, any format-specific information is converted insofar as
- possible if *message* is a :class:`Message` instance. If *message* is a string
+ possible if *message* is a :class:`Message` instance. If *message* is a string,
+ a byte string,
or a file, it should contain an :rfc:`2822`\ -compliant message, which is read
- and parsed.
+ and parsed. Files should be open in binary mode, but text mode files
+ are accepted for backward compatibility.
The format-specific state and behaviors offered by subclasses vary, but in
general it is only the properties that are not specific to a particular