#10839: raise an error on add of duplicate unique headers in new email policies

This feature was supposed to be part of the initial email6 checkin, but it got
lost in my big refactoring.

In this patch I'm not providing an easy way to turn off the errors, but they
only happen when a header is added programmatically, and it is almost never
the right thing to do to allow the duplicate to be added.  An application that
needs to add duplicates of unique headers can create a policy subclass to
allow it.

1 files changed, 19 insertions, 0 deletions

diff --git a/Lib/email/_policybase.py b/Lib/email/_policybase.py
index 6bc298b..d5e8df9 100644
--- a/Lib/email/_policybase.py
+++ b/Lib/email/_policybase.py
@@ -194,6 +194,25 @@ class Policy(_PolicyBase, metaclass=_DocstringExtenderMetaclass):
         """
         obj.defects.append(defect)
 
+    def header_max_count(self, name):
+        """Return the maximum allowed number of headers named 'name'.
+
+        Called when a header is added to a Message object.  If the returned
+        value is not 0 or None, and there are already a number of headers with
+        the name 'name' equal to the value returned, a ValueError is raised.
+
+        Because the default behavior of Message's __setitem__ is to append the
+        value to the list of headers, it is easy to create duplicate headers
+        without realizing it.  This method allows certain headers to be limited
+        in the number of instances of that header that may be added to a
+        Message programmatically.  (The limit is not observed by the parser,
+        which will faithfully produce as many headers as exist in the message
+        being parsed.)
+
+        The default implementation returns None for all header names.
+        """
+        return None
+
     @abc.abstractmethod
     def header_source_parse(self, sourcelines):
         """Given a list of linesep terminated strings constituting the lines of