Add stubs for PyInstaller (public API only) (#8702)

Author: Avasam

stubs/pyinstaller/@tests/stubtest_allowlist.txt

@@ -0,0 +1,42 @@
+# fake module, only exists once the app is frozen
+pyi_splash
+# Undocumented and clearly not meant to be exposed
+PyInstaller.__main__.generate_parser
+PyInstaller.__main__.run_build
+PyInstaller.__main__.run_makespec
+PyInstaller.utils.hooks.conda.lib_dir
+# A mix of modules meant to be private, and shallow incomplete type references for other modules
+PyInstaller.building.*
+PyInstaller.depend.analysis.*
+PyInstaller.isolated._parent.*
+# Most modules are not meant to be used, yet are not marked as private
+PyInstaller.archive.*
+PyInstaller.config
+PyInstaller.configure
+PyInstaller.depend.bindepend
+PyInstaller.depend.bytecode
+PyInstaller.depend.dylib
+PyInstaller.depend.imphook
+PyInstaller.depend.utils
+PyInstaller.exceptions
+PyInstaller.hooks.*
+PyInstaller.lib.*
+PyInstaller.loader.*
+PyInstaller.log
+PyInstaller.utils.cliutils.*
+PyInstaller.utils.conftest
+PyInstaller.utils.git
+PyInstaller.utils.hooks.django
+PyInstaller.utils.hooks.gi
+PyInstaller.utils.hooks.qt
+PyInstaller.utils.hooks.subproc.*
+PyInstaller.utils.hooks.tcl_tk
+PyInstaller.utils.misc
+PyInstaller.utils.osx
+PyInstaller.utils.run_tests
+PyInstaller.utils.tests
+PyInstaller.utils.win32.*
+# Explicitly private implementation details
+PyInstaller\._.*
+PyInstaller.isolated._child
+PyInstaller.utils._gitrevision

stubs/pyinstaller/METADATA.toml

@@ -0,0 +1,5 @@
+version = "5.4.*"
+requires = ["types-setuptools"]
+
+[tool.stubtest]
+ignore_missing_stub = false

stubs/pyinstaller/PyInstaller/__init__.pyi

@@ -0,0 +1,11 @@
+from typing_extensions import LiteralString
+
+from PyInstaller import compat as compat
+
+__all__ = ("HOMEPATH", "PLATFORM", "__version__", "DEFAULT_DISTPATH", "DEFAULT_SPECPATH", "DEFAULT_WORKPATH")
+__version__: str
+HOMEPATH: str
+DEFAULT_SPECPATH: str
+DEFAULT_DISTPATH: str
+DEFAULT_WORKPATH: str
+PLATFORM: LiteralString

stubs/pyinstaller/PyInstaller/__main__.pyi

@@ -0,0 +1,11 @@
+# https://pyinstaller.org/en/stable/usage.html#running-pyinstaller-from-python-code
+from _typeshed import SupportsKeysAndGetItem
+from collections.abc import Iterable
+from typing_extensions import TypeAlias
+
+# Used to update PyInstaller.config.CONF
+_PyIConfig: TypeAlias = (
+    SupportsKeysAndGetItem[str, bool | str | list[str] | None] | Iterable[tuple[str, bool | str | list[str] | None]]
+)
+
+def run(pyi_args: Iterable[str] | None = ..., pyi_config: _PyIConfig | None = ...) -> None: ...

stubs/pyinstaller/PyInstaller/building/__init__.pyi

@@ -0,0 +1,29 @@
+# Referenced in: https://pyinstaller.org/en/stable/hooks.html?highlight=get_hook_config#PyInstaller.utils.hooks.get_hook_config
+# Not to be imported during runtime, but is the type reference for hooks and analysis configuration
+
+from _typeshed import StrOrBytesPath
+from collections.abc import Iterable
+from typing import Any
+
+from PyInstaller.building.datastruct import Target
+
+class Analysis(Target):
+    # https://pyinstaller.org/en/stable/hooks-config.html#hook-configuration-options
+    hooksconfig: dict[str, dict[str, object]]
+    def __init__(
+        self,
+        scripts: Iterable[StrOrBytesPath],
+        pathex=...,
+        binaries=...,
+        datas=...,
+        hiddenimports=...,
+        hookspath=...,
+        hooksconfig: dict[str, dict[str, Any]] | None = ...,
+        excludes=...,
+        runtime_hooks=...,
+        cipher=...,
+        win_no_prefer_redirects: bool = ...,
+        win_private_assemblies: bool = ...,
+        noarchive: bool = ...,
+        module_collection_mode=...,
+    ) -> None: ...

stubs/pyinstaller/PyInstaller/building/build_main.pyi

@@ -0,0 +1,30 @@
+# https://pyinstaller.org/en/stable/advanced-topics.html#the-toc-and-tree-classes
+from collections.abc import Iterable, Sequence
+from typing import ClassVar
+from typing_extensions import Literal, LiteralString, SupportsIndex, TypeAlias
+
+_TypeCode: TypeAlias = Literal["DATA", "BINARY", "EXTENSION", "OPTION"]
+_TOCTuple: TypeAlias = tuple[str, str | None, _TypeCode | None]
+
+class TOC(list[_TOCTuple]):
+    filenames: set[str]
+    def __init__(self, initlist: Iterable[_TOCTuple] | None = ...) -> None: ...
+    def append(self, entry: _TOCTuple) -> None: ...
+    def insert(self, pos: SupportsIndex, entry: _TOCTuple) -> None: ...
+    def extend(self, other: Iterable[_TOCTuple]) -> None: ...
+
+class Target:
+    invcnum: ClassVar[int]
+    tocfilename: LiteralString
+    tocbasename: LiteralString
+    dependencies: TOC
+
+class Tree(Target, TOC):
+    root: str | None
+    prefix: str | None
+    excludes: Sequence[str]
+    typecode: _TypeCode
+    def __init__(
+        self, root: str | None = ..., prefix: str | None = ..., excludes: Sequence[str] | None = ..., typecode: _TypeCode = ...
+    ) -> None: ...
+    def assemble(self) -> None: ...

stubs/pyinstaller/PyInstaller/building/datastruct.pyi

@@ -0,0 +1,82 @@
+# https://pyinstaller.org/en/stable/hooks.html#module-PyInstaller.compat
+from _typeshed import FileDescriptor, GenericPath, StrOrBytesPath
+from collections.abc import Iterable
+from importlib.abc import _Path
+from types import ModuleType
+from typing import AnyStr, overload
+from typing_extensions import Literal, TypeAlias
+
+_OpenFile: TypeAlias = StrOrBytesPath | FileDescriptor
+
+is_64bits: bool
+is_py35: bool
+is_py36: bool
+is_py37: bool
+is_py38: bool
+is_py39: bool
+is_py310: bool
+is_win: bool
+is_win_10: bool
+is_win_wine: bool
+is_cygwin: bool
+is_darwin: bool
+is_linux: bool
+is_solar: bool
+is_aix: bool
+is_freebsd: bool
+is_openbsd: bool
+is_hpux: bool
+is_unix: bool
+is_musl: bool
+is_macos_11_compat: bool
+is_macos_11_native: bool
+is_macos_11: bool
+PYDYLIB_NAMES: set[str]
+base_prefix: str
+is_venv: bool
+is_virtualenv: bool
+is_conda: bool
+is_pure_conda: bool
+python_executable: str
+is_ms_app_store: bool
+BYTECODE_MAGIC: bytes
+EXTENSION_SUFFIXES: list[str]
+ALL_SUFFIXES: list[str]
+
+architecture: Literal["64bit", "n32bit", "32bit"]
+system: Literal["Cygwin", "Linux", "Darwin", "Java", "Windows"]
+machine: Literal["sw_64", "loongarch64", "arm", "intel", "ppc", "mips", "riscv", "s390x", "unknown", None]
+
+def is_wine_dll(filename: _OpenFile) -> bool: ...
+@overload
+def getenv(name: str, default: str) -> str: ...
+@overload
+def getenv(name: str, default: None = ...) -> str | None: ...
+def setenv(name: str, value: str) -> None: ...
+def unsetenv(name: str) -> None: ...
+def exec_command(
+    *cmdargs: str, encoding: str | None = ..., raise_enoent: bool | None = ..., **kwargs: int | bool | Iterable[int] | None
+) -> str: ...
+def exec_command_rc(*cmdargs: str, **kwargs: float | bool | Iterable[int] | None) -> int: ...
+def exec_command_stdout(
+    *command_args: str, encoding: str | None = ..., **kwargs: float | str | bytes | bool | Iterable[int] | None
+) -> str: ...
+def exec_command_all(
+    *cmdargs: str, encoding: str | None = ..., **kwargs: int | bool | Iterable[int] | None
+) -> tuple[int, str, str]: ...
+def exec_python(*args: str, **kwargs: str | None) -> str: ...
+def exec_python_rc(*args: str, **kwargs: str | None) -> int: ...
+def expand_path(path: GenericPath[AnyStr]) -> AnyStr: ...
+def getsitepackages(prefixes: Iterable[str] | None = ...) -> list[str]: ...
+def importlib_load_source(name: str, pathname: _Path) -> ModuleType: ...
+
+PY3_BASE_MODULES: set[str]
+PURE_PYTHON_MODULE_TYPES: set[str]
+SPECIAL_MODULE_TYPES: set[str]
+BINARY_MODULE_TYPES: set[str]
+VALID_MODULE_TYPES: set[str]
+BAD_MODULE_TYPES: set[str]
+ALL_MODULE_TYPES: set[str]
+MODULE_TYPES_TO_TOC_DICT: dict[str, str]
+
+def check_requirements() -> None: ...

stubs/pyinstaller/PyInstaller/compat.pyi

@@ -0,0 +1,18 @@
+# https://pyinstaller.org/en/stable/hooks.html#the-pre-safe-import-module-psim-api-method
+
+# The documentation explicitely mentions that "Normally you do not need to know about the module-graph."
+# However, some PyiModuleGraph typed class attributes are still documented as existing in imphookapi.
+from _typeshed import Incomplete
+
+class PyiModuleGraph:  # incomplete
+    def __init__(
+        self,
+        pyi_homepath: str,
+        user_hook_dirs=...,
+        excludes=...,
+        path: Incomplete | None = ...,
+        replace_paths=...,
+        implies=...,
+        graph: Incomplete | None = ...,
+        debug: int = ...,
+    ) -> None: ...

stubs/pyinstaller/PyInstaller/depend/__init__.pyi

@@ -0,0 +1,70 @@
+# https://pyinstaller.org/en/stable/hooks-config.html#adding-an-option-to-the-hook `hook_api` is a PostGraphAPI
+# Nothing in this module is meant to be initialized externally.
+# Instances are exposed through hooks during build.
+
+from _typeshed import StrOrBytesPath
+from collections.abc import Generator, Iterable
+from typing import Any
+from typing_extensions import Literal
+
+from PyInstaller.building.build_main import Analysis
+from PyInstaller.building.datastruct import TOC
+from PyInstaller.depend.analysis import PyiModuleGraph
+from PyInstaller.lib.modulegraph.modulegraph import Package
+
+# https://pyinstaller.org/en/stable/hooks.html#the-pre-safe-import-module-psim-api-method
+class PreSafeImportModuleAPI:
+    module_basename: str
+    module_name: str
+    def __init__(
+        self, module_graph: PyiModuleGraph, module_basename: str, module_name: str, parent_package: Package | None
+    ) -> None: ...
+    @property
+    def module_graph(self) -> PyiModuleGraph: ...
+    @property
+    def parent_package(self) -> Package | None: ...
+    def add_runtime_module(self, module_name: str) -> None: ...
+    def add_runtime_package(self, package_name: str) -> None: ...
+    def add_alias_module(self, real_module_name: str, alias_module_name: str) -> None: ...
+    def append_package_path(self, directory: str) -> None: ...
+
+# https://pyinstaller.org/en/stable/hooks.html#the-pre-find-module-path-pfmp-api-method
+class PreFindModulePathAPI:
+    search_dirs: Iterable[StrOrBytesPath]
+    def __init__(self, module_graph: PyiModuleGraph, module_name: str, search_dirs: Iterable[StrOrBytesPath]) -> None: ...
+    @property
+    def module_graph(self) -> PyiModuleGraph: ...
+    @property
+    def module_name(self) -> str: ...
+
+# https://pyinstaller.org/en/stable/hooks.html#the-hook-hook-api-function
+class PostGraphAPI:
+    module_graph: PyiModuleGraph
+    module: Package
+    def __init__(self, module_name: str, module_graph: PyiModuleGraph, analysis: Analysis) -> None: ...
+    @property
+    def __file__(self) -> str: ...
+    @property
+    def __path__(self) -> tuple[str, ...] | None: ...
+    @property
+    def __name__(self) -> str: ...
+    # Compiled code. See stdlib.builtins.compile
+    @property
+    def co(self) -> Any: ...
+    @property
+    def analysis(self) -> Analysis: ...
+    @property
+    def name(self) -> str: ...
+    @property
+    def graph(self) -> PyiModuleGraph: ...
+    @property
+    def node(self) -> Package: ...
+    @property
+    def imports(self) -> Generator[Package, None, None]: ...
+    def add_imports(self, *module_names: str) -> None: ...
+    def del_imports(self, *module_names: str) -> None: ...
+    def add_binaries(self, list_of_tuples: TOC | Iterable[tuple[StrOrBytesPath, StrOrBytesPath]]) -> None: ...
+    def add_datas(self, list_of_tuples: TOC | Iterable[tuple[StrOrBytesPath, StrOrBytesPath]]) -> None: ...
+    def set_module_collection_mode(
+        self, name: str | None, mode: Literal["pyz", "pyc", "py", "pyz+py", "py+pyz", None]
+    ) -> None: ...

stubs/pyinstaller/PyInstaller/depend/analysis.pyi

@@ -0,0 +1,2 @@
+# https://pyinstaller.org/en/stable/hooks.html#module-PyInstaller.isolated
+from PyInstaller.isolated._parent import Python as Python, call as call, decorate as decorate

stubs/pyinstaller/PyInstaller/depend/imphookapi.pyi

@@ -0,0 +1,19 @@
+from _typeshed import Self
+from collections.abc import Callable
+from types import TracebackType
+from typing import TypeVar
+from typing_extensions import ParamSpec
+
+_AC = TypeVar("_AC", bound=Callable[..., object])
+_R = TypeVar("_R")
+_P = ParamSpec("_P")
+
+class Python:
+    def __enter__(self: Self) -> Self: ...
+    def __exit__(
+        self, exc_type: type[BaseException] | None, exc_val: BaseException | None, exc_tb: TracebackType | None
+    ) -> None: ...
+    def call(self, function: Callable[_P, _R], *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
+
+def call(function: Callable[_P, _R], *args: _P.args, **kwargs: _P.kwargs) -> _R: ...
+def decorate(function: _AC) -> _AC: ...

stubs/pyinstaller/PyInstaller/isolated/__init__.pyi

@@ -0,0 +1,40 @@
+from typing import Any, Protocol
+
+class _SupportsGraphident(Protocol):
+    graphident: str
+
+# TODO: For typing purposes, once #5768 is complete, it'll be easier to use the modulegraph package directly.
+
+# code, filename and packagepath are always initialized to None. But they can be given a value later.
+class Node:
+    # Compiled code. See stdlib.builtins.compile
+    code: Any | None
+    filename: str | None
+    graphident: str
+    identifier: str
+    packagepath: str | None
+    def __init__(self, identifier: str) -> None: ...
+    def is_global_attr(self, attr_name: str) -> bool: ...
+    def is_submodule(self, submodule_basename: str) -> bool: ...
+    def add_global_attr(self, attr_name: str) -> None: ...
+    def add_global_attrs_from_module(self, target_module: Node) -> None: ...
+    def add_submodule(self, submodule_basename: str, submodule_node: Node) -> None: ...
+    def get_submodule(self, submodule_basename: str) -> Node: ...
+    def get_submodule_or_none(self, submodule_basename: str) -> Node | None: ...
+    def remove_global_attr_if_found(self, attr_name: str) -> None: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __ne__(self, other: object) -> bool: ...
+    def __lt__(self, other: _SupportsGraphident) -> bool: ...
+    def __le__(self, other: _SupportsGraphident) -> bool: ...
+    def __gt__(self, other: _SupportsGraphident) -> bool: ...
+    def __ge__(self, other: _SupportsGraphident) -> bool: ...
+    def infoTuple(self) -> tuple[str]: ...
+
+class BaseModule(Node):
+    filename: str
+    packagepath: str
+    def __init__(self, name: str, filename: str | None = ..., path: str | None = ...) -> None: ...
+    # Returns a tuple of length 0, 1, 2, or 3
+    def infoTuple(self) -> tuple[str, ...]: ...  # type: ignore[override]
+
+class Package(BaseModule): ...