Overload ast.parse to recognize that mode=exec means Module return.

[carljm]

With mode="exec" (which is the default mode), ast.parse always returns an ast.Module. It's irritating to always have to cast this.

Verified this change with a small file:

import ast

def foo() -> ast.Module:
    return ast.parse("a = 1")

This raises an error (expected Module, got AST) on typeshed master, passes with this PR.
Also added explicit mode="exec", same results.
With mode="eval", error on both master and this PR.

[carljm]

I tried taking this one step further to also recognize that mode="single" always returns ast.Interactive, but I can't seem to avoid mypy telling me that Literal["exec"] and Literal["single"] are "overlapping types with incompatible return types." Which doesn't make sense to me; maybe a bug in mypy needs fixing first? Anyway, since this partial version is better than the status quo for the much more common case of "exec" mode, I still think it should be merged.

Also, I think that the linter that enforces that parameter defaults in stub files must be ... is outdated with literal types. In this case, I'm able to make it happy because mypy just assumes an overload match if the parameter is omitted even without knowing the real default. I guess this means the workaround of putting the default value overload always first should work? It still seems to me that in the presence of Literal types, it's reasonable and more comprehensible to include the default in the stub, as in principle it is relevant to the typechecker, and relying on "default overload first" seems excessively implicit. I opened PyCQA/flake8-pyi#28 to track this.

[srittau]

Literal is not yet supported in typeshed, see #2913.

[carljm]

Per recent typing-sig thread, sounds like it's time for that to change :) (FWIW it's already clear that it doesn't cause trouble for pytype, because otherwise typeshed pytype tests would not pass).

[srittau]

LGTM, just one optional suggestion.

[srittau]

Optional: You could also add the following overload, since exec is the default mode:

    @overload
    def parse(source: Union[str, bytes], filename: Union[str, bytes] = ..., *,
              type_comments: bool = ..., feature_version: int = ...) -> Module: ...

Similar for the Python 3.7 version.

(Also a style nit: Please don't add empty lines between overloads.)

[carljm]

Sorry I didn't get back to this sooner, thanks for the merge! Regarding this comment, I tried adding that overload and IIRC mypy complained about overlapping overloads. It seems that implicitly due to ordering of overloads, mypy already treats this as the "default" one. (I think the clearer way to express this to typecheckers would be to actually include the default value of the optional argument in the stub).