classification
Title: Improve documentation of exec
Type: enhancement Stage: patch review
Components: Documentation Versions: Python 3.2, Python 3.3, Python 3.4, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder: exec of list comprehension fails on NameError
View: 13557
Assigned To: terry.reedy Nosy List: docs@python, ezio.melotti, jstadler, mark.dickinson, ncoghlan, r.david.murray, terry.reedy
Priority: normal Keywords: patch

Created on 2010-05-26 17:36 by terry.reedy, last changed 2012-11-25 18:51 by mark.dickinson.

Files
File name Uploaded Description Edit
exec_doc_touchup_3.x.patch jstadler, 2011-05-12 15:44 Documentation update for the use of exec in 3.x, more information about scope. -- no more 'in' review
exec_doc_touchup_2.x.patch jstadler, 2011-05-12 16:00 Documentation update for exec statement for 2.x, more information about scope. -- ``in`` instead of :keyword:`in` review
Messages (9)
msg106552 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-05-26 17:36
This doc improvement suggestion is inspired by #991196 (and subsequent duplicates) and the current discussion on py-dev in the thread
  'variable name resolution in exec is incorrect'
(which is not a correct claim). I believe there is consensus that the doc for exec needs improving.

My suggestion (which others may amend) is that the following paragraph (from the 3.x builtin functions exec entry)

"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, 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."

have these two sentences added:

"If only globals is provided or if onedict is provided as both globals and locals, the code is executed in a new top-level scope. If different objects are given as globals and locals, the code is executed as if it were in a class statement in a new top-level scope."
msg106555 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2010-05-26 17:52
To be super-clear, consider adding one more sentence, something like

"The result for code with def statements or lambda expressions may be different than it would be if the implied context were a function rather than a class."
msg135730 - (view) Author: Jordan Stadler (jstadler) Date: 2011-05-10 19:23
I'm going to update the documentation to include the scope information. Should be done within a day.
msg135746 - (view) Author: Jordan Stadler (jstadler) Date: 2011-05-10 22:02
Patches for 2.x and 3.x documentation related to 'exec'.

2.x
  Provides more information about scopes when using additional expressions
  for 'exec'. 2.x documentation for 'exec' is found in
  reference/simple_stmts.
3.x
  Provides more information about scopes when using additional expressions
  for 'exec'.  3.x documentation for 'exec' is found in library/functions.
msg135820 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2011-05-12 05:51
In 3.x exec is a function, so the reference to 'in' should be removed/updated.  On 2.x it might be better to just use ``in`` instead of :keyword:`in`, because the latter probably links to the 'in' operator that checks for containment.
msg135843 - (view) Author: Jordan Stadler (jstadler) Date: 2011-05-12 16:04
I've updated the 3.x patch, should be correct now.

I also updated the 2.x patch to use ``in``. :keyword:`in` was used in an earlier part of the paragraph I modified, so I have changed both for consistency.

This is the paragraph before modification:
"
  In all cases, if the optional parts are omitted, the code is executed in the
  current scope.  If only the first expression after :keyword:`in` is specified,
  it should be a dictionary, which will be used for both the global and the local
  variables.  If two expressions are given, they are used for the global and local
  variables, respectively. If provided, *locals* can be any mapping object.
"
msg176340 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2012-11-25 11:20
Should this be closed as a duplicate of issue #13557?
msg176383 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2012-11-25 18:50
I suggested more change here than I committed in #13557. I would like to think about the extra a bit more. The issue about def in exec just came up again on python-list, but I do not really like the third sentence I suggested.
msg176384 - (view) Author: Mark Dickinson (mark.dickinson) * (Python committer) Date: 2012-11-25 18:51
Okay;  sorry about that.  Reopening.
History
Date User Action Args
2012-11-25 18:51:54mark.dickinsonsetstatus: closed -> open
resolution: duplicate ->
messages: + msg176384
2012-11-25 18:50:36terry.reedysetassignee: docs@python -> terry.reedy
messages: + msg176383
2012-11-25 18:03:32mark.dickinsonsetstatus: open -> closed
superseder: exec of list comprehension fails on NameError
resolution: duplicate
2012-11-25 11:20:16mark.dickinsonsetmessages: + msg176340
2012-11-08 08:36:48ezio.melottisetnosy: + mark.dickinson

type: enhancement
versions: + Python 3.4, - Python 3.1
2011-05-12 16:04:56jstadlersetfiles: - exec_doc_touchup_2_x.patch
2011-05-12 16:04:30jstadlersetmessages: + msg135843
2011-05-12 16:00:38jstadlersetfiles: + exec_doc_touchup_2.x.patch
2011-05-12 15:44:34jstadlersetfiles: + exec_doc_touchup_3.x.patch
2011-05-12 15:44:20jstadlersetfiles: - exec_doc_touchup_3_x.patch
2011-05-12 05:51:47ezio.melottisetversions: + Python 3.3, - Python 2.6
nosy: + ezio.melotti

messages: + msg135820

stage: patch review
2011-05-11 02:38:36r.david.murraysetnosy: + r.david.murray
2011-05-10 22:02:29jstadlersetmessages: + msg135746
2011-05-10 21:55:59jstadlersetfiles: + exec_doc_touchup_3_x.patch
2011-05-10 21:55:12jstadlersetfiles: + exec_doc_touchup_2_x.patch
keywords: + patch
2011-05-10 19:23:22jstadlersetnosy: + jstadler
messages: + msg135730
2010-05-27 00:05:32ncoghlansetnosy: + ncoghlan
2010-05-26 17:52:44terry.reedysetmessages: + msg106555
2010-05-26 17:36:46terry.reedycreate