forestix
September 10, 2024, 4:46pm
1
Hi, all.
Back in July, I found that there was interest in bringing my IMAP IDLE implementation into imaplib, and a core developer encouraged me to submit a pull request. Here it is:
python:main ← foresto:imaplib-idle
opened 03:13AM - 01 Aug 24 UTC
This extends imaplib with support for the rfc2177 IMAP IDLE command, as requeste… d in #55454. It allows events to be pushed to a client as they occur, rather than having to continually poll for mailbox changes.
The interface is a new idle() method, which returns an iterable context manager. Entering the context starts IDLE mode, during which events (untagged responses) can be retrieved using the iteration protocol. Exiting the context sends DONE to the server, ending IDLE mode.
An optional time limit for the IDLE session is supported, for use with servers that impose an inactivity timeout.
The context manager also offers a burst() method, designed for programs wishing to process events in batch rather than one at a time.
Notable differences from other implementations:
- It's an extension to imaplib, rather than a replacement.
- It doesn't introduce additional threads.
- It doesn't impose new requirements on the use of imaplib's existing methods.
- It passes the unit tests in CPython's test/test_imaplib.py module (and adds new ones).
- It works on Windows, Linux, and other unix-like systems.
- It makes IDLE available on all of imaplib's client variants (including IMAP4_stream).
- The interface is pythonic and easy to use.
Caveats:
- Due to a Windows limitation, the special case of IMAP4_stream running on Windows lacks a duration/timeout feature. (This is the stdin/stdout pipe connection variant; timeouts work fine for socket-based connections, even on Windows.) I have documented it where appropriate.
- The file-like imaplib instance attributes are changed from buffered to unbuffered mode. This could potentially break any client code that uses those objects directly without expecting partial reads/writes. However, they are undocumented. As such, I think (and PEP 8 confirms) that they are fair game for changes. https://peps.python.org/pep-0008/#public-and-internal-interfaces
Usage examples:
https://github.com/python/cpython/issues/55454#issuecomment-2227543041
Recent discussion:
https://discuss.python.org/t/gauging-interest-in-my-imap4-idle-implementation-for-imaplib/59272
Earlier requests and suggestions:
https://github.com/python/cpython/issues/55454
https://mail.python.org/archives/list/python-ideas@python.org/thread/C4TVEYL5IBESQQPPS5GBR7WFBXCLQMZ2/
<!--
Thanks for your contribution!
Please read this comment in its entirety. It's quite important.
# Pull Request title
It should be in the following format:
```
gh-NNNNN: Summary of the changes made
```
Where: gh-NNNNN refers to the GitHub issue number.
Most PRs will require an issue number. Trivial changes, like fixing a typo, do not need an issue.
# Backport Pull Request title
If this is a backport PR (PR made against branches other than `main`),
please ensure that the PR title is in the following format:
```
[X.Y] <title from the original PR> (GH-NNNN)
```
Where: [X.Y] is the branch name, e.g. [3.6].
GH-NNNN refers to the PR number from `main`.
-->
* Issue: gh-55454
----
📚 Documentation preview 📚: https://cpython-previews--122542.org.readthedocs.build/
Could someone find time to review it?
Earlier discussion here:
Hi, folks.
Anyone who has used python to check an email account is probably aware of imaplib, its useful-but-basic support for the protocol, and its unfortunate lack of certain features that are widely expected and implemented in IMAP servers today.
One such feature is the IDLE command (defined in rfc2177 and rfc9051), which would allow the server to push events to a client as they occur, avoiding the need to continually poll for mailbox changes. I think it’s fair to say this would make the mo…
Thanks!
1 Like
forestix
September 20, 2024, 11:02pm
2
Thank you for the review, @mcepl .
This PR is now awaiting core review. Any takers?
1 Like
