[doc] mention that flags arg to imaplib's append should be a string

@ericvsmith

BPO	23323
Nosy	@ericvsmith, @bitdancer, @slateny

^{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:

assignee = None
closed_at = None
created_at = <Date 2015-01-26.12:41:03.391>
labels = ['easy', '3.11', 'type-feature', 'docs']
title = "[doc] mention that flags arg to imaplib's append should be a string"
updated_at = <Date 2022-03-01.09:57:22.397>
user = 'https://bugs.python.org/Pilessio'

bugs.python.org fields:

activity = <Date 2022-03-01.09:57:22.397>
actor = 'slateny'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2015-01-26.12:41:03.391>
creator = 'Pilessio'
dependencies = []
files = []
hgrepos = []
issue_num = 23323
keywords = ['easy']
message_count = 4.0
messages = ['234738', '234739', '234743', '414251']
nosy_count = 5.0
nosy_names = ['eric.smith', 'r.david.murray', 'docs@python', 'Pilessio', 'slateny']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'needs patch'
status = 'open'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue23323'
versions = ['Python 3.11']

Linked PRs

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/imaplib.py 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?

Thanks

flags is supposed to be a string. This is not well documented, like much of the module.

Try:
flags = r'(\Answered \Seen)'

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.

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 https://datatracker.ietf.org/doc/html/rfc3501#section-2.3.2

Hey! I am a beginner, can someone please tell where exactly the changes have to be made?

@Rajendra1308

@Rajendra1308 The changes should be made to https://docs.python.org/3/library/imaplib.html#imaplib.IMAP4.append

You can click "Show Source" on the left of the page to see the .rst page that needs modifying, and can compare with how the following IMAP4.authenticate() method documents arguments.

See https://devguide.python.org/ for advice on contributing, and https://devguide.python.org/documentation/start-documenting/ for building docs.

Hey, here's the screenshot of the fix I made and tested in the virtual environment

When I try to run tests, I get this error. Can you please help. It's my first time running tests.

Patchcheck needs to be run with a version of Python that you've built yourself in the repo.

For a docs change, you can skip this, especially as compiling on Windows is a bit harder to setup. Instead, go ahead and create a PR and we can check what the CI says.

@hugovk

Hey @hugovk Please check the PR and let me know if it's okay, it's the first one, please suggest any changes or provide advice if needed. :)

@hugovk

Hey @hugovk Please check the new PR and let me know if it's okay, please suggest any changes if needed :)

gh-67512: Document IMAP4.append() flags argument (#149907)

[3.13] gh-67512: Document IMAP4.append() flags argument (GH-149907) (G…

[3.14] gh-67512: Document IMAP4.append() flags argument (GH-149907) (G…

[3.15] gh-67512: Document IMAP4.append() flags argument (GH-149907) (G…

Navigation Menu

Repository navigation

[doc] mention that flags arg to imaplib's append should be a string #67512

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

[doc] mention that flags arg to imaplib's append should be a string #67512

Description

Linked PRs

Activity

Pilessio commented on Jan 26, 2015

ericvsmith commented on Jan 26, 2015

bitdancer commented on Jan 26, 2015

slateny commented on Mar 1, 2022

Rajendra1308 commented on Dec 24, 2023

hugovk commented on Dec 25, 2023

Rajendra1308 commented on Dec 26, 2023

hugovk commented on Dec 26, 2023

Rajendra1308 commented on Dec 26, 2023

Rajendra1308 commented on Dec 27, 2023

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions