# HG changeset patch
# Parent  3e721e79b602b14074b279764cc38303d2002b3c
Clarify some aspects of defects in the “email” package

* There is no class called Defect
* Some defects are never raised, even if the policy says they should

diff -r 3e721e79b602 -r d3639e4014be Doc/library/email.errors.rst
--- a/Doc/library/email.errors.rst	Mon Jun 13 04:00:53 2016 +0000
+++ b/Doc/library/email.errors.rst	Mon Jun 13 08:46:54 2016 +0000
@@ -70,8 +70,8 @@
 :mimetype:`multipart/alternative` had a malformed header, that nested message
 object would have a defect, but the containing messages would not.
 
-All defect classes are subclassed from :class:`email.errors.MessageDefect`, but
-this class is *not* an exception!
+All defect classes are subclassed from :class:`email.errors.MessageDefect`,
+which is an exception, but does not inherit from :class:`MessageError`!
 
 * :class:`NoBoundaryInMultipartDefect` -- A message claimed to be a multipart,
   but had no :mimetype:`boundary` parameter.
@@ -88,7 +88,8 @@
   line as its first header line.
 
 * :class:`MisplacedEnvelopeHeaderDefect` - A "Unix From" header was found in the
-  middle of a header block.
+  middle of a header block.  This defect is never raised as an exception,
+  despite the policy.
 
 * :class:`MissingHeaderBodySeparatorDefect` - A line was found while parsing
   headers that had no leading white space but contained no ':'.  Parsing
diff -r 3e721e79b602 -r d3639e4014be Doc/library/email.policy.rst
--- a/Doc/library/email.policy.rst	Mon Jun 13 04:00:53 2016 +0000
+++ b/Doc/library/email.policy.rst	Mon Jun 13 08:46:54 2016 +0000
@@ -186,8 +186,8 @@
 
    .. attribute:: raise_on_defect
 
-      If :const:`True`, any defects encountered will be raised as errors.  If
-      :const:`False` (the default), defects will be passed to the
+      If :const:`True`, some defects encountered will be raised as errors.  If
+      :const:`False` (the default), these defects will be passed to the
       :meth:`register_defect` method.
 
 
@@ -217,9 +217,7 @@
 
    .. method:: handle_defect(obj, defect)
 
-      Handle a *defect* found on *obj*.  When the email package calls this
-      method, *defect* will always be a subclass of
-      :class:`~email.errors.Defect`.
+      Handle a *defect* found on *obj*.
 
       The default implementation checks the :attr:`raise_on_defect` flag.  If
       it is ``True``, *defect* is raised as an exception.  If it is ``False``
@@ -227,8 +225,7 @@
 
    .. method:: register_defect(obj, defect)
 
-      Register a *defect* on *obj*.  In the email package, *defect* will always
-      be a subclass of :class:`~email.errors.Defect`.
+      Register a *defect* on *obj*.
 
       The default implementation calls the ``append`` method of the ``defects``
       attribute of *obj*.  When the email package calls :attr:`handle_defect`,
diff -r 3e721e79b602 -r d3639e4014be Lib/email/_policybase.py
--- a/Lib/email/_policybase.py	Mon Jun 13 04:00:53 2016 +0000
+++ b/Lib/email/_policybase.py	Mon Jun 13 08:46:54 2016 +0000
@@ -116,9 +116,10 @@
     Most of the classes and many of the methods in the email package accept
     Policy objects as parameters.  A Policy object contains a set of values and
     functions that control how input is interpreted and how output is rendered.
-    For example, the parameter 'raise_on_defect' controls whether or not an RFC
-    violation results in an error being raised or not, while 'max_line_length'
-    controls the maximum length of output lines when a Message is serialized.
+    For example, the parameter 'raise_on_defect' controls whether or not some
+    RFC violations result in errors being raised or not, while
+    'max_line_length' controls the maximum length of output lines when a
+    Message is serialized.
 
     Any valid attribute may be overridden when a Policy is created by passing
     it as a keyword argument to the constructor.  Policy objects are immutable,
@@ -130,8 +131,8 @@
 
     Settable attributes:
 
-    raise_on_defect     -- If true, then defects should be raised as errors.
-                           Default: False.
+    raise_on_defect     -- If true, then some defects should be raised as
+                           errors.  Default: False.
 
     linesep             -- string containing the value to use as separation
                            between output lines.  Default '\n'.
@@ -163,18 +164,17 @@
     mangle_from_ = False
 
     def handle_defect(self, obj, defect):
-        """Based on policy, either raise defect or call register_defect.
+        """Based on policy, either raise defect or call 'register_defect'.
 
             handle_defect(obj, defect)
 
-        defect should be a Defect subclass, but in any case must be an
-        Exception subclass.  obj is the object on which the defect should be
-        registered if it is not raised.  If the raise_on_defect is True, the
-        defect is raised as an error, otherwise the object and the defect are
-        passed to register_defect.
+        The 'defect' argument must be an Exception subclass.  The 'obj'
+        argument is the object on which the defect should be registered if it
+        is not raised.  If 'raise_on_defect' is True, the defect is raised as
+        an exception, otherwise the object and the defect are passed to
+        'register_defect'.
 
         This method is intended to be called by parsers that discover defects.
-        The email package parsers always call it with Defect instances.
 
         """
         if self.raise_on_defect: