Skip to content

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

Merged
gvanrossum merged 1 commit into
python:mainfrom
savagemechanic:gh-67512-document-imaplib-append-flags
May 16, 2026
Merged

gh-67512: Document IMAP4.append() flags argument#149907
gvanrossum merged 1 commit into
python:mainfrom
savagemechanic:gh-67512-document-imaplib-append-flags

Conversation

@savagemechanic

@savagemechanic savagemechanic commented May 16, 2026 •
edited by bedevere-app Bot
Loading

Copy link
Copy Markdown
Contributor

Clarify the type and format expected for the flags argument to imaplib.IMAP4.append().

The current documentation names the argument but does not explain that it should be an IMAP flag string. This can lead readers to pass a Python tuple or list of flags, which does not match the API. The updated text documents that flags may be None or a string of IMAP flag tokens, shows a multi-flag example, and notes that parentheses are added automatically when omitted.

Docs-only change.

Testing:

  • make -C Doc check
  • ./Doc/venv/bin/pre-commit run sphinx-lint --files Doc/library/imaplib.rst

@savagemechanic savagemechanic requested a review from a team as a code owner May 16, 2026 02:28
@python-cla-bot

python-cla-bot Bot commented May 16, 2026 •
edited
Loading

Copy link
Copy Markdown

All commit authors signed the Contributor License Agreement.

CLA signed

@bedevere-app bedevere-app Bot added docs Documentation in the Doc dir skip news labels May 16, 2026
@bedevere-app bedevere-app Bot mentioned this pull request May 16, 2026
Closed
@github-project-automation github-project-automation Bot moved this to Todo in Docs PRs May 16, 2026
@read-the-docs-community

read-the-docs-community Bot commented May 16, 2026 •
edited
Loading

Copy link
Copy Markdown

Documentation build overview

📚 cpython-previews | 🛠️ Build #32714101 | 📁 Comparing 43ef5ad against main (e56ae81)

  🔍 Preview build  

1 file changed
± library/imaplib.html

@savagemechanic savagemechanic force-pushed the gh-67512-document-imaplib-append-flags branch from 2cdbe5e to 43ef5ad Compare May 16, 2026 02:40
gvanrossum
gvanrossum approved these changes May 16, 2026
View reviewed changes

@gvanrossum gvanrossum left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Thanks! This looks like a good improvement -- there's no way to guess what to pass from the docs otherwise.

@gvanrossum gvanrossum merged commit 5f8d9d3 into python:main May 16, 2026
34 checks passed
@github-project-automation github-project-automation Bot moved this from Todo to Done in Docs PRs May 16, 2026
@serhiy-storchaka serhiy-storchaka added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes needs backport to 3.15 pre-release feature fixes, bugs and security fixes labels Jul 5, 2026
@miss-islington-app

miss-islington-app Bot commented Jul 5, 2026

Copy link
Copy Markdown

Thanks @savagemechanic for the PR, and @gvanrossum for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

@miss-islington-app

miss-islington-app Bot commented Jul 5, 2026

Copy link
Copy Markdown

Thanks @savagemechanic for the PR, and @gvanrossum for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

@miss-islington-app

miss-islington-app Bot commented Jul 5, 2026

Copy link
Copy Markdown

Thanks @savagemechanic for the PR, and @gvanrossum for merging it 🌮🎉.. I'm working now to backport this PR to: 3.15.
🐍🍒⛏🤖

@bedevere-app

bedevere-app Bot commented Jul 5, 2026

Copy link
Copy Markdown

GH-153076 is a backport of this pull request to the 3.14 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.14 bugs and security fixes label Jul 5, 2026
@bedevere-app

bedevere-app Bot commented Jul 5, 2026

Copy link
Copy Markdown

GH-153077 is a backport of this pull request to the 3.13 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.13 bugs and security fixes label Jul 5, 2026
@bedevere-app

bedevere-app Bot commented Jul 5, 2026

Copy link
Copy Markdown

GH-153078 is a backport of this pull request to the 3.15 branch.

@bedevere-app bedevere-app Bot removed the needs backport to 3.15 pre-release feature fixes, bugs and security fixes label Jul 5, 2026
serhiy-storchaka pushed a commit that referenced this pull request Jul 5, 2026
@miss-islington @savagemechanic
[3.13] gh-67512: Document IMAP4.append() flags argument (GH-149907) (G…
b8885ec 
…H-153077)

(cherry picked from commit 5f8d9d3)

Co-authored-by: Savage Mechanic <savagemechanic@github.com>
serhiy-storchaka pushed a commit that referenced this pull request Jul 5, 2026
@miss-islington @savagemechanic
[3.14] gh-67512: Document IMAP4.append() flags argument (GH-149907) (G…
bf32ccf 
…H-153076)

(cherry picked from commit 5f8d9d3)

Co-authored-by: Savage Mechanic <savagemechanic@github.com>
serhiy-storchaka pushed a commit that referenced this pull request Jul 5, 2026
@miss-islington @savagemechanic
[3.15] gh-67512: Document IMAP4.append() flags argument (GH-149907) (G…
f09f5dc 
…H-153078)

(cherry picked from commit 5f8d9d3)

Co-authored-by: Savage Mechanic <savagemechanic@github.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@gvanrossum gvanrossum gvanrossum approved these changes

Assignees

No one assigned

Labels

docs Documentation in the Doc dir skip news

Projects

Docs PRs
Status: Done

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@savagemechanic @gvanrossum @serhiy-storchaka