Skip to content

Commit fa43bf8

Browse files
committed
gh-80274: Add smtputf8 parameter to smtplib.SMTP.verify() and expn()
1 parent 5f46ac9 commit fa43bf8

5 files changed

Lines changed: 221 additions & 13 deletions

File tree

‎Doc/library/smtplib.rst‎

Lines changed: 41 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -320,17 +320,57 @@ An :class:`SMTP` instance has the following methods:
320320
by the server, :const:`False` otherwise. Case is ignored.
321321

322322

323-
.. method:: SMTP.verify(address)
323+
.. method:: SMTP.verify(address, *, smtputf8=False)
324324

325325
Check the validity of an address on this server using SMTP ``VRFY``. Returns a
326326
tuple consisting of code 250 and a full :rfc:`822` address (including human
327327
name) if the user address is valid. Otherwise returns an SMTP error code of 400
328328
or greater and an error string.
329329

330+
If *smtputf8* is true, the address is sent as UTF-8 together with the
331+
``SMTPUTF8`` parameter (:rfc:`6531`), which also allows UTF-8 in the reply.
332+
In that case, if there has been no previous ``EHLO`` or ``HELO`` command
333+
this session, this method tries ESMTP ``EHLO`` first.
334+
335+
This method may raise the following exceptions:
336+
337+
:exc:`SMTPNotSupportedError`
338+
*smtputf8* is true but the ``SMTPUTF8`` extension is not supported by
339+
the server.
340+
330341
.. note::
331342

332343
Many sites disable SMTP ``VRFY`` in order to foil spammers.
333344

345+
.. versionchanged:: next
346+
Added the *smtputf8* parameter.
347+
348+
349+
.. method:: SMTP.expn(address, *, smtputf8=False)
350+
351+
Expand a mailing list on this server using SMTP ``EXPN``. Returns a tuple
352+
consisting of code 250 and the members of the list, one full :rfc:`822`
353+
address (including human name) per line, if the list exists. Otherwise
354+
returns an SMTP error code of 400 or greater and an error string.
355+
356+
If *smtputf8* is true, the list name is sent as UTF-8 together with the
357+
``SMTPUTF8`` parameter (:rfc:`6531`), which also allows UTF-8 in the reply.
358+
In that case, if there has been no previous ``EHLO`` or ``HELO`` command
359+
this session, this method tries ESMTP ``EHLO`` first.
360+
361+
This method may raise the following exceptions:
362+
363+
:exc:`SMTPNotSupportedError`
364+
*smtputf8* is true but the ``SMTPUTF8`` extension is not supported by
365+
the server.
366+
367+
.. note::
368+
369+
Many sites disable SMTP ``EXPN`` in order to foil spammers.
370+
371+
.. versionchanged:: next
372+
Added the *smtputf8* parameter.
373+
334374

335375
.. method:: SMTP.login(user, password, *, initial_response_ok=True)
336376

‎Doc/whatsnew/3.16.rst‎

Lines changed: 9 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -688,6 +688,15 @@ shutil
688688
(Contributed by Emma Harper Smith and Stan Ulbrych in :gh:`84027`.)
689689

690690

691+
smtplib
692+
-------
693+
694+
* Add the *smtputf8* parameter to :meth:`~smtplib.SMTP.verify` and
695+
:meth:`~smtplib.SMTP.expn` to send non-ASCII addresses to servers that
696+
support the ``SMTPUTF8`` extension (:rfc:`6531`).
697+
(Contributed by Vasiliy Kiryanov in :gh:`80274`.)
698+
699+
691700
socket
692701
------
693702

‎Lib/smtplib.py‎

Lines changed: 40 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -589,16 +589,50 @@ def data(self, msg):
589589
self._print_debug('data:', (code, msg))
590590
return (code, msg)
591591

