[issue19557] ast - docs for every node type are missing
New submission from anatoly techtonik:
http://docs.python.org/2/library/ast.html
AST module doc is incomplete. To write node visitor, you need to know possible types of parameters and expected values for every node type. They are different.
http://hg.python.org/cpython/file/1ee45eb6aab9/Parser/Python.asdl
For example, visit_Assign expects: Assign(targets, value) `targets` can be List, Tuple or Name
When there is List, and when there is Tuple? It should be documented.
---------- assignee: docs@python components: Devguide, Documentation messages: 202675 nosy: docs@python, ezio.melotti, techtonik priority: normal severity: normal status: open title: ast - docs for every node type are missing
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue19557 _______________________________________
Brett Cannon added the comment:
The node types are all listed right there in the docs in the abstract grammar section, so arguing they are incomplete I don't think is accurate.
I'm willing to leave this open in case some ambitious person wants to write docs for every node type, but I think this is a very low priority task.
---------- nosy: +brett.cannon priority: normal -> low
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue19557 _______________________________________
Changes by Terry J. Reedy tjreedy@udel.edu:
---------- components: -Devguide
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue19557 _______________________________________
anatoly techtonik added the comment:
Neither you nor docs answer the question when Assign node gets Tuple as argument, when List and when Subscript.
While it is obvious to you, I personally don't know what a Subscript is. This is the kind of stuff that I'd like to see documented.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue19557 _______________________________________
anatoly techtonik added the comment:
http://stackoverflow.com/questions/8370132/what-syntax-is-represented-by-an-...
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue19557 _______________________________________
Changes by Brett Cannon brett@python.org:
---------- nosy: -brett.cannon
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue19557 _______________________________________
anatoly techtonik added the comment:
https://greentreesnakes.readthedocs.org/en/latest/
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue19557 _______________________________________
Georg Brandl added the comment:
When citing a link, it's customary to give at least a comment *why* you are citing it.
---------- nosy: +georg.brandl
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue19557 _______________________________________
anatoly techtonik added the comment:
SO link serves a proof that a problem is actual. It is needed, because, for example Brett doesn't think it is important.
2nd link is the same proof, and also an example of documentation wanted.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue19557 _______________________________________
anatoly techtonik added the comment:
In fact it may be the documentation that could be merged.
----------
_______________________________________ Python tracker report@bugs.python.org http://bugs.python.org/issue19557 _______________________________________
Batuhan batuhanosmantaskaya@gmail.com added the comment:
@pablogsal is working on documenting nodes (not every node type that exists, the ones that aren't deprecated) in PR 17812
---------- nosy: +BTaskaya, pablogsal
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue19557 _______________________________________
Cheryl Sabella cheryl.sabella@gmail.com added the comment:
@BTaskaya, thank you. I'm going to close this issue as a duplicate of that one.
---------- nosy: +cheryl.sabella resolution: -> duplicate stage: -> resolved status: open -> closed superseder: -> Improve the AST documentation
_______________________________________ Python tracker report@bugs.python.org https://bugs.python.org/issue19557 _______________________________________
participants (6)
-
anatoly techtonik -
Batuhan
-
Brett Cannon
-
Cheryl Sabella
-
Georg Brandl
-
Terry J. Reedy