Title: Documentation corrections for email defects
Type: Stage: patch review
Components: email Versions: Python 3.6, Python 3.5
Status: open Resolution:
Dependencies: 24364 Superseder:
Assigned To: Nosy List: barry, martin.panter, r.david.murray
Priority: normal Keywords: patch

Created on 2016-06-16 04:36 by martin.panter, last changed 2016-06-20 08:49 by martin.panter.

File name Uploaded Description Edit
defect-doc.patch martin.panter, 2016-06-16 04:36
defect-doc.v2.patch martin.panter, 2016-06-20 08:49 review
Messages (2)
msg268640 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-16 04:36
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 Issue 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.
msg268887 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2016-06-20 08:49
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 Issue 24364.
Date User Action Args
2016-06-20 08:49:57martin.pantersetfiles: + defect-doc.v2.patch

dependencies: + Not all defects pass through email policy
messages: + msg268887
stage: patch review
2016-06-16 04:36:20martin.pantercreate