Add concurrent.interpreters stubs for 3.14.0b3

stdlib/@tests/stubtest_allowlists/py314.txt

@@ -5,7 +5,6 @@
 _zstd.ZstdCompressor.set_pledged_input_size
 asyncio.tools
 compression.zstd.ZstdCompressor.set_pledged_input_size
-concurrent.interpreters
 multiprocessing.managers.BaseListProxy.clear
 multiprocessing.managers.BaseListProxy.copy
 multiprocessing.managers.DictProxy.__ior__
@@ -34,6 +33,15 @@ types.UnionType.__qualname__
 # Assigning `__new__` causes `func` not to get recognized.
 functools.partialmethod.__new__
 
+# decorator approximated by classmethod
+concurrent.interpreters._crossinterp.classonly.*
+
+# object() sentinels at runtime represented by NewTypes in the stubs
+concurrent.interpreters._crossinterp.UNBOUND_ERROR
+concurrent.interpreters._crossinterp.UNBOUND_REMOVE
+concurrent.interpreters._queues.UNBOUND_ERROR
+concurrent.interpreters._queues.UNBOUND_REMOVE
+
 # ====================================
 # Pre-existing errors from Python 3.13
 # ====================================

stdlib/VERSIONS

@@ -123,6 +123,7 @@ compileall: 3.0-
 compression: 3.14-
 concurrent: 3.2-
 concurrent.futures.interpreter: 3.14-
+concurrent.interpreters: 3.14-
 configparser: 3.0-
 contextlib: 3.0-
 contextvars: 3.7-

stdlib/_interpreters.pyi

@@ -1,8 +1,10 @@
 import types
 from collections.abc import Callable, Mapping
-from typing import Final, Literal, SupportsIndex
+from typing import Final, Literal, SupportsIndex, TypeVar
 from typing_extensions import TypeAlias
 
+_R = TypeVar("_R")
+
 _Configs: TypeAlias = Literal["default", "isolated", "legacy", "empty", ""]
 
 class InterpreterError(Exception): ...
@@ -20,18 +22,18 @@ def get_current() -> tuple[int, int]: ...
 def get_main() -> tuple[int, int]: ...
 def is_running(id: SupportsIndex, *, restrict: bool = False) -> bool: ...
 def get_config(id: SupportsIndex, *, restrict: bool = False) -> types.SimpleNamespace: ...
-def whence(id: SupportsIndex) -> int: ...
+def whence(id: SupportsIndex) -> _Whence: ...
 def exec(
     id: SupportsIndex, code: str | types.CodeType | Callable[[], object], shared: bool | None = None, *, restrict: bool = False
 ) -> None | types.SimpleNamespace: ...
 def call(
     id: SupportsIndex,
-    callable: Callable[..., object],
+    callable: Callable[..., _R],
     args: tuple[object, ...] | None = None,
     kwargs: dict[str, object] | None = None,
     *,
     restrict: bool = False,
-) -> object: ...
+) -> tuple[_R, types.SimpleNamespace]: ...
 def run_string(
     id: SupportsIndex, script: str | types.CodeType | Callable[[], object], shared: bool | None = None, *, restrict: bool = False
 ) -> None: ...
@@ -44,6 +46,7 @@ def decref(id: SupportsIndex, *, restrict: bool = False) -> None: ...
 def is_shareable(obj: object) -> bool: ...
 def capture_exception(exc: BaseException | None = None) -> types.SimpleNamespace: ...
 
+_Whence: TypeAlias = Literal[0, 1, 2, 3, 4, 5]
 WHENCE_UNKNOWN: Final = 0
 WHENCE_RUNTIME: Final = 1
 WHENCE_LEGACY_CAPI: Final = 2

stdlib/concurrent/interpreters/__init__.pyi

