incorrect example of fetching messages in imaplib documentation

[mvarnar]

BPO	35783
Nosy	@warsaw, @bitdancer, @mvarnar, @rahul-kumi

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2019-01-19.08:40:17.372>
labels = ['3.8', 'type-feature', '3.7', 'expert-email', 'docs']
title = 'incorrect example of fetching messages in imaplib documentation'
updated_at = <Date 2020-12-22.16:16:47.334>
user = 'https://github.com/mvarnar'

bugs.python.org fields:

activity = <Date 2020-12-22.16:16:47.334>
actor = 'rahul-kumi'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation', 'email']
creation = <Date 2019-01-19.08:40:17.372>
creator = 'Max Varnar'
dependencies = []
files = []
hgrepos = []
issue_num = 35783
keywords = []
message_count = 1.0
messages = ['334048']
nosy_count = 5.0
nosy_names = ['barry', 'r.david.murray', 'docs@python', 'Max Varnar', 'rahul-kumi']
pr_nums = []
priority = 'normal'
resolution = None
stage = None
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue35783'
versions = ['Python 2.7', 'Python 3.5', 'Python 3.6', 'Python 3.7', 'Python 3.8']

Linked PRs

• gh-79964: Clarify the imaplib fetch example in the docs #152780
• [3.15] gh-79964: Clarify the imaplib fetch example in the docs (GH-152780) #152859
• [3.14] gh-79964: Clarify the imaplib fetch example in the docs (GH-152780) #152860
• [3.13] gh-79964: Clarify the imaplib fetch example in the docs (GH-152780) #152861

[mvarnar]

An example of fetching messages from the mailbox given in "IMAP4 Example" section is incorrect:

typ, data = M.fetch(num, '(RFC822)')
print('Message %s\n%s\n' % (num, data[0][1]))

"fetch" may return server data that was not requested (see "7.4.2. FETCH Response" section of RFC 3501). In that case "data[0][1]" won't return what user expects.
This is a bad example, that many people repeat and advise to other developers:
https://stackoverflow.com/questions/13210737/get-only-new-emails-imaplib-and-python
https://gist.github.com/robulouski/7441883
https://stackoverflow.com/questions/51098962/check-if-email-inbox-is-empty-imaplib-python3
https://stackoverflow.com/questions/21116498/imaplib-not-getting-all-emails-in-folder
https://stackoverflow.com/questions/2230037/how-to-fetch-an-email-body-using-imaplib-in-python

I guess, this peculiarity should be clarified in the documentation. I offer to mark this fetching method is not safe and requests careful fetch result parsing.