builtins: do the TODO on compile() (#9567)

Author: JelleZijlstra

stdlib/builtins.pyi

@@ -1220,27 +1220,90 @@ if sys.version_info >= (3, 10):
     @overload
     async def anext(__i: SupportsAnext[_T], default: _VT) -> _T | _VT: ...
 
-# TODO: `compile` has a more precise return type in reality; work on a way of expressing that?
+# compile() returns a CodeType, unless the flags argument includes PyCF_ONLY_AST (=1024),
+# in which case it returns ast.AST. We have overloads for flag 0 (the default) and for
+# explicitly passing PyCF_ONLY_AST. We fall back to Any for other values of flags.
 if sys.version_info >= (3, 8):
+    @overload
     def compile(
         source: str | ReadableBuffer | _ast.Module | _ast.Expression | _ast.Interactive,
         filename: str | ReadableBuffer | _PathLike[Any],
         mode: str,
-        flags: int = 0,
+        flags: Literal[0],
+        dont_inherit: int = False,
+        optimize: int = -1,
+        *,
+        _feature_version: int = -1,
+    ) -> CodeType: ...
+    @overload
+    def compile(
+        source: str | ReadableBuffer | _ast.Module | _ast.Expression | _ast.Interactive,
+        filename: str | ReadableBuffer | _PathLike[Any],
+        mode: str,
+        *,
+        dont_inherit: int = False,
+        optimize: int = -1,
+        _feature_version: int = -1,
+    ) -> CodeType: ...
+    @overload
+    def compile(
+        source: str | ReadableBuffer | _ast.Module | _ast.Expression | _ast.Interactive,
+        filename: str | ReadableBuffer | _PathLike[Any],
+        mode: str,
+        flags: Literal[1024],
+        dont_inherit: int = False,
+        optimize: int = -1,
+        *,
+        _feature_version: int = -1,
+    ) -> _ast.AST: ...
+    @overload
+    def compile(
+        source: str | ReadableBuffer | _ast.Module | _ast.Expression | _ast.Interactive,
+        filename: str | ReadableBuffer | _PathLike[Any],
+        mode: str,
+        flags: int,
         dont_inherit: int = False,
         optimize: int = -1,
         *,
         _feature_version: int = -1,
     ) -> Any: ...
 
 else:
+    @overload
+    def compile(
+        source: str | ReadableBuffer | _ast.Module | _ast.Expression | _ast.Interactive,
+        filename: str | ReadableBuffer | _PathLike[Any],
+        mode: str,
+        flags: Literal[0],
+        dont_inherit: int = False,
+        optimize: int = -1,
+    ) -> CodeType: ...
+    @overload
+    def compile(
+        source: str | ReadableBuffer | _ast.Module | _ast.Expression | _ast.Interactive,
+        filename: str | ReadableBuffer | _PathLike[Any],
+        mode: str,
+        *,
+        dont_inherit: int = False,
+        optimize: int = -1,
+    ) -> CodeType: ...
+    @overload
     def compile(
         source: str | ReadableBuffer | _ast.Module | _ast.Expression | _ast.Interactive,
         filename: str | ReadableBuffer | _PathLike[Any],
         mode: str,
-        flags: int = ...,
-        dont_inherit: int = ...,
-        optimize: int = ...,
+        flags: Literal[1024],
+        dont_inherit: int = False,
+        optimize: int = -1,
+    ) -> _ast.AST: ...
+    @overload
+    def compile(
+        source: str | ReadableBuffer | _ast.Module | _ast.Expression | _ast.Interactive,
+        filename: str | ReadableBuffer | _PathLike[Any],
+        mode: str,
+        flags: int,
+        dont_inherit: int = False,
+        optimize: int = -1,
     ) -> Any: ...
 
 def copyright() -> None: ...