592-
def verify(self, address):
593-
"""SMTP 'verify' command -- checks for address validity."""
594-
self.putcmd("vrfy", _addr_only(address))
592+
def _putcmd_addr(self, cmd, address, smtputf8):
593+
"""Send an address command (VRFY or EXPN) to the server.
594+
595+
If 'smtputf8' is true, send the address as UTF-8 together with the
596+
SMTPUTF8 parameter.
597+
"""
598+
address = _addr_only(address)
599+
if smtputf8:
600+
self.ehlo_or_helo_if_needed()
601+
if not self.has_extn('smtputf8'):
602+
raise SMTPNotSupportedError('SMTPUTF8 not supported by server')
603+
# RFC 6531 section 3.7.4.2: the argument may be UTF-8, and the
604+
# SMTPUTF8 parameter allows UTF-8 in the reply.
605+
command_encoding = self.command_encoding
606+
self.command_encoding = 'utf-8'
607+
try:
608+
self.putcmd(cmd, f'{address} SMTPUTF8')
609+
finally:
610+
self.command_encoding = command_encoding
611+
else:
612+
self.putcmd(cmd, address)
613+
614+
def verify(self, address, *, smtputf8=False):
615+
"""SMTP 'verify' command - checks for address validity.
616+
617+
If 'smtputf8' is true, send the address as UTF-8 together with the
618+
SMTPUTF8 parameter (per RFC 6531), which also allows UTF-8 in the
619+
reply. In that case, if there has been no previous EHLO or HELO
620+
command this session, this method tries ESMTP EHLO first.
621+
"""
622+
self._putcmd_addr("vrfy", address, smtputf8)
595623
return self.getreply()
596624
# a.k.a.
597625
vrfy = verify
598626

599-
def expn(self, address):
600-
"""SMTP 'expn' command -- expands a mailing list."""
601-
self.putcmd("expn", _addr_only(address))
627+
def expn(self, address, *, smtputf8=False):
628+
"""SMTP 'expn' command - expands a mailing list.
629+
630+
If 'smtputf8' is true, send the list name as UTF-8 together with the
631+
SMTPUTF8 parameter (per RFC 6531), which also allows UTF-8 in the
632+
reply. In that case, if there has been no previous EHLO or HELO
633+
command this session, this method tries ESMTP EHLO first.
634+
"""
635+
self._putcmd_addr("expn", address, smtputf8)
602636
return self.getreply()
603637

604638
# some useful methods

‎Lib/test/test_smtplib.py‎

Lines changed: 128 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -806,13 +806,15 @@ def testLineTooLong(self):
806806
'Ms.B@xn--fo-fka.com':'Sally B',
807807
'Mrs.C@somewhereesle.com':'Ruth C',
808808
}
809+
sim_utf8_users = {'Ms.É@somewhere.com': 'Éva É'}
809810

810811
sim_auth = ('Mr.A@somewhere.com', 'somepassword')
811812
sim_cram_md5_challenge = ('PENCeUxFREJoU0NnbmhNWitOMjNGNn'
812813
'dAZWx3b29kLmlubm9zb2Z0LmNvbT4=')
813814
sim_lists = {'list-1':['Mr.A@somewhere.com','Mrs.C@somewhereesle.com'],
814815
'list-2':['Ms.B@xn--fo-fka.com',],
815816
}
817+
sim_utf8_lists = {'list-é': ['Mr.A@somewhere.com', 'Ms.É@somewhere.com']}
816818

817819
# Simulated SMTP channel & server
818820
class ResponseException(Exception): pass
@@ -949,23 +951,39 @@ def smtp_EHLO(self, arg):
949951
self.seen_greeting = arg
950952
self.extended_smtp = True
951953

954+
def _strip_smtputf8(self, arg):
955+
# RFC 6531 section 3.7.4.2: VRFY and EXPN take an optional SMTPUTF8
956+
# parameter which allows UTF-8 in the reply.
957+
if not arg:
958+
return arg
959+
arg, _, params = arg.partition(' ')
960+
params = self._getparams(params.upper().split())
961+
if params and params.pop('SMTPUTF8', False) is True:
962+
self.require_SMTPUTF8 = True
963+
return arg
964+
952965
def smtp_VRFY(self, arg):
953966
# For max compatibility smtplib should be sending the raw address.
954-
if arg in sim_users:
955-
self.push('250 %s %s' % (sim_users[arg], smtplib.quoteaddr(arg)))
967+
arg = self._strip_smtputf8(arg)
968+
users = sim_users | sim_utf8_users
969+
if arg in users:
970+
self.push('250 %s %s' % (users[arg], smtplib.quoteaddr(arg)))
956971
else:
957972
self.push('550 No such user: %s' % arg)
958973

