Docs does not mention that eval() allows a code object as an argument

[jfine2358]

BPO	34431
Nosy	@berkerpeksag, @csabella, @jfine2358, @furkanonder
PRs	gh-78612: Docs does not eval allows code object as argument #20000

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = None
closed_at = None
created_at = <Date 2018-08-18.16:03:19.804>
labels = ['3.8', 'type-bug', '3.7', 'docs']
title = 'Docs does not eval allows code object as argument'
updated_at = <Date 2020-05-17.20:03:25.956>
user = 'https://github.com/jfine2358'

bugs.python.org fields:

activity = <Date 2020-05-17.20:03:25.956>
actor = 'furkanonder'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2018-08-18.16:03:19.804>
creator = 'jfine2358'
dependencies = []
files = []
hgrepos = []
issue_num = 34431
keywords = ['patch']
message_count = 8.0
messages = ['323716', '323717', '323720', '323722', '323723', '333082', '333148', '369152']
nosy_count = 5.0
nosy_names = ['docs@python', 'berker.peksag', 'cheryl.sabella', 'jfine2358', 'furkanonder']
pr_nums = ['20000']
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue34431'
versions = ['Python 2.7', 'Python 3.6', 'Python 3.7', 'Python 3.8']

Linked PRs

• gh-78612: Mark up eval() using param list #115212
• [3.12] gh-78612: Mark up eval() using param list (GH-115212) #116044
• [3.11] gh-78612: Mark up eval() using param list (GH-115212) #116045

[jfine2358]

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

#66255 (The doc say all globals are copied on eval(), but only __builtins__ is copied)
#69996 (Python 3 documentation for eval is incorrect)

[berkerpeksag]

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.

[jfine2358]

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 bpo-22057, bpo-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'.

[berkerpeksag]

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/

#66255 and #69996 are out of scope for this issue, so let's not discuss them here.

[jfine2358]

OK. I'll do as you say. I've just signed the CLA.

[csabella]

Hi Jonathan,

Did you have any additional questions about opening a pull request for these changes? Thanks!

[jfine2358]

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.

[furkanonder]

Hi Jonathan,
Are you still planning to work on the patch?