#24277: The new email API is no longer provisional.

This is a wholesale reorganization and editing of the email documentation to
make the new API the standard one, and the old API the 'legacy' one.  The
default is still the compat32 policy, for backward compatibility.  We will
change that eventually.

1 files changed, 14 insertions, 8 deletions

diff --git a/Doc/includes/email-headers.py b/Doc/includes/email-headers.py
index 89c8f3af32..2c421451a8 100644
--- a/Doc/includes/email-headers.py
+++ b/Doc/includes/email-headers.py
@@ -1,18 +1,24 @@
 # Import the email modules we'll need
-from email.parser import Parser
+from email.parser import BytesParser, Parser
+from email.policy import default
 
 # If the e-mail headers are in a file, uncomment these two lines:
-# with open(messagefile) as fp:
-#     headers = Parser().parse(fp)
+# with open(messagefile, 'rb') as fp:
+#     headers = BytesParser(policy=default).parse(fp)
 
-#  Or for parsing headers in a string, use:
-headers = Parser().parsestr('From: <user@example.com>\n'
+#  Or for parsing headers in a string (this is an uncommon operation), use:
+headers = Parser(policy=default).parsestr(
+        'From: Foo Bar <user@example.com>\n'
         'To: <someone_else@example.com>\n'
         'Subject: Test message\n'
         '\n'
         'Body would go here\n')
 
 #  Now the header items can be accessed as a dictionary:
-print('To: %s' % headers['to'])
-print('From: %s' % headers['from'])
-print('Subject: %s' % headers['subject'])
+print('To: {}'.format(headers['to']))
+print('From: {}'.format(headers['from']))
+print('Subject: {}'.format(headers['subject']))
+
+# You can also access the parts of the addresses:
+print('Recipient username: {}'.format(headers['to'].addresses[0].username))
+print('Sender name: {}'.format(headers['from'].addresses[0].display_name))