Skip to content

ast.parse annotation excludes valid ast.AST subclasses #14416

New issue
New issue
Open
Open
ast.parse annotation excludes valid ast.AST subclasses#14416
Labels
stubs: false positiveType checkers report false errors
@hunterhogan

Description

@hunterhogan
hunterhogan
opened on Jul 15, 2025

typeshed/stdlib/ast.pyi

Lines 1731 to 1732 in 84e41f2

def parse(
source: str | ReadableBuffer,

Full annotation

typeshed/stdlib/ast.pyi

Lines 1729 to 1878 in 84e41f2

if sys.version_info >= (3, 13):
@overload
def parse(
source: str | ReadableBuffer,
filename: str | ReadableBuffer | os.PathLike[Any] = "<unknown>",
mode: Literal["exec"] = "exec",
*,
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
optimize: Literal[-1, 0, 1, 2] = -1,
) -> Module: ...
@overload
def parse(
source: str | ReadableBuffer,
filename: str | ReadableBuffer | os.PathLike[Any],
mode: Literal["eval"],
*,
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
optimize: Literal[-1, 0, 1, 2] = -1,
) -> Expression: ...
@overload
def parse(
source: str | ReadableBuffer,
filename: str | ReadableBuffer | os.PathLike[Any],
mode: Literal["func_type"],
*,
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
optimize: Literal[-1, 0, 1, 2] = -1,
) -> FunctionType: ...
@overload
def parse(
source: str | ReadableBuffer,
filename: str | ReadableBuffer | os.PathLike[Any],
mode: Literal["single"],
*,
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
optimize: Literal[-1, 0, 1, 2] = -1,
) -> Interactive: ...
@overload
def parse(
source: str | ReadableBuffer,
*,
mode: Literal["eval"],
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
optimize: Literal[-1, 0, 1, 2] = -1,
) -> Expression: ...
@overload
def parse(
source: str | ReadableBuffer,
*,
mode: Literal["func_type"],
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
optimize: Literal[-1, 0, 1, 2] = -1,
) -> FunctionType: ...
@overload
def parse(
source: str | ReadableBuffer,
*,
mode: Literal["single"],
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
optimize: Literal[-1, 0, 1, 2] = -1,
) -> Interactive: ...
@overload
def parse(
source: str | ReadableBuffer,
filename: str | ReadableBuffer | os.PathLike[Any] = "<unknown>",
mode: str = "exec",
*,
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
optimize: Literal[-1, 0, 1, 2] = -1,
) -> mod: ...
else:
@overload
def parse(
source: str | ReadableBuffer,
filename: str | ReadableBuffer | os.PathLike[Any] = "<unknown>",
mode: Literal["exec"] = "exec",
*,
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
) -> Module: ...
@overload
def parse(
source: str | ReadableBuffer,
filename: str | ReadableBuffer | os.PathLike[Any],
mode: Literal["eval"],
*,
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
) -> Expression: ...
@overload
def parse(
source: str | ReadableBuffer,
filename: str | ReadableBuffer | os.PathLike[Any],
mode: Literal["func_type"],
*,
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
) -> FunctionType: ...
@overload
def parse(
source: str | ReadableBuffer,
filename: str | ReadableBuffer | os.PathLike[Any],
mode: Literal["single"],
*,
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
) -> Interactive: ...
@overload
def parse(
source: str | ReadableBuffer,
*,
mode: Literal["eval"],
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
) -> Expression: ...
@overload
def parse(
source: str | ReadableBuffer,
*,
mode: Literal["func_type"],
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
) -> FunctionType: ...
@overload
def parse(
source: str | ReadableBuffer,
*,
mode: Literal["single"],
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
) -> Interactive: ...
@overload
def parse(
source: str | ReadableBuffer,
filename: str | ReadableBuffer | os.PathLike[Any] = "<unknown>",
mode: str = "exec",
*,
type_comments: bool = False,
feature_version: None | int | tuple[int, int] = None,
) -> mod: ...

However, some ast.AST objects are a valid type for source. See, e.g., python/cpython#130139

Pylance rejects ast.Module objects

import ast

ast.parse(ast.Module([], []))

Argument of type "Module" cannot be assigned to parameter "source" of type "str | ReadableBuffer" in function "parse"

Two diagnostic errors 

[{
	"resource": "Untitled-1",
	"owner": "pylance",
	"code": {
		"value": "reportCallIssue",
		"target": {
			"$mid": 1,
			"path": "/microsoft/pylance-release/blob/main/docs/diagnostics/reportCallIssue.md",
			"scheme": "https",
			"authority": "github.com"
		}
	},
	"severity": 8,
	"message": "No overloads for \"parse\" match the provided arguments",
	"source": "Pylance",
	"startLineNumber": 3,
	"startColumn": 1,
	"endLineNumber": 3,
	"endColumn": 30,
	"relatedInformation": [
		{
			"startLineNumber": 1794,
			"startColumn": 9,
			"endLineNumber": 1794,
			"endColumn": 14,
			"message": "Overload 8 is the closest match",
			"resource": "/c:/Users/hunte/.vscode-insiders/extensions/ms-python.vscode-pylance-2025.6.103/dist/typeshed-fallback/stdlib/ast.pyi"
		}
	],
	"origin": "extHost1"
},{
	"resource": "Untitled-1",
	"owner": "pylance",
	"code": {
		"value": "reportArgumentType",
		"target": {
			"$mid": 1,
			"path": "/microsoft/pylance-release/blob/main/docs/diagnostics/reportArgumentType.md",
			"scheme": "https",
			"authority": "github.com"
		}
	},
	"severity": 8,
	"message": "Argument of type \"Module\" cannot be assigned to parameter \"source\" of type \"str | ReadableBuffer\" in function \"parse\"\n  Type \"Module\" is not assignable to type \"str | ReadableBuffer\"\n    \"Module\" is not assignable to \"str\"\n    \"Module\" is incompatible with protocol \"Buffer\"\n      \"__buffer__\" is not present",
	"source": "Pylance",
	"startLineNumber": 3,
	"startColumn": 11,
	"endLineNumber": 3,
	"endColumn": 29,
	"origin": "extHost1"
}]

Metadata

Metadata

Assignees

No one assigned

    Labels

    stubs: false positiveType checkers report false errors

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions