Title: Clarify compile and eval interaction.
Type: enhancement Stage: needs patch
Components: Documentation Versions: Python 3.3, Python 3.4, Python 2.7
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: docs@python, ezio.melotti, terry.reedy
Priority: normal Keywords:

Created on 2013-10-18 22:25 by terry.reedy, last changed 2013-11-12 20:12 by ezio.melotti.

Messages (2)
msg200318 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2013-10-18 22:25
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)."

My suggestion:

"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.
msg202716 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2013-11-12 20:12
I find your suggestion difficult to read.  Maybe using a list would make it more understandable?
Date User Action Args
2013-11-12 20:12:46ezio.melottisettype: enhancement

messages: + msg202716
nosy: + ezio.melotti
2013-10-18 22:25:32terry.reedycreate