email examples should not gratuitously mess with preamble

[era]

BPO	36261
Nosy	@warsaw, @bitdancer, @zooba, @miss-islington, @carlbordum
PRs	bpo-36261: email example was misusing preamble field #14751 [3.8] bpo-36261: Improve example of the preamble field in email docs (GH-14751) #14760 [3.7] bpo-36261: Improve example of the preamble field in email docs (GH-14751) #14761

^{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 = <Date 2019-07-14.07:51:35.922>
created_at = <Date 2019-03-11.11:27:29.775>
labels = ['3.8', 'type-bug', '3.7', 'expert-email', '3.9']
title = 'email examples should not gratuitously mess with preamble'
updated_at = <Date 2019-07-14.07:53:18.292>
user = 'https://bugs.python.org/era'

bugs.python.org fields:

activity = <Date 2019-07-14.07:53:18.292>
actor = 'miss-islington'
assignee = 'none'
closed = True
closed_date = <Date 2019-07-14.07:51:35.922>
closer = 'steve.dower'
components = ['email']
creation = <Date 2019-03-11.11:27:29.775>
creator = 'era'
dependencies = []
files = []
hgrepos = []
issue_num = 36261
keywords = ['patch']
message_count = 8.0
messages = ['337657', '337677', '337678', '347835', '347869', '347870', '347871', '347872']
nosy_count = 6.0
nosy_names = ['barry', 'r.david.murray', 'era', 'steve.dower', 'miss-islington', 'carlbordum']
pr_nums = ['14751', '14760', '14761']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue36261'
versions = ['Python 3.7', 'Python 3.8', 'Python 3.9']

[era]

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.

[bitdancer]

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/email-mime.py). 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.

[bitdancer]

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.

[carlbordum]

I also only found the one case. Submitted a patch.

[zooba]

New changeset 8efade9 by Steve Dower (Carl Bordum Hansen) in branch 'master':
bpo-36261: Improve example of the preamble field in email docs (GH-14751)
8efade9

[zooba]

Merged, and I am assuming the backports will merge fine too. Thanks for the patch!

[miss-islington]

New changeset fb58024 by Miss Islington (bot) in branch '3.7':
bpo-36261: Improve example of the preamble field in email docs (GH-14751)
fb58024

[miss-islington]

New changeset 262779f by Miss Islington (bot) in branch '3.8':
bpo-36261: Improve example of the preamble field in email docs (GH-14751)
262779f