Update setuptools return types (#12991)

stubs/setuptools/setuptools/__init__.pyi

@@ -1,6 +1,6 @@
-from _typeshed import Incomplete, StrPath
+from _typeshed import Incomplete
 from abc import abstractmethod
-from collections.abc import Iterable, Mapping, Sequence
+from collections.abc import Mapping, Sequence
 from typing import Any, Literal, TypedDict, TypeVar, overload, type_check_only
 from typing_extensions import NotRequired
 
@@ -27,6 +27,7 @@ from .command.saveopts import saveopts
 from .command.sdist import sdist
 from .command.setopt import setopt
 from .depends import Require as Require
+from .discovery import _Finder
 from .dist import Distribution as Distribution
 from .extension import Extension as Extension
 from .warnings import SetuptoolsDeprecationWarning as SetuptoolsDeprecationWarning
@@ -54,11 +55,9 @@ class _BuildInfo(TypedDict):
     include_dirs: NotRequired[list[str]]
     cflags: NotRequired[list[str]]
 
-# Pytype fails with the following:
-# find_packages = PackageFinder.find
-# find_namespace_packages = PEP420PackageFinder.find
-def find_packages(where: StrPath = ".", exclude: Iterable[str] = (), include: Iterable[str] = ("*",)) -> list[str]: ...
-def find_namespace_packages(where: StrPath = ".", exclude: Iterable[str] = (), include: Iterable[str] = ("*",)) -> list[str]: ...
+find_packages = _Finder.find
+find_namespace_packages = _Finder.find
+
 def setup(
     *,
     name: str = ...,

stubs/setuptools/setuptools/build_meta.pyi

@@ -1,5 +1,7 @@
 from _typeshed import Incomplete, StrPath
 from collections.abc import Mapping
+from contextlib import _GeneratorContextManager
+from typing import NoReturn
 from typing_extensions import TypeAlias
 
 from . import dist
@@ -24,9 +26,9 @@ class SetupRequirementsError(BaseException):
     def __init__(self, specifiers) -> None: ...
 
 class Distribution(dist.Distribution):
-    def fetch_build_eggs(self, specifiers) -> None: ...
+    def fetch_build_eggs(self, specifiers) -> NoReturn: ...
     @classmethod
-    def patch(cls) -> None: ...
+    def patch(cls) -> _GeneratorContextManager[None]: ...
 
 class _BuildMetaBackend:
     def run_setup(self, setup_script: str = "setup.py") -> None: ...

stubs/setuptools/setuptools/command/bdist_egg.pyi

@@ -1,14 +1,15 @@
-from _typeshed import Incomplete, StrPath
-from collections.abc import Generator
-from typing import ClassVar, Final, TypeVar
+from _typeshed import GenericPath, Incomplete, StrPath
+from collections.abc import Iterator
+from types import CodeType
+from typing import AnyStr, ClassVar, Final, TypeVar
 from zipfile import _ZipFileMode
 
 from .. import Command
 
 _StrPathT = TypeVar("_StrPathT", bound=StrPath)
 
 def strip_module(filename): ...
-def sorted_walk(dir) -> Generator[Incomplete, None, None]: ...
+def sorted_walk(dir: GenericPath[AnyStr]) -> Iterator[tuple[AnyStr, list[AnyStr], list[AnyStr]]]: ...
 def write_stub(resource, pyfile) -> None: ...
 
 class bdist_egg(Command):
@@ -38,15 +39,15 @@ class bdist_egg(Command):
 
 NATIVE_EXTENSIONS: Final[dict[str, None]]
 
-def walk_egg(egg_dir) -> Generator[Incomplete, None, None]: ...
+def walk_egg(egg_dir: StrPath) -> Iterator[tuple[str, list[str], list[str]]]: ...
 def analyze_egg(egg_dir, stubs): ...
 def write_safety_flag(egg_dir, safe) -> None: ...
 
 safety_flags: Incomplete
 
 def scan_module(egg_dir, base, name, stubs): ...
-def iter_symbols(code) -> Generator[Incomplete, None, None]: ...
-def can_scan(): ...
+def iter_symbols(code: CodeType) -> Iterator[str]: ...
+def can_scan() -> bool: ...
 
 INSTALL_DIRECTORY_ATTRS: Final[list[str]]
 

stubs/setuptools/setuptools/command/build_ext.pyi

@@ -30,7 +30,8 @@ class build_ext(_build_ext):
     compiler: Incomplete
     def build_extension(self, ext) -> None: ...
     def links_to_dynamic(self, ext): ...
-    def get_outputs(self): ...
+    def get_source_files(self) -> list[str]: ...
+    def get_outputs(self) -> list[str]: ...
     def get_output_mapping(self) -> dict[str, str]: ...
     def write_stub(self, output_dir, ext, compile: bool = False) -> None: ...
 

stubs/setuptools/setuptools/command/build_py.pyi

@@ -24,21 +24,21 @@ class build_py(orig.build_py):
         level: Unused = 1,
     ) -> tuple[_StrPathT | str, bool]: ...
     def run(self) -> None: ...
-    data_files: list[tuple[Incomplete, Incomplete, Incomplete, list[Incomplete]]]
+    data_files: list[tuple[str, str, str, list[str]]]
     def __getattr__(self, attr: str): ...
     def build_module(self, module, module_file, package): ...
-    def get_data_files_without_manifest(self) -> list[tuple[Incomplete, Incomplete, Incomplete, list[Incomplete]]]: ...
-    def find_data_files(self, package, src_dir): ...
+    def get_data_files_without_manifest(self) -> list[tuple[str, str, str, list[str]]]: ...
+    def find_data_files(self, package, src_dir) -> list[str]: ...
     def get_outputs(self, include_bytecode: bool = True) -> list[str]: ...  # type: ignore[override] # Using a real boolean instead of 0|1
     def build_package_data(self) -> None: ...
     manifest_files: dict[Incomplete, Incomplete]
     def get_output_mapping(self) -> dict[str, str]: ...
     def analyze_manifest(self) -> None: ...
     def get_data_files(self) -> None: ...
     def check_package(self, package, package_dir): ...
-    packages_checked: dict[Incomplete, Incomplete]
     def initialize_options(self) -> None: ...
-    def get_package_dir(self, package): ...
+    packages_checked: dict[Incomplete, Incomplete]
+    def get_package_dir(self, package: str) -> str: ...
     def exclude_data_files(self, package, src_dir, files): ...
 
 def assert_relative(path): ...

stubs/setuptools/setuptools/command/easy_install.pyi

@@ -1,9 +1,9 @@
 from _typeshed import Incomplete
 from collections.abc import Iterable, Iterator
-from typing import Any, ClassVar, Literal, TypedDict
+from typing import Any, ClassVar, Literal, NoReturn, TypedDict
 from typing_extensions import Self
 
-from pkg_resources import Environment
+from pkg_resources import Distribution, Environment
 from setuptools.package_index import PackageIndex
 
 from .. import Command, SetuptoolsDeprecationWarning
@@ -60,28 +60,28 @@ class easy_install(Command):
     def pseudo_tempname(self): ...
     def warn_deprecated_options(self) -> None: ...
     def check_site_dir(self) -> None: ...
-    def cant_write_to_target(self) -> None: ...
+    def cant_write_to_target(self) -> NoReturn: ...
     def check_pth_processing(self): ...
     def install_egg_scripts(self, dist) -> None: ...
     def add_output(self, path) -> None: ...
     def not_editable(self, spec) -> None: ...
     def check_editable(self, spec) -> None: ...
-    def easy_install(self, spec, deps: bool = False): ...
-    def install_item(self, spec, download, tmpdir, deps, install_needed: bool = False): ...
+    def easy_install(self, spec, deps: bool = False) -> Distribution | None: ...
+    def install_item(self, spec, download, tmpdir, deps, install_needed: bool = False) -> Distribution | None: ...
     def select_scheme(self, name) -> None: ...
     def process_distribution(self, requirement, dist, deps: bool = True, *info) -> None: ...
-    def should_unzip(self, dist): ...
+    def should_unzip(self, dist) -> bool: ...
     def maybe_move(self, spec, dist_filename, setup_base): ...
     def install_wrapper_scripts(self, dist) -> None: ...
     def install_script(self, dist, script_name, script_text, dev_path: Incomplete | None = None) -> None: ...
     def write_script(self, script_name, contents, mode: str = "t", blockers=()) -> None: ...
-    def install_eggs(self, spec, dist_filename, tmpdir): ...
+    def install_eggs(self, spec, dist_filename, tmpdir) -> list[Distribution]: ...
     def egg_distribution(self, egg_path): ...
     def install_egg(self, egg_path, tmpdir): ...
     def install_exe(self, dist_filename, tmpdir): ...
-    def exe_to_egg(self, dist_filename, egg_tmp): ...
+    def exe_to_egg(self, dist_filename, egg_tmp) -> None: ...
     def install_wheel(self, wheel_path, tmpdir): ...
-    def installation_report(self, req, dist, what: str = "Installed"): ...
+    def installation_report(self, req, dist, what: str = "Installed") -> str: ...
     def report_editable(self, spec, setup_script): ...
     def run_setup(self, setup_script, setup_base, args) -> None: ...
     def build_and_install(self, setup_script, setup_base): ...

stubs/setuptools/setuptools/command/egg_info.pyi

@@ -30,7 +30,7 @@ class egg_info(InfoCommon, Command):
     egg_version: Incomplete
     def initialize_options(self) -> None: ...
     @property
-    def tag_svn_revision(self) -> None: ...
+    def tag_svn_revision(self) -> int | None: ...
     @tag_svn_revision.setter
     def tag_svn_revision(self, value) -> None: ...
     def save_version_info(self, filename) -> None: ...

stubs/setuptools/setuptools/command/sdist.pyi

@@ -1,11 +1,12 @@
 from _typeshed import Incomplete
+from collections.abc import Iterator
 from typing import ClassVar
 
 from setuptools.dist import Distribution
 
 from .._distutils.command import sdist as orig
 
-def walk_revctrl(dirname: str = "") -> None: ...
+def walk_revctrl(dirname: str = "") -> Iterator[Incomplete]: ...
 
 class sdist(orig.sdist):
     distribution: Distribution  # override distutils.dist.Distribution with setuptools.dist.Distribution

stubs/setuptools/setuptools/command/test.pyi

@@ -1,4 +1,4 @@
-from typing import ClassVar
+from typing import ClassVar, NoReturn
 from typing_extensions import deprecated
 
 from .. import Command
@@ -14,4 +14,4 @@ class test(Command):
     user_options: ClassVar[list[tuple[str, str, str]]]
     def initialize_options(self) -> None: ...
     def finalize_options(self) -> None: ...
-    def run(self) -> None: ...
+    def run(self) -> NoReturn: ...

stubs/setuptools/setuptools/config/__init__.pyi

@@ -1,16 +1,3 @@
-from _typeshed import Incomplete, StrPath
-from collections.abc import Callable
-from typing import TypeVar
+from .setupcfg import parse_configuration as parse_configuration, read_configuration as read_configuration
 
-from setuptools.config.setupcfg import AllCommandOptions, ConfigMetadataHandler, ConfigOptionsHandler
-from setuptools.dist import Distribution
-
-Fn = TypeVar("Fn", bound=Callable[..., Incomplete])  # noqa: Y001 # Exists at runtime
 __all__ = ("parse_configuration", "read_configuration")
-
-def read_configuration(
-    filepath: StrPath, find_others: bool = False, ignore_option_errors: bool = False
-) -> dict[Incomplete, Incomplete]: ...
-def parse_configuration(
-    distribution: Distribution, command_options: AllCommandOptions, ignore_option_errors: bool = False
-) -> tuple[ConfigMetadataHandler, ConfigOptionsHandler]: ...

stubs/setuptools/setuptools/config/expand.pyi

@@ -41,7 +41,7 @@ class EnsurePackagesDiscovered:
         self, exc_type: type[BaseException] | None, exc_value: BaseException | None, traceback: TracebackType | None
     ) -> None: ...
     @property
