eval() documentation is wrong about keyword arguments

[wjandrea]

Documentation

The docs for eval() say it takes keyword arguments, which is incorrect:

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

For example:

>>> eval('a', locals={'a': 0})
  ...
TypeError: eval() takes no keyword arguments

Meanwhile, help(eval) has the correct signature:

eval(source, globals=None, locals=None, /)

I found a previous, similar issue, #69996, which was resolved in #15173 (which shipped in 3.7) but then the syntax was changed in #96579 and the same sort of mistake was added back (which shipped in 3.11).

This issue is also similar:

• Clarify documentation of positional-only default values #67926

Linked PRs

• gh-100546: Remove incorrect positional-only marker from eval #100547
• [3.11] gh-100546: Remove incorrect positional-only marker from eval (GH-100547) #100654

[hauntsaninja]

Thanks for the report!

cc @JulienPalard the history here is confusing, would you mind posting on #98340 what the current state of using positional-only (and keyword-only) markers in docs is? I still see four positional-only markers in functions.rst (though only eval's seems to be in the wrong place)

[slateny]

There are some comments by Raymond on #100444, so one possible guideline for markers is the same for spelling/stylistic rules, where it just needs to be consistent per module instead of for all modules.

That said, I think it'd nonetheless be useful to have a deeper discussion on this for consistency and properly documenting default values, whether it be via markers, or [], or otherwise.