Mercurial > cpython-lru_cache-weakref

annotate Doc/reference/executionmodel.rst @ 66978:aed2bbafa550 3.1

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Blocked revisions 87324 via svnmerge ........ r87324 | r.david.murray | 2010-12-16 14:08:51 -0500 (Thu, 16 Dec 2010) | 9 lines #10719: restore messages generated on invalid compileall args Before the introduction of filename arguments to compileall it gave semi useful messages about not being able to 'list' names that weren't valid directories. This fix restores that behavior. In addition to the test for this case, the patch also adds a test for the default behavior of compileall when no arguments are provided, and fixes a bug in one of the previously added tests. ........
author R. David Murray <rdmurray@bitdance.com>
date Thu, 16 Dec 2010 19:10:16 +0000
parents d672753a03f0
children a3288a4e2ead
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
51201
02a90dc0c29a comprehrensions now have proper scoping #5106
Benjamin Peterson <benjamin@python.org>
parents: 48543
diff changeset
54 comprehensions and generator expressions since they are implemented using a
02a90dc0c29a comprehrensions now have proper scoping #5106
Benjamin Peterson <benjamin@python.org>
parents: 48543
diff changeset
55 function scope. This means that the following will fail::
44748
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
52182
0be1c1f127e0 Merged revisions 70397 via svnmerge from
Georg Brandl <georg@python.org>
parents: 51201
diff changeset
89 if occurring in an assignment, :keyword:`for` loop header, or after
65143
d672753a03f0 Merged revisions 85274 via svnmerge from
Georg Brandl <georg@python.org>
parents: 65111
diff changeset
90 :keyword:`as` in a :keyword:`with` statement or :keyword:`except` clause.
52182
0be1c1f127e0 Merged revisions 70397 via svnmerge from
Georg Brandl <georg@python.org>
parents: 51201
diff changeset
91 The :keyword:`import` statement
0be1c1f127e0 Merged revisions 70397 via svnmerge from
Georg Brandl <georg@python.org>
parents: 51201
diff changeset
92 of the form ``from ... import *`` binds all names defined in the imported
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
93 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
94 at the module level.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
95
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
96 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
97 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
98 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
99 will report a :exc:`SyntaxError`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
100
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
101 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
102 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
103
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
104 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
105 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
106 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
107 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
108 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
109 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
110
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
111 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
112 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
113 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
114 global namespace, i.e. the namespace of the module containing the code block,
55580
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53511
diff changeset
115 and the builtins namespace, the namespace of the module :mod:`builtins`. The
7b495c8f2a24 Merged revisions 73941-73943,74076,74094,74186,74211-74214,74247,74254,74262,74311,74334,74368 via svnmerge from
Georg Brandl <georg@python.org>
parents: 53511
diff changeset
116 global namespace is searched first. If the name is not found there, the builtins
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
117 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
118
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
119 .. XXX document "nonlocal" semantics here
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
120
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
121 .. index:: pair: restricted; execution
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
122
65111
a4c9746cb03c Merged revisions 78959,79170,79175,79177,79180,79183,79186,79193,79581 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56894
diff changeset
123 The builtins namespace associated with the execution of a code block is actually
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
124 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
125 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
126 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
127 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
128 ``__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
129 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
130 weak form of restricted execution.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
131
56894
b085fd0611de Merged revisions 75797 via svnmerge from
Georg Brandl <georg@python.org>
parents: 55580
diff changeset
132 .. impl-detail::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
133
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
134 Users should not touch ``__builtins__``; it is strictly an implementation
65111
a4c9746cb03c Merged revisions 78959,79170,79175,79177,79180,79183,79186,79193,79581 via svnmerge from
Georg Brandl <georg@python.org>
parents: 56894
diff changeset
135 detail. Users wanting to override values in the builtins namespace should
44098
0889daf6d0d9 #1535: rename __builtin__ module to builtins.
Georg Brandl <georg@python.org>
parents: 43282
diff changeset
136 :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
137 attributes appropriately.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
138
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
139 .. index:: module: __main__
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
140
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
141 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
142 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
143
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
144 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
145 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
146 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
147
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
148 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
149 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
150 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
151 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
152
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
153
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
154 .. _dynamic-features:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
155
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
156 Interaction with dynamic features
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
159 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
160 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
161
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
162 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
163 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
164
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
165 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
166 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
167 will raise a :exc:`SyntaxError`.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
168
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
169 .. 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
170
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
171 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
172 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
173 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
174 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
175 :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
176 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
177
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
178
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
179 .. _exceptions:
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
180
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
181 Exceptions
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
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
184 .. index:: single: exception
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
185
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
186 .. index::
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
187 single: raise an exception
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
188 single: handle an exception
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
189 single: exception handler
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
190 single: errors
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
191 single: error handling
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
192
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
193 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
194 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
195 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
196 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
197 the code block where the error occurred.
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
198
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
199 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
200 (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
201 exception with the :keyword:`raise` statement. Exception handlers are specified
47080
58a0d5524f9a Merged revisions 63119-63128,63130-63131,63133,63135-63144,63146-63148,63151-63152,63155-63165,63167-63176,63181-63186,63188-63189 via svnmerge from
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44748
diff changeset
202 with the :keyword:`try` ... :keyword:`except` statement. The :keyword:`finally`
58a0d5524f9a Merged revisions 63119-63128,63130-63131,63133,63135-63144,63146-63148,63151-63152,63155-63165,63167-63176,63181-63186,63188-63189 via svnmerge from
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44748
diff changeset
203 clause of such a statement can be used to specify cleanup code which does not
58a0d5524f9a Merged revisions 63119-63128,63130-63131,63133,63135-63144,63146-63148,63151-63152,63155-63165,63167-63176,63181-63186,63188-63189 via svnmerge from
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44748
diff changeset
204 handle the exception, but is executed whether an exception occurred or not in
58a0d5524f9a Merged revisions 63119-63128,63130-63131,63133,63135-63144,63146-63148,63151-63152,63155-63165,63167-63176,63181-63186,63188-63189 via svnmerge from
Alexandre Vassalotti <alexandre@peadrop.com>
parents: 44748
diff changeset
205 the preceding code.
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
206
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
207 .. index:: single: termination model
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
208
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
209 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
210 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
211 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
212 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
213
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
214 .. index:: single: SystemExit (built-in exception)
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
215
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
216 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
217 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
218 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
219
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
220 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
221 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
222 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
223 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
224
53511
11a5452e3305 Merged revisions 72009 via svnmerge from
Georg Brandl <georg@python.org>
parents: 52182
diff changeset
225 .. note::
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
226
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
227 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
228 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
229 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
230
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
231 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
232 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
233
48543
89f5cfec0573 #3113: document exception chaining.
Georg Brandl <georg@python.org>
parents: 47080
diff changeset
234
42604
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
235 .. rubric:: Footnotes
9e1529bf0442 Move the 3k reST doc tree in place.
Georg Brandl <georg@python.org>
parents:
diff changeset
236
43282
06f6682b2166 Continue going through the language reference, bringing it up-to-date.
Georg Brandl <georg@python.org>
parents: 42604
diff changeset
237 .. [#] 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
238 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
239