asyncio.unix_events: Make AbstractChildWatcher abstract, add PidfdChildWatcher (#7412)

Author: AlexWaygood

stdlib/asyncio/unix_events.pyi

@@ -1,8 +1,10 @@
 import sys
 import types
 from _typeshed import Self
+from abc import ABCMeta, abstractmethod
 from socket import socket
 from typing import Any, Callable
+from typing_extensions import Literal
 
 from .base_events import Server
 from .events import AbstractEventLoop, BaseDefaultEventLoopPolicy, _ProtocolFactory, _SSLContext
@@ -12,13 +14,20 @@ from .selector_events import BaseSelectorEventLoop
 # but other parts of typeshed need this defintion.
 # So, it is special cased.
 class AbstractChildWatcher:
+    @abstractmethod
     def add_child_handler(self, pid: int, callback: Callable[..., Any], *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) -> 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":
@@ -48,14 +57,27 @@ if sys.platform != "win32":
     else:
         __all__ = ["SelectorEventLoop", "AbstractChildWatcher", "SafeChildWatcher", "FastChildWatcher", "DefaultEventLoopPolicy"]
 
-    class BaseChildWatcher(AbstractChildWatcher):
+    # Doesn't actually have ABCMeta metaclass at runtime, but mypy complains if we don't have it in the stub.
+    # See discussion in #7412
+    class BaseChildWatcher(AbstractChildWatcher, metaclass=ABCMeta):
         def __init__(self) -> None: ...
+        def close(self) -> None: ...
+        if sys.version_info >= (3, 8):
+            def is_active(self) -> bool: ...
+
+        def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
 
     class SafeChildWatcher(BaseChildWatcher):
         def __enter__(self: 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[..., Any], *args: Any) -> None: ...
+        def remove_child_handler(self, pid: int) -> bool: ...
 
     class FastChildWatcher(BaseChildWatcher):
         def __enter__(self: 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[..., Any], *args: Any) -> None: ...
+        def remove_child_handler(self, pid: int) -> bool: ...
 
     class _UnixSelectorEventLoop(BaseSelectorEventLoop):
         if sys.version_info < (3, 7):
@@ -86,8 +108,39 @@ if sys.platform != "win32":
             ) -> None: ...
 
         class MultiLoopChildWatcher(AbstractChildWatcher):
+            def __init__(self) -> None: ...
+            def is_active(self) -> bool: ...
+            def close(self) -> None: ...
             def __enter__(self: 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[..., Any], *args: Any) -> None: ...
+            def remove_child_handler(self, pid: int) -> bool: ...
+            def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
 
         class ThreadedChildWatcher(AbstractChildWatcher):
+            def __init__(self) -> None: ...
+            def is_active(self) -> Literal[True]: ...
+            def close(self) -> None: ...
             def __enter__(self: Self) -> Self: ...
+            def __exit__(
+                self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: types.TracebackType | None
+            ) -> None: ...
             def __del__(self, _warn: _Warn = ...) -> None: ...
+            def add_child_handler(self, pid: int, callback: Callable[..., Any], *args: Any) -> None: ...
+            def remove_child_handler(self, pid: int) -> bool: ...
+            def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
+
+    if sys.version_info >= (3, 9):
+        class PidfdChildWatcher(AbstractChildWatcher):
+            def __init__(self) -> None: ...
+            def __enter__(self: Self) -> Self: ...
+            def __exit__(
+                self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: types.TracebackType | None
+            ) -> None: ...
+            def is_active(self) -> bool: ...
+            def close(self) -> None: ...
+            def attach_loop(self, loop: AbstractEventLoop | None) -> None: ...
+            def add_child_handler(self, pid: int, callback: Callable[..., Any], *args: Any) -> None: ...
+            def remove_child_handler(self, pid: int) -> bool: ...

tests/stubtest_allowlists/darwin-py310.txt

@@ -3,6 +3,4 @@ _curses.color_pair
 curses.color_pair
 
 # Exists at runtime, but missing from stubs
-asyncio.PidfdChildWatcher
-asyncio.unix_events.PidfdChildWatcher
 mmap.MADV_FREE

tests/stubtest_allowlists/darwin-py39.txt

@@ -1,6 +1,4 @@
 _?curses.A_ITALIC
 
 # Exists at runtime, but missing from stubs
-asyncio.PidfdChildWatcher
-asyncio.unix_events.PidfdChildWatcher
 mmap.MADV_FREE

tests/stubtest_allowlists/linux-py310.txt

@@ -18,8 +18,6 @@ signal.sigwaitinfo
 select.epoll.register
 
 # Exists at runtime, but missing from stubs
-asyncio.PidfdChildWatcher
-asyncio.unix_events.PidfdChildWatcher
 os.EFD_CLOEXEC
 os.EFD_NONBLOCK
 os.EFD_SEMAPHORE

tests/stubtest_allowlists/linux-py39.txt

@@ -2,8 +2,6 @@
 select.epoll.register
 
 # Exists at runtime, but missing from stubs
-asyncio.PidfdChildWatcher
-asyncio.unix_events.PidfdChildWatcher
 os.copy_file_range
 os.pidfd_open
 posix.copy_file_range