cpython-lru_cache-weakref: Doc/reference/simple

annotate Doc/reference/simple_stmts.rst @ 54294:dba767bc3155 legacy-trunk

remove mention of old ctypes version

author	Benjamin Peterson <benjamin@python.org>
date	Sat, 23 May 2009 20:59:09 +0000
parents	f227ff34e33d
children	4a2771f6b9dd

rev	line source
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	2 .. _simple:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	4 *****************
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	5 Simple statements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	6 *****************
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	7
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	8 .. index:: pair: simple; statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	9
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	10 Simple statements are comprised within a single logical line. Several simple
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	11 statements may occur on a single line separated by semicolons. The syntax for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	12 simple statements is:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	13
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	14 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	15 simple_stmt: `expression_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	16 : \| `assert_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	17 : \| `assignment_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	18 : \| `augmented_assignment_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	19 : \| `pass_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	20 : \| `del_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	21 : \| `print_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	22 : \| `return_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	23 : \| `yield_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	24 : \| `raise_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	25 : \| `break_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	26 : \| `continue_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	27 : \| `import_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	28 : \| `global_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	29 : \| `exec_stmt`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	30
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	31
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	32 .. _exprstmts:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	33
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	34 Expression statements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	35 =====================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	36
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	37 .. index::
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	38 pair: expression; statement
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	39 pair: expression; list
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	40
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	41 Expression statements are used (mostly interactively) to compute and write a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	42 value, or (usually) to call a procedure (a function that returns no meaningful
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	43 result; in Python, procedures return the value ``None``). Other uses of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	44 expression statements are allowed and occasionally useful. The syntax for an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	45 expression statement is:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	46
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	47 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	48 expression_stmt: `expression_list`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	49
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	50 An expression statement evaluates the expression list (which may be a single
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	51 expression).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	52
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	53 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	54 builtin: repr
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	55 object: None
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	56 pair: string; conversion
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	57 single: output
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	58 pair: standard; output
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	59 pair: writing; values
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	60 pair: procedure; call
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	61
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	62 In interactive mode, if the value is not ``None``, it is converted to a string
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	63 using the built-in :func:`repr` function and the resulting string is written to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	64 standard output (see section :ref:`print`) on a line by itself. (Expression
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	65 statements yielding ``None`` are not written, so that procedure calls do not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	66 cause any output.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	67
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	68
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	69 .. _assignment:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	70
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	71 Assignment statements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	72 =====================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	73
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	74 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	75 pair: assignment; statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	76 pair: binding; name
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	77 pair: rebinding; name
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	78 object: mutable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	79 pair: attribute; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	80
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	81 Assignment statements are used to (re)bind names to values and to modify
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	82 attributes or items of mutable objects:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	83
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	84 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	85 assignment_stmt: (`target_list` "=")+ (`expression_list` \| `yield_expression`)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	86 target_list: `target` ("," `target`)* [","]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	87 target: `identifier`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	88 : \| "(" `target_list` ")"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	89 : \| "[" `target_list` "]"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	90 : \| `attributeref`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	91 : \| `subscription`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	92 : \| `slicing`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	93
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	94 (See section :ref:`primaries` for the syntax definitions for the last three
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	95 symbols.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	96
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	97 .. index:: pair: expression; list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	98
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	99 An assignment statement evaluates the expression list (remember that this can be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	100 a single expression or a comma-separated list, the latter yielding a tuple) and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	101 assigns the single resulting object to each of the target lists, from left to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	102 right.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	103
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	104 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	105 single: target
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	106 pair: target; list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	107
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	108 Assignment is defined recursively depending on the form of the target (list).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	109 When a target is part of a mutable object (an attribute reference, subscription
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	110 or slicing), the mutable object must ultimately perform the assignment and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	111 decide about its validity, and may raise an exception if the assignment is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	112 unacceptable. The rules observed by various types and the exceptions raised are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	113 given with the definition of the object types (see section :ref:`types`).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	114
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	115 .. index:: triple: target; list; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	116
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	117 Assignment of an object to a target list is recursively defined as follows.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	118
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	119 * If the target list is a single target: The object is assigned to that target.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	120
51701 e7e544cd2c2b #5296: sequence -> iterable. Georg Brandl <georg@python.org> parents: 50868 diff changeset	121 * If the target list is a comma-separated list of targets: The object must be an
e7e544cd2c2b #5296: sequence -> iterable. Georg Brandl <georg@python.org> parents: 50868 diff changeset	122 iterable with the same number of items as there are targets in the target list,
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	123 and the items are assigned, from left to right, to the corresponding targets.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	124 (This rule is relaxed as of Python 1.5; in earlier versions, the object had to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	125 be a tuple. Since strings are sequences, an assignment like ``a, b = "xy"`` is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	126 now legal as long as the string has the right length.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	127
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	128 Assignment of an object to a single target is recursively defined as follows.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	129
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	130 * If the target is an identifier (name):
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	131
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	132 .. index:: statement: global
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	133
43281 4b2134e4730c Fix a wrong indentation for sublists. Georg Brandl <georg@python.org> parents: 42603 diff changeset	134 * If the name does not occur in a :keyword:`global` statement in the current
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	135 code block: the name is bound to the object in the current local namespace.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	136
43281 4b2134e4730c Fix a wrong indentation for sublists. Georg Brandl <georg@python.org> parents: 42603 diff changeset	137 * Otherwise: the name is bound to the object in the current global namespace.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	138
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	139 .. index:: single: destructor
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	140
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	141 The name is rebound if it was already bound. This may cause the reference count
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	142 for the object previously bound to the name to reach zero, causing the object to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	143 be deallocated and its destructor (if it has one) to be called.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	144
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	145 * If the target is a target list enclosed in parentheses or in square brackets:
51701 e7e544cd2c2b #5296: sequence -> iterable. Georg Brandl <georg@python.org> parents: 50868 diff changeset	146 The object must be an iterable with the same number of items as there are
e7e544cd2c2b #5296: sequence -> iterable. Georg Brandl <georg@python.org> parents: 50868 diff changeset	147 targets in the target list, and its items are assigned, from left to right,
e7e544cd2c2b #5296: sequence -> iterable. Georg Brandl <georg@python.org> parents: 50868 diff changeset	148 to the corresponding targets.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	149
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	150 .. index:: pair: attribute; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	151
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	152 * If the target is an attribute reference: The primary expression in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	153 reference is evaluated. It should yield an object with assignable attributes;
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	154 if this is not the case, :exc:`TypeError` is raised. That object is then asked
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	155 to assign the assigned object to the given attribute; if it cannot perform the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	156 assignment, it raises an exception (usually but not necessarily
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	157 :exc:`AttributeError`).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	158
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	159 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	160 pair: subscription; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	161 object: mutable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	162
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	163 * If the target is a subscription: The primary expression in the reference is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	164 evaluated. It should yield either a mutable sequence object (such as a list) or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	165 a mapping object (such as a dictionary). Next, the subscript expression is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	166 evaluated.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	167
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	168 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	169 object: sequence
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	170 object: list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	171
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	172 If the primary is a mutable sequence object (such as a list), the subscript must
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	173 yield a plain integer. If it is negative, the sequence's length is added to it.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	174 The resulting value must be a nonnegative integer less than the sequence's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	175 length, and the sequence is asked to assign the assigned object to its item with
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	176 that index. If the index is out of range, :exc:`IndexError` is raised
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	177 (assignment to a subscripted sequence cannot add new items to a list).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	178
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	179 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	180 object: mapping
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	181 object: dictionary
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	182
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	183 If the primary is a mapping object (such as a dictionary), the subscript must
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	184 have a type compatible with the mapping's key type, and the mapping is then
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	185 asked to create a key/datum pair which maps the subscript to the assigned
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	186 object. This can either replace an existing key/value pair with the same key
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	187 value, or insert a new key/value pair (if no key with the same value existed).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	188
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	189 .. index:: pair: slicing; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	190
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	191 * If the target is a slicing: The primary expression in the reference is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	192 evaluated. It should yield a mutable sequence object (such as a list). The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	193 assigned object should be a sequence object of the same type. Next, the lower
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	194 and upper bound expressions are evaluated, insofar they are present; defaults
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	195 are zero and the sequence's length. The bounds should evaluate to (small)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	196 integers. If either bound is negative, the sequence's length is added to it.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	197 The resulting bounds are clipped to lie between zero and the sequence's length,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	198 inclusive. Finally, the sequence object is asked to replace the slice with the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	199 items of the assigned sequence. The length of the slice may be different from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	200 the length of the assigned sequence, thus changing the length of the target
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	201 sequence, if the object allows it.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	202
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	203 (In the current implementation, the syntax for targets is taken to be the same
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	204 as for expressions, and invalid syntax is rejected during the code generation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	205 phase, causing less detailed error messages.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	206
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	207 WARNING: Although the definition of assignment implies that overlaps between the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	208 left-hand side and the right-hand side are 'safe' (for example ``a, b = b, a``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	209 swaps two variables), overlaps within the collection of assigned-to variables
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	210 are not safe! For instance, the following program prints ``[0, 2]``::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	211
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	212 x = [0, 1]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	213 i = 0
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	214 i, x[i] = 1, 2
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	215 print x
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	216
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	217
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	218 .. _augassign:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	219
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	220 Augmented assignment statements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	221 -------------------------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	222
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	223 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	224 pair: augmented; assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	225 single: statement; assignment, augmented
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	226
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	227 Augmented assignment is the combination, in a single statement, of a binary
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	228 operation and an assignment statement:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	229
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	230 .. productionlist::
50868 11cbf39c316f #4857: fix augmented assignment target spec. Georg Brandl <georg@python.org> parents: 50522 diff changeset	231 augmented_assignment_stmt: `augtarget` `augop` (`expression_list` \| `yield_expression`)
11cbf39c316f #4857: fix augmented assignment target spec. Georg Brandl <georg@python.org> parents: 50522 diff changeset	232 augtarget: `identifier` \| `attributeref` \| `subscription` \| `slicing`
49244 85b480ef2635 #3914: add //= to the augmented assign operators. Georg Brandl <georg@python.org> parents: 48127 diff changeset	233 augop: "+=" \| "-=" \| "=" \| "/=" \| "//=" \| "%=" \| "*="
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	234 : \| ">>=" \| "<<=" \| "&=" \| "^=" \| "\|="
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	235
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	236 (See section :ref:`primaries` for the syntax definitions for the last three
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	237 symbols.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	238
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	239 An augmented assignment evaluates the target (which, unlike normal assignment
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	240 statements, cannot be an unpacking) and the expression list, performs the binary
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	241 operation specific to the type of assignment on the two operands, and assigns
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	242 the result to the original target. The target is only evaluated once.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	243
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	244 An augmented assignment expression like ``x += 1`` can be rewritten as ``x = x +
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	245 1`` to achieve a similar, but not exactly equal effect. In the augmented
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	246 version, ``x`` is only evaluated once. Also, when possible, the actual operation
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	247 is performed in-place, meaning that rather than creating a new object and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	248 assigning that to the target, the old object is modified instead.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	249
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	250 With the exception of assigning to tuples and multiple targets in a single
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	251 statement, the assignment done by augmented assignment statements is handled the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	252 same way as normal assignments. Similarly, with the exception of the possible
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	253 in-place behavior, the binary operation performed by augmented assignment is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	254 the same as the normal binary operations.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	255
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	256 For targets which are attribute references, the initial value is retrieved with
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	257 a :meth:`getattr` and the result is assigned with a :meth:`setattr`. Notice
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	258 that the two methods do not necessarily refer to the same variable. When
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	259 :meth:`getattr` refers to a class variable, :meth:`setattr` still writes to an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	260 instance variable. For example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	261
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	262 class A:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	263 x = 3 # class variable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	264 a = A()
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	265 a.x += 1 # writes a.x as 4 leaving A.x as 3
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	266
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	267
43390 5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	268 .. _assert:
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	269
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	270 The :keyword:`assert` statement
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	271 ===============================
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	272
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	273 .. index::
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	274 statement: assert
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	275 pair: debugging; assertions
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	276
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	277 Assert statements are a convenient way to insert debugging assertions into a
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	278 program:
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	279
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	280 .. productionlist::
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	281 assert_stmt: "assert" `expression` ["," `expression`]
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	282
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	283 The simple form, ``assert expression``, is equivalent to ::
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	284
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	285 if __debug__:
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	286 if not expression: raise AssertionError
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	287
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	288 The extended form, ``assert expression1, expression2``, is equivalent to ::
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	289
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	290 if __debug__:
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	291 if not expression1: raise AssertionError, expression2
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	292
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	293 .. index::
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	294 single: __debug__
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	295 exception: AssertionError
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	296
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43390 diff changeset	297 These equivalences assume that :const:`__debug__` and :exc:`AssertionError` refer to
43390 5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	298 the built-in variables with those names. In the current implementation, the
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43390 diff changeset	299 built-in variable :const:`__debug__` is ``True`` under normal circumstances,
43390 5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	300 ``False`` when optimization is requested (command line option -O). The current
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	301 code generator emits no code for an assert statement when optimization is
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	302 requested at compile time. Note that it is unnecessary to include the source
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	303 code for the expression that failed in the error message; it will be displayed
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	304 as part of the stack trace.
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	305
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43390 diff changeset	306 Assignments to :const:`__debug__` are illegal. The value for the built-in variable
43390 5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	307 is determined when the interpreter starts.
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	308
5975a7316c06 A bit of reordering, also show more subheadings in the lang ref index. Georg Brandl <georg@python.org> parents: 43281 diff changeset	309
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	310 .. _pass:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	311
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	312 The :keyword:`pass` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	313 =============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	314
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	315 .. index::
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	316 statement: pass
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	317 pair: null; operation
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	318
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	319 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	320 pass_stmt: "pass"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	321
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	322 :keyword:`pass` is a null operation --- when it is executed, nothing happens.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	323 It is useful as a placeholder when a statement is required syntactically, but no
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	324 code needs to be executed, for example::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	325
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	326 def f(arg): pass # a function that does nothing (yet)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	327
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	328 class C: pass # a class with no methods (yet)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	329
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	330
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	331 .. _del:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	332
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	333 The :keyword:`del` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	334 ============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	335
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	336 .. index::
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	337 statement: del
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	338 pair: deletion; target
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	339 triple: deletion; target; list
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	340
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	341 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	342 del_stmt: "del" `target_list`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	343
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	344 Deletion is recursively defined very similar to the way assignment is defined.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	345 Rather that spelling it out in full details, here are some hints.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	346
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	347 Deletion of a target list recursively deletes each target, from left to right.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	348
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	349 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	350 statement: global
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	351 pair: unbinding; name
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	352
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	353 Deletion of a name removes the binding of that name from the local or global
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	354 namespace, depending on whether the name occurs in a :keyword:`global` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	355 in the same code block. If the name is unbound, a :exc:`NameError` exception
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	356 will be raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	357
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	358 .. index:: pair: free; variable
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	359
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	360 It is illegal to delete a name from the local namespace if it occurs as a free
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	361 variable in a nested block.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	362
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	363 .. index:: pair: attribute; deletion
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	364
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	365 Deletion of attribute references, subscriptions and slicings is passed to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	366 primary object involved; deletion of a slicing is in general equivalent to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	367 assignment of an empty slice of the right type (but even this is determined by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	368 the sliced object).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	369
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	370
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	371 .. _print:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	372
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	373 The :keyword:`print` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	374 ==============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	375
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	376 .. index:: statement: print
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	377
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	378 .. productionlist::
47493 af680fd3ffdc Fix brackets. Georg Brandl <georg@python.org> parents: 47248 diff changeset	379 print_stmt: "print" ([`expression` ("," `expression`)* [","]]
af680fd3ffdc Fix brackets. Georg Brandl <georg@python.org> parents: 47248 diff changeset	380 : \| ">>" `expression` [("," `expression`)+ [","]])
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	381
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	382 :keyword:`print` evaluates each expression in turn and writes the resulting
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	383 object to standard output (see below). If an object is not a string, it is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	384 first converted to a string using the rules for string conversions. The
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	385 (resulting or original) string is then written. A space is written before each
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	386 object is (converted and) written, unless the output system believes it is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	387 positioned at the beginning of a line. This is the case (1) when no characters
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	388 have yet been written to standard output, (2) when the last character written to
54250 f227ff34e33d Correction in softspace behavior description. Georg Brandl <georg@python.org> parents: 54052 diff changeset	389 standard output is a whitespace character except ``' '``, or (3) when the last
f227ff34e33d Correction in softspace behavior description. Georg Brandl <georg@python.org> parents: 54052 diff changeset	390 write operation on standard output was not a :keyword:`print` statement.
f227ff34e33d Correction in softspace behavior description. Georg Brandl <georg@python.org> parents: 54052 diff changeset	391 (In some cases it may be functional to write an empty string to standard output
f227ff34e33d Correction in softspace behavior description. Georg Brandl <georg@python.org> parents: 54052 diff changeset	392 for this reason.)
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	393
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	394 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	395
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	396 Objects which act like file objects but which are not the built-in file objects
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	397 often do not properly emulate this aspect of the file object's behavior, so it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	398 is best not to rely on this.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	399
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	400 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	401 single: output
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	402 pair: writing; values
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	403 pair: trailing; comma
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	404 pair: newline; suppression
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	405
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	406 A ``'\n'`` character is written at the end, unless the :keyword:`print`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	407 statement ends with a comma. This is the only action if the statement contains
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	408 just the keyword :keyword:`print`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	409
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	410 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	411 pair: standard; output
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	412 module: sys
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	413 single: stdout (in module sys)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	414 exception: RuntimeError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	415
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	416 Standard output is defined as the file object named ``stdout`` in the built-in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	417 module :mod:`sys`. If no such object exists, or if it does not have a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	418 :meth:`write` method, a :exc:`RuntimeError` exception is raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	419
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	420 .. index:: single: extended print statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	421
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	422 :keyword:`print` also has an extended form, defined by the second portion of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	423 syntax described above. This form is sometimes referred to as ":keyword:`print`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	424 chevron." In this form, the first expression after the ``>>`` must evaluate to a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	425 "file-like" object, specifically an object that has a :meth:`write` method as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	426 described above. With this extended form, the subsequent expressions are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	427 printed to this file object. If the first expression evaluates to ``None``,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	428 then ``sys.stdout`` is used as the file for output.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	429
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	430
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	431 .. _return:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	432
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	433 The :keyword:`return` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	434 ===============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	435
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	436 .. index::
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	437 statement: return
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	438 pair: function; definition
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	439 pair: class; definition
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	440
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	441 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	442 return_stmt: "return" [`expression_list`]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	443
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	444 :keyword:`return` may only occur syntactically nested in a function definition,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	445 not within a nested class definition.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	446
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	447 If an expression list is present, it is evaluated, else ``None`` is substituted.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	448
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	449 :keyword:`return` leaves the current function call with the expression list (or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	450 ``None``) as return value.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	451
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	452 .. index:: keyword: finally
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	453
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	454 When :keyword:`return` passes control out of a :keyword:`try` statement with a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	455 :keyword:`finally` clause, that :keyword:`finally` clause is executed before
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	456 really leaving the function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	457
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	458 In a generator function, the :keyword:`return` statement is not allowed to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	459 include an :token:`expression_list`. In that context, a bare :keyword:`return`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	460 indicates that the generator is done and will cause :exc:`StopIteration` to be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	461 raised.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	462
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	463
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	464 .. _yield:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	465
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	466 The :keyword:`yield` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	467 ==============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	468
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	469 .. index::
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	470 statement: yield
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	471 single: generator; function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	472 single: generator; iterator
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	473 single: function; generator
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	474 exception: StopIteration
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	475
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	476 .. productionlist::
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	477 yield_stmt: `yield_expression`
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	478
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	479 The :keyword:`yield` statement is only used when defining a generator function,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	480 and is only used in the body of the generator function. Using a :keyword:`yield`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	481 statement in a function definition is sufficient to cause that definition to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	482 create a generator function instead of a normal function.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	483
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	484 When a generator function is called, it returns an iterator known as a generator
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	485 iterator, or more commonly, a generator. The body of the generator function is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	486 executed by calling the generator's :meth:`next` method repeatedly until it
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	487 raises an exception.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	488
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	489 When a :keyword:`yield` statement is executed, the state of the generator is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	490 frozen and the value of :token:`expression_list` is returned to :meth:`next`'s
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	491 caller. By "frozen" we mean that all local state is retained, including the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	492 current bindings of local variables, the instruction pointer, and the internal
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	493 evaluation stack: enough information is saved so that the next time :meth:`next`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	494 is invoked, the function can proceed exactly as if the :keyword:`yield`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	495 statement were just another external call.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	496
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	497 As of Python version 2.5, the :keyword:`yield` statement is now allowed in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	498 :keyword:`try` clause of a :keyword:`try` ... :keyword:`finally` construct. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	499 the generator is not resumed before it is finalized (by reaching a zero
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	500 reference count or by being garbage collected), the generator-iterator's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	501 :meth:`close` method will be called, allowing any pending :keyword:`finally`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	502 clauses to execute.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	503
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	504 .. note::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	505
46396 29a7bec610cb Remove forward-looking statement Andrew M. Kuchling <amk@amk.ca> parents: 45707 diff changeset	506 In Python 2.2, the :keyword:`yield` statement was only allowed when the
29a7bec610cb Remove forward-looking statement Andrew M. Kuchling <amk@amk.ca> parents: 45707 diff changeset	507 ``generators`` feature has been enabled. This ``__future__``
29a7bec610cb Remove forward-looking statement Andrew M. Kuchling <amk@amk.ca> parents: 45707 diff changeset	508 import statement was used to enable the feature::
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	509
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	510 from __future__ import generators
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	511
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	512
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	513 .. seealso::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	514
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	515 :pep:`0255` - Simple Generators
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	516 The proposal for adding generators and the :keyword:`yield` statement to Python.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	517
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	518 :pep:`0342` - Coroutines via Enhanced Generators
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	519 The proposal that, among other generator enhancements, proposed allowing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	520 :keyword:`yield` to appear inside a :keyword:`try` ... :keyword:`finally` block.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	521
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	522
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	523 .. _raise:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	524
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	525 The :keyword:`raise` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	526 ==============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	527
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	528 .. index::
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	529 statement: raise
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	530 single: exception
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	531 pair: raising; exception
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	532
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	533 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	534 raise_stmt: "raise" [`expression` ["," `expression` ["," `expression`]]]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	535
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	536 If no expressions are present, :keyword:`raise` re-raises the last exception
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	537 that was active in the current scope. If no exception is active in the current
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	538 scope, a :exc:`TypeError` exception is raised indicating that this is an error
47248 9acb314b9072 Queue renaming reversal part 3: move module into place and Georg Brandl <georg@python.org> parents: 46939 diff changeset	539 (if running under IDLE, a :exc:`Queue.Empty` exception is raised instead).
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	540
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	541 Otherwise, :keyword:`raise` evaluates the expressions to get three objects,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	542 using ``None`` as the value of omitted expressions. The first two objects are
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	543 used to determine the type and value of the exception.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	544
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	545 If the first object is an instance, the type of the exception is the class of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	546 the instance, the instance itself is the value, and the second object must be
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	547 ``None``.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	548
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	549 If the first object is a class, it becomes the type of the exception. The second
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	550 object is used to determine the exception value: If it is an instance of the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	551 class, the instance becomes the exception value. If the second object is a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	552 tuple, it is used as the argument list for the class constructor; if it is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	553 ``None``, an empty argument list is used, and any other object is treated as a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	554 single argument to the constructor. The instance so created by calling the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	555 constructor is used as the exception value.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	556
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	557 .. index:: object: traceback
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	558
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	559 If a third object is present and not ``None``, it must be a traceback object
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	560 (see section :ref:`types`), and it is substituted instead of the current
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	561 location as the place where the exception occurred. If the third object is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	562 present and not a traceback object or ``None``, a :exc:`TypeError` exception is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	563 raised. The three-expression form of :keyword:`raise` is useful to re-raise an
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	564 exception transparently in an except clause, but :keyword:`raise` with no
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	565 expressions should be preferred if the exception to be re-raised was the most
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	566 recently active exception in the current scope.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	567
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	568 Additional information on exceptions can be found in section :ref:`exceptions`,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	569 and information about handling exceptions is in section :ref:`try`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	570
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	571
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	572 .. _break:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	573
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	574 The :keyword:`break` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	575 ==============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	576
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	577 .. index::
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	578 statement: break
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	579 statement: for
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	580 statement: while
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	581 pair: loop; statement
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	582
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	583 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	584 break_stmt: "break"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	585
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	586 :keyword:`break` may only occur syntactically nested in a :keyword:`for` or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	587 :keyword:`while` loop, but not nested in a function or class definition within
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	588 that loop.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	589
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	590 .. index:: keyword: else
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	591
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	592 It terminates the nearest enclosing loop, skipping the optional :keyword:`else`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	593 clause if the loop has one.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	594
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	595 .. index:: pair: loop control; target
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	596
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	597 If a :keyword:`for` loop is terminated by :keyword:`break`, the loop control
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	598 target keeps its current value.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	599
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	600 .. index:: keyword: finally
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	601
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	602 When :keyword:`break` passes control out of a :keyword:`try` statement with a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	603 :keyword:`finally` clause, that :keyword:`finally` clause is executed before
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	604 really leaving the loop.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	605
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	606
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	607 .. _continue:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	608
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	609 The :keyword:`continue` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	610 =================================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	611
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	612 .. index::
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	613 statement: continue
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	614 statement: for
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	615 statement: while
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	616 pair: loop; statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	617 keyword: finally
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	618
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	619 .. productionlist::
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	620 continue_stmt: "continue"
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	621
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	622 :keyword:`continue` may only occur syntactically nested in a :keyword:`for` or
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	623 :keyword:`while` loop, but not nested in a function or class definition or
45707 9cf70729c23f #2253: fix continue vs. finally docs. Georg Brandl <georg@python.org> parents: 44496 diff changeset	624 :keyword:`finally` clause within that loop. It continues with the next
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	625 cycle of the nearest enclosing loop.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	626
45707 9cf70729c23f #2253: fix continue vs. finally docs. Georg Brandl <georg@python.org> parents: 44496 diff changeset	627 When :keyword:`continue` passes control out of a :keyword:`try` statement with a
9cf70729c23f #2253: fix continue vs. finally docs. Georg Brandl <georg@python.org> parents: 44496 diff changeset	628 :keyword:`finally` clause, that :keyword:`finally` clause is executed before
9cf70729c23f #2253: fix continue vs. finally docs. Georg Brandl <georg@python.org> parents: 44496 diff changeset	629 really starting the next loop cycle.
9cf70729c23f #2253: fix continue vs. finally docs. Georg Brandl <georg@python.org> parents: 44496 diff changeset	630
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	631
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	632 .. _import:
44383 3625234bf3d2 Some cleanup in the docs. Georg Brandl <georg@python.org> parents: 43390 diff changeset	633 .. _from:
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	634
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	635 The :keyword:`import` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	636 ===============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	637
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	638 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	639 statement: import
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	640 single: module; importing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	641 pair: name; binding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	642 keyword: from
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	643
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	644 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	645 import_stmt: "import" `module` ["as" `name`] ( "," `module` ["as" `name`] )*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	646 : \| "from" `relative_module` "import" `identifier` ["as" `name`]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	647 : ( "," `identifier` ["as" `name`] )*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	648 : \| "from" `relative_module` "import" "(" `identifier` ["as" `name`]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	649 : ( "," `identifier` ["as" `name`] )* [","] ")"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	650 : \| "from" `module` "import" "*"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	651 module: (`identifier` ".")* `identifier`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	652 relative_module: "."* `module` \| "."+
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	653 name: `identifier`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	654
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	655 Import statements are executed in two steps: (1) find a module, and initialize
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	656 it if necessary; (2) define a name or names in the local namespace (of the scope
52535 ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	657 where the :keyword:`import` statement occurs). The statement comes in two
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	658 forms differing on whether it uses the :keyword:`from` keyword. The first form
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	659 (without :keyword:`from`) repeats these steps for each identifier in the list.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	660 The form with :keyword:`from` performs step (1) once, and then performs step
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	661 (2) repeatedly.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	662
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	663 .. index::
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	664 single: package
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	665
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	666 To understand how step (1) occurs, one must first understand how Python handles
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	667 hierarchical naming of modules. To help organize modules and provide a
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	668 hierarchy in naming, Python has a concept of packages. A package can contain
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	669 other packages and modules while modules cannot contain other modules or
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	670 packages. From a file system perspective, packages are directories and modules
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	671 are files. The original `specification for packages
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	672 <http://www.python.org/doc/essays/packages.html>`_ is still available to read,
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	673 although minor details have changed since the writing of that document.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	674
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	675 .. index::
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	676 single: sys.modules
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	677
52535 ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	678 Once the name of the module is known (unless otherwise specified, the term
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	679 "module" will refer to both packages and modules), searching
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	680 for the module or package can begin. The first place checked is
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	681 :data:`sys.modules`, the cache of all modules that have been imported
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	682 previously. If the module is found there then it is used in step (2) of import.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	683
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	684 .. index::
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	685 single: sys.meta_path
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	686 single: finder
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	687 pair: finder; find_module
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	688 single: __path__
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	689
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	690 If the module is not found in the cache, then :data:`sys.meta_path` is searched
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	691 (the specification for :data:`sys.meta_path` can be found in :pep:`302`).
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	692 The object is a list of :term:`finder` objects which are queried in order as to
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	693 whether they know how to load the module by calling their :meth:`find_module`
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	694 method with the name of the module. If the module happens to be contained
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	695 within a package (as denoted by the existence of a dot in the name), then a
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	696 second argument to :meth:`find_module` is given as the value of the
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	697 :attr:`__path__` attribute from the parent package (everything up to the last
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	698 dot in the name of the module being imported). If a finder can find the module
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	699 it returns a :term:`loader` (discussed later) or returns :keyword:`None`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	700
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	701 .. index::
52535 ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	702 single: sys.path_hooks
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	703 single: sys.path_importer_cache
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	704 single: sys.path
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	705
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	706 If none of the finders on :data:`sys.meta_path` are able to find the module
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	707 then some implicitly defined finders are queried. Implementations of Python
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	708 vary in what implicit meta path finders are defined. The one they all do
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	709 define, though, is one that handles :data:`sys.path_hooks`,
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	710 :data:`sys.path_importer_cache`, and :data:`sys.path`.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	711
52535 ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	712 The implicit finder searches for the requested module in the "paths" specified
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	713 in one of two places ("paths" do not have to be file system paths). If the
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	714 module being imported is supposed to be contained within a package then the
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	715 second argument passed to :meth:`find_module`, :attr:`__path__` on the parent
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	716 package, is used as the source of paths. If the module is not contained in a
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	717 package then :data:`sys.path` is used as the source of paths.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	718
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	719 Once the source of paths is chosen it is iterated over to find a finder that
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	720 can handle that path. The dict at :data:`sys.path_importer_cache` caches
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	721 finders for paths and is checked for a finder. If the path does not have a
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	722 finder cached then :data:`sys.path_hooks` is searched by calling each object in
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	723 the list with a single argument of the path, returning a finder or raises
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	724 :exc:`ImportError`. If a finder is returned then it is cached in
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	725 :data:`sys.path_importer_cache` and then used for that path entry. If no finder
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	726 can be found but the path exists then a value of :keyword:`None` is
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	727 stored in :data:`sys.path_importer_cache` to signify that an implicit,
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	728 file-based finder that handles modules stored as individual files should be
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	729 used for that path. If the path does not exist then a finder which always
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	730 returns :keyword:`None` is placed in the cache for the path.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	731
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	732 .. index::
52535 ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	733 single: loader
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	734 pair: loader; load_module
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	735 exception: ImportError
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	736
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	737 If no finder can find the module then :exc:`ImportError` is raised. Otherwise
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	738 some finder returned a loader whose :meth:`load_module` method is called with
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	739 the name of the module to load (see :pep:`302` for the original definition of
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	740 loaders). A loader has several responsibilities to perform on a module it
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	741 loads. First, if the module already exists in :data:`sys.modules` (a
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	742 possibility if the loader is called outside of the import machinery) then it
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	743 is to use that module for initialization and not a new module. But if the
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	744 module does not exist in :data:`sys.modules` then it is to be added to that
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	745 dict before initialization begins. If an error occurs during loading of the
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	746 module and it was added to :data:`sys.modules` it is to be removed from the
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	747 dict. If an error occurs but the module was already in :data:`sys.modules` it
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	748 is left in the dict.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	749
52535 ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	750 .. index::
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	751 single: __name__
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	752 single: __file__
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	753 single: __path__
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	754 single: __package__
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	755 single: __loader__
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	756
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	757 The loader must set several attributes on the module. :data:`__name__` is to be
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	758 set to the name of the module. :data:`__file__` is to be the "path" to the file
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	759 unless the module is built-in (and thus listed in
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	760 :data:`sys.builtin_module_names`) in which case the attribute is not set.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	761 If what is being imported is a package then :data:`__path__` is to be set to a
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	762 list of paths to be searched when looking for modules and packages contained
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	763 within the package being imported. :data:`__package__` is optional but should
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	764 be set to the name of package that contains the module or package (the empty
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	765 string is used for module not contained in a package). :data:`__loader__` is
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	766 also optional but should be set to the loader object that is loading the
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	767 module.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	768
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	769 .. index::
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	770 exception: ImportError
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	771
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	772 If an error occurs during loading then the loader raises :exc:`ImportError` if
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	773 some other exception is not already being propagated. Otherwise the loader
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	774 returns the module that was loaded and initialized.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	775
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	776 When step (1) finishes without raising an exception, step (2) can begin.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	777
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	778 The first form of :keyword:`import` statement binds the module name in the local
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	779 namespace to the module object, and then goes on to import the next identifier,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	780 if any. If the module name is followed by :keyword:`as`, the name following
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	781 :keyword:`as` is used as the local name for the module.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	782
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	783 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	784 pair: name; binding
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	785 exception: ImportError
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	786
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	787 The :keyword:`from` form does not bind the module name: it goes through the list
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	788 of identifiers, looks each one of them up in the module found in step (1), and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	789 binds the name in the local namespace to the object thus found. As with the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	790 first form of :keyword:`import`, an alternate local name can be supplied by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	791 specifying ":keyword:`as` localname". If a name is not found,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	792 :exc:`ImportError` is raised. If the list of identifiers is replaced by a star
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	793 (``'*'``), all public names defined in the module are bound in the local
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	794 namespace of the :keyword:`import` statement..
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	795
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	796 .. index:: single: __all__ (optional module attribute)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	797
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	798 The public names defined by a module are determined by checking the module's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	799 namespace for a variable named ``__all__``; if defined, it must be a sequence of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	800 strings which are names defined or imported by that module. The names given in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	801 ``__all__`` are all considered public and are required to exist. If ``__all__``
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	802 is not defined, the set of public names includes all names found in the module's
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	803 namespace which do not begin with an underscore character (``'_'``).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	804 ``__all__`` should contain the entire public API. It is intended to avoid
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	805 accidentally exporting items that are not part of the API (such as library
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	806 modules which were imported and used within the module).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	807
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	808 The :keyword:`from` form with ``*`` may only occur in a module scope. If the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	809 wild card form of import --- ``import *`` --- is used in a function and the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	810 function contains or is a nested block with free variables, the compiler will
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	811 raise a :exc:`SyntaxError`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	812
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	813 .. index::
52535 ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	814 single: relative; import
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	815
52535 ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	816 When specifying what module to import you do not have to specify the absolute
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	817 name of the module. When a module or package is contained within another
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	818 package it is possible to make a relative import within the same top package
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	819 without having to mention the package name. By using leading dots in the
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	820 specified module or package after :keyword:`from` you can specify how high to
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	821 traverse up the current package hierarchy without specifying exact names. One
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	822 leading dot means the current package where the module making the import
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	823 exists. Two dots means up one package level. Three dots is up two levels, etc.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	824 So if you execute ``from . import mod`` from a module in the ``pkg`` package
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	825 then you will end up importing ``pkg.mod``. If you execute ``from ..subpkg2
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	826 imprt mod`` from within ``pkg.subpkg1`` you will import ``pkg.subpkg2.mod``.
ae60e4c20ae3 #5529: backport new docs of import semantics written by Brett to 2.x. Georg Brandl <georg@python.org> parents: 51701 diff changeset	827 The specification for relative imports is contained within :pep:`328`.
48127 4b72c7f63077 This should really be a comment. Georg Brandl <georg@python.org> parents: 47493 diff changeset	828
54052 a6c4cdfda9d6 importlib.import_module is better these days Benjamin Peterson <benjamin@python.org> parents: 53331 diff changeset	829 :func:`importlib.import_module` is provided to support applications that
a6c4cdfda9d6 importlib.import_module is better these days Benjamin Peterson <benjamin@python.org> parents: 53331 diff changeset	830 determine which modules need to be loaded dynamically.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	831
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	832
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	833 .. _future:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	834
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	835 Future statements
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	836 -----------------
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	837
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	838 .. index:: pair: future; statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	839
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	840 A :dfn:`future statement` is a directive to the compiler that a particular
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	841 module should be compiled using syntax or semantics that will be available in a
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	842 specified future release of Python. The future statement is intended to ease
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	843 migration to future versions of Python that introduce incompatible changes to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	844 the language. It allows use of the new features on a per-module basis before
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	845 the release in which the feature becomes standard.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	846
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	847 .. productionlist:: *
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	848 future_statement: "from" "__future__" "import" feature ["as" name]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	849 : ("," feature ["as" name])*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	850 : \| "from" "__future__" "import" "(" feature ["as" name]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	851 : ("," feature ["as" name])* [","] ")"
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	852 feature: identifier
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	853 name: identifier
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	854
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	855 A future statement must appear near the top of the module. The only lines that
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	856 can appear before a future statement are:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	857
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	858 * the module docstring (if any),
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	859 * comments,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	860 * blank lines, and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	861 * other future statements.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	862
49677 82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49244 diff changeset	863 The features recognized by Python 2.6 are ``unicode_literals``,
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49244 diff changeset	864 ``print_function``, ``absolute_import``, ``division``, ``generators``,
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49244 diff changeset	865 ``nested_scopes`` and ``with_statement``. ``generators``, ``with_statement``,
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49244 diff changeset	866 ``nested_scopes`` are redundant in Python version 2.6 and above because they are
82ccc7e77ec5 Merged revisions 66801,66803-66804,66813,66854-66856,66866,66870-66872,66874,66887,66903,66905,66911,66913,66927,66932,66938,66942,66962,66964,66973-66974,66977,66992,66998-66999,67002,67005,67007,67028,67040-67041,67044,67070,67089,67091,67101,67117-67119,67123-67124 via svnmerge from Georg Brandl <georg@python.org> parents: 49244 diff changeset	867 always enabled.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	868
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	869 A future statement is recognized and treated specially at compile time: Changes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	870 to the semantics of core constructs are often implemented by generating
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	871 different code. It may even be the case that a new feature introduces new
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	872 incompatible syntax (such as a new reserved word), in which case the compiler
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	873 may need to parse the module differently. Such decisions cannot be pushed off
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	874 until runtime.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	875
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	876 For any given release, the compiler knows which feature names have been defined,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	877 and raises a compile-time error if a future statement contains a feature not
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	878 known to it.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	879
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	880 The direct runtime semantics are the same as for any import statement: there is
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	881 a standard module :mod:`__future__`, described later, and it will be imported in
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	882 the usual way at the time the future statement is executed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	883
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	884 The interesting runtime semantics depend on the specific feature enabled by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	885 future statement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	886
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	887 Note that there is nothing special about the statement::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	888
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	889 import __future__ [as name]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	890
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	891 That is not a future statement; it's an ordinary import statement with no
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	892 special semantics or syntax restrictions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	893
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	894 Code compiled by an :keyword:`exec` statement or calls to the builtin functions
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	895 :func:`compile` and :func:`execfile` that occur in a module :mod:`M` containing
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	896 a future statement will, by default, use the new syntax or semantics associated
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	897 with the future statement. This can, starting with Python 2.2 be controlled by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	898 optional arguments to :func:`compile` --- see the documentation of that function
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	899 for details.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	900
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	901 A future statement typed at an interactive interpreter prompt will take effect
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	902 for the rest of the interpreter session. If an interpreter is started with the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	903 :option:`-i` option, is passed a script name to execute, and the script includes
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	904 a future statement, it will be in effect in the interactive session started
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	905 after the script is executed.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	906
53331 41bc33ee1730 Add link to PEP 236. Georg Brandl <georg@python.org> parents: 52541 diff changeset	907 .. seealso::
41bc33ee1730 Add link to PEP 236. Georg Brandl <georg@python.org> parents: 52541 diff changeset	908
41bc33ee1730 Add link to PEP 236. Georg Brandl <georg@python.org> parents: 52541 diff changeset	909 :pep:`236` - Back to the __future__
41bc33ee1730 Add link to PEP 236. Georg Brandl <georg@python.org> parents: 52541 diff changeset	910 The original proposal for the __future__ mechanism.
41bc33ee1730 Add link to PEP 236. Georg Brandl <georg@python.org> parents: 52541 diff changeset	911
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	912
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	913 .. _global:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	914
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	915 The :keyword:`global` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	916 ===============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	917
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	918 .. index::
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	919 statement: global
3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	920 triple: global; name; binding
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	921
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	922 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	923 global_stmt: "global" `identifier` ("," `identifier`)*
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	924
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	925 The :keyword:`global` statement is a declaration which holds for the entire
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	926 current code block. It means that the listed identifiers are to be interpreted
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	927 as globals. It would be impossible to assign to a global variable without
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	928 :keyword:`global`, although free variables may refer to globals without being
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	929 declared global.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	930
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	931 Names listed in a :keyword:`global` statement must not be used in the same code
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	932 block textually preceding that :keyword:`global` statement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	933
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	934 Names listed in a :keyword:`global` statement must not be defined as formal
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	935 parameters or in a :keyword:`for` loop control target, :keyword:`class`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	936 definition, function definition, or :keyword:`import` statement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	937
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	938 (The current implementation does not enforce the latter two restrictions, but
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	939 programs should not abuse this freedom, as future implementations may enforce
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	940 them or silently change the meaning of the program.)
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	941
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	942 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	943 statement: exec
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	944 builtin: eval
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	945 builtin: execfile
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	946 builtin: compile
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	947
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	948 Programmer's note: the :keyword:`global` is a directive to the parser. It
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	949 applies only to code parsed at the same time as the :keyword:`global` statement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	950 In particular, a :keyword:`global` statement contained in an :keyword:`exec`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	951 statement does not affect the code block containing the :keyword:`exec`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	952 statement, and code contained in an :keyword:`exec` statement is unaffected by
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	953 :keyword:`global` statements in the code containing the :keyword:`exec`
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	954 statement. The same applies to the :func:`eval`, :func:`execfile` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	955 :func:`compile` functions.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	956
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	957
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	958 .. _exec:
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	959
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	960 The :keyword:`exec` statement
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	961 =============================
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	962
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	963 .. index:: statement: exec
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	964
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	965 .. productionlist::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	966 exec_stmt: "exec" `or_expr` ["in" `expression` ["," `expression`]]
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	967
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	968 This statement supports dynamic execution of Python code. The first expression
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	969 should evaluate to either a string, an open file object, or a code object. If
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	970 it is a string, the string is parsed as a suite of Python statements which is
52541 a3b2a9706fc3 #992207: document that the parser only accepts \\n newlines. Georg Brandl <georg@python.org> parents: 52535 diff changeset	971 then executed (unless a syntax error occurs). [#]_ If it is an open file, the file
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	972 is parsed until EOF and executed. If it is a code object, it is simply
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	973 executed. In all cases, the code that's executed is expected to be valid as
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	974 file input (see section :ref:`file-input`). Be aware that the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	975 :keyword:`return` and :keyword:`yield` statements may not be used outside of
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	976 function definitions even within the context of code passed to the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	977 :keyword:`exec` statement.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	978
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	979 In all cases, if the optional parts are omitted, the code is executed in the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	980 current scope. If only the first expression after :keyword:`in` is specified,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	981 it should be a dictionary, which will be used for both the global and the local
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	982 variables. If two expressions are given, they are used for the global and local
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	983 variables, respectively. If provided, locals can be any mapping object.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	984
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	985 .. versionchanged:: 2.4
44496 3c6f7543bdd6 Simplify index entries; fix #1712. Georg Brandl <georg@python.org> parents: 44383 diff changeset	986 Formerly, locals was required to be a dictionary.
42603 c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	987
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	988 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	989 single: __builtins__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	990 module: __builtin__
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	991
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	992 As a side effect, an implementation may insert additional keys into the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	993 dictionaries given besides those corresponding to variable names set by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	994 executed code. For example, the current implementation may add a reference to
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	995 the dictionary of the built-in module :mod:`__builtin__` under the key
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	996 ``__builtins__`` (!).
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	997
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	998 .. index::
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	999 builtin: eval
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1000 builtin: globals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1001 builtin: locals
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1002
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1003 Programmer's hints: dynamic evaluation of expressions is supported by the
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1004 built-in function :func:`eval`. The built-in functions :func:`globals` and
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1005 :func:`locals` return the current global and local dictionary, respectively,
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1006 which may be useful to pass around for use by :keyword:`exec`.
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1007
c62f6669ae22 Move the 2.6 reST doc tree in place. Georg Brandl <georg@python.org> parents: diff changeset	1008
52541 a3b2a9706fc3 #992207: document that the parser only accepts \\n newlines. Georg Brandl <georg@python.org> parents: 52535 diff changeset	1009 .. rubric:: Footnotes
a3b2a9706fc3 #992207: document that the parser only accepts \\n newlines. Georg Brandl <georg@python.org> parents: 52535 diff changeset	1010
a3b2a9706fc3 #992207: document that the parser only accepts \\n newlines. Georg Brandl <georg@python.org> parents: 52535 diff changeset	1011 .. [#] Note that the parser only accepts the Unix-style end of line convention.
a3b2a9706fc3 #992207: document that the parser only accepts \\n newlines. Georg Brandl <georg@python.org> parents: 52535 diff changeset	1012 If you are reading the code from a file, make sure to use universal
a3b2a9706fc3 #992207: document that the parser only accepts \\n newlines. Georg Brandl <georg@python.org> parents: 52535 diff changeset	1013 newline mode to convert Windows or Mac-style newlines.

Mercurial > cpython-lru_cache-weakref

annotate Doc/reference/simple_stmts.rst @ 54294:dba767bc3155 legacy-trunk