According to the documentation of eval():

> If the globals dictionary is present and lacks '__builtins__', the current globals are copied into globals before expression is parsed.

However in practice only the __builtins__ items are copied, see:

http://hg.python.org/cpython/file/2.7/Python/bltinmodule.c#l655

See http://stackoverflow.com/q/24934908/242762

Thanks for noticing this.  Do you want to propose a patch?

Patch for 2.7.8.

The patch is just changing "globals are" to "mapping of ‘__builtins__’ is", and subsequent paragraph reformatting.

Patch for 3.5.x

The patch is just changing "globals are" to "mapping of ‘__builtins__’ is", and subsequent paragraph reformatting.

Nearly identical to 2.7.8 patch.

+1 for this patch, the current documentation states it very wrong.

The patch looks good (though it would have been easier to check the diff if the text had not be reflowed).

I will apply it when I get a chance.  Or if anyone else wants to grab it, go ahead.

“the current mapping of '__builtins__' is copied into *globals* ”

That sounds like we insert each individual builtin name, i.e. globals.update(builtins_mapping). But my understanding is that it is the __builtins__ global variable that is affected:

globals["__builtins__"] = builtins_mapping

What about borrowing the wording from exec():

If the *globals* dictionary is present and lacks ‘__builtins__’, a reference to the current mapping of ‘__builtins__’ is inserted under that key . . .

See also Issue 26363, which also covers this problem.

I like Martin's suggestion in msg282262 and I've just created PR 8812 to implement it.

New changeset 225b05548027d55aafb11b65f6a4a2bef2f5196f by Berker Peksag in branch 'master':
bpo-22057: Clarify eval() documentation (GH-8812)
https://github.com/python/cpython/commit/225b05548027d55aafb11b65f6a4a2bef2f5196f

New changeset 0e1e8dbb0b99ec78f4567382428fdd46e2244d40 by Miss Islington (bot) in branch '3.7':
bpo-22057: Clarify eval() documentation (GH-8812)
https://github.com/python/cpython/commit/0e1e8dbb0b99ec78f4567382428fdd46e2244d40

New changeset f19579b8f1fcd2dd8ffaf3e443b09930057c01d1 by Miss Islington (bot) in branch '3.6':
bpo-22057: Clarify eval() documentation (GH-8812)
https://github.com/python/cpython/commit/f19579b8f1fcd2dd8ffaf3e443b09930057c01d1

Thanks for the review, Martin, and thanks for the report, Alon!