Improve sys stubs (#6816)

Co-authored-by: Akuli <[email protected]>

Author: AlexWaygood

stdlib/sys.pyi

@@ -34,7 +34,7 @@ displayhook: Callable[[object], Any]
 excepthook: Callable[[Type[BaseException], BaseException, TracebackType | None], Any]
 exec_prefix: str
 executable: str
-float_repr_style: str
+float_repr_style: Literal["short", "legacy"]
 hexversion: int
 last_type: Type[BaseException] | None
 last_value: BaseException | None
@@ -74,49 +74,105 @@ if sys.platform == "win32":
     winver: str
 _xoptions: dict[Any, Any]
 
+# Type alias used as a mixin for structseq classes that cannot be instantiated at runtime
+# This can't be represented in the type system, so we just use `structseq[Any]`
+_uninstantiable_structseq = structseq[Any]
+
 flags: _flags
 
-class _flags:
-    debug: int
-    division_warning: int
-    inspect: int
-    interactive: int
-    optimize: int
-    dont_write_bytecode: int
-    no_user_site: int
-    no_site: int
-    ignore_environment: int
-    verbose: int
-    bytes_warning: int
-    quiet: int
-    hash_randomization: int
+if sys.version_info >= (3, 10):
+    _FlagTuple = tuple[int, int, int, int, int, int, int, int, int, int, int, int, int, bool, int, int]
+elif sys.version_info >= (3, 7):
+    _FlagTuple = tuple[int, int, int, int, int, int, int, int, int, int, int, int, int, bool, int]
+else:
+    _FlagTuple = tuple[int, int, int, int, int, int, int, int, int, int, int, int, int]
+
+@final
+class _flags(_uninstantiable_structseq, _FlagTuple):
+    @property
+    def debug(self) -> int: ...
+    @property
+    def inspect(self) -> int: ...
+    @property
+    def interactive(self) -> int: ...
+    @property
+    def optimize(self) -> int: ...
+    @property
+    def dont_write_bytecode(self) -> int: ...
+    @property
+    def no_user_site(self) -> int: ...
+    @property
+    def no_site(self) -> int: ...
+    @property
+    def ignore_environment(self) -> int: ...
+    @property
+    def verbose(self) -> int: ...
+    @property
+    def bytes_warning(self) -> int: ...
+    @property
+    def quiet(self) -> int: ...
+    @property
+    def hash_randomization(self) -> int: ...
+    @property
+    def isolated(self) -> int: ...
     if sys.version_info >= (3, 7):
-        dev_mode: int
-        utf8_mode: int
+        @property
+        def dev_mode(self) -> bool: ...
+        @property
+        def utf8_mode(self) -> int: ...
+    if sys.version_info >= (3, 10):
+        @property
+        def warn_default_encoding(self) -> int: ...  # undocumented
 
 float_info: _float_info
 
-class _float_info:
-    epsilon: float  # DBL_EPSILON
-    dig: int  # DBL_DIG
-    mant_dig: int  # DBL_MANT_DIG
-    max: float  # DBL_MAX
-    max_exp: int  # DBL_MAX_EXP
-    max_10_exp: int  # DBL_MAX_10_EXP
-    min: float  # DBL_MIN
-    min_exp: int  # DBL_MIN_EXP
-    min_10_exp: int  # DBL_MIN_10_EXP
-    radix: int  # FLT_RADIX
-    rounds: int  # FLT_ROUNDS
+@final
+class _float_info(structseq[float], tuple[float, int, int, float, int, int, int, int, float, int, int]):
+    @property
+    def max(self) -> float: ...  # DBL_MAX
+    @property
+    def max_exp(self) -> int: ...  # DBL_MAX_EXP
+    @property
+    def max_10_exp(self) -> int: ...  # DBL_MAX_10_EXP
+    @property
+    def min(self) -> float: ...  # DBL_MIN
+    @property
+    def min_exp(self) -> int: ...  # DBL_MIN_EXP
+    @property
+    def min_10_exp(self) -> int: ...  # DBL_MIN_10_EXP
+    @property
+    def dig(self) -> int: ...  # DBL_DIG
+    @property
+    def mant_dig(self) -> int: ...  # DBL_MANT_DIG
+    @property
+    def epsilon(self) -> float: ...  # DBL_EPSILON
+    @property
+    def radix(self) -> int: ...  # FLT_RADIX
+    @property
+    def rounds(self) -> int: ...  # FLT_ROUNDS
 
 hash_info: _hash_info
 
-class _hash_info:
-    width: int
-    modulus: int
-    inf: int
-    nan: int
-    imag: int
+@final
+class _hash_info(structseq[Any | int], tuple[int, int, int, int, int, str, int, int, int]):
+    @property
+    def width(self) -> int: ...
+    @property
+    def modulus(self) -> int: ...
+    @property
+    def inf(self) -> int: ...
+    @property
+    def nan(self) -> int: ...
+    @property
+    def imag(self) -> int: ...
+    @property
+    def algorithm(self) -> str: ...
+    @property
+    def hash_bits(self) -> int: ...
+    @property
+    def seed_bits(self) -> int: ...
+    @property
+    def cutoff(self) -> int: ...  # undocumented
 
 implementation: _implementation
 
@@ -125,16 +181,22 @@ class _implementation:
     version: _version_info
     hexversion: int
     cache_tag: str
-    _multiarch: str
+    # Define __getattr__, as the documentation states:
+    # > sys.implementation may contain additional attributes specific to the Python implementation.
+    # > These non-standard attributes must start with an underscore, and are not described here.
+    def __getattr__(self, name: str) -> Any: ...
 
 int_info: _int_info
 
-class _int_info:
-    bits_per_digit: int
-    sizeof_digit: int
+@final
+class _int_info(structseq[int], tuple[int, int]):
+    @property
+    def bits_per_digit(self) -> int: ...
+    @property
+    def sizeof_digit(self) -> int: ...
 
 @final
-class _version_info(structseq[Any | int], tuple[int, int, int, str, int]):
+class _version_info(_uninstantiable_structseq, tuple[int, int, int, str, int]):
     @property
     def major(self) -> int: ...
     @property
@@ -185,19 +247,30 @@ _TraceFunc = Callable[[FrameType, str, Any], Optional[Callable[[FrameType, str,
 def gettrace() -> _TraceFunc | None: ...
 def settrace(tracefunc: _TraceFunc | None) -> None: ...
 
-class _WinVersion(tuple[int, int, int, int, str, int, int, int, int, tuple[int, int, int]]):
-    major: int
-    minor: int
-    build: int
-    platform: int
-    service_pack: str
-    service_pack_minor: int
-    service_pack_major: int
-    suite_mast: int
-    product_type: int
-    platform_version: tuple[int, int, int]
-
 if sys.platform == "win32":
+    # A tuple of length 5, even though it has more than 5 attributes.
+    @final
+    class _WinVersion(_uninstantiable_structseq, tuple[int, int, int, int, str]):
+        @property
+        def major(self) -> int: ...
+        @property
+        def minor(self) -> int: ...
+        @property
+        def build(self) -> int: ...
+        @property
+        def platform(self) -> int: ...
+        @property
+        def service_pack(self) -> str: ...
+        @property
+        def service_pack_minor(self) -> int: ...
+        @property
+        def service_pack_major(self) -> int: ...
+        @property
+        def suite_mask(self) -> int: ...
+        @property
+        def product_type(self) -> int: ...
+        @property
+        def platform_version(self) -> tuple[int, int, int]: ...
     def getwindowsversion() -> _WinVersion: ...
 
 def intern(__string: str) -> str: ...
@@ -219,7 +292,7 @@ if sys.version_info < (3, 9):
     def setcheckinterval(__n: int) -> None: ...  # deprecated
 
 if sys.version_info >= (3, 8):
-    # not exported by sys
+    # Doesn't exist at runtime, but exported in the stubs so pytest etc. can annotate their code more easily.
     class UnraisableHookArgs:
         exc_type: Type[BaseException]
         exc_value: BaseException | None
@@ -232,9 +305,12 @@ if sys.version_info >= (3, 8):
 
 _AsyncgenHook = Optional[Callable[[AsyncGenerator[Any, Any]], None]]
 
-class _asyncgen_hooks(tuple[_AsyncgenHook, _AsyncgenHook]):
-    firstiter: _AsyncgenHook
-    finalizer: _AsyncgenHook
+@final
+class _asyncgen_hooks(structseq[_AsyncgenHook], tuple[_AsyncgenHook, _AsyncgenHook]):
+    @property
+    def firstiter(self) -> _AsyncgenHook: ...
+    @property
+    def finalizer(self) -> _AsyncgenHook: ...
 
 def get_asyncgen_hooks() -> _asyncgen_hooks: ...
 def set_asyncgen_hooks(firstiter: _AsyncgenHook = ..., finalizer: _AsyncgenHook = ...) -> None: ...