classification
Title: Python 3 documentation for eval is incorrect
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.9, Python 3.8, Python 3.7, Python 3.6, Python 3.5
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: SilentGhost, aroberge, berker.peksag, cheryl.sabella, docs@python, ezio.melotti, gregory.p.smith, larry, martin.panter, miss-islington, r.david.murray, random832
Priority: normal Keywords: patch

Created on 2015-12-05 20:13 by aroberge, last changed 2019-09-11 10:55 by miss-islington.

Pull Requests
URL Status Linked Edit
PR 15173 closed python-dev, 2019-08-08 07:06
PR 15910 merged miss-islington, 2019-09-11 10:30
PR 15911 merged miss-islington, 2019-09-11 10:30
Messages (15)
msg255969 - (view) Author: Andre Roberge (aroberge) * Date: 2015-12-05 20:13
The documentation for eval() indicates that it takes keyword arguments:

eval(expression, globals=None, locals=None)

However, that is incorrect, as indicated by the builtin help:

>>> help(eval)
Help on built-in function eval in module builtins:

eval(...)
    eval(source[, globals[, locals]]) -> value
msg255970 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2015-12-05 20:25
I think this is the case where hard-coded strings where not updated in the C files.
msg255972 - (view) Author: (random832) Date: 2015-12-05 20:35
Whatever the case may be, it *doesn't* support keyword arguments. e.g.:

>>> eval("a+b", globals={'a':1}, locals={'b':2})
TypeError: eval() takes no keyword arguments

