Mercurial > cpython-lru_cache-weakref

annotate Doc/reference/executionmodel.rst @ 46567:ffeecbebf3ca

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Block 2.6-only doc change.
author Georg Brandl <georg@python.org>
date Sat, 26 Apr 2008 18:28:08 +0000
parents 4a67673e3481
children 58a0d5524f9a
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
1
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
2 .. _execmodel:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
3
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
4 ***************
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
5 Execution model
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
6 ***************
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
7
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
8 .. index:: single: execution model
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
9
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
10
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
11 .. _naming:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
12
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
13 Naming and binding
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
14 ==================
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
15
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
16 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
17 pair: code; block
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
18 single: namespace
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
19 single: scope
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
20
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
21 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
22 single: name
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
23 pair: binding; name
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
24
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
25 :dfn:`Names` refer to objects. Names are introduced by name binding operations.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
26 Each occurrence of a name in the program text refers to the :dfn:`binding` of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
27 that name established in the innermost function block containing the use.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
28
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
29 .. index:: block
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
30
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
31 A :dfn:`block` is a piece of Python program text that is executed as a unit.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
32 The following are blocks: a module, a function body, and a class definition.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
33 Each command typed interactively is a block. A script file (a file given as
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
34 standard input to the interpreter or specified on the interpreter command line
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
35 the first argument) is a code block. A script command (a command specified on
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
36 the interpreter command line with the '**-c**' option) is a code block. The
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
37 string argument passed to the built-in functions :func:`eval` and :func:`exec`
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
38 is a code block.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
39
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
40 .. index:: pair: execution; frame
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
41
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
42 A code block is executed in an :dfn:`execution frame`. A frame contains some
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
43 administrative information (used for debugging) and determines where and how
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
44 execution continues after the code block's execution has completed.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
45
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
46 .. index:: scope
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
47
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
48 A :dfn:`scope` defines the visibility of a name within a block. If a local
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
49 variable is defined in a block, its scope includes that block. If the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
50 definition occurs in a function block, the scope extends to any blocks contained
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
51 within the defining one, unless a contained block introduces a different binding
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
52 for the name. The scope of names defined in a class block is limited to the
44748
4a67673e3481 Merged revisions 60043-60052 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44098
diff changeset
53 class block; it does not extend to the code blocks of methods -- this includes
4a67673e3481 Merged revisions 60043-60052 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44098
diff changeset
54 generator expressions since they are implemented using a function scope. This
4a67673e3481 Merged revisions 60043-60052 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44098
diff changeset
55 means that the following will fail::
4a67673e3481 Merged revisions 60043-60052 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44098
diff changeset
56
4a67673e3481 Merged revisions 60043-60052 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44098
diff changeset
57 class A:
4a67673e3481 Merged revisions 60043-60052 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44098
diff changeset
58 a = 42
4a67673e3481 Merged revisions 60043-60052 via svnmerge from
Christian Heimes <christian@cheimes.de>
parents: 44098
diff changeset
59 b = list(a + i for i in range(10))
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
60
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
61 .. index:: single: environment
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
62
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
63 When a name is used in a code block, it is resolved using the nearest enclosing
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
64 scope. The set of all such scopes visible to a code block is called the block's
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
65 :dfn:`environment`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
66
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
67 .. index:: pair: free; variable
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
68
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
69 If a name is bound in a block, it is a local variable of that block, unless
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
70 declared as :keyword:`nonlocal`. If a name is bound at the module level, it is
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
71 a global variable. (The variables of the module code block are local and
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
72 global.) If a variable is used in a code block but not defined there, it is a
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
73 :dfn:`free variable`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
74
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
75 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
76 single: NameError (built-in exception)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
77 single: UnboundLocalError
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
78
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
79 When a name is not found at all, a :exc:`NameError` exception is raised. If the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
80 name refers to a local variable that has not been bound, a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
81 :exc:`UnboundLocalError` exception is raised. :exc:`UnboundLocalError` is a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
82 subclass of :exc:`NameError`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
83
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
84 .. index:: statement: from
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
85
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
86 The following constructs bind names: formal parameters to functions,
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
87 :keyword:`import` statements, class and function definitions (these bind the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
88 class or function name in the defining block), and targets that are identifiers
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
89 if occurring in an assignment, :keyword:`for` loop header, or in the second
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
90 position of an :keyword:`except` clause header. The :keyword:`import` statement
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
91 of the form "``from ...import *``" binds all names defined in the imported
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
92 module, except those beginning with an underscore. This form may only be used
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 at the module level.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
94
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95 A target occurring in a :keyword:`del` statement is also considered bound for
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 this purpose (though the actual semantics are to unbind the name). It is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
97 illegal to unbind a name that is referenced by an enclosing scope; the compiler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
98 will report a :exc:`SyntaxError`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
99
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100 Each assignment or import statement occurs within a block defined by a class or
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 function definition or at the module level (the top-level code block).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
102
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
103 If a name binding operation occurs anywhere within a code block, all uses of the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 name within the block are treated as references to the current block. This can
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
105 lead to errors when a name is used within a block before it is bound. This rule
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
106 is subtle. Python lacks declarations and allows name binding operations to
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
107 occur anywhere within a code block. The local variables of a code block can be
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
108 determined by scanning the entire text of the block for name binding operations.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
109
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
110 If the :keyword:`global` statement occurs within a block, all uses of the name
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
111 specified in the statement refer to the binding of that name in the top-level
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
112 namespace. Names are resolved in the top-level namespace by searching the
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
113 global namespace, i.e. the namespace of the module containing the code block,
44098
0889daf6d0d9 #1535: rename __builtin__ module to builtins.
Georg Brandl <georg@python.org>
parents: 43282
diff changeset
114 and the builtin namespace, the namespace of the module :mod:`builtins`. The
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
115 global namespace is searched first. If the name is not found there, the builtin
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
116 namespace is searched. The global statement must precede all uses of the name.
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
117
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
118 .. XXX document "nonlocal" semantics here
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
119
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120 .. index:: pair: restricted; execution
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122 The built-in namespace associated with the execution of a code block is actually
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
123 found by looking up the name ``__builtins__`` in its global namespace; this
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 should be a dictionary or a module (in the latter case the module's dictionary
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
125 is used). By default, when in the :mod:`__main__` module, ``__builtins__`` is
44098
0889daf6d0d9 #1535: rename __builtin__ module to builtins.
Georg Brandl <georg@python.org>
parents: 43282
diff changeset
126 the built-in module :mod:`builtins`; when in any other module,
0889daf6d0d9 #1535: rename __builtin__ module to builtins.
Georg Brandl <georg@python.org>
parents: 43282
diff changeset
127 ``__builtins__`` is an alias for the dictionary of the :mod:`builtins` module
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
128 itself. ``__builtins__`` can be set to a user-created dictionary to create a
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
129 weak form of restricted execution.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
130
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131 .. note::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
132
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133 Users should not touch ``__builtins__``; it is strictly an implementation
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 detail. Users wanting to override values in the built-in namespace should
44098
0889daf6d0d9 #1535: rename __builtin__ module to builtins.
Georg Brandl <georg@python.org>
parents: 43282
diff changeset
135 :keyword:`import` the :mod:`builtins` module and modify its
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
136 attributes appropriately.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
137
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138 .. index:: module: __main__
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
140 The namespace for a module is automatically created the first time a module is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
141 imported. The main module for a script is always called :mod:`__main__`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
142
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
143 The global statement has the same scope as a name binding operation in the same
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 block. If the nearest enclosing scope for a free variable contains a global
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
145 statement, the free variable is treated as a global.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
146
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
147 A class definition is an executable statement that may use and define names.
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
148 These references follow the normal rules for name resolution. The namespace of
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
149 the class definition becomes the attribute dictionary of the class. Names
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
150 defined at the class scope are not visible in methods.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
151
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
152
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153 .. _dynamic-features:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155 Interaction with dynamic features
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 ---------------------------------
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
157
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
158 There are several cases where Python statements are illegal when used in
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159 conjunction with nested scopes that contain free variables.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
160
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
161 If a variable is referenced in an enclosing scope, it is illegal to delete the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 name. An error will be reported at compile time.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
163
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
164 If the wild card form of import --- ``import *`` --- is used in a function and
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165 the function contains or is a nested block with free variables, the compiler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
166 will raise a :exc:`SyntaxError`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
167
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
168 .. XXX from * also invalid with relative imports (at least currently)
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
169
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
170 The :func:`eval` and :func:`exec` functions do not have access to the full
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
171 environment for resolving names. Names may be resolved in the local and global
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
172 namespaces of the caller. Free variables are not resolved in the nearest
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
173 enclosing namespace, but in the global namespace. [#]_ The :func:`exec` and
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
174 :func:`eval` functions have optional arguments to override the global and local
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
175 namespace. If only one namespace is specified, it is used for both.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
176
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
177
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178 .. _exceptions:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180 Exceptions
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 ==========
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
182
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
183 .. index:: single: exception
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
184
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 single: raise an exception
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 single: handle an exception
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 single: exception handler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 single: errors
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 single: error handling
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192 Exceptions are a means of breaking out of the normal flow of control of a code
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 block in order to handle errors or other exceptional conditions. An exception
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
194 is *raised* at the point where the error is detected; it may be *handled* by the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
195 surrounding code block or by any code block that directly or indirectly invoked
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
196 the code block where the error occurred.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
197
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198 The Python interpreter raises an exception when it detects a run-time error
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 (such as division by zero). A Python program can also explicitly raise an
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
200 exception with the :keyword:`raise` statement. Exception handlers are specified
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
201 with the :keyword:`try` ... :keyword:`except` statement. The :keyword:`try` ...
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
202 :keyword:`finally` statement specifies cleanup code which does not handle the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
203 exception, but is executed whether an exception occurred or not in the preceding
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
204 code.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
205
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206 .. index:: single: termination model
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208 Python uses the "termination" model of error handling: an exception handler can
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 find out what happened and continue execution at an outer level, but it cannot
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
210 repair the cause of the error and retry the failing operation (except by
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
211 re-entering the offending piece of code from the top).
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
212
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
213 .. index:: single: SystemExit (built-in exception)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
214
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215 When an exception is not handled at all, the interpreter terminates execution of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 the program, or returns to its interactive main loop. In either case, it prints
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
217 a stack backtrace, except when the exception is :exc:`SystemExit`.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
218
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
219 Exceptions are identified by class instances. The :keyword:`except` clause is
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 selected depending on the class of the instance: it must reference the class of
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
221 the instance or a base class thereof. The instance can be received by the
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
222 handler and can carry additional information about the exceptional condition.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
223
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
224 .. warning::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
225
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
226 Exception messages are not part of the Python API. Their contents may change
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
227 from one version of Python to the next without warning and should not be
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
228 relied on by code which will run under multiple versions of the interpreter.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
229
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
230 See also the description of the :keyword:`try` statement in section :ref:`try`
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 and :keyword:`raise` statement in section :ref:`raise`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
232
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
233 .. rubric:: Footnotes
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
234
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
235 .. [#] This limitation occurs because the code that is executed by these operations
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
236 is not available at the time the module is compiled.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
237