Fill out more annotations for distutils & setuptools dist (#9895)

Signed-off-by: Henry Schreiner <[email protected]>
Co-authored-by: Alex Waygood <[email protected]>
Co-authored-by: Jelle Zijlstra <[email protected]>

Author: 3 people

stdlib/distutils/dist.pyi

@@ -2,10 +2,14 @@ from _typeshed import FileDescriptorOrPath, Incomplete, SupportsWrite
 from collections.abc import Iterable, Mapping
 from distutils.cmd import Command
 from re import Pattern
-from typing import IO, Any
+from typing import IO, Any, ClassVar, TypeVar, overload
+from typing_extensions import TypeAlias
 
 command_re: Pattern[str]
 
+_OptionsList: TypeAlias = list[tuple[str, str | None, str, int] | tuple[str, str | None, str]]
+_CommandT = TypeVar("_CommandT", bound=Command)
+
 class DistributionMetadata:
     def __init__(self, path: FileDescriptorOrPath | None = None) -> None: ...
     name: str | None
@@ -59,22 +63,22 @@ class Distribution:
     def __init__(self, attrs: Mapping[str, Any] | None = None) -> None: ...
     def get_option_dict(self, command: str) -> dict[str, tuple[str, str]]: ...
     def parse_config_files(self, filenames: Iterable[str] | None = None) -> None: ...
-    def get_command_obj(self, command: str, create: bool = ...) -> Command | None: ...
-    global_options: Incomplete
-    common_usage: str
-    display_options: Incomplete
-    display_option_names: Incomplete
-    negative_opt: Incomplete
+    def get_command_obj(self, command: str, create: bool = True) -> Command | None: ...
+    global_options: ClassVar[_OptionsList]
+    common_usage: ClassVar[str]
+    display_options: ClassVar[_OptionsList]
+    display_option_names: ClassVar[list[str]]
+    negative_opt: ClassVar[dict[str, str]]
     verbose: int
     dry_run: int
     help: int
-    command_packages: Incomplete
-    script_name: Incomplete
-    script_args: Incomplete
-    command_options: Incomplete
-    dist_files: Incomplete
+    command_packages: list[str] | None
+    script_name: str | None
+    script_args: list[str] | None
+    command_options: dict[str, dict[str, tuple[str, str]]]
+    dist_files: list[tuple[str, str, str]]
     packages: Incomplete
-    package_data: Incomplete
+    package_data: dict[str, list[str]]
     package_dir: Incomplete
     py_modules: Incomplete
     libraries: Incomplete
@@ -101,21 +105,24 @@ class Distribution:
     def print_commands(self) -> None: ...
     def get_command_list(self): ...
     def get_command_packages(self): ...
-    def get_command_class(self, command): ...
-    def reinitialize_command(self, command, reinit_subcommands: int = 0): ...
+    def get_command_class(self, command: str) -> type[Command]: ...
+    @overload
+    def reinitialize_command(self, command: str, reinit_subcommands: bool = False) -> Command: ...
+    @overload
+    def reinitialize_command(self, command: _CommandT, reinit_subcommands: bool = False) -> _CommandT: ...
     def announce(self, msg, level: int = ...) -> None: ...
     def run_commands(self) -> None: ...
-    def run_command(self, command) -> None: ...
-    def has_pure_modules(self): ...
-    def has_ext_modules(self): ...
-    def has_c_libraries(self): ...
-    def has_modules(self): ...
-    def has_headers(self): ...
-    def has_scripts(self): ...
-    def has_data_files(self): ...
-    def is_pure(self): ...
+    def run_command(self, command: str) -> None: ...
+    def has_pure_modules(self) -> bool: ...
+    def has_ext_modules(self) -> bool: ...
+    def has_c_libraries(self) -> bool: ...
+    def has_modules(self) -> bool: ...
+    def has_headers(self) -> bool: ...
+    def has_scripts(self) -> bool: ...
+    def has_data_files(self) -> bool: ...
+    def is_pure(self) -> bool: ...
 
-    # Autogenerated getters
+    # Getter methods generated in __init__
     def get_name(self) -> str: ...
     def get_version(self) -> str: ...
     def get_fullname(self) -> str: ...

stubs/setuptools/@tests/stubtest_allowlist.txt

@@ -27,7 +27,10 @@ pkg_resources.to_filename
 pkg_resources.PathMetadata.egg_info
 pkg_resources.EggMetadata.loader
 
-# Dynamically created
+# 1 used for True as a default value
+setuptools._distutils.dist.Distribution.get_command_obj
+
+# Dynamically created in __init__
 setuptools._distutils.dist.Distribution.get_.*
 
 # Uncomment once ignore_missing_stub is turned off

stubs/setuptools/setuptools/_distutils/dist.pyi

@@ -1,11 +1,18 @@
 from _typeshed import FileDescriptorOrPath, Incomplete, SupportsWrite
 from collections.abc import Iterable, Mapping
-from typing import IO
+from re import Pattern
+from typing import IO, Any, ClassVar, TypeVar, overload
+from typing_extensions import TypeAlias
 
 from .cmd import Command
 
+command_re: Pattern[str]
+
+_OptionsList: TypeAlias = list[tuple[str, str | None, str, int] | tuple[str, str | None, str]]
+_CommandT = TypeVar("_CommandT", bound=Command)
+
 class DistributionMetadata:
-    def __init__(self, path: FileDescriptorOrPath | None = ...) -> None: ...
+    def __init__(self, path: FileDescriptorOrPath | None = None) -> None: ...
     name: str | None
     version: str | None
     author: str | None
@@ -54,12 +61,69 @@ class DistributionMetadata:
 class Distribution:
     cmdclass: dict[str, type[Command]]
     metadata: DistributionMetadata
-    def __init__(self, attrs: Mapping[str, Incomplete] | None = ...) -> None: ...
+    def __init__(self, attrs: Mapping[str, Any] | None = None) -> None: ...
     def get_option_dict(self, command: str) -> dict[str, tuple[str, str]]: ...
-    def parse_config_files(self, filenames: Iterable[str] | None = ...) -> None: ...
-    def get_command_obj(self, command: str, create: bool = ...) -> Command | None: ...
+    def parse_config_files(self, filenames: Iterable[str] | None = None) -> None: ...
+    def get_command_obj(self, command: str, create: bool = True) -> Command | None: ...
+    global_options: ClassVar[_OptionsList]
+    common_usage: ClassVar[str]
+    display_options: ClassVar[_OptionsList]
+    display_option_names: ClassVar[list[str]]
+    negative_opt: ClassVar[dict[str, str]]
+    verbose: int
+    dry_run: int
+    help: int
+    command_packages: list[str] | None
+    script_name: str | None
+    script_args: list[str] | None
+    command_options: dict[str, dict[str, tuple[str, str]]]
+    dist_files: list[tuple[str, str, str]]
+    packages: Incomplete
+    package_data: dict[str, list[str]]
+    package_dir: Incomplete
+    py_modules: Incomplete
+    libraries: Incomplete
+    headers: Incomplete
+    ext_modules: Incomplete
+    ext_package: Incomplete
+    include_dirs: Incomplete
+    extra_path: Incomplete
+    scripts: Incomplete
+    data_files: Incomplete
+    password: str
+    command_obj: dict[str, Command]
+    have_run: dict[str, bool]
+    want_user_cfg: bool
+    def dump_option_dicts(
+        self, header: Incomplete | None = None, commands: Incomplete | None = None, indent: str = ""
+    ) -> None: ...
+    def find_config_files(self): ...
+    commands: Incomplete
+    def parse_command_line(self): ...
+    def finalize_options(self) -> None: ...
+    def handle_display_options(self, option_order): ...
+    def print_command_list(self, commands, header, max_length) -> None: ...
+    def print_commands(self) -> None: ...
+    def get_command_list(self): ...
+    def get_command_packages(self): ...
+    def get_command_class(self, command: str) -> type[Command]: ...
+    @overload
+    def reinitialize_command(self, command: str, reinit_subcommands: bool = False) -> Command: ...
+    @overload
+    def reinitialize_command(self, command: _CommandT, reinit_subcommands: bool = False) -> _CommandT: ...
+    def announce(self, msg, level: int = ...) -> None: ...
+    def run_commands(self) -> None: ...
+    def run_command(self, command: str) -> None: ...
+    def has_pure_modules(self) -> bool: ...
+    def has_ext_modules(self) -> bool: ...
+    def has_c_libraries(self) -> bool: ...
+    def has_modules(self) -> bool: ...
+    def has_headers(self) -> bool: ...
+    def has_scripts(self) -> bool: ...
+    def has_data_files(self) -> bool: ...
+    def is_pure(self) -> bool: ...
 
-    # Autogenerated getters
+    # Getter methods generated in __init__
     def get_name(self) -> str: ...
     def get_version(self) -> str: ...
     def get_fullname(self) -> str: ...

stubs/setuptools/setuptools/dist.pyi

@@ -1,36 +1,29 @@
-from _typeshed import Incomplete
+from collections.abc import Iterable, Iterator, Mapping, MutableMapping
+from typing import Any
 
-from setuptools import SetuptoolsDeprecationWarning
+from setuptools import Command, SetuptoolsDeprecationWarning
 
 from ._distutils.dist import Distribution as _Distribution
 
 class Distribution(_Distribution):
-    def patch_missing_pkg_info(self, attrs) -> None: ...
-    package_data: Incomplete
-    dist_files: Incomplete
-    src_root: Incomplete
-    dependency_links: Incomplete
-    setup_requires: Incomplete
-    def __init__(self, attrs: Incomplete | None = ...) -> None: ...
-    def warn_dash_deprecation(self, opt, section): ...
-    def make_option_lowercase(self, opt, section): ...
-    def parse_config_files(self, filenames: Incomplete | None = ..., ignore_option_errors: bool = ...) -> None: ...
-    def fetch_build_eggs(self, requires): ...
-    def finalize_options(self): ...
-    def get_egg_cache_dir(self): ...
+    def patch_missing_pkg_info(self, attrs: Mapping[str, Any]) -> None: ...
+    src_root: str | None
+    dependency_links: list[str]
+    setup_requires: list[str]
+    def __init__(self, attrs: MutableMapping[str, Any] | None = None) -> None: ...
+    def warn_dash_deprecation(self, opt: str, section: str) -> str: ...
+    def make_option_lowercase(self, opt: str, section: str) -> str: ...
+    def parse_config_files(self, filenames: Iterable[str] | None = ..., ignore_option_errors: bool = ...) -> None: ...
+    def fetch_build_eggs(self, requires: str | Iterable[str]): ...
+    def get_egg_cache_dir(self) -> str: ...
     def fetch_build_egg(self, req): ...
-    def get_command_class(self, command): ...
-    def print_commands(self): ...
-    def get_command_list(self): ...
+    def get_command_class(self, command: str) -> type[Command]: ...
     def include(self, **attrs) -> None: ...
-    packages: Incomplete
-    py_modules: Incomplete
-    ext_modules: Incomplete
-    def exclude_package(self, package) -> None: ...
-    def has_contents_for(self, package): ...
+    def exclude_package(self, package: str) -> None: ...
+    def has_contents_for(self, package: str) -> bool | None: ...
     def exclude(self, **attrs) -> None: ...
-    def get_cmdline_options(self): ...
-    def iter_distribution_names(self) -> None: ...
+    def get_cmdline_options(self) -> dict[str, dict[str, str | None]]: ...
+    def iter_distribution_names(self) -> Iterator[str]: ...
     def handle_display_options(self, option_order): ...
 
 class DistDeprecationWarning(SetuptoolsDeprecationWarning): ...

tests/stubtest_allowlists/py3_common.txt

@@ -84,7 +84,9 @@ ctypes.memmove  # CFunctionType
 ctypes.memset  # CFunctionType
 ctypes.string_at  # docstring argument name is wrong
 ctypes.wstring_at  # docstring argument name is wrong
+distutils.core.Distribution.get_command_obj  # 1 used for True
 distutils.command.bdist_packager  # It exists in docs as package name but not in code except as a mention in a comment.
+distutils.dist.Distribution.get_command_obj  # 1 used for True
 distutils.version.Version._cmp  # class should have declared this
 distutils.version.Version.parse  # class should have declared this
 enum.Enum._generate_next_value_