[issue11762] Ast doc: warning and version number
New submission from Terry J. Reedy <tjreedy@udel.edu>: Two related proposals. 1. Add a warning similar to the one for the dis module. As modified: "CPython implementation detail: The ast definition is specific to the CPython interpreter! Ast nodes may be added, removed, or changed between versions. Use *ast.__version__* to work across versions." I omitted " Use of this module should not be considered to work across Python VMs or Python releases." as redundant and too legalistic. *ast.__version__* should link to its (new) entry). 2. Add a full entry for __version__. Currently (3.2): "The module defines a string constant __version__ which is the decimal Subversion revision number of the file shown below." Proposed replacement (with hidden reference point): ast.__version__ [__version__ in normal entry boldface] String constant with version number of abstract grammar file. 3.1: 67616; 3.2: 82163; 3.3: xxxxxxxxx ---------- assignee: docs@python components: Documentation messages: 132951 nosy: docs@python, terry.reedy priority: normal severity: normal stage: needs patch status: open title: Ast doc: warning and version number versions: Python 2.7, Python 3.2, Python 3.3 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________
Terry J. Reedy <tjreedy@udel.edu> added the comment: Modify entry slightly to String constant with version number of the abstract grammar file. 3.1: '67616'; 3.2: '82163'; 3.3: 'xxxxxxxxx' ---------- keywords: +patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________
Georg Brandl <georg@python.org> added the comment: Sounds good to me, except for "Use *ast.__version__* to work across versions." which is not quite clear. While talking about version numbers, we should probably also document *what changed* between those versions. ---------- nosy: +georg.brandl _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: Please improve this rough phrasing: “Check the value of *ast.__version__* to write version-specific code blocks if you need to work across versions.” ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________
Changes by Éric Araujo <merwok@netwok.org>: ---------- versions: +Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________
Changes by Daniel Urban <urban.dani+py@gmail.com>: ---------- nosy: +durban _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________
Éric Araujo <merwok@netwok.org> added the comment: The Python Insider blog has a nice phrasing: “The AST module exposes a constant, ``ast.__version__``, which provides a means for user code to vary its behaviour depending on the version of the AST it encounters.” ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________
Changes by Ezio Melotti <ezio.melotti@gmail.com>: ---------- keywords: +easy -patch type: -> enhancement versions: +Python 3.4 -Python 3.1 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________
Berker Peksag added the comment:
1. Add a warning similar to the one for the dis module.
The current documentation says: "The abstract syntax itself might change with each Python release; [...]" https://docs.python.org/3.4/library/ast.html
2. Add a full entry for __version__. Currently (3.2):
ast.__version__ has been removed in issue 12273. Closing this as "out of date". ---------- nosy: +berker.peksag resolution: -> out of date stage: needs patch -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue11762> _______________________________________
participants (6)
-
Berker Peksag -
Daniel Urban
-
Ezio Melotti
-
Georg Brandl
-
Terry J. Reedy
-
Éric Araujo