From 8886cc04fd318d8b9156df8c11322bd10bacf52c Mon Sep 17 00:00:00 2001 From: Sebb Date: Tue, 9 Jul 2024 12:11:40 +0100 Subject: [PATCH 1/5] Document mbox-from --- Doc/library/mailbox.rst | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 40ea71cd342b47..a0afa08782d7bc 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -587,12 +587,27 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. remarks: - .. method:: get_file(key) + .. method:: get_bytes(key, from_=False) + + Note: This method has an extra parameter (from_) compared with other classes. + The first line of an mbox file entry is the unix 'From ' line. + If from_ is False, the first line of the file is dropped. + + .. method:: get_file(key, from_=False) Using the file after calling :meth:`~Mailbox.flush` or :meth:`~Mailbox.close` on the :class:`!mbox` instance may yield unpredictable results or raise an exception. + Note: This method has an extra parameter (from_) compared with other classes. + The first line of an mbox file entry is the unix 'From ' line. + If from_ is False, the first line of the file is dropped. + + .. method:: get_string(key, from_=False) + + Note: This method has an extra parameter (from_) compared with other classes. + The first line of an mbox file entry is the unix 'From ' line. + If from_ is False, the first line of the file is dropped. .. method:: lock() unlock() From 72912b85b3ffc4d0d07fa1f8015356accdcb6d9f Mon Sep 17 00:00:00 2001 From: Sebb Date: Tue, 9 Jul 2024 20:13:21 +0100 Subject: [PATCH 2/5] Italicise parameter reference --- Doc/library/mailbox.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index a0afa08782d7bc..c34d8c683e1924 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -589,9 +589,9 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. .. method:: get_bytes(key, from_=False) - Note: This method has an extra parameter (from_) compared with other classes. + Note: This method has an extra parameter (*from_*) compared with other classes. The first line of an mbox file entry is the unix 'From ' line. - If from_ is False, the first line of the file is dropped. + If *from_* is False, the first line of the file is dropped. .. method:: get_file(key, from_=False) @@ -599,15 +599,15 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. :meth:`~Mailbox.close` on the :class:`!mbox` instance may yield unpredictable results or raise an exception. - Note: This method has an extra parameter (from_) compared with other classes. + Note: This method has an extra parameter (*from_*) compared with other classes. The first line of an mbox file entry is the unix 'From ' line. - If from_ is False, the first line of the file is dropped. + If *from_* is False, the first line of the file is dropped. .. method:: get_string(key, from_=False) - Note: This method has an extra parameter (from_) compared with other classes. + Note: This method has an extra parameter (*from_*) compared with other classes. The first line of an mbox file entry is the unix 'From ' line. - If from_ is False, the first line of the file is dropped. + If *from_* is False, the first line of the file is dropped. .. method:: lock() unlock() From 459a8f8800f4d550872dcaa0d98991eaa63f09c1 Mon Sep 17 00:00:00 2001 From: Sebb Date: Tue, 9 Jul 2024 20:29:23 +0100 Subject: [PATCH 3/5] Unix --- Doc/library/mailbox.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index c34d8c683e1924..0580c76eba82e7 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -590,7 +590,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. .. method:: get_bytes(key, from_=False) Note: This method has an extra parameter (*from_*) compared with other classes. - The first line of an mbox file entry is the unix 'From ' line. + The first line of an mbox file entry is the Unix 'From ' line. If *from_* is False, the first line of the file is dropped. .. method:: get_file(key, from_=False) @@ -600,13 +600,13 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. unpredictable results or raise an exception. Note: This method has an extra parameter (*from_*) compared with other classes. - The first line of an mbox file entry is the unix 'From ' line. + The first line of an mbox file entry is the Unix 'From ' line. If *from_* is False, the first line of the file is dropped. .. method:: get_string(key, from_=False) Note: This method has an extra parameter (*from_*) compared with other classes. - The first line of an mbox file entry is the unix 'From ' line. + The first line of an mbox file entry is the Unix 'From ' line. If *from_* is False, the first line of the file is dropped. .. method:: lock() From 48a38c482f376e3a02ae6652df555fe8b6748810 Mon Sep 17 00:00:00 2001 From: Sebb Date: Tue, 9 Jul 2024 21:01:35 +0100 Subject: [PATCH 4/5] From --- Doc/library/mailbox.rst | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 0580c76eba82e7..cd806c0eadf67e 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -590,7 +590,7 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. .. method:: get_bytes(key, from_=False) Note: This method has an extra parameter (*from_*) compared with other classes. - The first line of an mbox file entry is the Unix 'From ' line. + The first line of an mbox file entry is the Unix "From " line. If *from_* is False, the first line of the file is dropped. .. method:: get_file(key, from_=False) @@ -600,13 +600,13 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. unpredictable results or raise an exception. Note: This method has an extra parameter (*from_*) compared with other classes. - The first line of an mbox file entry is the Unix 'From ' line. + The first line of an mbox file entry is the Unix "From " line. If *from_* is False, the first line of the file is dropped. .. method:: get_string(key, from_=False) Note: This method has an extra parameter (*from_*) compared with other classes. - The first line of an mbox file entry is the Unix 'From ' line. + The first line of an mbox file entry is the Unix "From " line. If *from_* is False, the first line of the file is dropped. .. method:: lock() From e9e6424f482963c1da278d0e82426af9024ed096 Mon Sep 17 00:00:00 2001 From: Sebb Date: Sun, 23 Feb 2025 23:58:09 +0000 Subject: [PATCH 5/5] Update MMDF doc as well --- Doc/library/mailbox.rst | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/Doc/library/mailbox.rst b/Doc/library/mailbox.rst index 33b4ae9ab33710..e8a96f29ea185e 100644 --- a/Doc/library/mailbox.rst +++ b/Doc/library/mailbox.rst @@ -866,12 +866,22 @@ Supported mailbox formats are Maildir, mbox, MH, Babyl, and MMDF. remarks: - .. method:: get_file(key) + .. method:: get_bytes(key, from_=False) + + Note: This method has an extra parameter (*from_*) compared with other classes. + The first line of an mbox file entry is the Unix "From " line. + If *from_* is False, the first line of the file is dropped. + + .. method:: get_file(key, from_=False) Using the file after calling :meth:`~Mailbox.flush` or :meth:`~Mailbox.close` on the :class:`!MMDF` instance may yield unpredictable results or raise an exception. + Note: This method has an extra parameter (*from_*) compared with other classes. + The first line of an mbox file entry is the Unix "From " line. + If *from_* is False, the first line of the file is dropped. + .. method:: lock() unlock()