Skip to content

Commit 76111ce

Browse files
committed
Improve documentation of eval()
1 parent a87c46e commit 76111ce

File tree

2 files changed

+48
-27
lines changed

2 files changed

+48
-27
lines changed

Doc/library/functions.rst

Lines changed: 46 additions & 27 deletions
Original file line numberDiff line numberDiff line change
@@ -514,44 +514,40 @@ are always available. They are listed here in alphabetical order.
514514

515515
.. function:: eval(expression, /, globals=None, locals=None)
516516

517-
The arguments are a string and optional globals and locals. If provided,
517+
This function dynamically evaluates Python expressions. The first argument can
518+
be a string or a :ref:`code object <datamodel-codeobjects>`. The optional
519+
arguments specify the global and local namespaces respectively. If provided,
518520
*globals* must be a dictionary. If provided, *locals* can be any mapping
519521
object.
520522

521-
The *expression* argument is parsed and evaluated as a Python expression
522-
(technically speaking, a condition list) using the *globals* and *locals*
523-
dictionaries as global and local namespace. If the *globals* dictionary is
524-
present and does not contain a value for the key ``__builtins__``, a
525-
reference to the dictionary of the built-in module :mod:`builtins` is
526-
inserted under that key before *expression* is parsed. That way you can
527-
control what builtins are available to the executed code by inserting your
528-
own ``__builtins__`` dictionary into *globals* before passing it to
529-
:func:`eval`. If the *locals* dictionary is omitted it defaults to the
530-
*globals* dictionary. If both dictionaries are omitted, the expression is
531-
executed with the *globals* and *locals* in the environment where
532-
:func:`eval` is called. Note, *eval()* does not have access to the
533-
:term:`nested scopes <nested scope>` (non-locals) in the enclosing
534-
environment.
523+
When the *expression* argument is a string, it is parsed and evaluated as a
524+
Python expression (see :ref:`expression-input`). The leading and trailing spaces,
525+
tabs, and newlines are stripped.
526+
527+
The evaluation is performed in the environment specified by the arguments
528+
*globals* and *locals*. If both are omitted, by default it uses the
529+
environment where :func:`eval` is called. If only the *globals* argument is
530+
provided, the local namespace defaults to *globals*.
531+
532+
Before evaluation, the special key ``"__builtins__"`` is searched for in the
533+
global namespace that is explicitly or implicitly specified.
534+
If this key is not present, a reference to the dictionary of the
535+
built-in module :mod:`builtins` is inserted *in-place* under that key, so
536+
that built-in identifiers resolve to their usual built-in implementations.
537+
By overriding the value for the key ``"__builtins__"`` in *globals*, you
538+
can control what builtins are available to the expression being evaluated.
535539

536540
The return value is the result of
537-
the evaluated expression. Syntax errors are reported as exceptions. Example:
541+
the evaluated expression. Syntax errors are reported as exceptions. For example:
538542

539543
>>> x = 1
540544
>>> eval('x+1')
541545
2
542546

543547
This function can also be used to execute arbitrary code objects (such as
544-
those created by :func:`compile`). In this case, pass a code object instead
545-
of a string. If the code object has been compiled with ``'exec'`` as the
546-
*mode* argument, :func:`eval`\'s return value will be ``None``.
547-
548-
Hints: dynamic execution of statements is supported by the :func:`exec`
549-
function. The :func:`globals` and :func:`locals` functions
550-
return the current global and local dictionary, respectively, which may be
551-
useful to pass around for use by :func:`eval` or :func:`exec`.
552-
553-
If the given source is a string, then leading and trailing spaces and tabs
554-
are stripped.
548+
those created by :func:`compile`). In this case, *expression* will be
549+
a code object instead of a string. If the code object has been compiled with
550+
``'exec'`` as the *mode* argument, the return value will be ``None``.
555551

556552
See :func:`ast.literal_eval` for a function that can safely evaluate strings
557553
with expressions containing only literals.
@@ -561,6 +557,29 @@ are always available. They are listed here in alphabetical order.
561557
Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
562558
as the argument. Code compilation events may also be raised.
563559

560+
.. note::
561+
562+
Dynamic evaluation at run-time is not equivalent to embedding the
563+
expression at the same place in a Python program and having it compiled
564+
as a part of the whole program; see :ref:`dynamic-features` for details.
565+
566+
In particular, :func:`eval` does not have access to the :term:`nested
567+
scopes <nested scope>` (non-locals) in the enclosing environment. Of
568+
note are expressions such as :term:`lambdas <lambda>`,
569+
:ref:`comprehensions <comprehensions>`, and :term:`generator expressions
570+
<generator expression>`, which create an inner scope of their own.
571+
The action of an assignment expression (see :pep:`572`) also
572+
depends on scope information determined at compile-time.
573+
574+
Interaction between these expressions and :func:`eval` can be explicitly
575+
controlled by the arguments *globals* and *locals* in the aforementioned manner.
576+
The built-in functions :func:`globals` and :func:`locals` return the
577+
current global and local dictionaries respectively, which may be useful
578+
for constructing namespaces for these arguments.
579+
580+
Dynamic execution of *statements* is supported by the :func:`exec`
581+
function (see below).
582+
564583
.. index:: builtin: exec
565584

566585
.. function:: exec(object, globals=None, locals=None, /, *, closure=None)

Doc/reference/datamodel.rst

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -943,6 +943,8 @@ Internal types
943943

944944
.. index:: bytecode, object; code, code object
945945

946+
.. _datamodel-codeobjects:
947+
946948
Code objects
947949
Code objects represent *byte-compiled* executable Python code, or :term:`bytecode`.
948950
The difference between a code object and a function object is that the function

0 commit comments

Comments
 (0)