classification
Title: Ast doc: warning and version number
Type: enhancement Stage: resolved
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: closed Resolution: out of date
Dependencies: Superseder:
Assigned To: docs@python Nosy List: berker.peksag, daniel.urban, docs@python, eric.araujo, ezio.melotti, georg.brandl, terry.reedy
Priority: normal Keywords: easy

Created on 2011-04-04 16:16 by terry.reedy, last changed 2014-06-30 08:51 by berker.peksag. This issue is now closed.

Messages (6)
msg132951 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-04-04 16:16
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
msg132952 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011-04-04 16:18
Modify entry slightly to
    String constant with version number of the abstract grammar file.
    3.1: '67616'; 3.2: '82163'; 3.3: 'xxxxxxxxx'
msg133204 - (view) Author: Georg Brandl (georg.brandl) * (Python committer) Date: 2011-04-07 09:45
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.
msg134633 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-04-28 01:11
Please improve this rough phrasing: “Check the value of *ast.__version__* to write version-specific code blocks if you need to work across versions.”
msg135313 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2011-05-06 16:04
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.”
msg221949 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2014-06-30 08:51
> 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".
History
Date User Action Args
2014-06-30 08:51:12berker.peksagsetstatus: open -> closed

nosy: + berker.peksag
messages: + msg221949

resolution: out of date
stage: needs patch -> resolved
2012-11-08 08:35:00ezio.melottisetkeywords: + easy, - patch
type: enhancement
versions: + Python 3.4, - Python 3.1
2011-05-06 16:04:45eric.araujosetmessages: + msg135313
2011-04-30 12:23:01daniel.urbansetnosy: + daniel.urban
2011-04-30 02:57:16ezio.melottisetnosy: + ezio.melotti
2011-04-28 01:11:36eric.araujosetversions: + Python 3.1
2011-04-28 01:11:27eric.araujosetnosy: + eric.araujo
messages: + msg134633
2011-04-07 09:45:41georg.brandlsetnosy: + georg.brandl
messages: + msg133204
2011-04-04 16:18:56terry.reedysetkeywords: + patch

messages: + msg132952
2011-04-04 16:16:00terry.reedycreate