Documentation corrections for email defects

[vadmium]

BPO	27328
Nosy	@warsaw, @bitdancer, @vadmium
Dependencies	bpo-24364: Not all defects pass through email policy
Files	defect-doc.patch defect-doc.v2.patch

^{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 2016-06-16.04:36:20.590>
labels = ['expert-email']
title = 'Documentation corrections for email defects'
updated_at = <Date 2016-06-20.08:49:57.078>
user = 'https://github.com/vadmium'

bugs.python.org fields:

activity = <Date 2016-06-20.08:49:57.078>
actor = 'martin.panter'
assignee = 'none'
closed = False
closed_date = None
closer = None
components = ['email']
creation = <Date 2016-06-16.04:36:20.590>
creator = 'martin.panter'
dependencies = ['24364']
files = ['43404', '43482']
hgrepos = []
issue_num = 27328
keywords = ['patch']
message_count = 2.0
messages = ['268640', '268887']
nosy_count = 3.0
nosy_names = ['barry', 'r.david.murray', 'martin.panter']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue27328'
versions = ['Python 3.5', 'Python 3.6']

[vadmium]

In trying to understand the defects from parsing an email Message object, and trying to use the raise_on_defect=True mode, I found a few inconsistencies with the documentation. I made a preliminary patch, but it may need adjusting.

1. There is no class called email.errors.Defect. My patch just removes the sentences mentioning this class. But an alternative might be to say handle/register_defect() are called with a subclass of MessageDefect.

2. Some defects are never raised, even if the policy says they should. I changed some of the wording to be less strict. But later I discovered bpo-24364, so perhaps this is actually an implementation bug instead.

3(a). MessageDefect is an exception class, and its subclasses are raised directly with raise_on_defect=True. However the documentation is explicit that defect classes are not exceptions.

3(b). If you assume defects are not exceptions, the documentation leads you to expect a defect will raise Message/Header(Parse)Error. But the defect exception classes that are raised are not even subclasses of MessageError.

[vadmium]

Here is a new version which I think should be okay to apply. I restored the references to the base class, but now using the MessageDefect name. I removed the changes relating to raise_on_defect not being strict, in favour of fixing bpo-24364.