distutils & setuptools: Relax path related params (#11948)

Co-authored-by: Jelle Zijlstra <[email protected]>

stdlib/distutils/archive_util.pyi

@@ -1,9 +1,22 @@
-from typing import Literal
+from _typeshed import StrOrBytesPath, StrPath
+from typing import Literal, overload
 
+@overload
 def make_archive(
     base_name: str,
     format: str,
-    root_dir: str | None = None,
+    root_dir: StrOrBytesPath | None = None,
+    base_dir: str | None = None,
+    verbose: bool | Literal[0, 1] = 0,
+    dry_run: bool | Literal[0, 1] = 0,
+    owner: str | None = None,
+    group: str | None = None,
+) -> str: ...
+@overload
+def make_archive(
+    base_name: StrPath,
+    format: str,
+    root_dir: StrOrBytesPath,
     base_dir: str | None = None,
     verbose: bool | Literal[0, 1] = 0,
     dry_run: bool | Literal[0, 1] = 0,
@@ -12,7 +25,7 @@ def make_archive(
 ) -> str: ...
 def make_tarball(
     base_name: str,
-    base_dir: str,
+    base_dir: StrPath,
     compress: str | None = "gzip",
     verbose: bool | Literal[0, 1] = 0,
     dry_run: bool | Literal[0, 1] = 0,

stdlib/distutils/ccompiler.pyi

@@ -1,5 +1,7 @@
-from collections.abc import Callable
-from typing import Any, Literal
+from _typeshed import BytesPath, StrPath
+from collections.abc import Callable, Iterable
+from distutils.file_util import _BytesPathT, _StrPathT
+from typing import Any, Literal, overload
 from typing_extensions import TypeAlias
 
 _Macro: TypeAlias = tuple[str] | tuple[str, str | None]
@@ -145,18 +147,27 @@ class CCompiler:
         extra_preargs: list[str] | None = None,
         extra_postargs: list[str] | None = None,
     ) -> None: ...
-    def executable_filename(self, basename: str, strip_dir: bool | Literal[0, 1] = 0, output_dir: str = "") -> str: ...
+    @overload
+    def executable_filename(self, basename: str, strip_dir: Literal[0, False] = 0, output_dir: StrPath = "") -> str: ...
+    @overload
+    def executable_filename(self, basename: StrPath, strip_dir: Literal[1, True], output_dir: StrPath = "") -> str: ...
     def library_filename(
-        self, libname: str, lib_type: str = "static", strip_dir: bool | Literal[0, 1] = 0, output_dir: str = ""
+        self, libname: str, lib_type: str = "static", strip_dir: bool | Literal[0, 1] = 0, output_dir: StrPath = ""
     ) -> str: ...
     def object_filenames(
-        self, source_filenames: list[str], strip_dir: bool | Literal[0, 1] = 0, output_dir: str = ""
+        self, source_filenames: Iterable[StrPath], strip_dir: bool | Literal[0, 1] = 0, output_dir: StrPath | None = ""
     ) -> list[str]: ...
-    def shared_object_filename(self, basename: str, strip_dir: bool | Literal[0, 1] = 0, output_dir: str = "") -> str: ...
+    @overload
+    def shared_object_filename(self, basename: str, strip_dir: Literal[0, False] = 0, output_dir: StrPath = "") -> str: ...
+    @overload
+    def shared_object_filename(self, basename: StrPath, strip_dir: Literal[1, True], output_dir: StrPath = "") -> str: ...
     def execute(self, func: Callable[..., object], args: tuple[Any, ...], msg: str | None = None, level: int = 1) -> None: ...
     def spawn(self, cmd: list[str]) -> None: ...
     def mkpath(self, name: str, mode: int = 0o777) -> None: ...
-    def move_file(self, src: str, dst: str) -> str: ...
+    @overload
+    def move_file(self, src: StrPath, dst: _StrPathT) -> _StrPathT | str: ...
+    @overload
+    def move_file(self, src: BytesPath, dst: _BytesPathT) -> _BytesPathT | bytes: ...
     def announce(self, msg: str, level: int = 1) -> None: ...
     def warn(self, msg: str) -> None: ...
     def debug_print(self, msg: str) -> None: ...

stdlib/distutils/cmd.pyi

@@ -1,8 +1,9 @@
-from _typeshed import Incomplete, Unused
+from _typeshed import BytesPath, Incomplete, StrOrBytesPath, StrPath, Unused
 from abc import abstractmethod
 from collections.abc import Callable, Iterable
 from distutils.dist import Distribution
-from typing import Any, ClassVar, Literal
+from distutils.file_util import _BytesPathT, _StrPathT
+from typing import Any, ClassVar, Literal, overload
 
 class Command:
     distribution: Distribution
@@ -30,39 +31,64 @@ class Command:
     def warn(self, msg: str) -> None: ...
     def execute(self, func: Callable[..., object], args: Iterable[Any], msg: str | None = None, level: int = 1) -> None: ...
     def mkpath(self, name: str, mode: int = 0o777) -> None: ...
+    @overload
     def copy_file(
         self,
-        infile: str,
-        outfile: str,
+        infile: StrPath,
+        outfile: _StrPathT,
+        preserve_mode: bool | Literal[0, 1] = 1,
+        preserve_times: bool | Literal[0, 1] = 1,
+        link: str | None = None,
+        level: Unused = 1,
+    ) -> tuple[_StrPathT | str, bool]: ...
+    @overload
+    def copy_file(
+        self,
+        infile: BytesPath,
+        outfile: _BytesPathT,
         preserve_mode: bool | Literal[0, 1] = 1,
         preserve_times: bool | Literal[0, 1] = 1,
         link: str | None = None,
         level: Unused = 1,
-    ) -> tuple[str, bool]: ...
+    ) -> tuple[_BytesPathT | bytes, bool]: ...
     def copy_tree(
         self,
-        infile: str,
+        infile: StrPath,
         outfile: str,
         preserve_mode: bool | Literal[0, 1] = 1,
         preserve_times: bool | Literal[0, 1] = 1,
         preserve_symlinks: bool | Literal[0, 1] = 0,
         level: Unused = 1,
     ) -> list[str]: ...
-    def move_file(self, src: str, dst: str, level: Unused = 1) -> str: ...
+    @overload
+    def move_file(self, src: StrPath, dst: _StrPathT, level: Unused = 1) -> _StrPathT | str: ...
+    @overload
+    def move_file(self, src: BytesPath, dst: _BytesPathT, level: Unused = 1) -> _BytesPathT | bytes: ...
     def spawn(self, cmd: Iterable[str], search_path: bool | Literal[0, 1] = 1, level: Unused = 1) -> None: ...
+    @overload
     def make_archive(
         self,
         base_name: str,
         format: str,
-        root_dir: str | None = None,
+        root_dir: StrOrBytesPath | None = None,
+        base_dir: str | None = None,
+        owner: str | None = None,
+        group: str | None = None,
+    ) -> str: ...
+    @overload
+    def make_archive(
+        self,
+        base_name: StrPath,
+        format: str,
+        root_dir: StrOrBytesPath,
         base_dir: str | None = None,
         owner: str | None = None,
         group: str | None = None,
     ) -> str: ...
     def make_file(
         self,
         infiles: str | list[str] | tuple[str, ...],
-        outfile: str,
+        outfile: StrOrBytesPath,
         func: Callable[..., object],
         args: list[Any],
         exec_msg: str | None = None,

stdlib/distutils/command/config.pyi

@@ -1,3 +1,4 @@
+from _typeshed import StrOrBytesPath
 from collections.abc import Sequence
 from re import Pattern
 from typing import Any, Literal
@@ -80,4 +81,4 @@ class config(Command):
         self, header: str, include_dirs: Sequence[str] | None = None, library_dirs: Sequence[str] | None = None, lang: str = "c"
     ) -> bool: ...
 
-def dump_file(filename: str, head: Any | None = None) -> None: ...
+def dump_file(filename: StrOrBytesPath, head: Any | None = None) -> None: ...

stdlib/distutils/dep_util.pyi

@@ -1,3 +1,14 @@
-def newer(source: str, target: str) -> bool: ...
-def newer_pairwise(sources: list[str], targets: list[str]) -> list[tuple[str, str]]: ...
-def newer_group(sources: list[str], target: str, missing: str = "error") -> bool: ...
+from _typeshed import StrOrBytesPath, SupportsLenAndGetItem
+from collections.abc import Iterable
+from typing import Literal, TypeVar
+
+_SourcesT = TypeVar("_SourcesT", bound=StrOrBytesPath)
+_TargetsT = TypeVar("_TargetsT", bound=StrOrBytesPath)
+
+def newer(source: StrOrBytesPath, target: StrOrBytesPath) -> bool | Literal[1]: ...
+def newer_pairwise(
+    sources: SupportsLenAndGetItem[_SourcesT], targets: SupportsLenAndGetItem[_TargetsT]
+) -> tuple[list[_SourcesT], list[_TargetsT]]: ...
+def newer_group(
+    sources: Iterable[StrOrBytesPath], target: StrOrBytesPath, missing: Literal["error", "ignore", "newer"] = "error"
+) -> Literal[0, 1]: ...

stdlib/distutils/dir_util.pyi

@@ -1,11 +1,17 @@
+from _typeshed import StrOrBytesPath, StrPath
+from collections.abc import Iterable
 from typing import Literal
 
 def mkpath(name: str, mode: int = 0o777, verbose: bool | Literal[0, 1] = 1, dry_run: bool | Literal[0, 1] = 0) -> list[str]: ...
 def create_tree(
-    base_dir: str, files: list[str], mode: int = 0o777, verbose: bool | Literal[0, 1] = 1, dry_run: bool | Literal[0, 1] = 0
+    base_dir: StrPath,
+    files: Iterable[StrPath],
+    mode: int = 0o777,
+    verbose: bool | Literal[0, 1] = 1,
+    dry_run: bool | Literal[0, 1] = 0,
 ) -> None: ...
 def copy_tree(
-    src: str,
+    src: StrPath,
     dst: str,
     preserve_mode: bool | Literal[0, 1] = 1,
     preserve_times: bool | Literal[0, 1] = 1,
@@ -14,4 +20,4 @@ def copy_tree(
     verbose: bool | Literal[0, 1] = 1,
     dry_run: bool | Literal[0, 1] = 0,
 ) -> list[str]: ...
-def remove_tree(directory: str, verbose: bool | Literal[0, 1] = 1, dry_run: bool | Literal[0, 1] = 0) -> None: ...
+def remove_tree(directory: StrOrBytesPath, verbose: bool | Literal[0, 1] = 1, dry_run: bool | Literal[0, 1] = 0) -> None: ...

stdlib/distutils/dist.pyi

@@ -1,4 +1,4 @@
-from _typeshed import FileDescriptorOrPath, Incomplete, SupportsWrite
+from _typeshed import Incomplete, StrOrBytesPath, StrPath, SupportsWrite
 from collections.abc import Iterable, Mapping
 from distutils.cmd import Command
 from re import Pattern
@@ -11,7 +11,7 @@ _OptionsList: TypeAlias = list[tuple[str, str | None, str, int] | tuple[str, str
 _CommandT = TypeVar("_CommandT", bound=Command)
 
 class DistributionMetadata:
-    def __init__(self, path: FileDescriptorOrPath | None = None) -> None: ...
+    def __init__(self, path: StrOrBytesPath | None = None) -> None: ...
     name: str | None
     version: str | None
     author: str | None
@@ -30,7 +30,7 @@ class DistributionMetadata:
     requires: list[str] | None
     obsoletes: list[str] | None
     def read_pkg_file(self, file: IO[str]) -> None: ...
-    def write_pkg_info(self, base_dir: str) -> None: ...
+    def write_pkg_info(self, base_dir: StrPath) -> None: ...
     def write_pkg_file(self, file: SupportsWrite[str]) -> None: ...
     def get_name(self) -> str: ...
     def get_version(self) -> str: ...

stdlib/distutils/file_util.pyi

@@ -1,15 +1,38 @@
-from collections.abc import Sequence
-from typing import Literal
+from _typeshed import BytesPath, StrOrBytesPath, StrPath
+from collections.abc import Iterable
+from typing import Literal, TypeVar, overload
 
+_StrPathT = TypeVar("_StrPathT", bound=StrPath)
+_BytesPathT = TypeVar("_BytesPathT", bound=BytesPath)
+
+@overload
+def copy_file(
+    src: StrPath,
+    dst: _StrPathT,
+    preserve_mode: bool | Literal[0, 1] = 1,
+    preserve_times: bool | Literal[0, 1] = 1,
+    update: bool | Literal[0, 1] = 0,
+    link: str | None = None,
+    verbose: bool | Literal[0, 1] = 1,
+    dry_run: bool | Literal[0, 1] = 0,
+) -> tuple[_StrPathT | str, bool]: ...
+@overload
 def copy_file(
-    src: str,
-    dst: str,
+    src: BytesPath,
+    dst: _BytesPathT,
     preserve_mode: bool | Literal[0, 1] = 1,
     preserve_times: bool | Literal[0, 1] = 1,
     update: bool | Literal[0, 1] = 0,
     link: str | None = None,
     verbose: bool | Literal[0, 1] = 1,
     dry_run: bool | Literal[0, 1] = 0,
-) -> tuple[str, str]: ...
-def move_file(src: str, dst: str, verbose: bool | Literal[0, 1] = 0, dry_run: bool | Literal[0, 1] = 0) -> str: ...
-def write_file(filename: str, contents: Sequence[str]) -> None: ...
+) -> tuple[_BytesPathT | bytes, bool]: ...
+@overload
+def move_file(
+    src: StrPath, dst: _StrPathT, verbose: bool | Literal[0, 1] = 0, dry_run: bool | Literal[0, 1] = 0
+) -> _StrPathT | str: ...
+@overload
+def move_file(
+    src: BytesPath, dst: _BytesPathT, verbose: bool | Literal[0, 1] = 0, dry_run: bool | Literal[0, 1] = 0
+) -> _BytesPathT | bytes: ...
+def write_file(filename: StrOrBytesPath, contents: Iterable[str]) -> None: ...

stdlib/distutils/util.pyi

@@ -5,7 +5,7 @@ from typing import Any, Literal
 def get_host_platform() -> str: ...
 def get_platform() -> str: ...
 def convert_path(pathname: str) -> str: ...
-def change_root(new_root: str, pathname: str) -> str: ...
+def change_root(new_root: StrPath, pathname: StrPath) -> str: ...
 def check_environ() -> None: ...
 def subst_vars(s: str, local_vars: Mapping[str, str]) -> None: ...
 def split_quoted(s: str) -> list[str]: ...

stubs/setuptools/@tests/stubtest_allowlist.txt

@@ -119,7 +119,6 @@ distutils\..+
 
 # Is a functools.partial, so stubtest says "is not a function"
 setuptools.dep_util.newer_pairwise_group
-setuptools._distutils.dep_util.newer_pairwise
 setuptools.modified.newer_pairwise_group
 setuptools._distutils._modified.newer_pairwise_group
 

stubs/setuptools/pkg_resources/__init__.pyi

@@ -1,6 +1,6 @@
 import types
 import zipimport
-from _typeshed import Incomplete, StrPath, Unused
+from _typeshed import BytesPath, Incomplete, StrOrBytesPath, StrPath, Unused
 from collections.abc import Callable, Generator, Iterable, Iterator, Sequence
 from io import BytesIO
 from itertools import chain
@@ -183,11 +183,11 @@ run_main = run_script
 
 class Environment:
     def __init__(
-        self, search_path: Sequence[str] | None = None, platform: str | None = ..., python: str | None = ...
+        self, search_path: Iterable[str] | None = None, platform: str | None = ..., python: str | None = ...
     ) -> None: ...
     def can_add(self, dist: Distribution) -> bool: ...
     def remove(self, dist: Distribution) -> None: ...
-    def scan(self, search_path: Sequence[str] | None = None) -> None: ...
+    def scan(self, search_path: Iterable[str] | None = None) -> None: ...
     def __getitem__(self, project_name: str) -> list[Distribution]: ...
     def add(self, dist: Distribution) -> None: ...
     @overload
@@ -284,8 +284,8 @@ class ResourceManager:
     def resource_string(self, package_or_requirement: _PkgReqType, resource_name: str) -> bytes: ...
     def resource_listdir(self, package_or_requirement: _PkgReqType, resource_name: str) -> list[str]: ...
     def extraction_error(self) -> NoReturn: ...
-    def get_cache_path(self, archive_name: str, names: Iterable[str] = ()) -> str: ...
-    def postprocess(self, tempname: str, filename: str) -> None: ...
+    def get_cache_path(self, archive_name: str, names: Iterable[StrPath] = ()) -> str: ...
+    def postprocess(self, tempname: StrOrBytesPath, filename: str) -> None: ...
     def set_extraction_path(self, path: str) -> None: ...
     def cleanup_resources(self, force: bool = False) -> list[str]: ...
 
@@ -421,7 +421,7 @@ class Distribution(NullProvider):
     def activate(self, path: list[str] | None = None, replace: bool = False) -> None: ...
     def egg_name(self) -> str: ...  # type: ignore[override]  # supertype's egg_name is a variable, not a method
     @classmethod
-    def from_filename(cls, filename: str, metadata: _MetadataType = None, *, precedence: int = 3) -> Distribution: ...
+    def from_filename(cls, filename: StrOrBytesPath, metadata: _MetadataType = None, *, precedence: int = 3) -> Distribution: ...
     def as_requirement(self) -> Requirement: ...
     def load_entry_point(self, group: str, name: str) -> _ResolvedEntryPoint: ...
     @overload
@@ -491,7 +491,10 @@ get_platform = get_build_platform
 def get_supported_platform() -> str: ...
 def compatible_platforms(provided: str | None, required: str | None) -> bool: ...
 def get_default_cache() -> str: ...
-def ensure_directory(path: str) -> None: ...
-def normalize_path(filename: str) -> str: ...
+def ensure_directory(path: StrOrBytesPath) -> None: ...
+@overload
+def normalize_path(filename: StrPath) -> str: ...
+@overload
+def normalize_path(filename: BytesPath) -> bytes: ...
 
 class PkgResourcesDeprecationWarning(Warning): ...

stubs/setuptools/setuptools/_distutils/_modified.pyi

@@ -1,6 +1,17 @@
-from typing import Literal
+from _typeshed import StrOrBytesPath
+from collections.abc import Callable, Iterable
+from typing import Literal, TypeVar
 
-def newer(source, target): ...
-def newer_pairwise(sources, targets, newer=...): ...
-def newer_group(sources, target, missing: Literal["error", "newer", "ignore"] = "error"): ...
-def newer_pairwise_group(sources, targets, *, newer=...): ...
+_SourcesT = TypeVar("_SourcesT", bound=StrOrBytesPath)
+_TargetsT = TypeVar("_TargetsT", bound=StrOrBytesPath)
+
+def newer(source: StrOrBytesPath, target: StrOrBytesPath) -> bool: ...
+def newer_pairwise(
+    sources: Iterable[_SourcesT], targets: Iterable[_TargetsT], newer: Callable[[_SourcesT, _TargetsT], bool] = ...
+) -> tuple[list[_SourcesT], list[_TargetsT]]: ...
+def newer_group(
+    sources: Iterable[StrOrBytesPath], target: StrOrBytesPath, missing: Literal["error", "ignore", "newer"] = "error"
+) -> bool: ...
+def newer_pairwise_group(
+    sources: Iterable[_SourcesT], targets: Iterable[_TargetsT], *, newer: Callable[[_SourcesT, _TargetsT], bool] = ...
+) -> tuple[list[_SourcesT], list[_TargetsT]]: ...