Document bytes-like input and bytes return values for imaplib response helpers

[savagemechanic]

Documentation

The documentation for imaplib.Internaldate2tuple() and imaplib.ParseFlags() does not clearly state the Python-level input and output types for these helpers.

Both functions parse IMAP protocol response data, and the implementation uses bytes regexes:

• Internaldate2tuple() matches against the module-level InternalDate bytes pattern.
• ParseFlags() matches against the module-level Flags bytes pattern.

This means bytes-like response data works, while str input raises TypeError.

For example:

>>> import imaplib
>>> imaplib.Internaldate2tuple(
...     b'25 (INTERNALDATE "01-Jan-2000 00:00:00 +0000")'
... )
time.struct_time(...)

>>> imaplib.Internaldate2tuple(
...     '25 (INTERNALDATE "01-Jan-2000 00:00:00 +0000")'
... )
Traceback (most recent call last):
  ...
TypeError: cannot use a bytes pattern on a string-like object

>>> imaplib.ParseFlags(b'* 1 FETCH (FLAGS (\\Seen \\Deleted))')
(b'\\Seen', b'\\Deleted')

>>> imaplib.ParseFlags('* 1 FETCH (FLAGS (\\Seen \\Deleted))')
Traceback (most recent call last):
  ...
TypeError: cannot use a bytes pattern on a string-like object

The current docs say:

• Internaldate2tuple(datestr) parses an IMAP4 INTERNALDATE string.
• ParseFlags(flagstr) converts an IMAP4 FLAGS response to a tuple of individual flags.

This can be read as accepting Python str, especially because the parameter names end in str. It also does not document that ParseFlags() returns a tuple of bytes.

This is not a request to change behavior. The bytes behavior appears intentional for protocol-level response data, and related historical discussion exists in #55156.

Suggested documentation clarification:

• Internaldate2tuple() expects a bytes-like IMAP response containing an INTERNALDATE field.
• ParseFlags() expects a bytes-like IMAP FLAGS response.
• ParseFlags() returns a tuple of bytes.
• Malformed bytes-like input returns None for Internaldate2tuple() and () for ParseFlags(), but passing str raises TypeError.

I would be happy to work on a documentation PR if this clarification makes sense.

Linked PRs

• gh-149930: Clarify imaplib response helper types #149963
• [3.15] gh-149930: Clarify imaplib response helper types (GH-149963) #153123
• [3.14] gh-149930: Clarify imaplib response helper types (GH-149963) #153124
• [3.13] gh-149930: Clarify imaplib response helper types (GH-149963) #153125

[gvanrossum]

I betcha that those docs were essentially never updated since Python 2, where the distinction between strings and bytes did not exist (in the current form).

[savagemechanic]

I betcha that those docs were essentially never updated since Python 2, where the distinction between strings and bytes did not exist (in the current form).

Hahaha that’s funny