classification
Title: Improve the AST documentation
Type: Stage: patch review
Components: Documentation Versions: Python 3.9
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, pablogsal, serhiy.storchaka
Priority: normal Keywords: patch

Created on 2020-01-03 13:05 by pablogsal, last changed 2021-03-03 16:43 by pablogsal.

Pull Requests
URL Status Linked Edit
PR 17812 merged pablogsal, 2020-01-03 13:06
PR 18828 merged pablogsal, 2020-03-07 17:25
PR 24727 merged pablogsal, 2021-03-03 16:43
Messages (7)
msg359235 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2020-01-03 13:05
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.
msg363112 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2020-03-02 03:14
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/114081f8adafa16283df30c456716a1bef4758d0
msg363585 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-03-07 09:17
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))
msg363604 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2020-03-07 17:12
> Would not be better to use mode='eval' for expression nodes?

Agreed! I will prepare a PR soon to simplify the expression examples.
msg363611 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2020-03-07 18:23
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/02f64cb79175902705b40e3eaa8ea6c7038754ef
msg363777 - (view) Author: Serhiy Storchaka (serhiy.storchaka) * (Python committer) Date: 2020-03-09 22:29
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.
msg363783 - (view) Author: Pablo Galindo Salgado (pablogsal) * (Python committer) Date: 2020-03-09 22:46
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".
History
Date User Action Args
2021-03-03 16:43:03pablogsalsetpull_requests: + pull_request23499
2020-03-09 22:46:36pablogsalsetmessages: + msg363783
2020-03-09 22:29:51serhiy.storchakasetmessages: + msg363777
2020-03-07 18:23:03pablogsalsetmessages: + msg363611
2020-03-07 17:25:20pablogsalsetpull_requests: + pull_request18186
2020-03-07 17:12:08pablogsalsetmessages: + msg363604
2020-03-07 09:17:47serhiy.storchakasetnosy: + serhiy.storchaka
messages: + msg363585
2020-03-02 03:14:12pablogsalsetmessages: + msg363112
2020-01-12 14:30:47cheryl.sabellalinkissue19557 superseder
2020-01-03 13:06:29pablogsalsetkeywords: + patch
stage: patch review
pull_requests: + pull_request17239
2020-01-03 13:05:21pablogsalcreate