[New-bugs-announce] [issue38765] `ast.AST._attributes` is used by `ast.dump()` but not documented

[Pekka Klärck]

New submission from Pekka Klärck <pekka.klarck at gmail.com>:

We have implemented an ast for our own tool so that we extend Python's standard `ast.AST`. When using `ast.dump(node, include_attributes=True)`, we were surprised to notice that line numbers weren't dumped although the docs of `ast.dump()` said they should be and we had set both `lineno` and `end_lineno` attributes to our nodes.

Looking at the implementation of `ast.dump()` revealed that `include_attributes=True` alone wasn't enough, the node also needed to have `_attributes` attribute similarly as it needs to have `_fields` for `ast.dump()` to be able to dump also child nodes. The problem is that `_attributes` isn't documented at all. Related to that, `ast.dump()` using `_fields` isn't documented either, but at least `_fields` is mentioned in the docs otherwise. Relevant links to `ast.dump()` docs and to the source code below.

`ast.AST` documents the `_fields` attribute but doesn't mention similar `_attributes`:
https://docs.python.org/3/library/ast.html#ast.AST

`ast.dump()` documents the `include_attributes` argument but doesn't mention that `_attributes` is needed (or that `_fields` needs to be set correctly to get child notes dumped):
https://docs.python.org/3/library/ast.html#ast.dump

`ast.dump()` source code shows that the undocumented `_attributes` needs to be set in addition to using `include_attributes=True`:
https://github.com/python/cpython/blob/3.8/Lib/ast.py#L123

----------
messages: 356362
nosy: pekka.klarck
priority: normal
severity: normal
status: open
title: `ast.AST._attributes` is used by `ast.dump()` but not documented

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue38765>
_______________________________________