stdlib: Apply some simple deprecations (#11044)

stdlib/asyncio/events.pyi

@@ -6,7 +6,7 @@ from collections.abc import Callable, Coroutine, Generator, Sequence
 from contextvars import Context
 from socket import AddressFamily, SocketKind, _Address, _RetAddress, socket
 from typing import IO, Any, Protocol, TypeVar, overload
-from typing_extensions import Literal, Self, TypeAlias
+from typing_extensions import Literal, Self, TypeAlias, deprecated
 
 from . import _AwaitableLike, _CoroutineLike
 from .base_events import Server
@@ -613,8 +613,17 @@ def set_event_loop_policy(policy: AbstractEventLoopPolicy | None) -> None: ...
 def get_event_loop() -> AbstractEventLoop: ...
 def set_event_loop(loop: AbstractEventLoop | None) -> None: ...
 def new_event_loop() -> AbstractEventLoop: ...
-def get_child_watcher() -> AbstractChildWatcher: ...
-def set_child_watcher(watcher: AbstractChildWatcher) -> None: ...
+
+if sys.version_info >= (3, 12):
+    @deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
+    def get_child_watcher() -> AbstractChildWatcher: ...
+    @deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
+    def set_child_watcher(watcher: AbstractChildWatcher) -> None: ...
+
+else:
+    def get_child_watcher() -> AbstractChildWatcher: ...
+    def set_child_watcher(watcher: AbstractChildWatcher) -> None: ...
+
 def _set_running_loop(__loop: AbstractEventLoop | None) -> None: ...
 def _get_running_loop() -> AbstractEventLoop: ...
 def get_running_loop() -> AbstractEventLoop: ...

stdlib/asyncio/unix_events.pyi

@@ -3,7 +3,7 @@ import types
 from abc import ABCMeta, abstractmethod
 from collections.abc import Callable
 from typing import Any
-from typing_extensions import Literal, Self
+from typing_extensions import Literal, Self, deprecated
 
 from .events import AbstractEventLoop, BaseDefaultEventLoopPolicy
 from .selector_events import BaseSelectorEventLoop
@@ -11,22 +11,46 @@ from .selector_events import BaseSelectorEventLoop
 # This is also technically not available on Win,
 # but other parts of typeshed need this definition.
 # So, it is special cased.
-class AbstractChildWatcher:
-    @abstractmethod
-    def add_child_handler(self, pid: int, callback: Callable[..., object], *args: Any) -> None: ...
-    @abstractmethod
-    def remove_child_handler(self, pid: int) -> bool: ...
-    @abstractmethod
-    def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
-    @abstractmethod
-    def close(self) -> None: ...
-    @abstractmethod
-    def __enter__(self) -> Self: ...
-    @abstractmethod
-    def __exit__(self, typ: type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None) -> None: ...
-    if sys.version_info >= (3, 8):
+if sys.version_info >= (3, 12):
+    @deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
+    class AbstractChildWatcher:
         @abstractmethod
-        def is_active(self) -> bool: ...
+        def add_child_handler(self, pid: int, callback: Callable[..., object], *args: Any) -> None: ...
+        @abstractmethod
+        def remove_child_handler(self, pid: int) -> bool: ...
+        @abstractmethod
+        def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
+        @abstractmethod
+        def close(self) -> None: ...
+        @abstractmethod
+        def __enter__(self) -> Self: ...
+        @abstractmethod
+        def __exit__(
+            self, typ: type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None
+        ) -> None: ...
+        if sys.version_info >= (3, 8):
+            @abstractmethod
+            def is_active(self) -> bool: ...
+
+else:
+    class AbstractChildWatcher:
+        @abstractmethod
+        def add_child_handler(self, pid: int, callback: Callable[..., object], *args: Any) -> None: ...
+        @abstractmethod
+        def remove_child_handler(self, pid: int) -> bool: ...
+        @abstractmethod
+        def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
+        @abstractmethod
+        def close(self) -> None: ...
+        @abstractmethod
+        def __enter__(self) -> Self: ...
+        @abstractmethod
+        def __exit__(
+            self, typ: type[BaseException] | None, exc: BaseException | None, tb: types.TracebackType | None
+        ) -> None: ...
+        if sys.version_info >= (3, 8):
+            @abstractmethod
+            def is_active(self) -> bool: ...
 
 if sys.platform != "win32":
     if sys.version_info >= (3, 9):
@@ -62,28 +86,61 @@ if sys.platform != "win32":
 
         def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
 
-    class SafeChildWatcher(BaseChildWatcher):
-        def __enter__(self) -> Self: ...
-        def __exit__(self, a: type[BaseException] | None, b: BaseException | None, c: types.TracebackType | None) -> None: ...
-        def add_child_handler(self, pid: int, callback: Callable[..., object], *args: Any) -> None: ...
-        def remove_child_handler(self, pid: int) -> bool: ...
+    if sys.version_info >= (3, 12):
+        @deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
+        class SafeChildWatcher(BaseChildWatcher):
+            def __enter__(self) -> Self: ...
+            def __exit__(self, a: type[BaseException] | None, b: BaseException | None, c: types.TracebackType | None) -> None: ...
+            def add_child_handler(self, pid: int, callback: Callable[..., object], *args: Any) -> None: ...
+            def remove_child_handler(self, pid: int) -> bool: ...
 
-    class FastChildWatcher(BaseChildWatcher):
-        def __enter__(self) -> Self: ...
-        def __exit__(self, a: type[BaseException] | None, b: BaseException | None, c: types.TracebackType | None) -> None: ...
-        def add_child_handler(self, pid: int, callback: Callable[..., object], *args: Any) -> None: ...
-        def remove_child_handler(self, pid: int) -> bool: ...
+        @deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
+        class FastChildWatcher(BaseChildWatcher):
+            def __enter__(self) -> Self: ...
+            def __exit__(self, a: type[BaseException] | None, b: BaseException | None, c: types.TracebackType | None) -> None: ...
+            def add_child_handler(self, pid: int, callback: Callable[..., object], *args: Any) -> None: ...
+            def remove_child_handler(self, pid: int) -> bool: ...
+    else:
+        class SafeChildWatcher(BaseChildWatcher):
+            def __enter__(self) -> Self: ...
+            def __exit__(self, a: type[BaseException] | None, b: BaseException | None, c: types.TracebackType | None) -> None: ...
+            def add_child_handler(self, pid: int, callback: Callable[..., object], *args: Any) -> None: ...
+            def remove_child_handler(self, pid: int) -> bool: ...
+
+        class FastChildWatcher(BaseChildWatcher):
+            def __enter__(self) -> Self: ...
+            def __exit__(self, a: type[BaseException] | None, b: BaseException | None, c: types.TracebackType | None) -> None: ...
+            def add_child_handler(self, pid: int, callback: Callable[..., object], *args: Any) -> None: ...
+            def remove_child_handler(self, pid: int) -> bool: ...
 
     class _UnixSelectorEventLoop(BaseSelectorEventLoop): ...
 
     class _UnixDefaultEventLoopPolicy(BaseDefaultEventLoopPolicy):
-        def get_child_watcher(self) -> AbstractChildWatcher: ...
-        def set_child_watcher(self, watcher: AbstractChildWatcher | None) -> None: ...
+        if sys.version_info >= (3, 12):
+            @deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
+            def get_child_watcher(self) -> AbstractChildWatcher: ...
+            @deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
+            def set_child_watcher(self, watcher: AbstractChildWatcher | None) -> None: ...
+        else:
+            def get_child_watcher(self) -> AbstractChildWatcher: ...
+            def set_child_watcher(self, watcher: AbstractChildWatcher | None) -> None: ...
     SelectorEventLoop = _UnixSelectorEventLoop
 
     DefaultEventLoopPolicy = _UnixDefaultEventLoopPolicy
 
-    if sys.version_info >= (3, 8):
+    if sys.version_info >= (3, 12):
+        @deprecated("Deprecated as of Python 3.12; will be removed in Python 3.14")
+        class MultiLoopChildWatcher(AbstractChildWatcher):
+            def is_active(self) -> bool: ...
+            def close(self) -> None: ...
+            def __enter__(self) -> Self: ...
+            def __exit__(
+                self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: types.TracebackType | None
+            ) -> None: ...
+            def add_child_handler(self, pid: int, callback: Callable[..., object], *args: Any) -> None: ...
+            def remove_child_handler(self, pid: int) -> bool: ...
+            def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
+    elif sys.version_info >= (3, 8):
         class MultiLoopChildWatcher(AbstractChildWatcher):
             def is_active(self) -> bool: ...
             def close(self) -> None: ...
@@ -95,6 +152,7 @@ if sys.platform != "win32":
             def remove_child_handler(self, pid: int) -> bool: ...
             def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
 
+    if sys.version_info >= (3, 8):
         class ThreadedChildWatcher(AbstractChildWatcher):
             def is_active(self) -> Literal[True]: ...
             def close(self) -> None: ...

stdlib/builtins.pyi

@@ -64,6 +64,7 @@ from typing_extensions import (
     TypeAlias,
     TypeGuard,
     TypeVarTuple,
+    deprecated,
     final,
 )
 
@@ -938,6 +939,8 @@ class bool(int):
     @overload
     def __rxor__(self, __value: int) -> int: ...
     def __getnewargs__(self) -> tuple[int]: ...
+    @deprecated("Will throw an error in Python 3.14. Use `not` for logical negation of bools instead.")
+    def __invert__(self) -> int: ...
 
 @final
 class slice:

stdlib/pkgutil.pyi

@@ -3,6 +3,7 @@ from _typeshed import SupportsRead
 from collections.abc import Callable, Iterable, Iterator
 from importlib.abc import Loader, MetaPathFinder, PathEntryFinder
 from typing import IO, Any, NamedTuple, TypeVar
+from typing_extensions import deprecated
 
 __all__ = [
     "get_importer",
@@ -35,8 +36,10 @@ if sys.version_info < (3, 12):
     class ImpLoader:
         def __init__(self, fullname: str, file: IO[str], filename: str, etc: tuple[str, str, int]) -> None: ...
 
+@deprecated("Use importlib.util.find_spec() instead. Will be removed in Python 3.14.")
 def find_loader(fullname: str) -> Loader | None: ...
 def get_importer(path_item: str) -> PathEntryFinder | None: ...
+@deprecated("Use importlib.util.find_spec() instead. Will be removed in Python 3.14.")
 def get_loader(module_or_name: str) -> Loader | None: ...
 def iter_importers(fullname: str = "") -> Iterator[MetaPathFinder | PathEntryFinder]: ...
 def iter_modules(path: Iterable[str] | None = None, prefix: str = "") -> Iterator[ModuleInfo]: ...