cpython-lru_cache-weakref: Doc/reference/executionmodel.rst annotate

annotate Doc/reference/executionmodel.rst @ 74006:88198b93ff2f

Issue #13560: Add PyUnicode_EncodeLocale() * Use PyUnicode_EncodeLocale() in time.strftime() if wcsftime() is not available * Document my last changes in Misc/NEWS

author	Victor Stinner <victor.stinner@haypocalc.com>
date	Sat, 17 Dec 2011 04:13:41 +0100
parents	10256bd68787
children

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
65139 9afed70d3aca Fix errors found by "make suspicious". Georg Brandl <georg@python.org> parents: 59617 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
68183 10256bd68787 this isn't true anymore Benjamin Peterson <benjamin@python.org> parents: 67403 diff changeset	97 this purpose (though the actual semantics are to unbind the name).
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 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	100 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	101
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 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	103 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	104 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	105 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	106 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	107 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	108
43282 06f6682b2166 Continue going through the language reference, bringing it up-to-date. Georg Brandl <georg@python.org> parents: 42604 diff changeset	109 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	110 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	111 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	112 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	113 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	114 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	115 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	116
06f6682b2166 Continue going through the language reference, bringing it up-to-date. Georg Brandl <georg@python.org> parents: 42604 diff changeset	117 .. XXX document "nonlocal" semantics here
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119 .. index:: pair: restricted; execution
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120
59617 e7b5fc8646ab Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from Georg Brandl <georg@python.org> parents: 56894 diff changeset	121 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	122 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	123 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	124 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	125 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	126 ``__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	127 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	128 weak form of restricted execution.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
56894 b085fd0611de Merged revisions 75797 via svnmerge from Georg Brandl <georg@python.org> parents: 55580 diff changeset	130 .. impl-detail::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 Users should not touch ``__builtins__``; it is strictly an implementation
59617 e7b5fc8646ab Merged revisions 78760,78771-78773,78802,78922,78952 via svnmerge from Georg Brandl <georg@python.org> parents: 56894 diff changeset	133 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	134 :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	135 attributes appropriately.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	137 .. index:: module: __main__
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 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	140 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	141
67403 a3288a4e2ead Fix various issues (mostly Python 2 relics) found by Jacques Ducasse. Georg Brandl <georg@python.org> parents: 65139 diff changeset	142 The :keyword:`global` statement has the same scope as a name binding operation
a3288a4e2ead Fix various issues (mostly Python 2 relics) found by Jacques Ducasse. Georg Brandl <georg@python.org> parents: 65139 diff changeset	143 in the same block. If the nearest enclosing scope for a free variable contains
a3288a4e2ead Fix various issues (mostly Python 2 relics) found by Jacques Ducasse. Georg Brandl <georg@python.org> parents: 65139 diff changeset	144 a global statement, the free variable is treated as a global.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	146 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	147 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	148 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	149 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	150
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 .. _dynamic-features:
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 Interaction with 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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 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	158 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	159
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 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	161 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	162
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 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	164 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	165 will raise a :exc:`SyntaxError`.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166
43282 06f6682b2166 Continue going through the language reference, bringing it up-to-date. Georg Brandl <georg@python.org> parents: 42604 diff changeset	167 .. 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	168
06f6682b2166 Continue going through the language reference, bringing it up-to-date. Georg Brandl <georg@python.org> parents: 42604 diff changeset	169 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	170 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	171 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	172 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	173 :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	174 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	175
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 .. _exceptions:
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
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182 .. index:: single: exception
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::
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 single: raise an exception
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 single: handle an exception
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 single: exception handler
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188 single: errors
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 single: error handling
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 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	192 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	193 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	194 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	195 the code block where the error occurred.
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 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	198 (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	199 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	200 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	201 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	202 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	203 the preceding code.
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 .. index:: single: termination model
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 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	208 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	209 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	210 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	211
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 .. index:: single: SystemExit (built-in exception)
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 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	215 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	216 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	217
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 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	219 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	220 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	221 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	222
53511 11a5452e3305 Merged revisions 72009 via svnmerge from Georg Brandl <georg@python.org> parents: 52182 diff changeset	223 .. note::
42604 9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224
43282 06f6682b2166 Continue going through the language reference, bringing it up-to-date. Georg Brandl <georg@python.org> parents: 42604 diff changeset	225 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	226 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	227 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	228
9e1529bf0442 Move the 3k reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229 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	230 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	231
48543 89f5cfec0573 #3113: document exception chaining. Georg Brandl <georg@python.org> parents: 47080 diff changeset	232
42604 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

Mercurial > cpython-lru_cache-weakref

annotate Doc/reference/executionmodel.rst @ 74006:88198b93ff2f