From 7cb4fe0495f7fc87d1e2ed4a650d5c668c9a20bc Mon Sep 17 00:00:00 2001
From: Semyon Moroz <donbarbos@proton.me>
Date: Mon, 12 May 2025 23:20:07 +0000
Subject: [PATCH] Bump `imaplib` to 3.14 (#14022)

---
 stdlib/@tests/stubtest_allowlists/py314.txt |  4 --
 stdlib/imaplib.pyi                          | 41 ++++++++++++++++++---
 2 files changed, 35 insertions(+), 10 deletions(-)

diff --git a/stdlib/@tests/stubtest_allowlists/py314.txt b/stdlib/@tests/stubtest_allowlists/py314.txt
index 8bcf628f4..ccf1541bf 100644
--- a/stdlib/@tests/stubtest_allowlists/py314.txt
+++ b/stdlib/@tests/stubtest_allowlists/py314.txt
@@ -87,10 +87,6 @@ fractions.Fraction.from_number
 gzip.GzipFile.readinto
 gzip.GzipFile.readinto1
 gzip.compress
-imaplib.IMAP4.file
-imaplib.IMAP4.idle
-imaplib.IMAP4_SSL.file
-imaplib.IMAP4_stream.file
 importlib.abc.ResourceReader
 importlib.abc.Traversable
 importlib.abc.TraversableResources
diff --git a/stdlib/imaplib.pyi b/stdlib/imaplib.pyi
index ccee92bd5..536985a59 100644
--- a/stdlib/imaplib.pyi
+++ b/stdlib/imaplib.pyi
@@ -1,16 +1,16 @@
 import subprocess
 import sys
 import time
-from _typeshed import ReadableBuffer, SizedBuffer
+from _typeshed import ReadableBuffer, SizedBuffer, Unused
 from builtins import list as _list  # conflicts with a method named "list"
-from collections.abc import Callable
+from collections.abc import Callable, Generator
 from datetime import datetime
 from re import Pattern
 from socket import socket as _socket
 from ssl import SSLContext, SSLSocket
 from types import TracebackType
 from typing import IO, Any, Literal, SupportsAbs, SupportsInt
-from typing_extensions import Self, TypeAlias
+from typing_extensions import Self, TypeAlias, deprecated
 
 __all__ = ["IMAP4", "IMAP4_stream", "Internaldate2tuple", "Int2AP", "ParseFlags", "Time2Internaldate", "IMAP4_SSL"]
 
@@ -42,11 +42,17 @@ class IMAP4:
     PROTOCOL_VERSION: str
     def __init__(self, host: str = "", port: int = 143, timeout: float | None = None) -> None: ...
     def open(self, host: str = "", port: int = 143, timeout: float | None = None) -> None: ...
+    if sys.version_info >= (3, 14):
+        @property
+        @deprecated("IMAP4.file is unsupported, can cause errors, and may be removed.")
+        def file(self) -> IO[str] | IO[bytes]: ...
+    else:
+        file: IO[str] | IO[bytes]
+
     def __getattr__(self, attr: str) -> Any: ...
     host: str
     port: int
     sock: _socket
-    file: IO[str] | IO[bytes]
     def read(self, size: int) -> bytes: ...
     def readline(self) -> bytes: ...
     def send(self, data: ReadableBuffer) -> None: ...
@@ -72,6 +78,9 @@ class IMAP4:
     def getannotation(self, mailbox: str, entry: str, attribute: str) -> _CommandResults: ...
     def getquota(self, root: str) -> _CommandResults: ...
     def getquotaroot(self, mailbox: str) -> _CommandResults: ...
+    if sys.version_info >= (3, 14):
+        def idle(self, duration: float | None = None) -> Idler: ...
+
     def list(self, directory: str = '""', pattern: str = "*") -> tuple[str, _AnyResponseData]: ...
     def login(self, user: str, password: str) -> tuple[Literal["OK"], _list[bytes]]: ...
     def login_cram_md5(self, user: str, password: str) -> _CommandResults: ...
@@ -100,6 +109,15 @@ class IMAP4:
     def xatom(self, name: str, *args: str) -> _CommandResults: ...
     def print_log(self) -> None: ...
 
+if sys.version_info >= (3, 14):
+    class Idler:
+        def __init__(self, imap: IMAP4, duration: float | None = None) -> None: ...
+        def __enter__(self) -> Self: ...
+        def __exit__(self, exc_type: object, exc_val: Unused, exc_tb: Unused) -> Literal[False]: ...
+        def __iter__(self) -> Self: ...
+        def __next__(self) -> tuple[str, float | None]: ...
+        def burst(self, interval: float = 0.1) -> Generator[tuple[str, float | None]]: ...
+
 class IMAP4_SSL(IMAP4):
     if sys.version_info < (3, 12):
         keyfile: str
@@ -119,14 +137,25 @@ class IMAP4_SSL(IMAP4):
             timeout: float | None = None,
         ) -> None: ...
     sslobj: SSLSocket
-    file: IO[Any]
+    if sys.version_info >= (3, 14):
+        @property
+        @deprecated("IMAP4_SSL.file is unsupported, can cause errors, and may be removed.")
+        def file(self) -> IO[Any]: ...
+    else:
+        file: IO[Any]
+
     def open(self, host: str = "", port: int | None = 993, timeout: float | None = None) -> None: ...
     def ssl(self) -> SSLSocket: ...
 
 class IMAP4_stream(IMAP4):
     command: str
     def __init__(self, command: str) -> None: ...
-    file: IO[Any]
+    if sys.version_info >= (3, 14):
+        @property
+        @deprecated("IMAP4_stream.file is unsupported, can cause errors, and may be removed.")
+        def file(self) -> IO[Any]: ...
+    else:
+        file: IO[Any]
     process: subprocess.Popen[bytes]
     writefile: IO[Any]
     readfile: IO[Any]