Skip to content

bpo-43605: Improve the documentation to exec() and eval() #25039

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
wants to merge 3 commits into
base: main
Choose a base branch
from
Open

bpo-43605: Improve the documentation to exec() and eval() #25039

Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
ecd5e7b
bpo-43605: Improve the documentation to exec() and eval()
congma Mar 27, 2021
4ffc9cd
Further revise eval/exec documentations for consistency and accuracy.
congma Mar 29, 2021
6504b9c
Fix invalid RST syntax.
congma Mar 29, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
158 changes: 88 additions & 70 deletions Doc/library/functions.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -496,44 +496,41 @@ are always available. They are listed here in alphabetical order.

.. function:: eval(expression[, globals[, locals]])

The arguments are a string and optional globals and locals. If provided,
*globals* must be a dictionary. If provided, *locals* can be any mapping
object.

The *expression* argument is parsed and evaluated as a Python expression
(technically speaking, a condition list) using the *globals* and *locals*
dictionaries as global and local namespace. If the *globals* dictionary is
present and does not contain a value for the key ``__builtins__``, a
reference to the dictionary of the built-in module :mod:`builtins` is
inserted under that key before *expression* is parsed. That way you can
control what builtins are available to the executed code by inserting your
own ``__builtins__`` dictionary into *globals* before passing it to
:func:`eval`. If the *locals* dictionary is omitted it defaults to the
*globals* dictionary. If both dictionaries are omitted, the expression is
executed with the *globals* and *locals* in the environment where
:func:`eval` is called. Note, *eval()* does not have access to the
:term:`nested scopes <nested scope>` (non-locals) in the enclosing
environment.

The return value is the result of
the evaluated expression. Syntax errors are reported as exceptions. Example:
This function supports the dynamic evaluation of Python expressions. The
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
This function supports the dynamic evaluation of Python expressions. The
This function dynamically evaluates Python expressions. The

first argument can be a string or a code object. The optional arguments
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe link this to the documentation for code objects.

specify the global and local namespaces respectively. If provided,
*globals* must be a dictionary. If provided, *locals* can be any
:term:`mapping` object.

In the most common case, the *expression* argument is a string, and it is
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
In the most common case, the *expression* argument is a string, and it is
When the *expression* argument is a string, it is

Tighten the wording

parsed and evaluated as a Python expression (see the section
":ref:`expression-input`" in the Language Reference). The leading and
trailing spaces, tabs, and newlines are stripped.

The evaluation is performed in the environment specified by the arguments
*globals* and *locals*. If both are omitted, by default it uses the
environment where :func:`eval` is called. If only the *globals* argument is
given, the local namespace defaults to *globals*.

Before evaluation, the special key ``"__builtins__"`` is searched for in the
global namespace that is explicitly or impcitly specified for :func:`eval`.
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
global namespace that is explicitly or impcitly specified for :func:`eval`.
global namespace that is explicitly or implicitly specified.

If this key is not present, by default a reference to the dictionary of the
built-in module :mod:`builtins` is inserted *in-place* under that key, so
that built-in identifiers resolve to their usual built-in implementations.
By overriding the value for the key ``"__builtins__"`` in *globals*, you
can control what builtins are available to the expression being evaluated.

The return value is the result of the evaluated expression. Syntax errors
are reported as exceptions. For example:

>>> x = 1
>>> eval('x+1')
2

This function can also be used to execute arbitrary code objects (such as
those created by :func:`compile`). In this case pass a code object instead
of a string. If the code object has been compiled with ``'exec'`` as the
*mode* argument, :func:`eval`\'s return value will be ``None``.

Hints: dynamic execution of statements is supported by the :func:`exec`
function. The :func:`globals` and :func:`locals` functions
returns the current global and local dictionary, respectively, which may be
useful to pass around for use by :func:`eval` or :func:`exec`.

If the given source is a string, then leading and trailing spaces and tabs
are stripped.
The :func:`eval` function can also be used to execute code objects, such as
those created by :func:`compile`. In this case, pass a code object instead
of a string as the first argument. If the code object has been compiled
with ``'exec'`` as the *mode* argument, the return value will be ``None``.

See :func:`ast.literal_eval` for a function that can safely evaluate strings
with expressions containing only literals.
Expand All @@ -543,36 +540,60 @@ are always available. They are listed here in alphabetical order.
Raises an :ref:`auditing event <auditing>` ``exec`` with the code object
as the argument. Code compilation events may also be raised.

.. _eval_limitation_dynamic:
.. note::

Dynamic evaluation at run-time is not equivalent to embedding the
expression at the same place in a Python program and having it compiled
as a part of the whole program; this is explained in the section
":ref:`dynamic-features`" in the Language Reference.

