|
10 | 10 | .. changes for IMAP4_SSL by Tino Lange <Tino.Lange@isg.de>, March 2002
|
11 | 11 | .. changes for IMAP4_stream by Piers Lauder <piers@communitysolutions.com.au>,
|
12 | 12 | November 2002
|
| 13 | +.. changes for IDLE by Forest <forestix@nom.one> August 2024 |
13 | 14 |
|
14 | 15 | **Source code:** :source:`Lib/imaplib.py`
|
15 | 16 |
|
@@ -187,7 +188,7 @@ However, the *password* argument to the ``LOGIN`` command is always quoted. If
|
187 | 188 | you want to avoid having an argument string quoted (eg: the *flags* argument to
|
188 | 189 | ``STORE``) then enclose the string in parentheses (eg: ``r'(\Deleted)'``).
|
189 | 190 |
|
190 |
| -Each command returns a tuple: ``(type, [data, ...])`` where *type* is usually |
| 191 | +Most commands return a tuple: ``(type, [data, ...])`` where *type* is usually |
191 | 192 | ``'OK'`` or ``'NO'``, and *data* is either the text from the command response,
|
192 | 193 | or mandated results from the command. Each *data* is either a ``bytes``, or a
|
193 | 194 | tuple. If a tuple, then the first part is the header of the response, and the
|
@@ -307,6 +308,48 @@ An :class:`IMAP4` instance has the following methods:
|
307 | 308 | of the IMAP4 QUOTA extension defined in rfc2087.
|
308 | 309 |
|
309 | 310 |
|
| 311 | +.. method:: IMAP4.idle([dur]) |
| 312 | + |
| 313 | + Return an iterable context manager implementing the ``IDLE`` command |
| 314 | + as defined in :rfc:`2177`. |
| 315 | + |
| 316 | + The optional *dur* argument specifies a maximum duration (in seconds) to |
| 317 | + keep idling. It defaults to ``None``, meaning no time limit. |
| 318 | + To avoid inactivity timeouts on servers that impose them, callers are |
| 319 | + advised to keep this <= 29 minutes. See the note below regarding |
| 320 | + :class:`IMAP4_stream` on Windows. |
| 321 | + |
| 322 | + The context manager sends the ``IDLE`` command upon entry, produces |
| 323 | + responses via iteration, and sends ``DONE`` upon exit. |
| 324 | + It represents responses as ``(type, datum)`` tuples, rather than the |
| 325 | + ``(type, [data, ...])`` tuples returned by other methods, because only |
| 326 | + one response is represented at a time. |
| 327 | + |
| 328 | + Example:: |
| 329 | + |
| 330 | + with M.idle(dur=29*60) as idler: |
| 331 | + for response in idler: |
| 332 | + typ, datum = response |
| 333 | + print(typ, datum) |
| 334 | + |
| 335 | + It is also possible to process a burst of responses all at once instead |
| 336 | + of one at a time. See `IDLE Context Manager`_ for details. |
| 337 | + |
| 338 | + Responses produced by the iterator are not added to the internal |
| 339 | + cache for retrieval by :meth:`IMAP4.response`. |
| 340 | + |
| 341 | + .. note:: |
| 342 | + |
| 343 | + Windows :class:`IMAP4_stream` connections have no way to accurately |
| 344 | + respect *dur*, since Windows ``select()`` only works on sockets. |
| 345 | + However, if the server regularly sends status messages during ``IDLE``, |
| 346 | + they will wake our selector and keep iteration from blocking for long. |
| 347 | + Dovecot's ``imap_idle_notify_interval`` is two minutes by default. |
| 348 | + Assuming that's typical of IMAP servers, subtracting it from the 29 |
| 349 | + minutes needed to avoid server inactivity timeouts would make 27 |
| 350 | + minutes a sensible value for *dur* in this situation. |
| 351 | + |
| 352 | + |
310 | 353 | .. method:: IMAP4.list([directory[, pattern]])
|
311 | 354 |
|
312 | 355 | List mailbox names in *directory* matching *pattern*. *directory* defaults to
|
@@ -612,6 +655,62 @@ The following attributes are defined on instances of :class:`IMAP4`:
|
612 | 655 | .. versionadded:: 3.5
|
613 | 656 |
|
614 | 657 |
|
| 658 | +.. _idle context manager: |
| 659 | + |
| 660 | +IDLE Context Manager |
| 661 | +-------------------- |
| 662 | + |
| 663 | +The object returned by :meth:`IMAP4.idle` implements the context management |
| 664 | +protocol for the :keyword:`with` statement, and the :term:`iterator` protocol |
| 665 | +for retrieving untagged responses while the context is active. |
| 666 | +It also has the following method: |
| 667 | + |
| 668 | +.. method:: IdleContextManager.burst([interval]) |
| 669 | + |
| 670 | + Yield a burst of responses no more than *interval* seconds apart. |
| 671 | + |
| 672 | + This generator retrieves the next response along with any |
| 673 | + immediately available subsequent responses (e.g. a rapid series of |
| 674 | + ``EXPUNGE`` responses after a bulk delete) so they can be efficiently |
| 675 | + processed as a batch instead of one at a time. |
| 676 | + |
| 677 | + The optional *interval* argument specifies a time limit (in seconds) |
| 678 | + for each response after the first. It defaults to 0.1 seconds. |
| 679 | + (The ``IDLE`` context's maximum duration is respected when waiting for the |
| 680 | + first response.) |
| 681 | + |
| 682 | + Represents responses as ``(type, datum)`` tuples, just as when |
| 683 | + iterating directly on the context manager. |
| 684 | + |
| 685 | + Example:: |
| 686 | + |
| 687 | + with M.idle() as idler: |
| 688 | + |
| 689 | + # get the next response and any others following by < 0.1 seconds |
| 690 | + batch = list(idler.burst()) |
| 691 | + |
| 692 | + print(f'processing {len(batch)} responses...') |
| 693 | + for typ, datum in batch: |
| 694 | + print(typ, datum) |
| 695 | + |
| 696 | + Produces no responses and returns immediately if the ``IDLE`` context's |
| 697 | + maximum duration (the *dur* argument to :meth:`IMAP4.idle`) has elapsed. |
| 698 | + Callers should plan accordingly if using this method in a loop. |
| 699 | + |
| 700 | + .. note:: |
| 701 | + |
| 702 | + Windows :class:`IMAP4_stream` connections will ignore the *interval* |
| 703 | + argument, yielding endless responses and blocking indefinitely for each |
| 704 | + one, since Windows ``select()`` only works on sockets. It is therefore |
| 705 | + advised not to use this method with an :class:`IMAP4_stream` connection |
| 706 | + on Windows. |
| 707 | + |
| 708 | +.. note:: |
| 709 | + |
| 710 | + The context manager's type name is not part of its public interface, |
| 711 | + and is subject to change. |
| 712 | + |
| 713 | + |
615 | 714 | .. _imap4-example:
|
616 | 715 |
|
617 | 716 | IMAP4 Example
|
|
0 commit comments