[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