Repository navigation
Python 3 documentation for eval is incorrect #69996
Description
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 = <Date 2021-12-01.10:15:35.374>
created_at = <Date 2015-12-05.20:13:23.131>
labels = ['3.8', 'type-feature', '3.7', '3.9', 'docs']
title = 'Python 3 documentation for eval is incorrect'
updated_at = <Date 2021-12-01.10:15:35.370>
user = 'https://github.com/aroberge'bugs.python.org fields:
activity = <Date 2021-12-01.10:15:35.370>
actor = 'iritkatriel'
assignee = 'docs@python'
closed = True
closed_date = <Date 2021-12-01.10:15:35.374>
closer = 'iritkatriel'
components = ['Documentation']
creation = <Date 2015-12-05.20:13:23.131>
creator = 'aroberge'
dependencies = []
files = []
hgrepos = []
issue_num = 25810
keywords = ['patch']
message_count = 16.0
messages = ['255969', '255970', '255972', '255973', '255975', '255976', '255977', '255982', '255989', '255992', '256022', '340919', '351799', '351812', '351814', '407436']
nosy_count = 13.0
nosy_names = ['gregory.p.smith', 'larry', 'aroberge', 'ezio.melotti', 'r.david.murray', 'SilentGhost', 'docs@python', 'berker.peksag', 'martin.panter', 'random832', 'cheryl.sabella', 'miss-islington', 'iritkatriel']
pr_nums = ['15173', '15910', '15911']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue25810'
versions = ['Python 3.5', 'Python 3.6', 'Python 3.7', 'Python 3.8', 'Python 3.9']
Activity
aroberge commentedon Dec 5, 2015
The documentation for eval() indicates that it takes keyword arguments:
However, that is incorrect, as indicated by the builtin help:
SilentGhost commentedon Dec 5, 2015
I think this is the case where hard-coded strings where not updated in the C files.
random832 commentedon Dec 5, 2015
Whatever the case may be, it *doesn't* support keyword arguments. e.g.:
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.
random832 commentedon Dec 5, 2015
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).
SilentGhost commentedon Dec 5, 2015
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.
random832 commentedon Dec 5, 2015
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?
SilentGhost commentedon Dec 5, 2015
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?
vadmium commentedon Dec 5, 2015
See bpo-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 bpo-21314 about explaining the slash notation used by Argument Clinic and pydoc.
random832 commentedon Dec 5, 2015
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?
vadmium commentedon Dec 5, 2015
See bpo-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?
bitdancer commentedon Dec 6, 2015
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.
csabella commentedon Apr 26, 2019
See also PEP-570 and bpo-36540.
gpshead commentedon Sep 11, 2019
New changeset 7a0023e by Gregory P. Smith (smokephil) in branch 'master':
bpo-25810: Clarify eval() docs, it does not keywords (GH-15173)
7a0023e
miss-islington commentedon Sep 11, 2019
New changeset 4e914ab by Miss Islington (bot) in branch '3.8':
bpo-25810: Clarify eval() docs, it does not keywords (GH-15173)
4e914ab
miss-islington commentedon Sep 11, 2019
New changeset d378fdb by Miss Islington (bot) in branch '3.7':
bpo-25810: Clarify eval() docs, it does not keywords (GH-15173)
d378fdb
iritkatriel commentedon Dec 1, 2021
Help is now showing
with the / that indicates the args are positional only. The docs were updated here to state that the args are positional.