959974
def smtp_EXPN(self, arg):
975+
arg = self._strip_smtputf8(arg)
960976
list_name = arg.lower()
961-
if list_name in sim_lists:
962-
user_list = sim_lists[list_name]
977+
lists = sim_lists | sim_utf8_lists
978+
users = sim_users | sim_utf8_users
979+
if list_name in lists:
980+
user_list = lists[list_name]
963981
for n, user_email in enumerate(user_list):
964982
quoted_addr = smtplib.quoteaddr(user_email)
965983
if n < len(user_list) - 1:
966-
self.push('250-%s %s' % (sim_users[user_email], quoted_addr))
984+
self.push('250-%s %s' % (users[user_email], quoted_addr))
967985
else:
968-
self.push('250 %s %s' % (sim_users[user_email], quoted_addr))
986+
self.push('250 %s %s' % (users[user_email], quoted_addr))
969987
else:
970988
self.push('550 No access for you!')
971989

@@ -1357,6 +1375,40 @@ def test_send_unicode_without_SMTPUTF8(self):
13571375
self.addCleanup(smtp.close)
13581376
self.assertRaises(UnicodeEncodeError, smtp.sendmail, 'Alice', 'Böb', '')
13591377
self.assertRaises(UnicodeEncodeError, smtp.mail, 'Älice')
1378+
self.assertRaises(UnicodeEncodeError, smtp.verify, 'Ms.É@somewhere.com')
1379+
self.assertRaises(UnicodeEncodeError, smtp.expn, 'list-é')
1380+
1381+
def test_vrfy_NotSupportedError_if_no_SMTPUTF8(self):
1382+
smtp = smtplib.SMTP(
1383+
HOST, self.port, local_hostname='localhost',
1384+
timeout=support.LOOPBACK_TIMEOUT)
1385+
self.addCleanup(smtp.close)
1386+
1387+
smtp.ehlo()
1388+
self.assertFalse(smtp.has_extn('smtputf8'))
1389+
with self.assertRaises(smtplib.SMTPNotSupportedError):
1390+
smtp.vrfy('Mr.A@somewhere.com', smtputf8=True)
1391+
with self.assertRaises(smtplib.SMTPNotSupportedError):
1392+
smtp.vrfy('Ms.É@somewhere.com', smtputf8=True)
1393+
1394+
# Nothing was sent, the connection is still usable
1395+
self.assertEqual(smtp.noop(), (250, b'OK'))
1396+
1397+
def test_expn_NotSupportedError_if_no_SMTPUTF8(self):
1398+
smtp = smtplib.SMTP(
1399+
HOST, self.port, local_hostname='localhost',
1400+
timeout=support.LOOPBACK_TIMEOUT)
1401+
self.addCleanup(smtp.close)
1402+
1403+
smtp.ehlo()
1404+
self.assertFalse(smtp.has_extn('smtputf8'))
1405+
with self.assertRaises(smtplib.SMTPNotSupportedError):
1406+
smtp.expn('list-1', smtputf8=True)
1407+
with self.assertRaises(smtplib.SMTPNotSupportedError):
1408+
smtp.expn('list-é', smtputf8=True)
1409+
1410+
# Nothing was sent, the connection is still usable
1411+
self.assertEqual(smtp.noop(), (250, b'OK'))
13601412

13611413
def test_send_message_error_on_non_ascii_addrs_if_no_smtputf8(self):
13621414
# This test is located here and not in the SMTPUTF8SimTests
@@ -1485,6 +1537,76 @@ def test_send_unicode_with_SMTPUTF8_via_sendmail(self):
14851537
self.assertIn('SMTPUTF8', self.serv.last_mail_options)
14861538
self.assertEqual(self.serv.last_rcpt_options, [])
14871539

