[docs] [issue19290] Clarify compile and eval interaction.
Terry J. Reedy
report at bugs.python.org
Sat Oct 19 00:25:32 CEST 2013
New submission from Terry J. Reedy:
This issue was stimulated by #17294 where there seems to be some confusion over the purpose of the compile modes with regards to return values. I then noticed that the eval doc starts wrong and later corrects itself.
I think the following sentence from the compile doc could be improved. The current version:
"The mode argument specifies what kind of code must be compiled; it can be 'exec' if source consists of a sequence of statements, 'eval' if it consists of a single expression, or 'single' if it consists of a single interactive statement (in the latter case, expression statements that evaluate to something other than None will be printed)."
"The mode argument specifies the allowed source and the return value when the result is passed to eval(). It can be 'exec' for any source (a sequence of 0 to many statements); the return value will be None. It can be 'eval' if the source is a single expression; the return value will be the value of the expression. It can be 'single' if the source is a single non-empty interactive statement; the return value will be None, as with 'exec', but if the statement is an expression that evaluates to something other than None, the value will be printed."
(#13677 is about changing the doc and docstring for the compile flags argument. Patches for that and this should be disjoint.)
The eval(expression, ..) doc say that expression is a string. It much later says that it can also be a code object. I think the eval doc should follow the exec doc and call the first positional-only arg 'object' and then say the same thing: 'object must be either a string or a code object.' I don't have a complete suggested revision yet.
assignee: docs at python
nosy: docs at python, terry.reedy
stage: needs patch
title: Clarify compile and eval interaction.
versions: Python 2.7, Python 3.3, Python 3.4
Python tracker <report at bugs.python.org>
More information about the docs