From: Forest <forestix@nom.one>
Date: Mon, 23 Sep 2024 21:59:26 +0000 (-0700)
Subject: imaplib: rename _Idler to Idler, update its docs
X-Git-Url: http://git.ipfire.org/gitweb.cgi?a=commitdiff_plain;h=94c02e88a9d3c827624789abb4ad2e0c1fdbfa0a;p=thirdparty%2FPython%2Fcpython.git

imaplib: rename _Idler to Idler, update its docs
---

diff --git a/Doc/library/imaplib.rst b/Doc/library/imaplib.rst
index 757cd715704a..6f765bbed1cc 100644
--- a/Doc/library/imaplib.rst
+++ b/Doc/library/imaplib.rst
@@ -310,8 +310,8 @@ An :class:`IMAP4` instance has the following methods:
 
 .. method:: IMAP4.idle(dur=None)
 
-   Return an iterable context manager implementing the ``IDLE`` command
-   as defined in :rfc:`2177`.
+   Return an ``Idler``: an iterable context manager implementing the ``IDLE``
+   command as defined in :rfc:`2177`.
 
    The context manager sends the ``IDLE`` command when activated by the
    :keyword:`with` statement, produces IMAP untagged responses via the
@@ -346,7 +346,7 @@ An :class:`IMAP4` instance has the following methods:
    batch processing aid is provided by the context's ``burst()``
    :term:`generator`:
 
-   .. method:: idler.burst(interval=0.1)
+   .. method:: Idler.burst(interval=0.1)
 
       Yield a burst of responses no more than *interval* seconds apart.
 
@@ -391,6 +391,13 @@ An :class:`IMAP4` instance has the following methods:
       not to use ``burst()`` with an :class:`IMAP4_stream` connection on
       Windows.
 
+   .. note::
+
+      Note: The ``Idler`` class name and structure are internal interfaces,
+      subject to change.  Calling code can rely on its context management,
+      iteration, and public method to remain stable, but should not
+      subclass, instantiate, or otherwise directly reference the class.
+
 
 .. method:: IMAP4.list([directory[, pattern]])
 
diff --git a/Lib/imaplib.py b/Lib/imaplib.py
index bbb844312153..596b3d3f34da 100644
--- a/Lib/imaplib.py
+++ b/Lib/imaplib.py
@@ -649,7 +649,7 @@ class IMAP4:
 
 
     def idle(self, dur=None):
-        """Return an iterable context manager implementing the IDLE command
+        """Return an Idler: an iterable context manager for the IDLE command
 
         :param dur:     Maximum duration (in seconds) to keep idling,
                         or None for no time limit.
@@ -681,8 +681,13 @@ class IMAP4:
         Assuming that's typical of IMAP servers, subtracting it from the 29
         minutes needed to avoid server inactivity timeouts would make 27
         minutes a sensible value for 'dur' in this situation.
+
+        Note: The Idler class name and structure are internal interfaces,
+        subject to change.  Calling code can rely on its context management,
+        iteration, and public method to remain stable, but should not
+        subclass, instantiate, or otherwise directly reference the class.
         """
-        return _Idler(self, dur)
+        return Idler(self, dur)
 
 
     def list(self, directory='""', pattern='*'):
@@ -1384,13 +1389,24 @@ class IMAP4:
                 n -= 1
 
 
-class _Idler:
-    # Iterable context manager: start IDLE & produce untagged responses
-    #
-    # This iterator produces (type, datum) tuples.  They slightly differ
-    # from the tuples returned by IMAP4.response():  The second item in the
-    # tuple is a single datum, rather than a list of them, because only one
-    # untagged response is produced at a time.
+class Idler:
+    """Iterable context manager: start IDLE & produce untagged responses
+
+    An object of this type is returned by the IMAP4.idle() method.
+    It sends the IDLE command when activated by the 'with' statement, produces
+    IMAP untagged responses via the iterator protocol, and sends DONE upon
+    context exit.
+
+    Iteration produces (type, datum) tuples.  They slightly differ
+    from the tuples returned by IMAP4.response():  The second item in the
+    tuple is a single datum, rather than a list of them, because only one
+    untagged response is produced at a time.
+
+    Note: The name and structure of this class are internal interfaces,
+    subject to change.  Calling code can rely on its context management,
+    iteration, and public method to remain stable, but should not
+    subclass, instantiate, or otherwise directly reference the class.
+    """
 
     def __init__(self, imap, dur=None):
         if 'IDLE' not in imap.capabilities: