This issue tracker has been migrated to GitHub, and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

Title: [doc] mention that flags arg to imaplib's append should be a string
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.11
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Pilessio, docs@python, eric.smith, r.david.murray, slateny
Priority: normal Keywords: easy

Created on 2015-01-26 12:41 by Pilessio, last changed 2022-04-11 14:58 by admin.

Messages (4)
msg234738 - (view) Author: Alessio (Pilessio) Date: 2015-01-26 12:41
In example when appending a message with more than one flag in a tuple with imaplib:

print flags
('\\Answered', '\\Seen')

connection.append('INBOX', flags, date, msg)

TypeError                                 Traceback (most recent call last)
<ipython-input-42-832414ffe4b5> in <module>()
----> 1 connection.append('INBOX', flags, date, msg[1][0][1])

/usr/lib/python2.7/ in append(self, mailbox, flags, date_time, message)
    326         if flags:
    327             if (flags[0],flags[-1]) != ('(',')'):
--> 328                 flags = '(%s)' % flags
    329         else:
    330             flags = None

TypeError: not all arguments converted during string formatting

When I have only one flag to append:

print flags
Out[70]: ('\\Answered',)

connection.append('INBOX', flags, date, msg)
Out[74]: ('OK', ['[APPENDUID 1 1012] APPEND completed'])

Any ideas?

msg234739 - (view) Author: Eric V. Smith (eric.smith) * (Python committer) Date: 2015-01-26 13:04
flags is supposed to be a string. This is not well documented, like much of the module.

flags = r'(\Answered \Seen)'
msg234743 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-01-26 14:04
Indeed, as with much of the early email related code in the stdlib, the documentation assumes way too much familiarity with the relevant RFC...which is really hard to read.  We should add a few more details to the docs (like FLAGS being a string) even if we don't have the resources to do a full overhaul.
msg414251 - (view) Author: Stanley (slateny) * Date: 2022-03-01 09:57
How would this sound as clarification for the flags argument?

*flags* is a space-separated string containing IMAP flags tokens. Must start with ``\``.

Perhaps optionally also provide the list of system flags as given in
Date User Action Args
2022-04-11 14:58:12adminsetgithub: 67512
2022-03-01 09:57:22slatenysetnosy: + slateny
messages: + msg414251
2021-11-27 12:22:00iritkatrielsetkeywords: + easy
title: Issue with imaplib and append messages passing a tuple with flags -> [doc] mention that flags arg to imaplib's append should be a string
type: enhancement
versions: + Python 3.11, - Python 2.7, Python 3.4, Python 3.5
2015-01-26 14:04:31r.david.murraysetassignee: docs@python
components: + Documentation, - Library (Lib)
versions: + Python 3.4, Python 3.5
nosy: + docs@python, r.david.murray

messages: + msg234743
stage: needs patch
2015-01-26 13:04:22eric.smithsetnosy: + eric.smith
messages: + msg234739
2015-01-26 12:41:03Pilessiocreate