1540+
def test_vrfy_with_SMTPUTF8(self):
1541+
smtp = smtplib.SMTP(
1542+
HOST, self.port, local_hostname='localhost',
1543+
timeout=support.LOOPBACK_TIMEOUT)
1544+
self.addCleanup(smtp.close)
1545+
1546+
smtp.ehlo()
1547+
self.assertTrue(smtp.has_extn('smtputf8'))
1548+
self.assertEqual(
1549+
smtp.vrfy('Ms.É@somewhere.com', smtputf8=True),
1550+
(250, 'Éva É <Ms.É@somewhere.com>'.encode('utf-8'))
1551+
)
1552+
# ASCII reply
1553+
self.assertEqual(
1554+
smtp.vrfy('Mr.A@somewhere.com', smtputf8=True),
1555+
(250, b'John A <Mr.A@somewhere.com>')
1556+
)
1557+
# encoding doesn't leak out of a command
1558+
self.assertEqual(smtp.command_encoding, 'ascii')
1559+
self.assertEqual(
1560+
smtp.vrfy('unknown@unknown.com', smtputf8=True),
1561+
(550, b'No such user: unknown@unknown.com')
1562+
)
1563+
# Reply stream still in sync
1564+
self.assertEqual(smtp.noop(), (250, b'OK'))
1565+
1566+
def test_vrfy_smtputf8_ehlo_if_needed(self):
1567+
smtp = smtplib.SMTP(
1568+
HOST, self.port, local_hostname='localhost',
1569+
timeout=support.LOOPBACK_TIMEOUT)
1570+
self.addCleanup(smtp.close)
1571+
1572+
self.assertEqual(
1573+
smtp.vrfy('Ms.É@somewhere.com', smtputf8=True),
1574+
(250, 'Éva É <Ms.É@somewhere.com>'.encode('utf-8'))
1575+
)
1576+
self.assertTrue(smtp.has_extn('smtputf8'))
1577+
# No reply was left unread
1578+
self.assertEqual(smtp.noop(), (250, b'OK'))
1579+
1580+
def test_vrfy_smtputf8_helo_fails(self):
1581+
smtp = smtplib.SMTP(
1582+
HOST, self.port, local_hostname='localhost',
1583+
timeout=support.LOOPBACK_TIMEOUT)
1584+
self.addCleanup(smtp.close)
1585+
1586+
smtp.helo()
1587+
with self.assertRaises(smtplib.SMTPNotSupportedError):
1588+
smtp.vrfy('Mr.A@somewhere.com', smtputf8=True)
1589+
self.assertFalse(smtp.has_extn('smtputf8'))
1590+
# Nothing was sent, the connection is still usable
1591+
self.assertEqual(smtp.noop(), (250, b'OK'))
1592+
1593+
def test_expn_with_SMTPUTF8(self):
1594+
smtp = smtplib.SMTP(
1595+
HOST, self.port, local_hostname='localhost',
1596+
timeout=support.LOOPBACK_TIMEOUT)
1597+
self.addCleanup(smtp.close)
1598+
1599+
smtp.ehlo()
1600+
self.assertTrue(smtp.has_extn('smtputf8'))
1601+
self.assertEqual(
1602+
smtp.expn('list-é', smtputf8=True),
1603+
(250, ('John A <Mr.A@somewhere.com>\n'
1604+
'Éva É <Ms.É@somewhere.com>').encode('utf-8')))
1605+
# Encoding doesn't leak out of a command
1606+
self.assertEqual(smtp.command_encoding, 'ascii')
1607+
# No reply was left unread
1608+
self.assertEqual(smtp.noop(), (250, b'OK'))
1609+
14881610
def test_send_unicode_with_SMTPUTF8_via_low_level_API(self):
14891611
m = '¡a test message containing unicode!'.encode('utf-8')
14901612
smtp = smtplib.SMTP(
Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
Add the *smtputf8* parameter to :meth:`smtplib.SMTP.verify` and
2+
:meth:`smtplib.SMTP.expn` to send non-ASCII addresses to servers that
3+
support the ``SMTPUTF8`` extension (:rfc:`6531`).

0 commit comments

Comments
 (0)