classification
Title: ast - docs for every node type are missing
Type: Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: duplicate
Dependencies: Superseder: Improve the AST documentation
View: 39199
Assigned To: docs@python Nosy List: BTaskaya, cheryl.sabella, docs@python, ezio.melotti, georg.brandl, pablogsal, techtonik
Priority: low Keywords:

Created on 2013-11-12 06:52 by techtonik, last changed 2020-01-12 14:30 by cheryl.sabella. This issue is now closed.

Messages (10)
msg202675 - (view) Author: anatoly techtonik (techtonik) Date: 2013-11-12 06:52
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.
msg202697 - (view) Author: Brett Cannon (brett.cannon) * (Python committer) Date: 2013-11-12 15:43
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.
msg203734 - (view) Author: anatoly techtonik (techtonik) Date: 2013-11-22 10:57
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.
msg204073 - (view) Author: anatoly techtonik (techtonik) Date: 2013-11-23 18:32
http://stackoverflow.com/questions/8370132/what-syntax-is-represented-by-an-extslice-node-in-pythons-ast
msg204479 - (view) Author: anatoly techtonik (techtonik) Date: 2013-11-26 14:51
https://greentreesnakes.readthedocs.org/en/latest/
msg204513 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2013-11-26 18:28
When citing a link, it's customary to give at least a comment *why* you are citing it.
msg204528 - (view) Author: anatoly techtonik (techtonik) Date: 2013-11-26 20:29
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.
msg204529 - (view) Author: anatoly techtonik (techtonik) Date: 2013-11-26 20:30
In fact it may be the documentation that could be merged.
msg359759 - (view) Author: Batuhan Taskaya (BTaskaya) * (Python committer) Date: 2020-01-10 21:27
@pablogsal is working on documenting nodes (not every node type that exists, the ones that aren't deprecated) in PR 17812
msg359851 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2020-01-12 14:30
@BTaskaya, thank you.  I'm going to close this issue as a duplicate of that one.
History
Date User Action Args
2020-01-12 14:30:47cheryl.sabellasetstatus: open -> closed

superseder: Improve the AST documentation

nosy: + cheryl.sabella
messages: + msg359851
resolution: duplicate
stage: resolved
2020-01-10 21:27:12BTaskayasetnosy: + pablogsal, BTaskaya
messages: + msg359759
2013-11-26 20:30:44techtoniksetmessages: + msg204529
2013-11-26 20:29:24techtoniksetmessages: + msg204528
2013-11-26 18:28:54georg.brandlsetnosy: + georg.brandl
messages: + msg204513
2013-11-26 14:51:35techtoniksetmessages: + msg204479
2013-11-24 15:36:29brett.cannonsetnosy: - brett.cannon
2013-11-23 18:32:25techtoniksetmessages: + msg204073
2013-11-22 10:57:19techtoniksetmessages: + msg203734
2013-11-16 00:46:26terry.reedysetcomponents: - Devguide
2013-11-12 15:43:02brett.cannonsetpriority: normal -> low
nosy: + brett.cannon
messages: + msg202697

2013-11-12 06:52:24techtonikcreate