Skip to content

Commit f4b3dd5

Browse files
miss-islingtonserhiy-storchakaclaude
authored
[3.15] gh-63121: Refresh imaplib capabilities on state changes (GH-152752) (GH-152854)
imaplib fetched the server capabilities only once, at connection time. They are now also refreshed after a successful LOGIN or AUTHENTICATE, from the CAPABILITY response the server sent or, if it sent none, by querying it. This lets methods such as enable() see capabilities added after login, for example ENABLE on Gmail (gh-103451). Capabilities advertised in the server greeting are now used too, saving a redundant CAPABILITY command. (cherry picked from commit c89b72a) Co-authored-by: Serhiy Storchaka <storchaka@gmail.com> Co-authored-by: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
1 parent 0ab38f4 commit f4b3dd5

3 files changed

Lines changed: 87 additions & 2 deletions

File tree

‎Lib/imaplib.py‎

Lines changed: 12 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -255,7 +255,7 @@ def _connect(self):
255255
else:
256256
raise self.error(self.welcome)
257257

258-
self._get_capabilities()
258+
self._refresh_capabilities()
259259
if __debug__:
260260
if self.debug >= 3:
261261
self._mesg('CAPABILITIES: %r' % (self.capabilities,))
@@ -533,6 +533,7 @@ def authenticate(self, mechanism, authobject):
533533
if typ != 'OK':
534534
raise self.error(dat[-1].decode('utf-8', 'replace'))
535535
self.state = 'AUTH'
536+
self._refresh_capabilities()
536537
return typ, dat
537538

538539

@@ -714,6 +715,7 @@ def login(self, user, password):
714715
if typ != 'OK':
715716
raise self.error(dat[-1].decode('UTF-8', 'replace'))
716717
self.state = 'AUTH'
718+
self._refresh_capabilities()
717719
return typ, dat
718720

719721

@@ -1201,6 +1203,15 @@ def _get_capabilities(self):
12011203
self.capabilities = tuple(dat.split())
12021204

12031205

1206+
def _refresh_capabilities(self):
1207+
# Use a CAPABILITY response sent by the server, or ask for it.
1208+
if 'CAPABILITY' in self.untagged_responses:
1209+
dat = self.untagged_responses.pop('CAPABILITY')[-1]
1210+
self.capabilities = tuple(str(dat, self._encoding).upper().split())
1211+
else:
1212+
self._get_capabilities()
1213+
1214+
12041215
def _get_response(self, start_timeout=False):
12051216

12061217
# Read response and store.

‎Lib/test/test_imaplib.py‎

Lines changed: 68 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -136,9 +136,11 @@ def _send_textline(self, message):
136136
def _send_tagged(self, tag, code, message):
137137
self._send_textline(' '.join((tag, code, message)))
138138

139+
welcome = '* OK IMAP4rev1'
140+
139141
def handle(self):
140142
# Send a welcome message.
141-
self._send_textline('* OK IMAP4rev1')
143+
self._send_textline(self.welcome)
142144
while 1:
143145
# Gather up input until we receive a line terminator or we timeout.
144146
# Accumulate read(1) because it's simpler to handle the differences
@@ -634,6 +636,71 @@ def test_login(self):
634636
self.assertEqual(data[0], b'LOGIN completed')
635637
self.assertEqual(client.state, 'AUTH')
636638

639+
def test_login_capabilities(self):
640+
# A server may advertise new capabilities after login (as an
641+
# untagged CAPABILITY response); imaplib must refresh its cached
642+
# capability list (gh-63121, gh-103451).
643+
class CapabilityLoginHandler(SimpleIMAPHandler):
644+
def cmd_LOGIN(self, tag, args):
645+
self.server.logged = args[0]
646+
self._send_textline('* CAPABILITY IMAP4rev1 ENABLE UTF8=ACCEPT')
647+
self._send_tagged(tag, 'OK', 'LOGIN completed')
648+
def cmd_ENABLE(self, tag, args):
649+
self._send_tagged(tag, 'OK', 'ENABLE completed')
650+
651+
client, _ = self._setup(CapabilityLoginHandler)
652+
self.assertNotIn('ENABLE', client.capabilities)
653+
client.login('user', 'pass')
654+
self.assertIn('ENABLE', client.capabilities)
655+
self.assertIn('UTF8=ACCEPT', client.capabilities)
656+
typ, _ = client.enable('UTF8=ACCEPT')
657+
self.assertEqual(typ, 'OK')
658+
659+
def test_authenticate_capabilities(self):
660+
# Capabilities are also refreshed after AUTHENTICATE, here from a
661+
# CAPABILITY response code in the tagged OK response.
662+
class CapabilityAuthHandler(SimpleIMAPHandler):
663+
def cmd_AUTHENTICATE(self, tag, args):
664+
self._send_textline('+')
665+
self.server.response = yield
666+
self._send_tagged(
667+
tag, 'OK',
668+
'[CAPABILITY IMAP4rev1 ENABLE] AUTHENTICATE completed')
669+
670+
client, _ = self._setup(CapabilityAuthHandler)
671+
self.assertNotIn('ENABLE', client.capabilities)
672+
client.authenticate('MYAUTH', lambda x: b'fake')
673+
self.assertIn('ENABLE', client.capabilities)
674+
675+
def test_greeting_capabilities(self):
676+
# Capabilities advertised in the greeting are used directly,
677+
# without sending a separate CAPABILITY command.
678+
class GreetingHandler(SimpleIMAPHandler):
679+
welcome = '* OK [CAPABILITY IMAP4rev1 ENABLE] Server ready'
680+
def cmd_CAPABILITY(self, tag, args):
681+
self.server.capability_queried = True
682+
super().cmd_CAPABILITY(tag, args)
683+
684+
client, server = self._setup(GreetingHandler)
685+
self.assertEqual(client.capabilities, ('IMAP4REV1', 'ENABLE'))
686+
self.assertFalse(getattr(server, 'capability_queried', False))
687+
688+
def test_login_requery_capabilities(self):
689+
# If the server does not advertise capabilities after login,
690+
# imaplib re-queries them (as it does after STARTTLS), so a
691+
# capability that becomes available only after authentication is
692+
# still recognized (gh-63121).
693+
class RequeryHandler(SimpleIMAPHandler):
694+
def cmd_CAPABILITY(self, tag, args):
695+
caps = 'IMAP4rev1 ENABLE' if self.server.logged else 'IMAP4rev1'
696+
self._send_textline('* CAPABILITY ' + caps)
697+
self._send_tagged(tag, 'OK', 'CAPABILITY completed')
698+
699+
client, _ = self._setup(RequeryHandler)
700+
self.assertNotIn('ENABLE', client.capabilities)
701+
client.login('user', 'pass')
702+
self.assertIn('ENABLE', client.capabilities)
703+
637704
def test_logout(self):
638705
client, _ = self._setup(SimpleIMAPHandler)
639706
typ, data = client.login('user', 'pass')

‎Misc/NEWS.d/next/Library/2026-07-01-10-30-00.gh-issue-63121.Rm4tZp.rst‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
:mod:`imaplib` now refreshes the cached capability list after a successful
2+
:meth:`~imaplib.IMAP4.login` or :meth:`~imaplib.IMAP4.authenticate`, using
3+
the ``CAPABILITY`` response sent by the server or, if none was sent, by
4+
querying it, so that capabilities that become available only after
5+
authentication (such as ``ENABLE`` on Gmail) are recognized. Capabilities
6+
advertised in the server greeting are now also used, avoiding a redundant
7+
``CAPABILITY`` command.

0 commit comments

Comments
 (0)