@@ -0,0 +1,63 @@
+import threading
+import types
+from collections.abc import Callable, Mapping
+from typing import Literal, TypeVar
+from typing_extensions import ParamSpec, Self
+
+from _interpreters import (
+    InterpreterError as InterpreterError,
+    InterpreterNotFoundError as InterpreterNotFoundError,
+    NotShareableError as NotShareableError,
+    _Whence,
+    is_shareable as is_shareable,
+)
+
+from ._queues import Queue as Queue, QueueEmpty as QueueEmpty, QueueFull as QueueFull, create as create_queue
+
+__all__ = [
+    "ExecutionFailed",
+    "Interpreter",
+    "InterpreterError",
+    "InterpreterNotFoundError",
+    "NotShareableError",
+    "Queue",
+    "QueueEmpty",
+    "QueueFull",
+    "create",
+    "create_queue",
+    "get_current",
+    "get_main",
+    "is_shareable",
+    "list_all",
+]
+
+_R = TypeVar("_R")
+_P = ParamSpec("_P")
+
+class ExecutionFailed(InterpreterError):
+    excinfo: types.SimpleNamespace
+
+    def __init__(self, excinfo: types.SimpleNamespace) -> None: ...
+
+def create() -> Interpreter: ...
+def list_all() -> list[Interpreter]: ...
+def get_current() -> Interpreter: ...
+def get_main() -> Interpreter: ...
+
+class Interpreter:
+    def __new__(cls, id: int, /, _whence: _Whence | None = None, _ownsref: bool | None = None) -> Self: ...
+    def __getnewargs__(self) -> tuple[int]: ...
+    def __hash__(self) -> int: ...
+    def __del__(self) -> None: ...
+    @property
+    def id(self) -> int: ...
+    @property
+    def whence(
+        self,
+    ) -> Literal["unknown", "runtime init", "legacy C-API", "C-API", "cross-interpreter C-API", "_interpreters module"]: ...
+    def is_running(self) -> bool: ...
+    def close(self) -> None: ...
+    def prepare_main(self, ns: Mapping[str, object] | None = None, /, **kwargs: object) -> None: ...
+    def exec(self, code: str | types.CodeType | Callable[[], object], /) -> None: ...
+    def call(self, callable: Callable[_P, _R], /, *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
+    def call_in_thread(self, callable: Callable[_P, object], /, *args: _P.args, **kwargs: _P.kwargs) -> threading.Thread: ...

stdlib/concurrent/interpreters/_crossinterp.pyi

@@ -0,0 +1,27 @@
+from collections.abc import Callable
+from typing import Never, NewType
+from typing_extensions import Self, TypeAlias
+
+from _interpqueues import _UnboundOp
+
+class ItemInterpreterDestroyed(Exception): ...
+
+# Actually a descriptor that behaves similarly to classmethod but prevents
+# access from instances.
+classonly = classmethod
+
+class UnboundItem:
+    def __new__(cls) -> Never: ...
+    @classonly
+    def singleton(cls, kind: str, module: str, name: str = "UNBOUND") -> Self: ...
+
+_UnboundErrorType = NewType("_UnboundErrorType", object)
+_UnboundRemoveType = NewType("_UnboundRemoveType", object)
+
+UNBOUND_ERROR: _UnboundErrorType
+UNBOUND_REMOVE: _UnboundRemoveType
+UNBOUND: UnboundItem  # analogous to UNBOUND_REPLACE in C
+_AnyUnbound: TypeAlias = _UnboundErrorType | _UnboundRemoveType | UnboundItem
+
+def serialize_unbound(unbound: _AnyUnbound) -> tuple[_UnboundOp]: ...
+def resolve_unbound(flag: _UnboundOp, exctype_destroyed: Callable[[str], BaseException]) -> UnboundItem: ...

stdlib/concurrent/interpreters/_queues.pyi

@@ -0,0 +1,57 @@
+import queue
+from typing import SupportsIndex
+from typing_extensions import Self
+
+from _interpqueues import QueueError as QueueError, QueueNotFoundError as QueueNotFoundError
+
+from . import _crossinterp
+from ._crossinterp import UNBOUND_ERROR as UNBOUND_ERROR, UNBOUND_REMOVE as UNBOUND_REMOVE
+
+__all__ = [
+    "UNBOUND",
+    "UNBOUND_ERROR",
+    "UNBOUND_REMOVE",
+    "ItemInterpreterDestroyed",
+    "Queue",
+    "QueueEmpty",
+    "QueueError",
+    "QueueFull",
+    "QueueNotFoundError",
+    "create",
+    "list_all",
+]
+
+class QueueEmpty(QueueError, queue.Empty): ...
+class QueueFull(QueueError, queue.Full): ...
+class ItemInterpreterDestroyed(QueueError, _crossinterp.ItemInterpreterDestroyed): ...
+
+UNBOUND: _crossinterp.UnboundItem
+
+def create(maxsize: int = 0, *, unbounditems: _crossinterp._AnyUnbound = ...) -> Queue: ...
+def list_all() -> list[Queue]: ...
+
+class Queue:
+    def __new__(cls, id: int, /) -> Self: ...
+    def __del__(self) -> None: ...
+    def __hash__(self) -> int: ...
+    def __getnewargs__(self) -> tuple[int]: ...
+    @property
+    def id(self) -> int: ...
+    @property
+    def unbounditems(self) -> _crossinterp._AnyUnbound: ...
+    @property
+    def maxsize(self) -> int: ...
+    def empty(self) -> bool: ...
+    def full(self) -> bool: ...
+    def qsize(self) -> int: ...
+    def put(
+        self,
+        obj: object,
+        timeout: SupportsIndex | None = None,
+        *,
+        unbounditems: _crossinterp._AnyUnbound | None = None,
+        _delay: float = ...,
+    ) -> None: ...
+    def put_nowait(self, obj: object, *, unbounditems: _crossinterp._AnyUnbound | None = None) -> None: ...
+    def get(self, timeout: SupportsIndex | None = None, *, _delay: float = ...) -> object: ...
+    def get_nowait(self) -> object: ...