[New-bugs-announce] [issue27328] Documentation corrections for email defects

[Martin Panter]

New submission from Martin Panter:

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.

----------
components: email
files: defect-doc.patch
keywords: patch
messages: 268640
nosy: barry, martin.panter, r.david.murray
priority: normal
severity: normal
status: open
title: Documentation corrections for email defects
versions: Python 3.5, Python 3.6
Added file: http://bugs.python.org/file43404/defect-doc.patch

_______________________________________
Python tracker <report at bugs.python.org>
<http://bugs.python.org/issue27328>
_______________________________________