Title: email examples should not gratuitously mess with preamble
Type: behavior Stage: resolved
Components: email Versions: Python 3.9, Python 3.8, Python 3.7
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: Nosy List: barry, carlbordum, era, miss-islington, r.david.murray, steve.dower
Priority: normal Keywords: patch

Created on 2019-03-11 11:27 by era, last changed 2019-07-14 07:53 by miss-islington. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 14751 merged carlbordum, 2019-07-13 14:53
PR 14760 merged miss-islington, 2019-07-14 07:46
PR 14761 merged miss-islington, 2019-07-14 07:46
Messages (8)
msg337657 - (view) Author: (era) Date: 2019-03-11 11:27
Several of the examples in the email module documentation modify the preamble.

This is not good practice. The email MIME preamble is really only useful for communicating information about MIME itself, not for general human-readable content like 'Our family reunion'.

The MIME preamble is problematic because it typically only supports ASCII and often defaults to an English-language message, even when applications are used in locales where English is not widely understood.  For this reason, it is moderately useful to be able to override the preamble from Python code; but this should by no means be done routinely, and the documentation should certainly not demonstrate this in basic examples.
msg337677 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2019-03-11 15:36
I don't see "several", can you point to the other instances?  I only see that one case you mention (for reference, it is in Doc/includes/  The other case of setting preamble is actually correct ("You will not see this in a MIME-aware mail reader").  We could change email-mime to say the same thing.
msg337678 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2019-03-11 15:39
We could also change both of them to be more correct and say something like "If you are reading this your browser probably does not support MIME, and you will have to find a MIME aware email client or decode the message by hand."  That demonstrates what the preamble is actually for.
msg347835 - (view) Author: Carl Bordum Hansen (carlbordum) * Date: 2019-07-13 14:54
I also only found the one case. Submitted a patch.
msg347869 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-07-14 07:46
New changeset 8efade91b12a13102a09a3856179021e579da5e9 by Steve Dower (Carl Bordum Hansen) in branch 'master':
bpo-36261: Improve example of the preamble field in email docs (GH-14751)
msg347870 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2019-07-14 07:51
Merged, and I am assuming the backports will merge fine too. Thanks for the patch!
msg347871 - (view) Author: miss-islington (miss-islington) Date: 2019-07-14 07:51
New changeset fb58024688050385ed2fd93caf02a5807d1ccfed by Miss Islington (bot) in branch '3.7':
bpo-36261: Improve example of the preamble field in email docs (GH-14751)
msg347872 - (view) Author: miss-islington (miss-islington) Date: 2019-07-14 07:53
New changeset 262779fb5038db7574180c6a89b4f0968f29bd79 by Miss Islington (bot) in branch '3.8':
bpo-36261: Improve example of the preamble field in email docs (GH-14751)
Date User Action Args
2019-07-14 07:53:18miss-islingtonsetmessages: + msg347872
2019-07-14 07:51:53miss-islingtonsetnosy: + miss-islington
messages: + msg347871
2019-07-14 07:51:35steve.dowersetstatus: open -> closed
nosy: barry, r.david.murray, era, steve.dower, carlbordum
messages: + msg347870

resolution: fixed
stage: patch review -> resolved
2019-07-14 07:46:36miss-islingtonsetpull_requests: + pull_request14556
2019-07-14 07:46:29miss-islingtonsetpull_requests: + pull_request14555
2019-07-14 07:46:28steve.dowersetnosy: + steve.dower
messages: + msg347869
2019-07-14 07:45:31steve.dowersetversions: + Python 3.8, Python 3.9
2019-07-13 14:54:05carlbordumsetnosy: + carlbordum
messages: + msg347835
2019-07-13 14:53:27carlbordumsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request14546
2019-03-11 15:39:29r.david.murraysetstage: needs patch
2019-03-11 15:39:13r.david.murraysetmessages: + msg337678
2019-03-11 15:36:19r.david.murraysetmessages: + msg337677
2019-03-11 11:27:29eracreate