Improve the AST documentation

[pablogsal]

BPO	39199
Nosy	@serhiy-storchaka, @pablogsal
PRs	bpo-39199: Add descriptions of non-deprecated AST nodes to the AST module documentation #17812 bpo-39199: Use 'eval' mode for the examples with expression nodes #18828 bpo-39199: Add attribution to the Green Tree Snakes in the AST docs #24727

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2020-01-03.13:05:21.001>
labels = ['3.9', 'docs']
title = 'Improve the AST documentation'
updated_at = <Date 2021-03-03.16:43:03.193>
user = 'https://github.com/pablogsal'

bugs.python.org fields:

activity = <Date 2021-03-03.16:43:03.193>
actor = 'pablogsal'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2020-01-03.13:05:21.001>
creator = 'pablogsal'
dependencies = []
files = []
hgrepos = []
issue_num = 39199
keywords = ['patch']
message_count = 7.0
messages = ['359235', '363112', '363585', '363604', '363611', '363777', '363783']
nosy_count = 3.0
nosy_names = ['docs@python', 'serhiy.storchaka', 'pablogsal']
pr_nums = ['17812', '18828', '24727']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = None
url = 'https://bugs.python.org/issue39199'
versions = ['Python 3.9']

[pablogsal]

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.

[pablogsal]

New changeset 114081f by Pablo Galindo in branch 'master':
bpo-39199: Add descriptions of non-deprecated nodes to the AST module documentation (GH-17812)
114081f

[serhiy-storchaka]

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))

[pablogsal]

Would not be better to use mode='eval' for expression nodes?

Agreed! I will prepare a PR soon to simplify the expression examples.

[pablogsal]

New changeset 02f64cb by Pablo Galindo in branch 'master':
bpo-39199: Use 'eval' mode for the examples with expression nodes (GH-18828)
02f64cb

[serhiy-storchaka]

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.

[pablogsal]

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".