So as the current situation stands, the documentation is wrong, and the help string is consistent with the code's actual behavior. Confirmed in Python 3.5.0.
msg255973 - (view) Author: (random832) Date: 2015-12-05 20:39
Oh, I just noticed, the help string is also wrong in 3.5 (which explains why you removed 3.5 from the versions list, which I hadn't noticed until after posting my previous comment).
msg255975 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2015-12-05 20:48
Yes, whatever Andre's posted is not an output from 3.5. It's 3.4 or earlier.

Also it's a wider problem because the same issue exists for exec: built-in help shows keyword arguments, while docs and implementation require only positional.
msg255976 - (view) Author: (random832) Date: 2015-12-05 20:56
I guess the next question is what the intent is. Was there an intent, which was not followed through on, to upgrade these methods to support keyword arguments? Or is there an intent (here and everywhere) that documentation using keyword argument syntax is appropriate to use to document methods that have default values but do not in fact support keyword arguments? What does the "/" in the help text mean?

According to PEP 0436 (Argument Clinic), the "/" here indicates that the preceding parameters are positional-only, despite the apparent use of keyword syntax. Should this convention also be used in the documentation?
msg255977 - (view) Author: SilentGhost (SilentGhost) * (Python triager) Date: 2015-12-05 21:00
I'm not sure how the people are supposed to discover this convention according to pep 436. Or is this now intended as two separate incompatible conventions for online docs and built-in help?
msg255982 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-12-05 21:52
See Issue 23738 where my current patch proposes using the PEP 457 slash (/) notation in the RST documentation, including for eval(). I’m not sure if there is a clear concensus for applying my patch however. An alternative would be to use the square-bracket notation, and explain in the text that the default values are None.

See also Issue 21314 about explaining the slash notation used by Argument Clinic and pydoc.
msg255989 - (view) Author: (random832) Date: 2015-12-05 23:03
What about fixing all methods so that they can take keywords? Are the functions with their current C signatures part of the stable ABI? Is there somewhere we could centrally add some magic "convert tuple+keywords to tuple, given list of names" code?
msg255992 - (view) Author: Martin Panter (martin.panter) * (Python committer) Date: 2015-12-05 23:21
See Issue 8706 about changing functions and methods to accept keyword arguments. But this cannot be done in general. What would you call the first argument to dict() such that all possible keyword arguments still work? What is the first range() argument called: start or stop?
msg256022 - (view) Author: R. David Murray (r.david.murray) * (Python committer) Date: 2015-12-06 18:42
As I recall it, in the python2 docs we used the [... notation, sometimes even when the actual arguments were or accepted keywords.  In the python3 docs we converted to always using keyword notation...and then realized that that also caused confusion, in the other direction.  Some things we converted back to [... notation.  Then argument clinic came along, and we kind of postponed worrying about it until we converted as much as practical to argument clinic.

I think we are moving toward using (and documenting in the main docs) the / notation.  Especially since it shows up in the inspect module as well as the docstring help.

Martin, if you don't think you have consensus on your patch, perhaps it is time to ping python-dev.
msg340919 - (view) Author: Cheryl Sabella (cheryl.sabella) * (Python committer) Date: 2019-04-26 14:19
See also PEP570 and issue 36540.
msg351799 - (view) Author: Gregory P. Smith (gregory.p.smith) * (Python committer) Date: 2019-09-11 10:30
New changeset 7a0023e8d17566eb32c836b65c33663303a2224f by Gregory P. Smith (smokephil) in branch 'master':
bpo-25810: Clarify eval() docs, it does not keywords (GH-15173)
https://github.com/python/cpython/commit/7a0023e8d17566eb32c836b65c33663303a2224f
msg351812 - (view) Author: miss-islington (miss-islington) Date: 2019-09-11 10:53
New changeset 4e914ab29f6d48a9fd045ea6a25dbf9e2fb603f9 by Miss Islington (bot) in branch '3.8':
bpo-25810: Clarify eval() docs, it does not keywords (GH-15173)
https://github.com/python/cpython/commit/4e914ab29f6d48a9fd045ea6a25dbf9e2fb603f9
msg351814 - (view) Author: miss-islington (miss-islington) Date: 2019-09-11 10:55
New changeset d378fdb10a5476b86b5a01d74c1bcc4e2f52e003 by Miss Islington (bot) in branch '3.7':
bpo-25810: Clarify eval() docs, it does not keywords (GH-15173)
https://github.com/python/cpython/commit/d378fdb10a5476b86b5a01d74c1bcc4e2f52e003
History
Date User Action Args
2019-09-11 10:55:32miss-islingtonsetmessages: + msg351814
2019-09-11 10:53:19miss-islingtonsetnosy: + miss-islington
messages: + msg351812
2019-09-11 10:30:21miss-islingtonsetpull_requests: + pull_request15552
2019-09-11 10:30:15miss-islingtonsetpull_requests: + pull_request15551
2019-09-11 10:30:08gregory.p.smithsetnosy: + gregory.p.smith
messages: + msg351799
2019-08-08 07:06:55python-devsetkeywords: + patch
stage: needs patch -> patch review
pull_requests: + pull_request14905
2019-08-08 06:45:48smokephilsetversions: + Python 3.8, Python 3.9
2019-08-08 06:45:17smokephilsetversions: + Python 3.7
2019-04-26 14:19:02cheryl.sabellasetnosy: + cheryl.sabella
messages: + msg340919
2018-08-19 11:20:42berker.peksagsetnosy: + berker.peksag
2016-01-04 03:55:57ezio.melottisetnosy: + ezio.melotti

type: enhancement
versions: - Python 3.4
2015-12-06 18:42:46r.david.murraysetnosy: + r.david.murray
messages: + msg256022
2015-12-05 23:27:17martin.panterlinkissue23738 dependencies
2015-12-05 23:21:59martin.pantersetmessages: + msg255992
2015-12-05 23:03:46random832setmessages: + msg255989
2015-12-05 21:52:58martin.pantersetnosy: + martin.panter

messages: + msg255982
versions: - Python 3.2, Python 3.3
2015-12-05 21:01:18SilentGhostsetnosy: + larry
2015-12-05 21:00:05SilentGhostsetmessages: + msg255977
2015-12-05 20:56:29random832setmessages: + msg255976
2015-12-05 20:48:22SilentGhostsetmessages: + msg255975
versions: + Python 3.6
2015-12-05 20:39:41random832setmessages: + msg255973
2015-12-05 20:35:39random832setnosy: + random832

messages: + msg255972
versions: + Python 3.5
2015-12-05 20:29:56SilentGhostsetstage: needs patch
2015-12-05 20:25:44SilentGhostsetnosy: + SilentGhost

messages: + msg255970
versions: - Python 3.5, Python 3.6
2015-12-05 20:13:23arobergecreate