classification
Title: Docs does not eval allows code object as argument
Type: behavior Stage: needs patch
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: berker.peksag, cheryl.sabella, docs@python, jfine2358
Priority: normal Keywords:

Created on 2018-08-18 16:03 by jfine2358, last changed 2019-01-07 13:38 by jfine2358.

Messages (7)
msg323716 - (view) Author: Jonathan Fine (jfine2358) * Date: 2018-08-18 16:03
See https://docs.python.org/3.6/library/functions.html#eval
This says the following won't happen. But it does.

Python 3.6.2 (default, Jul 29 2017, 00:00:00) 
[GCC 4.8.4] on linux
Type "help", "copyright", "credits" or "license" for more information.
>>> def fn(): print(3); return 4
... 
>>> eval(fn.__code__)
3
4

Compare with https://docs.python.org/3.6/library/functions.html#exec

Search for eval in title of open issues bring up related

#22057 (The doc say all globals are copied on eval(), but only __builtins__ is copied)
#25810 (Python 3 documentation for eval is incorrect)
msg323717 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-08-18 16:49
Thank you for your report.

Quoting from https://docs.python.org/3.6/library/functions.html#eval

    This function can also be used to execute arbitrary code objects
    (such as those created by compile()). In this case pass a code
    object instead of a string.

So, your example is already documented as a legal way of using the eval() function.

I don't see anything wrong here.
msg323720 - (view) Author: Jonathan Fine (jfine2358) * Date: 2018-08-18 17:15
Summary: There's my problem, and others. I'm willing to provide a patch, if supported.

There's a gotcha here. I fell into it. The docs for eval state
===
eval(expression, globals=None, locals=None)
The arguments are a string and optional globals and locals.
===
I read this and concluded, fairly I think, that I'm not allowed to pass in a code object [1]. So I didn't read any further. I'd already got the answer to my question.

But I knew that exec would take a code object, so I had doubt, and did my little experiment.

I'd prefer something more like exec, which says
===
This function supports dynamic execution of Python code. object must be either a string or a code object.
===

There are other problems, such as not agreeing with the help(eval) etc messages (and the still open #22057, #25810):
===
eval(source, globals=None, locals=None, /)
    Evaluate the given source in the context of globals and locals.
    
    The source may be a string representing a Python expression
    or a code object as returned by compile().
    The globals must be a dictionary and locals can be any mapping,
    defaulting to the current globals and locals.
    If only globals is given, locals defaults to it.
===
exec(source, globals=None, locals=None, /)
    Execute the given source in the context of globals and locals.
    
    The source may be a string representing one or more Python statements
    or a code object as returned by compile().
    The globals must be a dictionary and locals can be any mapping,
    defaulting to the current globals and locals.
    If only globals is given, locals defaults to it.
===

Finally, I'm willing to provide a patch, if supported. (I've not contributed to Python before.)

[1] I'd just read the docs for exec, which is up-front about 'string or code'.
msg323722 - (view) Author: Berker Peksag (berker.peksag) * (Python committer) Date: 2018-08-18 17:41
Ok, I think it would be a good idea to mention that the function accepts a code object in the first sentence. I'd be happy to review such PR. The eval() documentation is located at https://github.com/python/cpython/blob/master/Doc/library/functions.rst

See https://devguide.python.org/ for more details about the contribution process.

Note that you need to sign the CLA in order to contribute to Python: https://www.python.org/psf/contrib/contrib-form/

#22057 and #25810 are out of scope for this issue, so let's not discuss them here.
msg323723 - (view) Author: Jonathan Fine (jfine2358) * Date: 2018-08-18 17:52
OK. I'll do as you say. I've just signed the CLA.
msg333082 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-01-05 23:27
Hi Jonathan,

Did you have any additional questions about opening a pull request for these changes?  Thanks!
msg333148 - (view) Author: Jonathan Fine (jfine2358) * Date: 2019-01-07 13:38
This graceful reminder is most welcome. At present, it's not help I'm short of, but time. I've given myself a reminder, to spend time on this before the end of this month (January 2019).

Once again, thank you for this reminder. This is something I want to do. It would be my first Python contribution.
History
Date User Action Args
2019-01-07 13:38:27jfine2358setmessages: + msg333148
2019-01-05 23:27:00cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg333082
2018-08-18 17:52:27jfine2358setmessages: + msg323723
2018-08-18 17:41:11berker.peksagsetresolution: not a bug ->
messages: + msg323722
stage: needs patch
2018-08-18 17:15:27jfine2358setstatus: pending -> open

messages: + msg323720
2018-08-18 16:49:19berker.peksagsetstatus: open -> pending

type: behavior
versions: - Python 3.4, Python 3.5
nosy: + berker.peksag

messages: + msg323717
resolution: not a bug
2018-08-18 16:03:19jfine2358create