aboutsummaryrefslogtreecommitdiffstatshomepage
path: root/Lib/imaplib.py
Commit message (Collapse)AuthorAge
* gh-55454: Add IMAP4 IDLE support to imaplib (#122542)Forest2025-02-06
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | * gh-55454: Add IMAP4 IDLE support to imaplib This extends imaplib with support for the rfc2177 IMAP IDLE command, as requested 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, these attributes 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 Original 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/ * gh-55454: Clarify imaplib idle() docs - Add example idle response tuples, to make the minor difference from other imaplib response tuples more obvious. - Merge the idle context manager's burst() method docs with the IMAP object's idle() method docs, for easier understanding. - Upgrade the Windows note regarding lack of pipe timeouts to a warning. - Rephrase various things for clarity. * docs: words instead of <= Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * docs: improve style in an example Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * docs: grammatical edit Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * docs consistency Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * comment -> docstring Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * docs: refer to imaplib as "this module" Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * imaplib: simplify & clarify idle debug message Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * imaplib: elaborate in idle context manager comment * imaplib: re-raise BaseException instead of bare except Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * imaplib: convert private doc string to comment * docs: correct mistake in imaplib example This is a correction to 8077f2eab287703b77350f1bfc9db2bd236dd9a7, which changed a variable name in only one place and broke the subsequent reference to it, departed from the naming convention used in the rest of the module, and shadowed the type() builtin along the way. * imaplib: simplify example code in doc string This is for consistency with the documentation change in 8077f2eab287 and subsequent correction in 013bbf18fc42. * imaplib: rename _Idler to Idler, update its docs * imaplib: add comment in Idler._pop() Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * imaplib: remove unnecessary blank line Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * imaplib: comment on use of unbuffered pipes * docs: imaplib: use the reStructuredText :class: role Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * Revert "docs: imaplib: use the reStructuredText :class: role" This reverts commit f385e441df15d962d1f22e9bab2f15a39e5363d5, because it triggers CI failures in the docs by referencing a class that is (deliberately) undocumented. * docs: imaplib: use the reST :class: role, escaped This is a different approach to f385e441df15, which was reverted for creating dangling link references. By prefixing the reStructuredText role target with a ! we disable conversion to a link, thereby passing continuous integration checks even though the referenced class is deliberately absent from the documentation. * docs: refer to IMAP4 IDLE instead of just IDLE This clarifies that we are referring to the email protocol, not the editor with the same name. Co-authored-by: Guido van Rossum <gvanrossum@gmail.com> * imaplib: IDLE -> IMAP4 IDLE in exception message Co-authored-by: Peter Bierma <zintensitydev@gmail.com> * docs: imaplib idle() phrasing and linking tweaks * docs: imaplib: avoid linking to an invalid target This reverts and rephrases part of a3f21cd75b4d7c97c0d7e46b0a0cc0875e29f6cc which created links to a method on a deliberately undocumented class. The links didn't work consistently, and caused sphinx warnings that broke cpython's continuous integration tests. * imaplib: update test after recent exception change This fixes a test that was broken by changing an exception in b01de95171d6124f8acc7b907c1842472ea5f5fb * imaplib: rename idle() dur argument to duration * imaplib: bytes.index() -> bytes.find() This makes it more obvious which statement triggers the branch. * imaplib: remove no-longer-necessary statement Co-authored-by: Martin Panter <vadmium@users.noreply.github.com> * docs: imaplib: concise & valid method links The burst() method is a little tricky to link in restructuredText, due to quirks of its parent class. This syntax allows sphinx to generate working links without generating warnings (which break continuous integration) and without burdening the reader with unimportant namespace qualifications. It makes the reST source ugly, but few people read the reST source, so it's a tolerable tradeoff. * imaplib: note data types present in IDLE responses * docs: imaplib: add comma to reST changes header Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com> * imaplib: sync doc strings with reST docs * docs: imaplib: minor Idler clarifications * imaplib: idle: emit (type, [data, ...]) tuples This allows our iterator to emit untagged responses that contain literal strings in the same way that imaplib's existing methods do, while still emitting exactly one whole response per iteration. * imaplib: while/yield instead of yield from iter() * imaplib: idle: use deadline idiom when iterating This simplifies the code, and avoids idle duration drift from time spent processing each iteration. * docs: imaplib: state duration/interval arg types * docs: imaplib: minor rephrasing of a sentence * docs: imaplib: reposition a paragraph This might improve readability, especially when encountering Idler.burst() for the first time. * docs: imaplib: wrap long lines in idle() section * docs: imaplib: note: Idler objects require 'with' * docs: imaplib: say that 29 minutes is 1740 seconds * docs: imaplib: mark a paragraph as a 'tip' * docs: imaplib: rephrase reference to MS Windows * imaplib: end doc string titles with a period * imaplib: idle: socket timeouts instead of select() IDLE timeouts were originally implemented using select() after checking for the presence of already-buffered data. That allowed timeouts on pipe connetions like IMAP4_stream. However, it seemed possible that SSL data arriving without any IMAP data afterward could cause select() to indicate available application data when there was none, leading to a read() call that would block with no timeout. It was unclear under what conditions this would happen in practice. This change switches to socket timeouts instead of select(), just to be safe. This also reverts IMAP4_stream changes that were made to support IDLE timeouts, since our new implementation only supports socket connections. * imaplib: Idler: rename private state attributes * imaplib: rephrase a comment in example code * docs: imaplib: idle: use Sphinx code-block:: pycon * docs: whatsnew: imaplib: reformat IMAP4.idle entry * imaplib: idle: make doc strings brief Since we generally rely on the reST/html documentation for details, we can keep these doc strings short. This matches the module's existing doc string style and avoids having to sync small changes between two files. * imaplib: Idler: split assert into two statements * imaplib: Idler: move assignment out of try: block * imaplib: Idler: move __exit__() for readability * imaplib: Idler: move __next__() for readability * imaplib: test: make IdleCmdHandler a global class * docs: imaplib: idle: collapse double-spaces * imaplib: warn on use of undocumented 'file' attr * imaplib: revert import reformatting Since we no longer import platform or selectors, the original import statement style can be restored, reducing the footprint of PR #122542. * imaplib: restore original exception msg formatting This reduces the footprint of PR #122542. * docs: imaplib: idle: versionadded:: next * imaplib: move import statement to where it's used This import is only needed if external code tries to use an attribute that it shouldn't be using. Making it a local import reduces module loading time in supported cases. * imaplib test: RuntimeWarning on IMAP4.file access * imaplib: use stacklevel=2 in warnings.warn() * imaplib test: simplify IMAP4.file warning test * imaplib test: pre-idle-continuation response * imaplib test: post-done untagged response * imaplib: downgrade idle-denied exception to error This makes it easier for client code to distinguish a temporary rejection of the IDLE command from a server responding incorrectly to IDLE. * imaplib: simplify check for socket object * imaplib: narrow the scope of IDLE socket timeouts If an IDLE duration or burst() was in use, and an unsolicited response contained a literal string, and crossed a packet boundary, and the subsequent packet was delayed beyond the IDLE feature's time limit, the timeout would leave the incoming protocol stream in a bad state (with the tail of that response appearing where the start of a response is expected). This change moves the IDLE socket timeout to cover only the start of a response, so it can no longer cause that problem. * imaplib: preserve partial reads on exception This ensures that short IDLE durations / burst() intervals won't risk corrupting response lines that span multiple packets. * imaplib: read/readline: save multipart buffer tail For resilience if read() or readline() ever complete with more than one bytes object remaining in the buffer. This is not expected to happen, but it seems wise to be prepared for a future change making it possible. * imaplib: use TimeoutError subclass only if needed * doc: imaplib: elaborate on IDLE response delivery * doc: imaplib: elaborate in note re: IMAP4.response * imaplib: comment on benefit of reading in chunks Our read() implementation designed to support IDLE replaces the one from PR #119514, fixing the same problem it was addressing. The tests that it added are preserved. * imaplib: readline(): treat ConnectionError as EOF --------- Co-authored-by: Gregory P. Smith <greg@krypto.org> Co-authored-by: Peter Bierma <zintensitydev@gmail.com> Co-authored-by: Guido van Rossum <guido@python.org> Co-authored-by: Guido van Rossum <gvanrossum@gmail.com> Co-authored-by: Martin Panter <vadmium@users.noreply.github.com> Co-authored-by: Bénédikt Tran <10796600+picnixz@users.noreply.github.com>
* gh-119511: Fix a potential denial of service in imaplib (#119514)Serhiy Storchaka2025-01-27
| | | | | | | | | | The IMAP4 client could consume an arbitrary amount of memory when trying to connect to a malicious server, because it read a "literal" data with a single read(size) call, and BufferedReader.read() allocates the bytes object of the specified size before reading. Now the IMAP4 client reads data by chunks, therefore the amount of used memory is limited by the amount of the data actually been sent by the server. Co-authored-by: Gregory P. Smith <greg@krypto.org>
* Remove almost all unpaired backticks in docstrings (#119231)Geoffrey Thomas2024-05-22
| | | | | | | | | | | | | | | | | | As reported in #117847 and #115366, an unpaired backtick in a docstring tends to confuse e.g. Sphinx running on subclasses of standard library objects, and the typographic style of using a backtick as an opening quote is no longer in favor. Convert almost all uses of the form The variable `foo' should do xyz to The variable 'foo' should do xyz and also fix up miscellaneous other unpaired backticks (extraneous / missing characters). No functional change is intended here other than in human-readable docstrings.
* gh-94172: Remove keyfile, certfile and check_hostname parameters (#94173)Victor Stinner2022-11-03
| | | | | | | | | | | | Remove the keyfile, certfile and check_hostname parameters, deprecated since Python 3.6, in modules: ftplib, http.client, imaplib, poplib and smtplib. Use the context parameter (ssl_context in imaplib) instead. Parameters following the removed parameters become keyword-only parameters. ftplib: Remove the FTP_TLS.ssl_version class attribute: use the context parameter instead.
* bpo-44045: fix spelling of uppercase vs upper-case (GH-25985)Jürgen Gmach2021-05-28
| | | | | And also of lowercase vs lower-case. The `-` notation should only be used for adjectives.
* bpo-26543: Fix IMAP4.noop when debug mode is enabled (GH-15206)Sanyam Khurana2020-06-02
|
* bpo-40375: Implement imaplib.IMAP4.unselect (GH-19712)Dong-hee Na2020-04-27
|
* bpo-38615: Add timeout parameter for IMAP4 and IMAP4_SSL constructor (GH-17203)Dong-hee Na2020-01-07
| | | | | | | | imaplib.IMAP4 and imaplib.IMAP4_SSL now have an optional *timeout* parameter for their constructors. Also, the imaplib.IMAP4.open() method now has an optional *timeout* parameter with this change. The overridden methods of imaplib.IMAP4_SSL and imaplib.IMAP4_stream were applied to this change.
* Fix typos in comments, docs and test names (#15018)Min ho Kim2019-07-30
| | | | | | | | | | | | | | | | | | | | | | | | * Fix typos in comments, docs and test names * Update test_pyparse.py account for change in string length * Apply suggestion: splitable -> splittable Co-Authored-By: Terry Jan Reedy <tjreedy@udel.edu> * Apply suggestion: splitable -> splittable Co-Authored-By: Terry Jan Reedy <tjreedy@udel.edu> * Apply suggestion: Dealloccte -> Deallocate Co-Authored-By: Terry Jan Reedy <tjreedy@udel.edu> * Update posixmodule checksum. * Reverse idlelib changes.
* bpo-37390: Add audit event table to documentations (GH-14406)Steve Dower2019-06-27
| | | Also updates some (unreleased) event names to be consistent with the others.
* bpo-37363: Add audit events for a range of modules (GH-14301)Steve Dower2019-06-24
|
* bpo-36348: IMAP4.logout() doesn't ignore exc (GH-12411)Victor Stinner2019-04-15
| | | | | | | | | | | | The imap.IMAP4.logout() method no longer ignores silently arbitrary exceptions. Changes: * The IMAP4.logout() method now expects a "BYE" untagged response, rather than relying on _check_bye() which raises a self.abort() exception. * IMAP4.__exit__() now does nothing if the client already logged out. * Add more debug info if test_logout() tests fail.
* bpo-35128: Fix spacing issues in warning.warn() messages. (GH-10268)Pablo Aguiar2018-11-01
|
* bpo-18540: Fix EAI_NONAME in imaplib.IMAP4*() (GH-8634)Berker Peksag2018-08-07
|
* bpo-33336, imaplib: Legalize MOVE command (GH-6569)Matěj Cepl2018-07-23
| | | | | imaplib now allows MOVE command in IMAP4.uid() (RFC 6851: IMAP MOVE Extension) and potentially as a name of supported method of IMAP4 object.
* bpo-32157: Removed explicit quotes around %r and {!r}. (#4582)Serhiy Storchaka2017-11-28
|
* bpo-30329: Catch Windows error 10022 on shutdown() (#1538)Victor Stinner2017-05-15
| | | | | | Catch the Windows socket WSAEINVAL error (code 10022) in imaplib and poplib on shutdown(SHUT_RDWR): An invalid operation was attempted This error occurs sometimes on SSL connections.
* Merge: #25591: improve imap tests.R David Murray2016-12-24
|\
| * #25591: improve imap tests.R David Murray2016-12-24
| | | | | | | | Patch by Maciej Szulik.
* | Issue #28022: Deprecate ssl-related arguments in favor of SSLContext.Christian Heimes2016-09-10
| | | | | | | | | | | | | | The deprecation include manual creation of SSLSocket and certfile/keyfile (or similar) in ftplib, httplib, imaplib, smtplib, poplib and urllib. ssl.wrap_socket() is not marked as deprecated yet.
* | #27364: fix "incorrect" uses of escape character in the stdlib.R David Murray2016-09-08
| | | | | | | | | | | | | | And most of the tools. Patch by Emanual Barry, reviewed by me, Serhiy Storchaka, and Martin Panter.
* | #21815: violate IMAP RFC to be compatible with, e.g., gmailR David Murray2016-01-02
|/ | | | | | | | | | | and others, including imaplib's own behavior. I'm applying this only to 3.6 because there's a potential backward compatibility concern: if there are servers that include ] characters in the 'text' portion of their imap responses, this code change could introduce a new bug. Patch by Lita Cho, reviewed by Jessica McKellar, Berker Peksag, Maciej Szulik, silentghost, and me (I fleshed out the comments with the additional info/concerns.)
* Issue #23779: imaplib raises TypeError if authenticator tries to abort.Robert Collins2015-07-31
|\ | | | | | | Patch from Craig Holmquist.
| * Issue #23779: imaplib raises TypeError if authenticator tries to abort.Robert Collins2015-07-31
| | | | | | | | Patch from Craig Holmquist.
* | #21800: Add RFC 6855 support to imaplib.R David Murray2015-05-10
| | | | | | | | | | Original patch by Milan Oberkirch, updated by myself and Maciej Szulik.
* | Merge: #23647: Increase imaplib's MAXLINE to accommodate modern mailbox sizes.R David Murray2015-03-22
|\|
| * #23647: Increase imaplib's MAXLINE to accommodate modern mailbox sizes.R David Murray2015-03-22
| |
* | merge 3.4 (#22921)Benjamin Peterson2014-11-23
|\|
| * don't require OpenSSL SNI to pass hostname to ssl functions (#22921)Benjamin Peterson2014-11-23
| | | | | | | | Patch by Donald Stufft.
* | imaplib.IMAP4 now supports the context manager protocol.Serhiy Storchaka2014-09-09
|/ | | | Original patch by Tarek Ziadé.
* #20013: don't raise socket error when selected mailbox deleted.R David Murray2014-02-07
| | | | | | | | I'm checking this in without a test because not much of this code is tested and I don't have time to work up the necessary extensions to the existing test framework. The patch itself was tested by the person who reported the bug.
* Issue #19782: imaplib now supports SSLContext.check_hostname and server nameChristian Heimes2013-12-02
| | | | indication for TLS/SSL connections.
* Issue #19735: Implement private function ssl._create_stdlib_context() toChristian Heimes2013-11-23
| | | | | create SSLContext objects in Python's stdlib module. It provides a single configuration point and makes use of SSLContext.load_default_certs().
* Issue #17276: MD5 as default digestmod for HMAC is deprecated. The HMACChristian Heimes2013-11-20
| | | | module supports digestmod names, e.g. hmac.HMAC('sha1').
* merge with 3.3Georg Brandl2013-10-27
|\
| * Issue #16039: CVE-2013-1752: Change use of readline in imaplib module to limitGeorg Brandl2013-10-27
| | | | | | | | line length. Patch by Emil Lind.
* | Issue #18200: Back out usage of ModuleNotFoundError (8d28d44f3a9a)Brett Cannon2013-07-04
| |
* | Improve imap error message in unusual failure mode.R David Murray2013-06-28
| | | | | | | | | | | | | | | | We ran into this during the sprits at PyCon and this patch has been sitting on my disk ever since. This just adds some information to the error message that we found useful during debugging. There's no good way to add a test, since the message only got generated via code that we had modified for debugging purposes.
* | Issue #18200: Update the stdlib (except tests) to useBrett Cannon2013-06-13
| | | | | | | | ModuleNotFoundError.
* | Merge: #17443: Fix buffering in IMAP4_stream.R David Murray2013-03-19
|\| | | | | | | | | | | | | | | | | | | | | | | | | In Python2 Popen uses *FILE objects, which wind up buffering even though subprocess defaults to no buffering. In Python3, subprocess streams really are unbuffered by default, but the imaplib code assumes read is buffered. This patch uses the default buffer size from the io module to get buffered streams from Popen. Much debugging work and patch by Diane Trout. The imap protocol is too complicated to write a test for this simple change with our current level of test infrastructure.
| * Merge: #17443: Fix buffering in IMAP4_stream.R David Murray2013-03-19
| |\ | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | In Python2 Popen uses *FILE objects, which wind up buffering even though subprocess defaults to no buffering. In Python3, subprocess streams really are unbuffered by default, but the imaplib code assumes read is buffered. This patch uses the default buffer size from the io module to get buffered streams from Popen. Much debugging work and patch by Diane Trout. The imap protocol is too complicated to write a test for this simple change with our current level of test infrastructure.
| | * #17443: Fix buffering in IMAP4_stream.R David Murray2013-03-19
| | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | | In Python2 Popen uses *FILE objects, which wind up buffering even though subprocess defaults to no buffering. In Python3, subprocess streams really are unbuffered by default, but the imaplib code assumes read is buffered. This patch uses the default buffer size from the io module to get buffered streams from Popen. Much debugging work and patch by Diane Trout. The imap protocol is too complicated to write a test for this simple change with our current level of test infrastructure.
* | | Merge: #13700: Make imap.authenticate with authobject work.R David Murray2013-02-19
|\| | | | | | | | | | | | | | | | | | | | This fixes a bytes/string confusion in the API which prevented custom authobjects from working at all. Original patch by Erno Tukia.
| * | Merge: #13700: Make imap.authenticate with authobject work.R David Murray2013-02-19
| |\| | | | | | | | | | | | | | | | | | | This fixes a bytes/string confusion in the API which prevented custom authobjects from working at all. Original patch by Erno Tukia.
| | * #13700: Make imap.authenticate with authobject work.R David Murray2013-02-19
| | | | | | | | | | | | | | | | | | | | | This fixes a bytes/string confusion in the API which prevented custom authobjects from working at all. Original patch by Erno Tukia.
* | | Issue #16717: get rid of socket.error, replace with OSErrorAndrew Svetlov2012-12-18
|/ /
* | Issue #16714: use 'raise' exceptions, don't 'throw'.Andrew Svetlov2012-12-18
|\| | | | | | | Patch by Serhiy Storchaka.
* | Issues #11024: Fixes and additional tests for Time2Internaldate.Alexander Belopolsky2012-06-22
| |
* | Issue #10941: Fix imaplib.Internaldate2tuple to produce correct result nearAlexander Belopolsky2012-04-29
|\| | | | | | | the DST transition. Patch by Joe Peterson.
| * Issue #10941: Fix imaplib.Internaldate2tuple to produce correct result nearAlexander Belopolsky2012-04-29
| | | | | | | | the DST transition. Patch by Joe Peterson.
generated by cgit v1.2.3 (git 2.39.1) at 2025-06-06 17:51:02 +0000