[_thread] Deprecate undocumented synonyms (#15436)

Author: donbarbos

stdlib/_thread.pyi

@@ -5,7 +5,7 @@ from collections.abc import Callable
 from threading import Thread
 from types import TracebackType
 from typing import Any, Final, NoReturn, final, overload
-from typing_extensions import TypeVarTuple, Unpack, disjoint_base
+from typing_extensions import TypeVarTuple, Unpack, deprecated, disjoint_base
 
 _Ts = TypeVarTuple("_Ts")
 
@@ -38,9 +38,12 @@ if sys.version_info >= (3, 13):
         def acquire(self, blocking: bool = True, timeout: float = -1) -> bool: ...
         def release(self) -> None: ...
         def locked(self) -> bool: ...
-        def acquire_lock(self, blocking: bool = True, timeout: float = -1) -> bool: ...
-        def release_lock(self) -> None: ...
-        def locked_lock(self) -> bool: ...
+        @deprecated("Obsolete synonym. Use `acquire()` instead.")
+        def acquire_lock(self, blocking: bool = True, timeout: float = -1) -> bool: ...  # undocumented
+        @deprecated("Obsolete synonym. Use `release()` instead.")
+        def release_lock(self) -> None: ...  # undocumented
+        @deprecated("Obsolete synonym. Use `locked()` instead.")
+        def locked_lock(self) -> bool: ...  # undocumented
         def __enter__(self) -> bool: ...
         def __exit__(
             self, type: type[BaseException] | None, value: BaseException | None, traceback: TracebackType | None
@@ -53,9 +56,12 @@ else:
         def acquire(self, blocking: bool = True, timeout: float = -1) -> bool: ...
         def release(self) -> None: ...
         def locked(self) -> bool: ...
-        def acquire_lock(self, blocking: bool = True, timeout: float = -1) -> bool: ...
-        def release_lock(self) -> None: ...
-        def locked_lock(self) -> bool: ...
+        @deprecated("Obsolete synonym. Use `acquire()` instead.")
+        def acquire_lock(self, blocking: bool = True, timeout: float = -1) -> bool: ...  # undocumented
+        @deprecated("Obsolete synonym. Use `release()` instead.")
+        def release_lock(self) -> None: ...  # undocumented
+        @deprecated("Obsolete synonym. Use `locked()` instead.")
+        def locked_lock(self) -> bool: ...  # undocumented
         def __enter__(self) -> bool: ...
         def __exit__(
             self, type: type[BaseException] | None, value: BaseException | None, traceback: TracebackType | None
@@ -65,12 +71,12 @@ else:
 def start_new_thread(function: Callable[[Unpack[_Ts]], object], args: tuple[Unpack[_Ts]], /) -> int: ...
 @overload
 def start_new_thread(function: Callable[..., object], args: tuple[Any, ...], kwargs: dict[str, Any], /) -> int: ...
-
-# Obsolete synonym for start_new_thread()
 @overload
-def start_new(function: Callable[[Unpack[_Ts]], object], args: tuple[Unpack[_Ts]], /) -> int: ...
+@deprecated("Obsolete synonym. Use `start_new_thread()` instead.")
+def start_new(function: Callable[[Unpack[_Ts]], object], args: tuple[Unpack[_Ts]], /) -> int: ...  # undocumented
 @overload
-def start_new(function: Callable[..., object], args: tuple[Any, ...], kwargs: dict[str, Any], /) -> int: ...
+@deprecated("Obsolete synonym. Use `start_new_thread()` instead.")
+def start_new(function: Callable[..., object], args: tuple[Any, ...], kwargs: dict[str, Any], /) -> int: ...  # undocumented
 
 if sys.version_info >= (3, 10):
     def interrupt_main(signum: signal.Signals = signal.SIGINT, /) -> None: ...
@@ -79,9 +85,11 @@ else:
     def interrupt_main() -> None: ...
 
 def exit() -> NoReturn: ...
-def exit_thread() -> NoReturn: ...  # Obsolete synonym for exit()
+@deprecated("Obsolete synonym. Use `exit()` instead.")
+def exit_thread() -> NoReturn: ...  # undocumented
 def allocate_lock() -> LockType: ...
-def allocate() -> LockType: ...  # Obsolete synonym for allocate_lock()
+@deprecated("Obsolete synonym. Use `allocate_lock()` instead.")
+def allocate() -> LockType: ...  # undocumented
 def get_ident() -> int: ...
 def stack_size(size: int = 0, /) -> int: ...