-    def package_dir(self) -> Mapping[str, str]: ...
+    def package_dir(self) -> LazyMappingProxy[str, str]: ...
 
 class LazyMappingProxy(Mapping[_K, _V_co]):
     def __init__(self, obtain_mapping_value: Callable[[], Mapping[_K, _V_co]]) -> None: ...

stubs/setuptools/setuptools/config/setupcfg.pyi

@@ -1,5 +1,6 @@
 from _typeshed import Incomplete, StrPath
-from collections.abc import Iterable
+from abc import abstractmethod
+from collections.abc import Callable, Iterable
 from typing import Any, ClassVar, Generic, TypeVar
 from typing_extensions import TypeAlias
 
@@ -38,7 +39,8 @@ class ConfigHandler(Generic[Target]):
         ensure_discovered: expand.EnsurePackagesDiscovered,
     ) -> None: ...
     @property
-    def parsers(self) -> None: ...
+    @abstractmethod
+    def parsers(self) -> dict[str, Callable[..., Incomplete]]: ...
     def __setitem__(self, option_name, value): ...
     def parse_section(self, section_options) -> None: ...
     def parse(self) -> None: ...
@@ -59,7 +61,7 @@ class ConfigMetadataHandler(ConfigHandler[DistributionMetadata]):
         root_dir: StrPath | None = ".",
     ) -> None: ...
     @property
