From 89350057968225617016c569281fa58573e4c50c Mon Sep 17 00:00:00 2001 From: Guido van Rossum Date: Mon, 28 Jan 2019 09:47:36 -0800 Subject: [PATCH] Document type_comments=True and mode='func_type' for ast.parse() --- Doc/library/ast.rst | 19 ++++++++++++++++++- 1 file changed, 18 insertions(+), 1 deletion(-) diff --git a/Doc/library/ast.rst b/Doc/library/ast.rst index 7715a28ce1b8..359b627c1dc5 100644 --- a/Doc/library/ast.rst +++ b/Doc/library/ast.rst @@ -126,16 +126,33 @@ The abstract grammar is currently defined as follows: Apart from the node classes, the :mod:`ast` module defines these utility functions and classes for traversing abstract syntax trees: -.. function:: parse(source, filename='', mode='exec') +.. function:: parse(source, filename='', mode='exec', *, type_comments=False) Parse the source into an AST node. Equivalent to ``compile(source, filename, mode, ast.PyCF_ONLY_AST)``. + If ``type_comments=True`` is given, the parser is modified to check + and return type comments as specified by :pep:`484` and :pep:526`. + This is equivalent to adding :data:`ast.PyCF_TYPE_COMMENTS` to the + flags passed to :func:`compile()`. This will report syntax errors + for misplaced type comments. Without this flag, type comments will + be ignored, and the ``type_comment`` field on selected AST nodes + will always be ``None``. In addition, the locations of ``# type: + ignore`` comments will be returned as the ``type_ignores`` + attribute of :class:`Module` (otherwise it is always an empty list). + + In addition, if ``mode`` is ``'func_type'``, the input syntax is + modified to correspond to :pep:`484` "signature type comments", + e.g. ``(str, int) -> List[str]``. + .. warning:: It is possible to crash the Python interpreter with a sufficiently large/complex string due to stack depth limitations in Python's AST compiler. + .. versionchanged:: 3.8 + Added ``type_comments=True`` and ``mode='func_type'``. + .. function:: literal_eval(node_or_string) -- 2.47.3