In particular, :func:`eval` does not have access to the :term:`nested
scopes <nested scope>` (non-locals) in the enclosing environment. Of
note are expressions such as :term:`lambdas <lambda>`,
:ref:`comprehensions <comprehensions>`, and :term:`generator expressions
<generator expression>` which create an inner scope of their own. Since
Python 3.8, the action of an assignment expression (see :pep:`572`) also
depends on scope information determined at compile-time. Interaction
Copy link
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Suggested change
depends on scope information determined at compile-time. Interaction
depends on scope information determined at compile time. Interaction

between these expressions and :func:`eval` can be explicitly controlled
by the arguments *globals* and *locals* in the aforementioned manner.

The built-in functions :func:`globals` and :func:`locals` return the
current global and local dictionaries respectively, which may be useful
for constructing namespaces passed as the second and third arguments to
:func:`eval`.

Dynamic execution of *statements* is supported by the :func:`exec`
function (see below).


.. index:: builtin: exec

.. function:: exec(object[, globals[, locals]])

This function supports dynamic execution of Python code. *object* must be
either a string or a code object. If it is a string, the string is parsed as
a suite of Python statements which is then executed (unless a syntax error
occurs). [#]_ If it is a code object, it is simply executed. In all cases,
the code that's executed is expected to be valid as file input (see the
section "File input" in the Reference Manual). Be aware that the
:keyword:`nonlocal`, :keyword:`yield`, and :keyword:`return`
statements may not be used outside of
function definitions even within the context of code passed to the
:func:`exec` function. The return value is ``None``.

In all cases, if the optional parts are omitted, the code is executed in the
current scope. If only *globals* is provided, it must be a dictionary
(and not a subclass of dictionary), which
will be used for both the global and the local variables. If *globals* and
*locals* are given, they are used for the global and local variables,
respectively. If provided, *locals* can be any mapping object. Remember
that at module level, globals and locals are the same dictionary. If exec
gets two separate objects as *globals* and *locals*, the code will be
executed as if it were embedded in a class definition.

If the *globals* dictionary does not contain a value for the key
``__builtins__``, a reference to the dictionary of the built-in module
:mod:`builtins` is inserted under that key. That way you can control what
builtins are available to the executed code by inserting your own
``__builtins__`` dictionary into *globals* before passing it to :func:`exec`.
This function supports the dynamic execution of Python code. *object* must
be either a string or a code object. If it is a string, the string is
parsed as a suite of Python statements which is then executed (unless a
syntax error occurs). If it is a code object, it is simply executed. In
all cases, the code being executed is expected to be valid as file input
(see the section ":ref:`file-input`" in the Language Reference). The return
value of :func:`exec` is ``None``.

If provided, *globals* must be a dictionary. If provided, *locals* can be
any mapping object.

The execution is performed in the environment specified by the arguments
*globals* and *locals*. If both are omitted, by default it uses the
environment where :func:`exec` is called. If only the *globals* argument is
given, the local namespace defaults to *globals*.

Before execution, the special key ``"__builtins__"`` is searched for in the
global namespace that is explicitly or impcitly specified for :func:`exec`.
If this key is not present, by default a reference to the dictionary of the
built-in module :mod:`builtins` is inserted *in-place* under that key, so
that built-in identifiers resolve to their usual built-in implementations.
By overriding the value for the key ``"__builtins__"`` in *globals*, you
can control what builtins are available to the code being executed.

.. audit-event:: exec code_object exec

Expand All @@ -581,16 +602,19 @@ are always available. They are listed here in alphabetical order.

.. note::

The built-in functions :func:`globals` and :func:`locals` return the current
global and local dictionary, respectively, which may be useful to pass around
for use as the second and third argument to :func:`exec`.
Like :func:`eval`, :func:`exec` is limited by constraints particular to
:ref:`dynamic code execution and namespaces <eval_limitation_dynamic>`.
The built-in functions :func:`globals` and :func:`locals` return the
current global and local dictionaries respectively, which may be useful
for constructing namespaces passed as the second and third arguments to
:func:`exec`.

.. note::

The default *locals* act as described for function :func:`locals` below:
modifications to the default *locals* dictionary should not be attempted.
Pass an explicit *locals* dictionary if you need to see effects of the
code on *locals* after function :func:`exec` returns.
You can explicitly pass a distinct *locals* dictionary to :func:`exec` to
observe the effects of executing the code on the local namespace.


.. function:: filter(function, iterable)
Expand Down Expand Up @@ -1955,9 +1979,3 @@ are always available. They are listed here in alphabetical order.
.. versionchanged:: 3.9
When the command line options :option:`-E` or :option:`-I` are being used,
the environment variable :envvar:`PYTHONCASEOK` is now ignored.

.. rubric:: Footnotes

.. [#] Note that the parser only accepts the Unix-style end of line convention.
If you are reading the code from a file, make sure to use newline conversion
mode to convert Windows or Mac-style newlines.