-    def parsers(self): ...
+    def parsers(self) -> dict[str, Callable[..., Incomplete]]: ...
 
 class ConfigOptionsHandler(ConfigHandler[Distribution]):
     section_prefix: str
@@ -73,10 +75,10 @@ class ConfigOptionsHandler(ConfigHandler[Distribution]):
         ensure_discovered: expand.EnsurePackagesDiscovered,
     ) -> None: ...
     @property
-    def parsers(self): ...
+    def parsers(self) -> dict[str, Callable[..., Incomplete]]: ...
     def parse_section_packages__find(self, section_options): ...
     def parse_section_entry_points(self, section_options) -> None: ...
     def parse_section_package_data(self, section_options) -> None: ...
     def parse_section_exclude_package_data(self, section_options) -> None: ...
-    def parse_section_extras_require(self, section_options): ...
+    def parse_section_extras_require(self, section_options) -> None: ...
     def parse_section_data_files(self, section_options) -> None: ...

stubs/setuptools/setuptools/depends.pyi

@@ -1,5 +1,7 @@
 from _typeshed import Incomplete
-from typing import IO, Any, Literal
+from typing import IO, Any, Literal, TypeVar
+
+_T = TypeVar("_T")
 
 __all__ = ["Require", "find_module", "get_module_constant", "extract_constant"]
 
