importlib.resources.contents is deprecated (#14835)

Author: sobolevn

stdlib/@tests/test_cases/check_importlib_resources.py

@@ -29,4 +29,4 @@ def f(pth: pathlib.Path | str | _CustomPathLike) -> None:
         importlib.resources.read_binary("pkg", pth)
         importlib.resources.path("pkg", pth)
         importlib.resources.is_resource("pkg", pth)
-        importlib.resources.contents("pkg", pth)
+        importlib.resources.contents("pkg", pth)  # pyright: ignore[reportDeprecated]

stdlib/importlib/resources/__init__.pyi

@@ -5,7 +5,7 @@ from contextlib import AbstractContextManager
 from pathlib import Path
 from types import ModuleType
 from typing import Any, BinaryIO, Literal, TextIO
-from typing_extensions import TypeAlias
+from typing_extensions import TypeAlias, deprecated
 
 if sys.version_info >= (3, 11):
     from importlib.resources.abc import Traversable
@@ -64,7 +64,11 @@ else:
     def read_text(package: Package, resource: Resource, encoding: str = "utf-8", errors: str = "strict") -> str: ...
     def path(package: Package, resource: Resource) -> AbstractContextManager[Path, Literal[False]]: ...
     def is_resource(package: Package, name: str) -> bool: ...
-    def contents(package: Package) -> Iterator[str]: ...
+    if sys.version_info >= (3, 11):
+        @deprecated("Deprecated since Python 3.11. Use `files(anchor).iterdir()`.")
+        def contents(package: Package) -> Iterator[str]: ...
+    else:
+        def contents(package: Package) -> Iterator[str]: ...
 
 if sys.version_info >= (3, 11):
     from importlib.resources._common import as_file as as_file

stdlib/importlib/resources/_functional.pyi

@@ -9,7 +9,7 @@ if sys.version_info >= (3, 13):
     from io import TextIOWrapper
     from pathlib import Path
     from typing import BinaryIO, Literal, overload
-    from typing_extensions import Unpack
+    from typing_extensions import Unpack, deprecated
 
     def open_binary(anchor: Anchor, *path_names: StrPath) -> BinaryIO: ...
     @overload
@@ -27,4 +27,5 @@ if sys.version_info >= (3, 13):
     def read_text(anchor: Anchor, *path_names: StrPath, encoding: str | None, errors: str | None = "strict") -> str: ...
     def path(anchor: Anchor, *path_names: StrPath) -> AbstractContextManager[Path, Literal[False]]: ...
     def is_resource(anchor: Anchor, *path_names: StrPath) -> bool: ...
+    @deprecated("Deprecated since Python 3.11. Use `files(anchor).iterdir()`.")
     def contents(anchor: Anchor, *path_names: StrPath) -> Iterator[str]: ...