[stdlib] Deprecate old functions (#14553)

* [stdlib] Deprecate many functions

* Fix typo

* Imporove message for asyncio/trsock

* Apply suggestions from code review

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

* Add Python before version

* [pre-commit.ci] auto fixes from pre-commit.com hooks

* Wrap comment lines

* fix the rest

---------

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

stdlib/importlib/__init__.pyi

@@ -2,6 +2,7 @@ import sys
 from importlib._bootstrap import __import__ as __import__
 from importlib.abc import Loader
 from types import ModuleType
+from typing_extensions import deprecated
 
 __all__ = ["__import__", "import_module", "invalidate_caches", "reload"]
 
@@ -9,6 +10,7 @@ __all__ = ["__import__", "import_module", "invalidate_caches", "reload"]
 def import_module(name: str, package: str | None = None) -> ModuleType: ...
 
 if sys.version_info < (3, 12):
+    @deprecated("Deprecated since Python 3.4; removed in Python 3.12. Use `importlib.util.find_spec()` instead.")
     def find_loader(name: str, path: str | None = None) -> Loader | None: ...
 
 def invalidate_caches() -> None: ...

stdlib/importlib/_abc.pyi

@@ -2,11 +2,16 @@ import sys
 import types
 from abc import ABCMeta
 from importlib.machinery import ModuleSpec
+from typing_extensions import deprecated
 
 if sys.version_info >= (3, 10):
     class Loader(metaclass=ABCMeta):
         def load_module(self, fullname: str) -> types.ModuleType: ...
         if sys.version_info < (3, 12):
+            @deprecated(
+                "Deprecated since Python 3.4; removed in Python 3.12. "
+                "The module spec is now used by the import machinery to generate a module repr."
+            )
             def module_repr(self, module: types.ModuleType) -> str: ...
 
         def create_module(self, spec: ModuleSpec) -> types.ModuleType | None: ...

stdlib/importlib/abc.pyi

@@ -37,6 +37,7 @@ else:
         def exec_module(self, module: types.ModuleType) -> None: ...
 
 if sys.version_info < (3, 12):
+    @deprecated("Deprecated since Python 3.3; removed in Python 3.12. Use `MetaPathFinder` or `PathEntryFinder` instead.")
     class Finder(metaclass=ABCMeta): ...
 
 @deprecated("Deprecated as of Python 3.7: Use importlib.resources.abc.TraversableResources instead.")
@@ -71,6 +72,7 @@ if sys.version_info >= (3, 10):
     # Please keep in sync with _typeshed.importlib.MetaPathFinderProtocol
     class MetaPathFinder(metaclass=ABCMeta):
         if sys.version_info < (3, 12):
+            @deprecated("Deprecated since Python 3.4; removed in Python 3.12. Use `MetaPathFinder.find_spec()` instead.")
             def find_module(self, fullname: str, path: Sequence[str] | None) -> Loader | None: ...
 
         def invalidate_caches(self) -> None: ...
@@ -81,7 +83,9 @@ if sys.version_info >= (3, 10):
 
     class PathEntryFinder(metaclass=ABCMeta):
         if sys.version_info < (3, 12):
+            @deprecated("Deprecated since Python 3.4; removed in Python 3.12. Use `PathEntryFinder.find_spec()` instead.")
             def find_module(self, fullname: str) -> Loader | None: ...
+            @deprecated("Deprecated since Python 3.4; removed in Python 3.12. Use `find_spec()` instead.")
             def find_loader(self, fullname: str) -> tuple[Loader | None, Sequence[str]]: ...
 
         def invalidate_caches(self) -> None: ...

stdlib/importlib/metadata/__init__.pyi

@@ -11,7 +11,7 @@ from os import PathLike
 from pathlib import Path
 from re import Pattern
 from typing import Any, ClassVar, Generic, NamedTuple, TypeVar, overload
-from typing_extensions import Self, TypeAlias
+from typing_extensions import Self, TypeAlias, deprecated
 
 _T = TypeVar("_T")
 _KT = TypeVar("_KT")
@@ -148,6 +148,7 @@ if sys.version_info >= (3, 10) and sys.version_info < (3, 12):
         def keys(self) -> dict_keys[_KT, _VT]: ...
         def values(self) -> dict_values[_KT, _VT]: ...
 
+    @deprecated("Deprecated since Python 3.10; removed in Python 3.12. Use `select` instead.")
     class SelectableGroups(Deprecated[str, EntryPoints], dict[str, EntryPoints]):  # use as dict is deprecated since 3.10
         @classmethod
         def load(cls, eps: Iterable[EntryPoint]) -> Self: ...

stdlib/importlib/util.pyi

@@ -12,13 +12,25 @@ from importlib._bootstrap_external import (
     spec_from_file_location as spec_from_file_location,
 )
 from importlib.abc import Loader
-from typing_extensions import ParamSpec
+from typing_extensions import ParamSpec, deprecated
 
 _P = ParamSpec("_P")
 
 if sys.version_info < (3, 12):
+    @deprecated(
+        "Deprecated since Python 3.4; removed in Python 3.12. "
+        "`__name__`, `__package__` and `__loader__` are now set automatically."
+    )
     def module_for_loader(fxn: Callable[_P, types.ModuleType]) -> Callable[_P, types.ModuleType]: ...
+    @deprecated(
+        "Deprecated since Python 3.4; removed in Python 3.12. "
+        "`__name__`, `__package__` and `__loader__` are now set automatically."
+    )
     def set_loader(fxn: Callable[_P, types.ModuleType]) -> Callable[_P, types.ModuleType]: ...
+    @deprecated(
+        "Deprecated since Python 3.4; removed in Python 3.12. "
+        "`__name__`, `__package__` and `__loader__` are now set automatically."
+    )
     def set_package(fxn: Callable[_P, types.ModuleType]) -> Callable[_P, types.ModuleType]: ...
 
 def resolve_name(name: str, package: str | None) -> str: ...