@@ -19,9 +21,11 @@ class Require:
     ) -> None: ...
     def full_name(self): ...
     def version_ok(self, version): ...
-    def get_version(self, paths: Incomplete | None = None, default: str = "unknown"): ...
+    def get_version(
+        self, paths: Incomplete | None = None, default: _T | Literal["unknown"] = "unknown"
+    ) -> _T | Literal["unknown"] | None | Any: ...
     def is_present(self, paths: Incomplete | None = None): ...
     def is_current(self, paths: Incomplete | None = None): ...
 
-def get_module_constant(module, symbol, default: str | int = -1, paths: Incomplete | None = None) -> Any: ...
-def extract_constant(code, symbol, default: str | int = -1) -> Any: ...
+def get_module_constant(module, symbol, default: _T | int = -1, paths: Incomplete | None = None) -> _T | int | None | Any: ...
+def extract_constant(code, symbol, default: _T | int = -1) -> _T | int | None | Any: ...

stubs/setuptools/setuptools/dist.pyi

@@ -187,7 +187,7 @@ class Distribution(_Distribution):
     def reinitialize_command(self, command: _CommandT, reinit_subcommands: bool = False) -> _CommandT: ...
     def include(self, **attrs) -> None: ...
     def exclude_package(self, package: str) -> None: ...
