Repository navigation
IMAP library lacks documentation about expected parameter types #68215
Description
Activity
pmoleri commented
on Apr 22, 2015 pmolerimannequinMannequinAuthorI used the IMAP library and I feel it lacks a lot of documentation regarding types and encoding.
Example:
IMAP4.list([directory[, pattern]]):
It doesn't state if it expects the directory argument to be an string (unicode) or a imap_utf7 encoded string or bytes.
It also expects names with spaces to be between double quotation marks and it doesn't state that it returns a bytes raw output.This is valid for every function that receives a directory or mailbox argument. Also for most return values.
Documentation aside, I think it would be a nice improvement in the implementation to add an imap_utf7 convertion function, and check every directory or mailbox argument to see if it has characters outside the imap_utf7 charset and attempts to convert them automatically.
Documentation patches are welcome. imaplib has not seen much attention for quite some time (though there is currently someone interested in working on it, so that may change).
Please open a separate issue for the utf7 enhancement proposal.
mcepl commented
on Apr 21, 2018 mceplmannequinMannequinUTF-7 is tackled in https://bugs.python.org/issue5305
Regarding double-quoting, the general rule implied by https://docs.python.org/3/library/imaplib.html#imap4-objects for almost all command arguments is the command methods sometimes quote their arguments (e.g. if they contain spaces), but not if they already look like a quoted string or parenthesized list. However this quoting functionality was accidentally removed (Issue #92835). And the caller always had to do their own quoting anyway if the raw argument value happens to be enclosed in quotes or brackets.
It might be worth specifying what IMAP syntax is required for directory and mailbox arguments (presumably the mailbox rule).
Regarding return values, the general rule does say the data items are either bytes or tuples. It seems that each bytes item is based on an IMAP server response (tagged status or untagged data), while the tuples may be 2-tuples involving IMAP literal strings. The “header” seems to be based on the IMAP response that precedes the literal, including the {number} prefix of the literal, but excluding the CRLF. The tuple might be followed by more tuples, and then a final bytes item, all corresponding to one untagged server data response.
It seems these returned items aren’t always pure raw IMAP protocol. FETCH responses seem to have the initial asterisk and trailing CRLF removed, as well as the FETCH atom and a space removed from the middle of the string. Here is a single FETCH response returned as two lines including a literal string. You can see how the first line doesn’t quite match the IMAP protocol from the raw debug log.
>>> M.fetch('1', '(BODY.PEEK[HEADER.FIELDS (DATE)])') 56:52.30 > b'NMFB14 FETCH 1 (BODY.PEEK[HEADER.FIELDS (DATE)])' 56:52.68 < b'* 1 FETCH (BODY[HEADER.FIELDS (DATE)] {41}' 56:52.68 read literal size 41 56:52.68 < b')' 56:52.68 < b'NMFB14 OK Success' ('OK', [(b'1 (BODY[HEADER.FIELDS (DATE)] {41}', b'Date: Fri, 17 Sep 2004 11:56:09 +1000\r\n\r\n'), b')'])
Similarly, EXPUNGE responses seem to be just the message number from the protocol, with the asterisk, EXPUNGE and CRLF removed:
>>> M.noop() 15:50.85 > b'NMFB22 NOOP' 15:51.18 < b'* 887 EXPUNGE' 15:51.18 < b'* 886 EXISTS' 15:51.18 < b'NMFB22 OK Success' ('OK', [b'Success']) >>> M.response('EXPUNGE') ('EXPUNGE', [b'887'])
I’ve also seen the list [None] being returned as the data list, where I would expect an empty list. This might be hinted at in the response method documentation, but it is not clear enough, and doesn’t seem limited to that method.
>>> NONEXISTENT_UID = '999999' >>> M.uid('FETCH', NONEXISTENT_UID, '(FLAGS)') 40:06.75 > b'NMFB24 UID FETCH 999999 (FLAGS)' 40:07.13 < b'NMFB24 OK Success' ('OK', [None])
Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.
Show more details
GitHub fields:
bugs.python.org fields: