From b8cd3e4e30d3219ecf00ce7f114a15746561ea87 Mon Sep 17 00:00:00 2001
From: R David Murray <rdmurray@bitdance.com>
Date: Sat, 16 May 2015 15:05:53 -0400
Subject: #21804: Add RFC 6856 (UTF8) support to poplib.

Patch by Milan Oberkirch.
---
 Doc/library/poplib.rst  |  9 +++++++++
 Doc/whatsnew/3.5.rst    |  7 +++++++
 Lib/poplib.py           |  7 +++++++
 Lib/test/test_poplib.py | 16 ++++++++++++++++
 Misc/NEWS               |  2 ++
 5 files changed, 41 insertions(+)

diff --git a/Doc/library/poplib.rst b/Doc/library/poplib.rst
index 45baad9..fee6298 100644
--- a/Doc/library/poplib.rst
+++ b/Doc/library/poplib.rst
@@ -194,6 +194,15 @@ An :class:`POP3` instance has the following methods:
    the unique id for that message in the form ``'response mesgnum uid``, otherwise
    result is list ``(response, ['mesgnum uid', ...], octets)``.
 
+
+.. method:: POP3.utf8()
+
+   Try to switch to UTF-8 mode. Returns the server response if sucessful,
+   raises :class:`error_proto` if not. Specified in :RFC:`6856`.
+
+   .. versionadded:: 3.5
+
+
 .. method:: POP3.stls(context=None)
 
    Start a TLS session on the active connection as specified in :rfc:`2595`.
diff --git a/Doc/whatsnew/3.5.rst b/Doc/whatsnew/3.5.rst
index 86173a0..6411667 100644
--- a/Doc/whatsnew/3.5.rst
+++ b/Doc/whatsnew/3.5.rst
@@ -452,6 +452,13 @@ pickle
   classes) now are supported with pickle protocols < 4.
   (Contributed by Serhiy Storchaka in :issue:`23611`.)
 
+poplib
+------
+
+* A new command :meth:`~poplib.POP3.utf8` enables :rfc:`6856`
+  (internationalized email) support if the POP server supports it.  (Contributed
+  by Milan OberKirch in :issue:`21804`.)
+
 re
 --
 
diff --git a/Lib/poplib.py b/Lib/poplib.py
index 4915628..f672390 100644
--- a/Lib/poplib.py
+++ b/Lib/poplib.py
@@ -71,6 +71,7 @@ class POP3:
             UIDL [msg]              uidl(msg = None)
             CAPA                    capa()
             STLS                    stls()
+            UTF8                    utf8()
 
     Raises one exception: 'error_proto'.
 
@@ -348,6 +349,12 @@ class POP3:
         return self._longcmd('UIDL')
 
 
+    def utf8(self):
+        """Try to enter UTF-8 mode (see RFC 6856). Returns server response.
+        """
+        return self._shortcmd('UTF8')
+
+
     def capa(self):
         """Return server capabilities (RFC 2449) as a dictionary
         >>> c=poplib.POP3('localhost')
diff --git a/Lib/test/test_poplib.py b/Lib/test/test_poplib.py
index 14a519d..bceeb93 100644
--- a/Lib/test/test_poplib.py
+++ b/Lib/test/test_poplib.py
@@ -44,6 +44,7 @@ line3\r\n\
 class DummyPOP3Handler(asynchat.async_chat):
 
     CAPAS = {'UIDL': [], 'IMPLEMENTATION': ['python-testlib-pop-server']}
+    enable_UTF8 = False
 
     def __init__(self, conn):
         asynchat.async_chat.__init__(self, conn)
@@ -142,6 +143,11 @@ class DummyPOP3Handler(asynchat.async_chat):
                 self.push(' '.join(_ln))
         self.push('.')
 
+    def cmd_utf8(self, arg):
+        self.push('+OK I know RFC6856'
+                  if self.enable_UTF8
+                  else '-ERR What is UTF8?!')
+
     if SUPPORTS_SSL:
 
         def cmd_stls(self, arg):
@@ -309,6 +315,16 @@ class TestPOP3Class(TestCase):
         self.client.uidl()
         self.client.uidl('foo')
 
+    def test_utf8_raises_if_unsupported(self):
+        self.server.handler.enable_UTF8 = False
+        self.assertRaises(poplib.error_proto, self.client.utf8)
+
+    def test_utf8(self):
+        self.server.handler.enable_UTF8 = True
+        expected = b'+OK I know RFC6856'
+        result = self.client.utf8()
+        self.assertEqual(result, expected)
+
     def test_capa(self):
         capa = self.client.capa()
         self.assertTrue('IMPLEMENTATION' in capa.keys())
diff --git a/Misc/NEWS b/Misc/NEWS
index 1b23a98..3d59983 100644
--- a/Misc/NEWS
+++ b/Misc/NEWS
@@ -47,6 +47,8 @@ Core and Builtins
 Library
 -------
 
+- Issue #21804: poplib now supports RFC 6856 (UTF8).
+
 - Issue #18682: Optimized pprint functions for builtin scalar types.
 
 - Issue #22027: smtplib now supports RFC 6531 (SMTPUTF8).
-- 
cgit v0.12