[issue39199] Improve the AST documentation
New submission from Pablo Galindo Salgado <pablogsal@gmail.com>: The AST docs need some love as they can be a bit obscure to someone new to the module. Improvements to be considered in this issue: * Document all available nodes (as of 3.8 and not deprecated ones). This helps to know what classes to consider when implementing methods for the visitors. * Add some short practical examples for the visitors: one to query an AST and another to modify it. ---------- assignee: docs@python components: Documentation messages: 359235 nosy: docs@python, pablogsal priority: normal severity: normal status: open title: Improve the AST documentation versions: Python 3.9 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________
Change by Pablo Galindo Salgado <pablogsal@gmail.com>: ---------- keywords: +patch pull_requests: +17239 stage: -> patch review pull_request: https://github.com/python/cpython/pull/17812 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________
Pablo Galindo Salgado <pablogsal@gmail.com> added the comment: New changeset 114081f8adafa16283df30c456716a1bef4758d0 by Pablo Galindo in branch 'master': bpo-39199: Add descriptions of non-deprecated nodes to the AST module documentation (GH-17812) https://github.com/python/cpython/commit/114081f8adafa16283df30c456716a1bef4... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________
Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment: Would not be better to use mode='eval' for expression nodes? >>> print(ast.dump(ast.parse('123', mode='eval'), indent=4)) Expression( body=Constant(value=123, kind=None)) ---------- nosy: +serhiy.storchaka _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________
Pablo Galindo Salgado <pablogsal@gmail.com> added the comment:
Would not be better to use mode='eval' for expression nodes?
Agreed! I will prepare a PR soon to simplify the expression examples. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________
Change by Pablo Galindo Salgado <pablogsal@gmail.com>: ---------- pull_requests: +18186 pull_request: https://github.com/python/cpython/pull/18828 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________
Pablo Galindo Salgado <pablogsal@gmail.com> added the comment: New changeset 02f64cb79175902705b40e3eaa8ea6c7038754ef by Pablo Galindo in branch 'master': bpo-39199: Use 'eval' mode for the examples with expression nodes (GH-18828) https://github.com/python/cpython/commit/02f64cb79175902705b40e3eaa8ea6c7038... ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________
Serhiy Storchaka <storchaka+cpython@gmail.com> added the comment: As you worked much with ast.dump(), what multi-line formatting do you prefer, the current Module( body=[ If( test=Name(id='x', ctx=Load()), body=[ Expr( value=Constant(value=Ellipsis))], orelse=[ If( test=Name(id='y', ctx=Load()), body=[ Expr( value=Constant(value=Ellipsis))], orelse=[ Expr( value=Constant(value=Ellipsis))])])], type_ignores=[]) or with closing brackets on separate lines? Module( body=[ If( test=Name(id='x', ctx=Load()), body=[ Expr( value=Constant(value=Ellipsis) ) ], orelse=[ If( test=Name(id='y', ctx=Load()), body=[ Expr( value=Constant(value=Ellipsis) ) ], orelse=[ Expr( value=Constant(value=Ellipsis) ) ] ) ] ) ], type_ignores=[] ) The latter make contain long stairs of closing brackets. ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________
Pablo Galindo Salgado <pablogsal@gmail.com> added the comment: The first one looks on first inspection "cleaner" but then I tried to look at a random closed bracket/parenthesis like the ones in value=Constant(value=Ellipsis))])])], and trying to guess where that closes and is confusing to say the least so I think I would prefer the second one as is less "dense". Additionally, I was curious and I have asked several people with different examples and almost everyone prefers the second one, being the only reason someone preferred the first the fact that "fits vertically in the screen and you need less scrolling to read it all". ---------- _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________
Change by Pablo Galindo Salgado <pablogsal@gmail.com>: ---------- pull_requests: +23499 pull_request: https://github.com/python/cpython/pull/24727 _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue39199> _______________________________________
participants (2)
-
Pablo Galindo Salgado -
Serhiy Storchaka