-    def has_contents_for(self, package: str) -> bool | None: ...
+    def has_contents_for(self, package: str) -> bool: ...
     def exclude(self, **attrs) -> None: ...
     def get_cmdline_options(self) -> dict[str, dict[str, str | None]]: ...
     def iter_distribution_names(self) -> Iterator[str]: ...

stubs/setuptools/setuptools/msvc.pyi

@@ -59,7 +59,7 @@ class RegistryInfo:
     def microsoft(self, key: LiteralString, x86: bool = False) -> LiteralString: ...
     @overload
     def microsoft(self, key: str, x86: bool = False) -> str: ...  # type: ignore[misc]
-    def lookup(self, key: str, name: str) -> str: ...
+    def lookup(self, key: str, name: str) -> str | None: ...
 
 class SystemInfo:
     WinDir: Final[str]
@@ -80,7 +80,7 @@ class SystemInfo:
     @property
     def VCInstallDir(self) -> str: ...
     @property
-    def WindowsSdkVersion(self) -> tuple[str, ...] | None: ...
+    def WindowsSdkVersion(self) -> tuple[LiteralString, ...] | None: ...
     @property
     def WindowsSdkLastVersion(self) -> str: ...
     @property
@@ -94,7 +94,7 @@ class SystemInfo:
     @property
     def UniversalCRTSdkLastVersion(self) -> str: ...
     @property
-    def NetFxSdkVersion(self) -> tuple[str, ...]: ...
+    def NetFxSdkVersion(self) -> tuple[LiteralString, ...]: ...
     @property
     def NetFxSdkDir(self) -> str: ...
     @property

stubs/setuptools/setuptools/package_index.pyi

@@ -1,20 +1,24 @@
 import configparser
 import urllib.request
 from _typeshed import Incomplete
+from collections.abc import Generator
 from hashlib import _Hash
 from re import Pattern
 from typing import ClassVar
 from typing_extensions import NamedTuple
 
-from pkg_resources import Environment
+from pkg_resources import Distribution, Environment
 
 __all__ = ["PackageIndex", "distros_for_url", "parse_bdist_wininst", "interpret_distro_name"]
 
 def parse_bdist_wininst(name): ...
-def distros_for_url(url, metadata: Incomplete | None = None) -> None: ...
+def distros_for_url(url, metadata: Incomplete | None = None) -> Generator[Distribution]: ...
+def distros_for_location(
+    location, basename, metadata: Incomplete | None = None
+) -> list[Distribution] | Generator[Distribution]: ...
 def interpret_distro_name(
     location, basename, metadata, py_version: Incomplete | None = None, precedence=1, platform: Incomplete | None = None
-) -> None: ...
+) -> Generator[Distribution]: ...
 
 class ContentChecker:
     def feed(self, block) -> None: ...

stubs/setuptools/setuptools/sandbox.pyi

@@ -1,6 +1,6 @@
 import sys
 from types import TracebackType
-from typing import ClassVar, Literal
+from typing import ClassVar
 from typing_extensions import Self
 
 from ._distutils.errors import DistutilsError
@@ -13,9 +13,7 @@ class UnpickleableException(Exception):
 
 class ExceptionSaver:
     def __enter__(self) -> Self: ...
-    def __exit__(
-        self, type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None
-    ) -> Literal[True] | None: ...
+    def __exit__(self, type: type[BaseException] | None, exc: BaseException | None, tb: TracebackType | None) -> bool: ...
     def resume(self) -> None: ...
 
 def run_setup(setup_script, args): ...