Type PyInstaller.building.api and related modules (#9730)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

stubs/pyinstaller/@tests/stubtest_allowlist.txt

@@ -2,15 +2,19 @@
 pyi_splash
 
 # Undocumented and clearly not meant to be exposed
+PyInstaller\..+?\.logger
 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\.building\.\w+?
+PyInstaller.building.build_main.*
+PyInstaller.building.datastruct.unique_name
 PyInstaller.depend.analysis.*
 PyInstaller.isolated._parent.*
+PyInstaller\.lib\.modulegraph\.modulegraph\.\w+?
 
 # Most modules are not meant to be used, yet are not marked as private
 PyInstaller.archive.*
@@ -23,7 +27,7 @@ PyInstaller.depend.imphook
 PyInstaller.depend.utils
 PyInstaller.exceptions
 PyInstaller.hooks.*
-PyInstaller.lib.*
+PyInstaller\.lib\.modulegraph\.\w+?
 PyInstaller.loader.*
 PyInstaller.log
 PyInstaller.utils.cliutils.*
@@ -37,4 +41,4 @@ PyInstaller.utils.misc
 PyInstaller.utils.osx
 PyInstaller.utils.run_tests
 PyInstaller.utils.tests
-PyInstaller.utils.win32.*
+PyInstaller\.utils\.win32\.\w+?

stubs/pyinstaller/@tests/stubtest_allowlist_win32.txt

@@ -0,0 +1,2 @@
+PyInstaller\.utils\.win32\.versioninfo\.\w+?
+PyInstaller\.utils\.win32\.winmanifest\.\w+?

stubs/pyinstaller/PyInstaller/__main__.pyi

@@ -1,5 +1,3 @@
-# https://pyinstaller.org/en/stable/usage.html#running-pyinstaller-from-python-code
-import logging
 from _typeshed import SupportsKeysAndGetItem
 from collections.abc import Iterable
 from typing_extensions import TypeAlias
@@ -9,6 +7,5 @@ _PyIConfig: TypeAlias = (
     SupportsKeysAndGetItem[str, bool | str | list[str] | None] | Iterable[tuple[str, bool | str | list[str] | None]]
 )
 
-logger: logging.Logger
-
+# https://pyinstaller.org/en/stable/usage.html#running-pyinstaller-from-python-code
 def run(pyi_args: Iterable[str] | None = None, pyi_config: _PyIConfig | None = None) -> None: ...

stubs/pyinstaller/PyInstaller/building/__init__.pyi

@@ -0,0 +1,7 @@
+from typing_extensions import TypeAlias
+
+# PyiBlockCipher is deprecated and misleads users into thinking it adds any security. Runtime deprecation warning:
+# DEPRECATION: Bytecode encryption will be removed in PyInstaller v6.
+# Please remove cipher and block_cipher parameters from your spec file to avoid breakages on upgrade.
+# For the rationale/alternatives see https://github.com/pyinstaller/pyinstaller/pull/6999
+_PyiBlockCipher: TypeAlias = None  # noqa: Y047  # Used by other modules

stubs/pyinstaller/PyInstaller/building/api.pyi

@@ -0,0 +1,168 @@
+# PYZ, EXE and COLLECT referenced in https://pyinstaller.org/en/stable/spec-files.html#spec-file-operation
+# MERGE is referenced in https://pyinstaller.org/en/stable/spec-files.html#example-merge-spec-file
+# Not to be imported during runtime, but is the type reference for spec files which are executed as python code
+import sys
+from _typeshed import FileDescriptorOrPath, StrOrBytesPath, StrPath, Unused
+from collections.abc import Iterable, Mapping, Sequence
+from types import CodeType
+from typing import ClassVar
+from typing_extensions import Final, Literal, TypeAlias
+
+from PyInstaller.building import _PyiBlockCipher
+from PyInstaller.building.build_main import Analysis
+from PyInstaller.building.datastruct import TOC, Target, _TOCTuple
+from PyInstaller.building.splash import Splash
+from PyInstaller.utils.win32.versioninfo import VSVersionInfo
+from PyInstaller.utils.win32.winmanifest import Manifest
+
+if sys.platform == "darwin":
+    _TargetArch: TypeAlias = Literal["x86_64", "arm64", "universal2"]
+    _SuportedTargetArchParam: TypeAlias = _TargetArch | None
+    _CodesignIdentity: TypeAlias = str | None
+    _CodesignIdentityParam: TypeAlias = str | None
+else:
+    _TargetArch: TypeAlias = None
+    _SuportedTargetArchParam: TypeAlias = object
+    _CodesignIdentity: TypeAlias = None
+    _CodesignIdentityParam: TypeAlias = object
+
+if sys.platform == "win32":
+    _Icon: TypeAlias = list[StrPath] | str
+    _IconParam: TypeAlias = StrPath | list[StrPath] | None
+elif sys.platform == "darwin":
+    _Icon: TypeAlias = list[StrPath] | None
+    _IconParam: TypeAlias = StrPath | list[StrPath] | None
+else:
+    _Icon: TypeAlias = None
+    _IconParam: TypeAlias = object
+
+if sys.platform == "win32":
+    _VersionSrc: TypeAlias = VSVersionInfo | None
+    _VersionParam: TypeAlias = VSVersionInfo | StrOrBytesPath | None
+    _Manifest: TypeAlias = Manifest
+    _ManifestParam: TypeAlias = Manifest | None
+else:
+    _VersionSrc: TypeAlias = None
+    _VersionParam: TypeAlias = object
+    _Manifest: TypeAlias = None
+    _ManifestParam: TypeAlias = object
+
+class PYZ(Target):
+    name: str
+    cipher: _PyiBlockCipher
+    dependencies: list[_TOCTuple]  # type: ignore[assignment]
+    toc: TOC
+    code_dict: dict[str, CodeType]
+    def __init__(self, *tocs: TOC, name: str | None = None, cipher: _PyiBlockCipher = None) -> None: ...
+    def assemble(self) -> None: ...
+
+class PKG(Target):
+    xformdict: ClassVar[dict[str, str]]
+    toc: TOC
+    cdict: Mapping[str, bool]
+    name: str
+    exclude_binaries: bool
+    strip_binaries: bool
+    upx_binaries: bool
+    upx_exclude: Iterable[str]
+    target_arch: _TargetArch | None
+    codesign_identity: _CodesignIdentity
+    entitlements_file: FileDescriptorOrPath | None
+    def __init__(
+        self,
+        toc: TOC,
+        name: str | None = None,
+        cdict: Mapping[str, bool] | None = None,
+        exclude_binaries: bool = False,
+        strip_binaries: bool = False,
+        upx_binaries: bool = False,
+        upx_exclude: Iterable[str] | None = None,
+        target_arch: _SuportedTargetArchParam = None,
+        codesign_identity: _CodesignIdentityParam = None,
+        entitlements_file: FileDescriptorOrPath | None = None,
+    ) -> None: ...
+    def assemble(self) -> None: ...
+
+class EXE(Target):
+    exclude_binaries: bool
+    bootloader_ignore_signals: bool
+    console: bool
+    disable_windowed_traceback: bool
+    debug: bool
+    name: str
+    icon: _Icon
+    versrsrc: _VersionSrc
+    manifest: _Manifest
+    embed_manifest: bool
+    resources: Sequence[str]
+    strip: bool
+    upx_exclude: Iterable[str]
+    runtime_tmpdir: str | None
+    append_pkg: bool
+    uac_admin: bool
+    uac_uiaccess: bool
+    argv_emulation: bool
+    target_arch: _TargetArch
+    codesign_identity: _CodesignIdentity
+    entitlements_file: FileDescriptorOrPath | None
+    upx: bool
+    pkgname: str
+    toc: TOC
+    pkg: PKG
+    dependencies: TOC
+    exefiles: TOC
+    def __init__(
+        self,
+        *args: Iterable[_TOCTuple] | PYZ | Splash,
+        exclude_binaries: bool = False,
+        bootloader_ignore_signals: bool = False,
+        console: bool = True,
+        disable_windowed_traceback: bool = False,
+        debug: bool = False,
+        name: str | None = None,
+        icon: _IconParam = None,
+        version: _VersionParam = None,
+        manifest: _ManifestParam = None,
+        embed_manifest: bool = True,
+        resources: Sequence[str] = ...,
+        strip: bool = False,
+        upx_exclude: Iterable[str] = ...,
+        runtime_tmpdir: str | None = None,
+        append_pkg: bool = True,
+        uac_admin: bool = False,
+        uac_uiaccess: bool = False,
+        argv_emulation: bool = False,
+        target_arch: _SuportedTargetArchParam = None,
+        codesign_identity: _CodesignIdentityParam = None,
+        entitlements_file: FileDescriptorOrPath | None = None,
+        upx: bool = False,
+        cdict: Mapping[str, bool] | None = None,
+    ) -> None: ...
+    mtm: float
+    def assemble(self) -> None: ...
+
+class COLLECT(Target):
+    strip_binaries: bool
+    upx_exclude: Iterable[str]
+    console: bool
+    target_arch: _TargetArch | None
+    codesign_identity: _CodesignIdentity
+    entitlements_file: FileDescriptorOrPath | None
+    upx_binaries: bool
+    name: str
+    toc: TOC
+    def __init__(
+        self,
+        *args: Iterable[_TOCTuple] | EXE,
+        strip: bool = False,
+        upx_exclude: Iterable[str] = ...,
+        upx: bool = False,
+        name: str,
+    ) -> None: ...
+    def assemble(self) -> None: ...
+
+class MERGE:
+    def __init__(self, *args: tuple[Analysis, Unused, str]) -> None: ...
+
+UNCOMPRESSED: Final = False
+COMPRESSED: Final = True

stubs/pyinstaller/PyInstaller/building/build_main.pyi

@@ -1,15 +1,28 @@
-# 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 Incomplete, StrPath
 from collections.abc import Iterable
 from typing import Any
 
-from PyInstaller.building.datastruct import Target
+from PyInstaller.building import _PyiBlockCipher
+from PyInstaller.building.datastruct import TOC, Target
 
+# Referenced in: https://pyinstaller.org/en/stable/hooks.html#PyInstaller.utils.hooks.get_hook_config
+# Not to be imported during runtime, but is the type reference for hooks and analysis configuration
+# Also referenced in https://pyinstaller.org/en/stable/spec-files.html
+# Not to be imported during runtime, but is the type reference for spec files which are executed as python code
 class Analysis(Target):
     # https://pyinstaller.org/en/stable/hooks-config.html#hook-configuration-options
     hooksconfig: dict[str, dict[str, object]]
+    # https://pyinstaller.org/en/stable/spec-files.html#spec-file-operation
+    # https://pyinstaller.org/en/stable/feature-notes.html
+    pure: TOC
+    zipped_data: TOC
+    # https://pyinstaller.org/en/stable/spec-files.html#giving-run-time-python-options
+    # https://pyinstaller.org/en/stable/spec-files.html#the-splash-target
+    scripts: TOC
+    # https://pyinstaller.org/en/stable/feature-notes.html#practical-examples
+    binaries: TOC
+    zipfiles: TOC
+    datas: TOC
     def __init__(
         self,
         scripts: Iterable[StrPath],
@@ -21,7 +34,7 @@ class Analysis(Target):
         hooksconfig: dict[str, dict[str, Any]] | None = None,
         excludes: Incomplete | None = None,
         runtime_hooks: Incomplete | None = None,
-        cipher: Incomplete | None = None,
+        cipher: _PyiBlockCipher = None,
         win_no_prefer_redirects: bool = False,
         win_private_assemblies: bool = False,
         noarchive: bool = False,

stubs/pyinstaller/PyInstaller/building/datastruct.pyi

@@ -1,7 +1,7 @@
 # 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
+from typing_extensions import Literal, LiteralString, Self, SupportsIndex, TypeAlias
 
 _TypeCode: TypeAlias = Literal["DATA", "BINARY", "EXTENSION", "OPTION"]
 _TOCTuple: TypeAlias = tuple[str, str | None, _TypeCode | None]
@@ -11,13 +11,22 @@ class TOC(list[_TOCTuple]):
     def __init__(self, initlist: Iterable[_TOCTuple] | None = None) -> None: ...
     def append(self, entry: _TOCTuple) -> None: ...
     def insert(self, pos: SupportsIndex, entry: _TOCTuple) -> None: ...
+    def __add__(self, other: Iterable[_TOCTuple]) -> TOC: ...  # type: ignore[override]
+    def __radd__(self, other: Iterable[_TOCTuple]) -> TOC: ...
+    def __iadd__(self, other: Iterable[_TOCTuple]) -> Self: ...  # type: ignore[override]
     def extend(self, other: Iterable[_TOCTuple]) -> None: ...
+    def __sub__(self, other: Iterable[_TOCTuple]) -> TOC: ...
+    def __rsub__(self, other: Iterable[_TOCTuple]) -> TOC: ...
+    # slicing a TOC is not supported, but has a special case for slice(None, None, None)
+    def __setitem__(self, key: int | slice, value: Iterable[_TOCTuple]) -> None: ...  # type: ignore[override]
 
 class Target:
     invcnum: ClassVar[int]
     tocfilename: LiteralString
     tocbasename: LiteralString
     dependencies: TOC
+    def __init__(self) -> None: ...
+    def __postinit__(self) -> None: ...
 
 class Tree(Target, TOC):
     root: str | None

stubs/pyinstaller/PyInstaller/building/splash.pyi

@@ -0,0 +1,31 @@
+from _typeshed import Incomplete, StrPath
+from collections.abc import Iterable
+
+from PyInstaller.building.datastruct import TOC, Target, _TOCTuple
+
+splash_requirements: list[str]
+
+# Referenced in https://pyinstaller.org/en/stable/spec-files.html#example-merge-spec-file
+# Not to be imported during runtime, but is the type reference for spec files which are executed as python code
+class Splash(Target):
+    image_file: str
+    full_tk: Incomplete
+    name: Incomplete
+    script_name: Incomplete
+    minify_script: Incomplete
+    rundir: Incomplete
+    max_img_size: Incomplete
+    text_pos: Incomplete
+    text_size: Incomplete
+    text_font: Incomplete
+    text_color: Incomplete
+    text_default: Incomplete
+    always_on_top: Incomplete
+    uses_tkinter: Incomplete
+    script: Incomplete
+    splash_requirements: Incomplete
+    binaries: TOC
+    def __init__(self, image_file: StrPath, binaries: TOC, datas: Iterable[_TOCTuple], **kwargs: Incomplete) -> None: ...
+    def assemble(self) -> None: ...
+    def test_tk_version(self) -> None: ...
+    def generate_script(self) -> str: ...

stubs/pyinstaller/PyInstaller/utils/hooks/__init__.pyi

@@ -1,6 +1,5 @@
 # https://pyinstaller.org/en/stable/hooks.html
 
-import logging
 from _typeshed import StrOrBytesPath, StrPath
 from collections.abc import Callable, Iterable
 from typing import Any
@@ -14,7 +13,6 @@ from PyInstaller.utils.hooks.win32 import get_pywin32_module_file_attribute as g
 
 conda_support = conda
 
-logger: logging.Logger
 PY_IGNORE_EXTENSIONS: Final[set[str]]
 hook_variables: dict[str, str]
 

stubs/pyinstaller/PyInstaller/utils/hooks/conda.pyi

@@ -1,4 +1,4 @@
-# https://pyinstaller.org/en/stable/hooks.html?highlight=conda_support#module-PyInstaller.utils.hooks.conda
+# https://pyinstaller.org/en/stable/hooks.html#module-PyInstaller.utils.hooks.conda
 
 import sys
 from _typeshed import StrOrBytesPath

stubs/pyinstaller/PyInstaller/utils/win32/versioninfo.pyi

@@ -0,0 +1,51 @@
+from _typeshed import SliceableBuffer
+from collections.abc import Sequence
+from typing import Protocol
+from typing_extensions import Literal, TypeAlias
+
+_FourIntSequence: TypeAlias = Sequence[int]
+_TwoIntSequence: TypeAlias = Sequence[int]
+
+class _Kid(Protocol):
+    def toRaw(self) -> bytes: ...
+    def __str__(self, __indent: str = "") -> str: ...
+
+# Used by other types referenced in https://pyinstaller.org/en/stable/spec-files.html#spec-file-operation
+class VSVersionInfo:
+    ffi: FixedFileInfo | None
+    kids: list[_Kid]
+    def __init__(self, ffi: FixedFileInfo | None = None, kids: list[_Kid] | None = None) -> None: ...
+    def fromRaw(self, data: SliceableBuffer) -> int: ...
+    def toRaw(self) -> bytes: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __str__(self, indent: str = "") -> str: ...
+
+class FixedFileInfo:
+    sig: Literal[0xFEEF04BD]
+    strucVersion: Literal[0x10000]
+    fileVersionMS: int
+    fileVersionLS: int
+    productVersionMS: int
+    productVersionLS: int
+    fileFlagsMask: int
+    fileFlags: int
+    fileOS: int
+    fileType: int
+    fileSubtype: int
+    fileDateMS: int
+    fileDateLS: int
+    def __init__(
+        self,
+        filevers: _FourIntSequence = ...,
+        prodvers: _FourIntSequence = ...,
+        mask: int = 0x3F,
+        flags: int = 0x0,
+        OS: int = 0x40004,
+        fileType: int = 0x1,
+        subtype: int = 0x0,
+        date: _TwoIntSequence = ...,
+    ) -> None: ...
+    def fromRaw(self, data: SliceableBuffer, i: int) -> int: ...
+    def toRaw(self) -> bytes: ...
+    def __eq__(self, other: object) -> bool: ...
+    def __str__(self, indent: str = "") -> str: ...

stubs/pyinstaller/PyInstaller/utils/win32/winmanifest.pyi

@@ -0,0 +1,127 @@
+from _typeshed import Incomplete, ReadableBuffer, Unused
+from typing import IO, AnyStr, overload
+from typing_extensions import Literal
+from xml.dom.minidom import Document as _Document, Element as _Element, Node
+
+def getChildElementsByTagName(self: Node, tagName: str) -> list[Element]: ...
+def getFirstChildElementByTagName(self: Node, tagName: str) -> Element | None: ...
+
+class Document(_Document):
+    cE = _Document.createElement
+    cT = _Document.createTextNode
+    aChild = _Document.appendChild
+    getEByTN = _Document.getElementsByTagName
+    getCEByTN = getChildElementsByTagName
+    getFCEByTN = getFirstChildElementByTagName
+
+class Element(_Element):
+    getA = _Element.getAttribute
+    remA = _Element.removeAttribute
+    setA = _Element.setAttribute
+    aChild = _Element.appendChild
+    getEByTN = _Element.getElementsByTagName
+    getCEByTN = getChildElementsByTagName
+    getFCEByTN = getFirstChildElementByTagName
+
+# Used by other types referenced in https://pyinstaller.org/en/stable/spec-files.html#spec-file-operation
+class Manifest:
+    filename: Incomplete
+    optional: Incomplete
+    manifestType: Incomplete
+    manifestVersion: Incomplete
+    noInheritable: Incomplete
+    noInherit: Incomplete
+    type: Incomplete
+    name: Incomplete
+    language: str | None
+    processorArchitecture: Incomplete
+    version: Incomplete
+    publicKeyToken: Incomplete
+    applyPublisherPolicy: Incomplete
+    description: Incomplete
+    requestedExecutionLevel: Incomplete
+    uiAccess: Incomplete
+    dependentAssemblies: Incomplete
+    bindingRedirects: Incomplete
+    files: Incomplete
+    comInterfaceExternalProxyStubs: Incomplete
+    def __init__(
+        self,
+        manifestType: str = "assembly",
+        manifestVersion: Incomplete | None = None,
+        noInheritable: bool = False,
+        noInherit: bool = False,
+        type_: Incomplete | None = None,
+        name: Incomplete | None = None,
+        language: str | None = None,
+        processorArchitecture: Incomplete | None = None,
+        version: Incomplete | None = None,
+        publicKeyToken: Incomplete | None = None,
+        description: Unused = None,
+        requestedExecutionLevel: Incomplete | None = None,
+        uiAccess: Incomplete | None = None,
+        dependentAssemblies: Incomplete | None = None,
+        files: Incomplete | None = None,
+        comInterfaceExternalProxyStubs: Incomplete | None = None,
+    ) -> None: ...
+    @overload
+    def __eq__(self, other: Manifest | str) -> bool: ...  # type: ignore[misc]
+    @overload
+    def __eq__(self, other: object) -> Literal[False]: ...
+    @overload
+    def __ne__(self, other: Manifest | str) -> bool: ...  # type: ignore[misc]
+    @overload
+    def __ne__(self, other: object) -> Literal[True]: ...
+    def add_dependent_assembly(
+        self,
+        manifestVersion: Incomplete | None = None,
+        noInheritable: bool = False,
+        noInherit: bool = False,
+        type_: Incomplete | None = None,
+        name: Incomplete | None = None,
+        language: str | None = None,
+        processorArchitecture: Incomplete | None = None,
+        version: Incomplete | None = None,
+        publicKeyToken: Incomplete | None = None,
+        description: Incomplete | None = None,
+        requestedExecutionLevel: Incomplete | None = None,
+        uiAccess: Incomplete | None = None,
+        dependentAssemblies: Incomplete | None = None,
+        files: Incomplete | None = None,
+        comInterfaceExternalProxyStubs: Incomplete | None = None,
+    ) -> None: ...
+    def add_file(
+        self,
+        name: str = "",
+        hashalg: str = "",
+        hash: str = "",
+        comClasses: Incomplete | None = None,
+        typelibs: Incomplete | None = None,
+        comInterfaceProxyStubs: Incomplete | None = None,
+        windowClasses: Incomplete | None = None,
+    ) -> None: ...
+    @classmethod
+    def get_winsxs_dir(cls) -> str: ...
+    @classmethod
+    def get_manifest_dir(cls) -> str: ...
+    @classmethod
+    def get_policy_dir(cls) -> str: ...
+    def get_policy_redirect(self, language: str | None = None, version: Incomplete | None = None) -> Incomplete: ...
+    def find_files(self, ignore_policies: bool = True) -> list[Incomplete]: ...
+    def getid(self, language: str | None = None, version: Incomplete | None = None) -> str: ...
+    def getlanguage(self, language: str | None = None, windowsversion: Incomplete | None = None) -> str: ...
+    def getpolicyid(self, fuzzy: bool = True, language: str | None = None, windowsversion: Incomplete | None = None) -> str: ...
+    def load_dom(self, domtree: Document | Element, initialize: bool = True) -> None: ...
+    def parse(self, filename_or_file: str | IO[AnyStr], initialize: bool = True) -> None: ...
+    def parse_string(self, xmlstr: ReadableBuffer | str, initialize: bool = True) -> None: ...
+    def same_id(self, manifest: Manifest, skip_version_check: bool = False) -> bool: ...
+    def todom(self) -> Document: ...
+    def toprettyxml(self, indent: str = "  ", newl: str = ..., encoding: str = "UTF-8") -> str: ...
+    def toxml(self, encoding: str = "UTF-8") -> str: ...
+    def update_resources(self, dstpath: str, names: Incomplete | None = None, languages: Incomplete | None = None) -> None: ...
+    def writeprettyxml(
+        self, filename_or_file: str | IO[AnyStr] | None = None, indent: str = "  ", newl: str = ..., encoding: str = "UTF-8"
+    ) -> None: ...
+    def writexml(
+        self, filename_or_file: str | IO[AnyStr] | None = None, indent: Unused = "  ", newl: Unused = ..., encoding: str = "UTF-8"
+    ) -> None: ...