Overload ast.parse to recognize that mode=exec means Module return. (#3039)

Author: carljm

stdlib/3/ast.pyi

@@ -5,7 +5,8 @@ import sys
 # from _ast below when loaded in an unorthodox way by the Dropbox
 # internal Bazel integration.
 import typing as _typing
-from typing import Any, Iterator, Optional, Union, TypeVar
+from typing import overload, Any, Iterator, Optional, Union, TypeVar
+from typing_extensions import Literal
 
 # The same unorthodox Bazel integration causes issues with sys, which
 # is imported in both modules. unfortunately we can't just rename sys,
@@ -23,9 +24,18 @@ class NodeTransformer(NodeVisitor):
 _T = TypeVar('_T', bound=AST)
 
 if sys.version_info >= (3, 8):
+    @overload
+    def parse(source: Union[str, bytes], filename: Union[str, bytes] = ..., mode: Literal["exec"] = ...,
+              type_comments: bool = ..., feature_version: int = ...) -> Module: ...
+
+    @overload
     def parse(source: Union[str, bytes], filename: Union[str, bytes] = ..., mode: str = ...,
               type_comments: bool = ..., feature_version: int = ...) -> AST: ...
 else:
+    @overload
+    def parse(source: Union[str, bytes], filename: Union[str, bytes] = ..., mode: Literal["exec"] = ...) -> Module: ...
+
+    @overload
     def parse(source: Union[str, bytes], filename: Union[str, bytes] = ..., mode: str = ...) -> AST: ...
 
 def copy_location(new_node: _T, old_node: AST) -> _T: ...