homepage

This issue tracker has been migrated to GitHub , and is currently read-only.
For more information, see the GitHub FAQs in the Python's Developer Guide.

classification
Title: correct docstring for builtin compile
Type: behavior Stage:
Components: Documentation Versions: Python 3.8, Python 3.7, Python 3.6, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: Jim.Jewett, docs@python, eric.araujo, terry.reedy
Priority: normal Keywords: patch

Created on 2011年12月29日 17:49 by Jim.Jewett, last changed 2022年04月11日 14:57 by admin.

Files
File name Uploaded Description Edit
bltinmodule.c.patch Jim.Jewett, 2011年12月29日 17:49 Change to compile_doc
Messages (5)
msg150337 - (view) Author: Jim Jewett (Jim.Jewett) * (Python triager) Date: 2011年12月29日 17:49
The current docstring for compile suggests that the flags are strictly for selecting future statements. These are not the only flags.
It also suggests that the source must be source code and the result will be bytecode, which isn't quite true.
I suggest changing:
"The flags argument, if present, controls which future statements influence the compilation of the code."
to:
"The flags argument, if present, largely controls which future 
statements influence the compilation of the code. (Additional 
flags are documented in the AST module.)"
msg150400 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011年12月30日 21:48
Flags comment applies to 3.2.2 docs and 2.7.2 docs. There is only one additional flag: ast.PyCF_ONLY_AST, so 'flags' should be singular.
As for src and dst, doc has been updated to say 'Compile the source into a code or AST object. ... source can either be a string or an AST object.
'source' should be capitalized.
msg150407 - (view) Author: Jim Jewett (Jim.Jewett) * (Python triager) Date: 2011年12月31日 01:51
I'm not sure we're looking at the same thing. I was talking about the docstring that shows up at the interactive prompt in response to 
>>> help(compile)
Going to hg.python.org/cpython and selecting branches, then default, then browse, got me to
http://hg.python.org/cpython/file/7010fa9bd190/Python/bltinmodule.c
which still doesn't mention AST. I also don't see any reference to "src" or "dst", or any "source" that looks like it should be capitalized.
I agree that there is (to my knowledge, at this time) only one additional flag. I figured ast or future was needed to get the compilation constants, so it made sense to delegate -- but you seem to be reading something newer than I am.
msg150408 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2011年12月31日 04:47
I am aware that the docstring, shown at help(compile), is what you were talking about. The docstring and manuals should say the same thing, or at least not contradict each other, so it is common for both to be out of date and both to be updated at the same time. So I went and looked at the current py2 and py3 docs to see if they also need change. And they do, though not quite as much. src and dst were unofficial abbreviations for source and output, in reference to what you said. Sorry for the confusion.
msg150947 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2012年01月09日 16:22
The compiler flags are not really documented in the ast module doc or anywhere: see #12207 and #1612012.
History
Date User Action Args
2022年04月11日 14:57:25adminsetgithub: 57886
2018年03月22日 08:38:26serhiy.storchakasetversions: + Python 3.6, Python 3.7, Python 3.8, - Python 3.2, Python 3.3
2012年01月09日 16:22:02eric.araujosetmessages: + msg150947
2011年12月31日 11:19:10eric.araujosetnosy: + eric.araujo
2011年12月31日 04:47:26terry.reedysetmessages: + msg150408
2011年12月31日 01:51:17Jim.Jewettsetmessages: + msg150407
2011年12月30日 21:48:47terry.reedysetnosy: + terry.reedy

messages: + msg150400
versions: + Python 2.7, Python 3.2, Python 3.3
2011年12月29日 17:49:22Jim.Jewettcreate

AltStyle によって変換されたページ (->オリジナル) /