bpo-43605: Improve the documentation to exec() and eval() by congma · Pull Request #25039 · python/cpython

- Add links to the relevant section in Language Reference about dynamic
  execution's limitation with respect to namespaces.
- For eval(), move some explanatory text into a "Note" box.
- Make the first paragraph of eval's doc consistent about what the first
  argument accepts.
- For exec(), remove the text about the "globals" optional argument
  having to be a dict but not an instance of a subclass of dict. This is
  no longer true -- the code calls PyDict_Check(), not
  PyDict_CheckExact().
- Put quotes around the ``__builtins__`` in the text: clarify that in
  the context it means a string key in the dict passed to eval/exec as
  the globals dict. Otherwise, since the identifier __builtins__ refers
  to a module, it can be confusing and misleading.
- Reordering some paragraphs so that overall the structure is improved.
- Re-wrap some long lines in RST source.

The documentations for eval/exec are further modified for consistency
and accuracy.

- For both functions, the documentation mostly follows the following
  structure: description of arguments, default values for optional
  arguments, special treatment of the "__builtins__" key, and notices
  about limitations or other noteworthy material. Previously, the
  description about the special "__builtins__" key is intermingled with
  the description about default values for missing arguments. Now, these
  are in separate paragraphs. Also, it is stressed that the special key
  is inserted in-place.
- In the notice about limitations to dynamic eval/exec w.r.t. scopes,
  also mention the assignment expression succinctly.
- Remove the description that exec() with both globals and locals behave
  "as if" the source string is embedded in a class block. Again, a class
  block inside a function can access the non-locals, but this is not
  available to exec().
- Instead of mentioning passing the return values of globals() and
  locals() around, we now say that the programmer can construct their
  own namespaces based on their return values. The reason is that
  currently the semantics of locals() is not very well defined, and in
  the light of PEP 558 it may change in the future.  Explicitly
  constructing new namespaces is more predictable than using the "raw"
  return value of locals(). In the future, this part of the docs can be
  further updated to keep up with the new definition of locals().
- Omit the footnote to exec() about the parser only accepting Unix-style
  LF newlines. This piece of information is outdated.
- Other small fixes for grammar.