@@ -514,44 +514,40 @@ are always available. They are listed here in alphabetical order.
514
514
515
515
.. function :: eval(expression, /, globals=None, locals=None)
516
516
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,
518
520
*globals * must be a dictionary. If provided, *locals * can be any mapping
519
521
object.
520
522
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.
535
539
536
540
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 :
538
542
539
543
>>> x = 1
540
544
>>> eval (' x+1' )
541
545
2
542
546
543
547
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 ``.
555
551
556
552
See :func: `ast.literal_eval ` for a function that can safely evaluate strings
557
553
with expressions containing only literals.
@@ -561,6 +557,29 @@ are always available. They are listed here in alphabetical order.
561
557
Raises an :ref: `auditing event <auditing >` ``exec `` with the code object
562
558
as the argument. Code compilation events may also be raised.
563
559
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
+
564
583
.. index :: builtin: exec
565
584
566
585
.. function :: exec(object, globals=None, locals=None, /, *, closure=None)
0 commit comments