diff options
Diffstat (limited to 'Doc/ref')
| -rw-r--r-- | Doc/ref/ref4.tex | 279 | ||||
| -rw-r--r-- | Doc/ref/refa1.tex | 112 |
2 files changed, 134 insertions, 257 deletions
diff --git a/Doc/ref/ref4.tex b/Doc/ref/ref4.tex index 2272f3e..e2bfcca 100644 --- a/Doc/ref/ref4.tex +++ b/Doc/ref/ref4.tex @@ -2,166 +2,147 @@ \index{execution model} -\section{Code blocks, execution frames, and namespaces \label{execframes}} -\index{code block} +\section{Naming and binding \label{naming}} +\indexii{code}{block} \index{namespace} -\indexii{execution}{frame} - -A \dfn{code block}\indexii{code}{block} is a piece -of Python program text that can be executed as a unit, such as a -module, a class definition or a function body. Some code blocks (like -modules) are normally executed only once, others (like function -bodies) may be executed many times. Code blocks may textually contain -other code blocks. Code blocks may invoke other code blocks (that may -or may not be textually contained in them) as part of their execution, -e.g., by invoking (calling) a function. - -The following are code blocks: A module is a code block. A function -body is a code block. A class definition is a code block. Each -command typed interactively is a separate code block; a script file (a -file given as standard input to the interpreter or specified on the -interpreter command line the first argument) is a code block; a script -command (a command specified on the interpreter command line with the -`\strong{-c}' option) is a code block. The file read by the built-in -function \function{execfile()} is a code block. The string argument -passed to the built-in function \function{eval()} and to the -\keyword{exec} statement is a code block. And finally, the expression -read and evaluated by the built-in function \function{input()} is a -code block. - -A code block is executed in an execution frame. An \dfn{execution -frame}\indexii{execution}{frame} contains some administrative -information (used for debugging), determines where and how execution -continues after the code block's execution has completed, and (perhaps -most importantly) defines two namespaces, the local and the global -namespace, that affect execution of the code block. - -A \dfn{namespace}\index{namespace} is a mapping from names -(identifiers) to objects. A particular namespace may be referenced by -more than one execution frame, and from other places as well. Adding -a name to a namespace is called \dfn{binding}\indexii{binding}{name} a -name (to an object); changing the mapping of a name is called -\dfn{rebinding}\indexii{rebinding}{name}; removing a name is -\dfn{unbinding}\indexii{unbinding}{name}. Namespaces are functionally -equivalent to dictionaries (and often implemented as dictionaries). - -The \dfn{local namespace}\indexii{local}{namespace} of an execution -frame determines the default place where names are defined and -searched. The -\dfn{global namespace}\indexii{global}{namespace} determines the place -where names listed in \keyword{global}\stindex{global} statements are -defined and searched, and where names that are not bound anywhere in -the current code block are searched. - -Whether a name is local or global in a code block is determined by -static inspection of the source text for the code block: in the -absence of \keyword{global} statements, a name that is bound anywhere -in the code block is local in the entire code block; all other names -are considered global. The \keyword{global} statement forces global -interpretation of selected names throughout the code block. The -following constructs bind names: formal parameters to functions, +\index{scope} + +\dfn{Names}\index{name} refer to objects. Names are introduced by +name binding operations. Each occurrence of a name in the program +text refers to the \dfn{binding}\indexii{binding}{name} of that name +established in the innermost function block containing the use. + +A \dfn{block}\index{block} is a piece of Python program text that is +executed as a unit. The following are blocks: a module, a function +body, and a class definition. Each command typed interactively is a +block. A script file (a file given as standard input to the +interpreter or specified on the interpreter command line the first +argument) is a code block. A script command (a command specified on +the interpreter command line with the `\strong{-c}' option) is a code +block. The file read by the built-in function \function{execfile()} +is a code block. The string argument passed to the built-in function +\function{eval()} and to the \keyword{exec} statement is a code block. +The expression read and evaluated by the built-in function +\function{input()} is a code block. + +A \dfn{scope}\index{scope} defines the visibility of a name within a +block. If a local variable is defined in a block, it's scope includes +that block. If the definition occurs in a function block, the scope +extends to any blocks contained within the defining one, unless a +contained block introduces a different binding for the name. The +scope of names defined in a class block is limited to the class block; +it does not extend to the code blocks of methods. + +When a name is used in a code block, it is resolved using the nearest +enclosing scope. The set of all such scopes visible to a code block +is called the block's \dfn{environment}\index{environment}. + +If a name is bound in a block, it is a local variable of that block. +If a name is bound at the module level, it is a global variable. (The +variables of the module code block are local and global.) If a +variable is used in a code block but not defined there, it is a +\dfn{free variable}\indexii{free}{variable}. + +When a name is not found at all, a +\exception{NameError}\withsubitem{(built-in +exception)}{\ttindex{NameError}} exception is raised. If the name +refers to a local variable that has not been bound, a +\exception{UnboundLocalError}\ttindex{UnboundLocalError} exception is +raised. \exception{UnboundLocalError} is a subclass of +\exception{NameError}. + +The following constructs bind names: formal parameters to functions, \keyword{import} statements, class and function definitions (these bind the class or function name in the defining block), and targets that are identifiers if occurring in an assignment, \keyword{for} loop header, or in the second position of an \keyword{except} clause -header. Local names are searched only on the local namespace; global -names are searched only in the global and built-in -namespace.\footnote{ - If the code block contains \keyword{exec} statements or the - construct ``\samp{from \ldots import *}'', the semantics of local - names change: local name lookup first searches the local namespace, - then the global namespace and the built-in namespace.} +header. The \keyword{import} statement of the form ``\samp{from +\ldots import *}''\stindex{from} binds all names defined in the +imported module, except those beginning with an underscore. This form +may only be used at the module level. A target occurring in a \keyword{del} statement is also considered bound -for this purpose (though the actual semantics are to ``unbind'' the -name). - -When a global name is not found in the global namespace, it is -searched in the built-in namespace (which is actually the global -namespace of the module -\module{__builtin__}\refbimodindex{__builtin__}). The built-in -namespace associated with the execution of a code block is actually -found by looking up the name \code{__builtins__} in its global -namespace; this should be a dictionary or a module (in the latter case -its dictionary is used). Normally, the \code{__builtins__} namespace -is the dictionary of the built-in module \module{__builtin__} (note: -no `s'); if it isn't, restricted -execution\indexii{restricted}{execution} mode is in effect. When a -name is not found at all, a -\exception{NameError}\withsubitem{(built-in -exception)}{\ttindex{NameError}} exception is raised. -\stindex{from} -\stindex{exec} -\stindex{global} - -The following table lists the meaning of the local and global -namespace for various types of code blocks. The namespace for a -particular module is automatically created when the module is first -imported (i.e., when it is loaded). Note that in almost all cases, -the global namespace is the namespace of the containing module --- -scopes in Python do not nest! - -\begin{tableiv}{l|l|l|l}{textrm} - {Code block type}{Global namespace}{Local namespace}{Notes} - \lineiv{Module} - {n.s. for this module} - {same as global}{} - \lineiv{Script (file or command)} - {n.s. for \module{__main__}\refbimodindex{__main__}} - {same as global}{(1)} - \lineiv{Interactive command} - {n.s. for \module{__main__}\refbimodindex{__main__}} - {same as global}{} - \lineiv{Class definition} - {global n.s. of containing block} - {new n.s.}{} - \lineiv{Function body} - {global n.s. of containing block} - {new n.s.}{(2)} - \lineiv{String passed to \keyword{exec} statement} - {global n.s. of containing block} - {local n.s. of containing block}{(2), (3)} - \lineiv{String passed to \function{eval()}} - {global n.s. of caller} - {local n.s. of caller}{(2), (3)} - \lineiv{File read by \function{execfile()}} - {global n.s. of caller} - {local n.s. of caller}{(2), (3)} - \lineiv{Expression read by \function{input()}} - {global n.s. of caller} - {local n.s. of caller}{} -\end{tableiv} - -Notes: - -\begin{description} - -\item[n.s.] means \emph{namespace} - -\item[(1)] The main module for a script is always called -\module{__main__}; ``the filename don't enter into it.'' - -\item[(2)] The global and local namespace for these can be -overridden with optional extra arguments. - -\item[(3)] The \keyword{exec} statement and the \function{eval()} and +for this purpose (though the actual semantics are to unbind the +name). It is illegal to unbind a name that is referenced by an +enclosing scope; the compiler will report a \exception{SyntaxError}. + +Each assignment or import statement occurs within a block defined by a +class or function definition or at the module level (the top-level +code block). + +If a name binding operation occurs anywhere within a code block, all +uses of the name within the block are treated as references to the +current block. This can lead to errors when a name is used within a +block before it is bound. + +The previous rule is a subtle. Python lacks declarations and allows +name binding operations to occur anywhere within a code block. The +local variables of a code block can be determined by scanning the +entire text of the block for name binding operations. + +If the global statement occurs within a block, all uses of the name +specified in the statement refer to the binding of that name in the +top-level namespace. Names are resolved in the top-level namespace by +searching the global namespace, i.e. the namespace of the module +containing the code block, and the builtin namespace, the namespace of +the module \module{__builtin__}. The global namespace is searched +first. If the name is not found there, the builtin namespace is +searched. The global statement must precede all uses of the name. + +The built-in namespace associated with the execution of a code block +is actually found by looking up the name \code{__builtins__} in its +global namespace; this should be a dictionary or a module (in the +latter case the module's dictionary is used). Normally, the +\code{__builtins__} namespace is the dictionary of the built-in module +\module{__builtin__} (note: no `s'). If it isn't, restricted +execution\indexii{restricted}{execution} mode is in effect. + +The namespace for a module is automatically created the first time a +module is imported. The main module for a script is always called +\module{__main__}\refbimodindex{__main__}. + +The global statement has the same scope as a name binding operation +in the same block. If the nearest enclosing scope for a free variable +contains a global statement, the free variable is treated as a global. + +A class definition is an executable statement that may use and define +names. These references follow the normal rules for name resolution. +The namespace of the class definition becomes the attribute dictionary +of the class. Names defined at the class scope are not visible in +methods. + +\subsection{Interaction with dynamic features \label{dynamic-features}} + +There are several cases where Python statements are illegal when +used in conjunction with nested scopes that contain free +variables. + +If a variable is referenced in an enclosing scope, it is illegal +to delete the name. An error will be reported at compile time. + +If the wild card form of import --- \samp{import *} --- is used in a +function and the function contains or is a nested block with free +variables, the compiler will raise a SyntaxError. + +If \keyword{exec} is used in a function and the function contains or +is a nested block with free variables, the compiler will raise a +\exception{SyntaxError} unless the exec explicitly specifies the local +namespace for the \keyword{exec}. (In other words, \samp{exec obj} +would be illegal, but \samp{exec obj in ns} would be legal.) + +The \function{eval()}, \function{execfile()}, and \function{input()} +functions and the \keyword{exec} statement do not have access to the +full environment for resolving names. Names may be resolved in the +local and global namespaces of the caller. Free variables are not +resolved in the nearest enclosing namespace, but in the global +namespace.\footnote{This limitation occurs because the code that is + executed by these operations is not available at the time the + module is compiled.} +The \keyword{exec} statement and the \function{eval()} and \function{execfile()} functions have optional arguments to override the global and local namespace. If only one namespace is specified, it is used for both. -\end{description} - -The built-in functions \function{globals()} and \function{locals()} returns a -dictionary representing the current global and local namespace, -respectively. The effect of modifications to this dictionary on the -namespace are undefined.\footnote{ - The current implementations return the dictionary actually used to - implement the namespace, \emph{except} for functions, where the - optimizer may cause the local namespace to be implemented - differently, and \function{locals()} returns a read-only - dictionary.} - - \section{Exceptions \label{exceptions}} \index{exception} diff --git a/Doc/ref/refa1.tex b/Doc/ref/refa1.tex index bf40c2d..fe1bc75 100644 --- a/Doc/ref/refa1.tex +++ b/Doc/ref/refa1.tex @@ -40,9 +40,10 @@ lines that can appear before a future statement are: \end{itemize} -The features recognized by Python 2.2 are \samp{generators}, -\samp{division} and \samp{nested_scopes}. \samp{nested_scopes} -is redundant in 2.2 as the nested scopes feature is active by default. +The features recognized by Python 2.3 are \samp{generators}, +\samp{division} and \samp{nested_scopes}. \samp{generators} and +\samp{nested_scopes} are redundant in 2.3 because they are always +enabled. A future statement is recognized and treated specially at compile time: Changes to the semantics of core constructs are often @@ -157,108 +158,3 @@ the feature in dynamically compiled code. This flag is stored in the No feature description will ever be deleted from \module{__future__}. -\section{Nested scopes \label{nested-scopes}} -\indexii{nested}{scopes} - -This section defines the new scoping semantics that will be introduced -in Python 2.2. They are available in Python 2.1 by using the future -statement \samp{nested_scopes}. This section begins with a bit of -terminology. - -\subsection{Definitions and rules \label{definitions}} - -\dfn{Names} refer to objects. Names are introduced by name binding -operations. Each occurrence of a name in the program text refers to -the binding of that name established in the innermost function block -containing the use. - -A \dfn{block} is a piece of Python program text that is executed as -a unit. The following are blocks: a module, a function body, and a -class definition. - -A \dfn{scope} defines the visibility of a name within a block. If a -local variable is defined in a block, it's scope includes that block. -If the definition occurs in a function block, the scope extends to any -blocks contained within the defining one, unless a contained block -introduces a different binding for the name. The scope of names -defined in a class block is limited to the class block; it does not -extend to the code blocks of methods. - -When a name is used in a code block, it is resolved using the nearest -enclosing scope. The set of all such scopes visible to a code block -is called the block's \dfn{environment}. - -If a name is bound in a block, it is a local variable of that block. -If a name is bound at the module level, it is a global variable. (The -variables of the module code block are local and global.) If a -variable is used in a code block but not defined there, it is a -\dfn{free variable}. - -The name binding operations are assignment, class and function -definition, import statements, for statements, and except statements. -Each assignment or import statement occurs within a block defined by a -class or function definition or at the module level (the top-level -code block). - -If a name binding operation occurs anywhere within a code block, all -uses of the name within the block are treated as references to the -current block. This can lead to errors when a name is used within a -block before it is bound. - -The previous rule is a subtle. Python lacks declarations and allows -name binding operations to occur anywhere within a code block. The -local variables of a code block can be determined by scanning the -entire text of the block for name binding operations. - -If the global statement occurs within a block, all uses of the name -specified in the statement refer to the binding of that name in the -top-level namespace. Names are resolved in the top-level namespace by -searching the global namespace, i.e. the namespace of the module -containing the code block, and the builtin namespace, the namespace of -the module \module{__builtin__}. The global namespace is searched -first. If the name is not found there, the builtin namespace is -searched. The global statement must precede all uses of the name. - -The global statement has the same scope as a name binding operation -in the same block. If the nearest enclosing scope for a free variable -contains a global statement, the free variable is treated as a global. - -A class definition is an executable statement that may use and define -names. These references follow the normal rules for name resolution. -The namespace of the class definition becomes the attribute dictionary -of the class. Names defined at the class scope are not visible in -methods. - -\subsection{Interaction with dynamic features \label{dynamic-features}} - -There are several cases where Python statements are illegal when -used in conjunction with nested scopes that contain free -variables. - -If a variable is referenced in an enclosing scope, it is illegal -to delete the name. An error will be reported at compile time. - -If the wild card form of import --- \samp{import *} --- is used in a -function and the function contains or is a nested block with free -variables, the compiler will raise a SyntaxError. - -If exec is used in a function and the function contains or is a nested -block with free variables, the compiler will raise a SyntaxError -unless the exec explicitly specifies the local namespace for the exec. -(In other words, "exec obj" would be illegal, but "exec obj in ns" -would be legal.) - -The builtin functions \function{eval()} and \function{input()} can not -access free variables unless the variables are also referenced by the -program text of the block that contains the call to \function{eval()} -or \function{input()}. - -\emph{Compatibility note}: The compiler for Python 2.1 will issue -warnings for uses of nested functions that will behave differently -with nested scopes. The warnings will not be issued if nested scopes -are enabled via a future statement. If a name bound in a function -scope and the function contains a nested function scope that uses the -name, the compiler will issue a warning. The name resolution rules -will result in different bindings under Python 2.1 than under Python -2.2. The warning indicates that the program may not run correctly -with all versions of Python. |