[docs] [issue34431] Docs does not eval allows code object as argument

[Jonathan Fine]

Jonathan Fine <jfine2358 at gmail.com> added the comment:

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'.

----------
status: pending -> open

_______________________________________
Python tracker <report at bugs.python.org>
<https://bugs.python.org/issue34431>
_______________________________________