Make headerregistry fully part of the provisional api.

When I made the checkin of the provisional email policy, I knew that
Address and Group needed to be made accessible from somewhere.  The more
I looked at it, though, the more it became clear that since this is a
provisional API anyway, there's no good reason to hide headerregistry as
a private API.  It was designed to ultimately be part of the public API,
and so it should be part of the provisional API.

This patch fully documents the headerregistry API, and deletes the
abbreviated version of those docs I had added to the provisional policy
docs.

5 files changed, 38 insertions, 39 deletions

diff --git a/Lib/email/_headerregistry.py b/Lib/email/headerregistry.py
index 6588546..6588546 100644
--- a/Lib/email/_headerregistry.py
+++ b/Lib/email/headerregistry.py
diff --git a/Lib/email/policy.py b/Lib/email/policy.py
index 18946c3..47ed66b 100644
--- a/Lib/email/policy.py
+++ b/Lib/email/policy.py
@@ -4,7 +4,7 @@ code that adds all the email6 features.
 
 from email._policybase import Policy, Compat32, compat32
 from email.utils import _has_surrogates
-from email._headerregistry import HeaderRegistry as _HeaderRegistry
+from email.headerregistry import HeaderRegistry as HeaderRegistry
 
 __all__ = [
     'Compat32',
@@ -60,13 +60,13 @@ class EmailPolicy(Policy):
     """
 
     refold_source = 'long'
-    header_factory = _HeaderRegistry()
+    header_factory = HeaderRegistry()
 
     def __init__(self, **kw):
         # Ensure that each new instance gets a unique header factory
         # (as opposed to clones, which share the factory).
         if 'header_factory' not in kw:
-            object.__setattr__(self, 'header_factory', _HeaderRegistry())
+            object.__setattr__(self, 'header_factory', HeaderRegistry())
         super().__init__(**kw)
 
     # The logic of the next three methods is chosen such that it is possible to
diff --git a/Lib/test/test_email/test__headerregistry.py b/Lib/test/test_email/test_headerregistry.py
index 23bc5ff..fa8fd97 100644
--- a/Lib/test/test_email/test__headerregistry.py
+++ b/Lib/test/test_email/test_headerregistry.py
@@ -5,72 +5,71 @@ from email import errors
 from email import policy
 from email.message import Message
 from test.test_email import TestEmailBase
-from email import _headerregistry
-# Address and Group are public but I'm not sure where to put them yet.
-from email._headerregistry import Address, Group
+from email import headerregistry
+from email.headerregistry import Address, Group
 
 
 class TestHeaderRegistry(TestEmailBase):
 
     def test_arbitrary_name_unstructured(self):
-        factory = _headerregistry.HeaderRegistry()
+        factory = headerregistry.HeaderRegistry()
         h = factory('foobar', 'test')
-        self.assertIsInstance(h, _headerregistry.BaseHeader)
-        self.assertIsInstance(h, _headerregistry.UnstructuredHeader)
+        self.assertIsInstance(h, headerregistry.BaseHeader)
+        self.assertIsInstance(h, headerregistry.UnstructuredHeader)
 
     def test_name_case_ignored(self):
-        factory = _headerregistry.HeaderRegistry()
+        factory = headerregistry.HeaderRegistry()
         # Whitebox check that test is valid
         self.assertNotIn('Subject', factory.registry)
         h = factory('Subject', 'test')
-        self.assertIsInstance(h, _headerregistry.BaseHeader)
-        self.assertIsInstance(h, _headerregistry.UniqueUnstructuredHeader)
+        self.assertIsInstance(h, headerregistry.BaseHeader)
+        self.assertIsInstance(h, headerregistry.UniqueUnstructuredHeader)
 
     class FooBase:
         def __init__(self, *args, **kw):
             pass
 
     def test_override_default_base_class(self):
-        factory = _headerregistry.HeaderRegistry(base_class=self.FooBase)
+        factory = headerregistry.HeaderRegistry(base_class=self.FooBase)
         h = factory('foobar', 'test')
         self.assertIsInstance(h, self.FooBase)
-        self.assertIsInstance(h, _headerregistry.UnstructuredHeader)
+        self.assertIsInstance(h, headerregistry.UnstructuredHeader)
 
     class FooDefault:
-        parse = _headerregistry.UnstructuredHeader.parse
+        parse = headerregistry.UnstructuredHeader.parse
 
     def test_override_default_class(self):
-        factory = _headerregistry.HeaderRegistry(default_class=self.FooDefault)
+        factory = headerregistry.HeaderRegistry(default_class=self.FooDefault)
         h = factory('foobar', 'test')
-        self.assertIsInstance(h, _headerregistry.BaseHeader)
+        self.assertIsInstance(h, headerregistry.BaseHeader)
         self.assertIsInstance(h, self.FooDefault)
 
     def test_override_default_class_only_overrides_default(self):
-        factory = _headerregistry.HeaderRegistry(default_class=self.FooDefault)
+        factory = headerregistry.HeaderRegistry(default_class=self.FooDefault)
         h = factory('subject', 'test')
-        self.assertIsInstance(h, _headerregistry.BaseHeader)
-        self.assertIsInstance(h, _headerregistry.UniqueUnstructuredHeader)
+        self.assertIsInstance(h, headerregistry.BaseHeader)
+        self.assertIsInstance(h, headerregistry.UniqueUnstructuredHeader)
 
     def test_dont_use_default_map(self):
-        factory = _headerregistry.HeaderRegistry(use_default_map=False)
+        factory = headerregistry.HeaderRegistry(use_default_map=False)
         h = factory('subject', 'test')
-        self.assertIsInstance(h, _headerregistry.BaseHeader)
-        self.assertIsInstance(h, _headerregistry.UnstructuredHeader)
+        self.assertIsInstance(h, headerregistry.BaseHeader)
+        self.assertIsInstance(h, headerregistry.UnstructuredHeader)
 
     def test_map_to_type(self):
-        factory = _headerregistry.HeaderRegistry()
+        factory = headerregistry.HeaderRegistry()
         h1 = factory('foobar', 'test')
-        factory.map_to_type('foobar', _headerregistry.UniqueUnstructuredHeader)
+        factory.map_to_type('foobar', headerregistry.UniqueUnstructuredHeader)
         h2 = factory('foobar', 'test')
-        self.assertIsInstance(h1, _headerregistry.BaseHeader)
-        self.assertIsInstance(h1, _headerregistry.UnstructuredHeader)
-        self.assertIsInstance(h2, _headerregistry.BaseHeader)
-        self.assertIsInstance(h2, _headerregistry.UniqueUnstructuredHeader)
+        self.assertIsInstance(h1, headerregistry.BaseHeader)
+        self.assertIsInstance(h1, headerregistry.UnstructuredHeader)
+        self.assertIsInstance(h2, headerregistry.BaseHeader)
+        self.assertIsInstance(h2, headerregistry.UniqueUnstructuredHeader)
 
 
 class TestHeaderBase(TestEmailBase):
 
-    factory = _headerregistry.HeaderRegistry()
+    factory = headerregistry.HeaderRegistry()
 
     def make_header(self, name, value):
         return self.factory(name, value)
@@ -149,13 +148,13 @@ class TestDateHeader(TestHeaderBase):
 
     def test_date_header_properties(self):
         h = self.make_header('date', self.datestring)
-        self.assertIsInstance(h, _headerregistry.UniqueDateHeader)
+        self.assertIsInstance(h, headerregistry.UniqueDateHeader)
         self.assertEqual(h.max_count, 1)
         self.assertEqual(h.defects, ())
 
     def test_resent_date_header_properties(self):
         h = self.make_header('resent-date', self.datestring)
-        self.assertIsInstance(h, _headerregistry.DateHeader)
+        self.assertIsInstance(h, headerregistry.DateHeader)
         self.assertEqual(h.max_count, None)
         self.assertEqual(h.defects, ())
 
diff --git a/Lib/test/test_email/test_pickleable.py b/Lib/test/test_email/test_pickleable.py
index e4c77ca..9ebf933 100644
--- a/Lib/test/test_email/test_pickleable.py
+++ b/Lib/test/test_email/test_pickleable.py
@@ -4,7 +4,7 @@ import copy
 import pickle
 from email import policy
 from email import message_from_string
-from email._headerregistry import HeaderRegistry
+from email.headerregistry import HeaderRegistry
 from test.test_email import TestEmailBase
 
 class TestPickleCopyHeader(TestEmailBase):
diff --git a/Lib/test/test_email/test_policy.py b/Lib/test/test_email/test_policy.py
index 45a7666..983bd49 100644
--- a/Lib/test/test_email/test_policy.py
+++ b/Lib/test/test_email/test_policy.py
@@ -5,7 +5,7 @@ import unittest
 import email.policy
 import email.parser
 import email.generator
-from email import _headerregistry
+from email import headerregistry
 
 def make_defaults(base_defaults, differences):
     defaults = base_defaults.copy()
@@ -185,11 +185,11 @@ class PolicyAPITests(unittest.TestCase):
     def test_default_header_factory(self):
         h = email.policy.default.header_factory('Test', 'test')
         self.assertEqual(h.name, 'Test')
-        self.assertIsInstance(h, _headerregistry.UnstructuredHeader)
-        self.assertIsInstance(h, _headerregistry.BaseHeader)
+        self.assertIsInstance(h, headerregistry.UnstructuredHeader)
+        self.assertIsInstance(h, headerregistry.BaseHeader)
 
     class Foo:
-        parse = _headerregistry.UnstructuredHeader.parse
+        parse = headerregistry.UnstructuredHeader.parse
 
     def test_each_Policy_gets_unique_factory(self):
         policy1 = email.policy.EmailPolicy()
@@ -197,10 +197,10 @@ class PolicyAPITests(unittest.TestCase):
         policy1.header_factory.map_to_type('foo', self.Foo)
         h = policy1.header_factory('foo', 'test')
         self.assertIsInstance(h, self.Foo)
-        self.assertNotIsInstance(h, _headerregistry.UnstructuredHeader)
+        self.assertNotIsInstance(h, headerregistry.UnstructuredHeader)
         h = policy2.header_factory('foo', 'test')
         self.assertNotIsInstance(h, self.Foo)
-        self.assertIsInstance(h, _headerregistry.UnstructuredHeader)
+        self.assertIsInstance(h, headerregistry.UnstructuredHeader)
 
     def test_clone_copies_factory(self):
         policy1 = email.policy.EmailPolicy()