sam-t2/devtools/v9/html/python/ref/assignment.html

<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
<html>
<head>
<link rel="STYLESHEET" href="ref.css" type='text/css' />
<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
<link rel='start' href='../index.html' title='Python Documentation Index' />
<link rel="first" href="ref.html" title='Python Reference Manual' />
<link rel='contents' href='contents.html' title="Contents" />
<link rel='index' href='genindex.html' title='Index' />
<link rel='last' href='about.html' title='About this document...' />
<link rel='help' href='about.html' title='About this document...' />
<link rel="next" href="pass.html" />
<link rel="prev" href="assert.html" />
<link rel="parent" href="simple.html" />
<link rel="next" href="augassign.html" />
<meta name='aesop' content='information' />
<title>6.3 Assignment statements </title>
</head>
<body>
<DIV CLASS="navigation">
<div id='top-navigation-panel' xml:id='top-navigation-panel'>
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="6.2 Assert statements"
  href="assert.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="6. Simple statements"
  href="simple.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6.3.1 Augmented assignment statements"
  href="augassign.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="assert.html">6.2 Assert statements</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="simple.html">6. Simple statements</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="augassign.html">6.3.1 Augmented assignment statements</A>
</div>
<hr /></div>
</DIV>
<!--End of Navigation Panel-->

<H1><A NAME="SECTION008300000000000000000"></A><A NAME="assignment"></A>
<BR>
6.3 Assignment statements
</H1>

<P>
Assignment statements<a id='l2h-465' xml:id='l2h-465'></a> are used to
(re)bind names to values and to modify attributes or items of mutable
objects:
<a id='l2h-466' xml:id='l2h-466'></a><a id='l2h-467' xml:id='l2h-467'></a><a id='l2h-468' xml:id='l2h-468'></a><a id='l2h-469' xml:id='l2h-469'></a>
<P>
<dl><dd class="grammar">
<div class="productions">
<table>
<tr>
    <td><a id='tok-assignment_stmt' xml:id='tok-assignment_stmt'>assignment_stmt</a></td>
    <td>::=</td>
    <td>(<a class='grammartoken' href="assignment.html#tok-target_list">target_list</a> "=")+ <a class='grammartoken' href="exprlists.html#tok-expression_list">expression_list</a></td></tr>
  <tr>
    <td><a id='tok-target_list' xml:id='tok-target_list'>target_list</a></td>
    <td>::=</td>
    <td><a class='grammartoken' href="assignment.html#tok-target">target</a> ("," <a class='grammartoken' href="assignment.html#tok-target">target</a>)* [","]</td></tr>
  <tr>
    <td><a id='tok-target' xml:id='tok-target'>target</a></td>
    <td>::=</td>
    <td><a class='grammartoken' href="identifiers.html#tok-identifier">identifier</a></td></tr>
  <tr>
    <td></td>
    <td></td>
    <td><code>| "(" <a class='grammartoken' href="assignment.html#tok-target_list">target_list</a> ")"</code></td></tr>
  <tr>
    <td></td>
    <td></td>
    <td><code>| "[" <a class='grammartoken' href="assignment.html#tok-target_list">target_list</a> "]"</code></td></tr>
  <tr>
    <td></td>
    <td></td>
    <td><code>| <a class='grammartoken' href="attribute-references.html#tok-attributeref">attributeref</a></code></td></tr>
  <tr>
    <td></td>
    <td></td>
    <td><code>| <a class='grammartoken' href="subscriptions.html#tok-subscription">subscription</a></code></td></tr>
  <tr>
    <td></td>
    <td></td>
    <td><code>| <a class='grammartoken' href="slicings.html#tok-slicing">slicing</a></code></td></tr>
</table>
</div>
<a class="grammar-footer"
  href="grammar.txt" type="text/plain"
  >Download entire grammar as text.</a>
</dd></dl>

<P>
(See section&nbsp;<A href="primaries.html#primaries">5.3</A> for the syntax definitions for the last
three symbols.)

<P>
An assignment statement evaluates the expression list (remember that
this can be a single expression or a comma-separated list, the latter
yielding a tuple) and assigns the single resulting object to each of
the target lists, from left to right.
<a id='l2h-470' xml:id='l2h-470'></a>
<P>
Assignment is defined recursively depending on the form of the target
(list).  When a target is part of a mutable object (an attribute
reference, subscription or slicing), the mutable object must
ultimately perform the assignment and decide about its validity, and
may raise an exception if the assignment is unacceptable.  The rules
observed by various types and the exceptions raised are given with the
definition of the object types (see section&nbsp;<A href="types.html#types">3.2</A>).
<a id='l2h-482' xml:id='l2h-482'></a>
<a id='l2h-471' xml:id='l2h-471'></a>
<P>
Assignment of an object to a target list is recursively defined as
follows.
<a id='l2h-472' xml:id='l2h-472'></a>
<P>

<UL>
<LI>If the target list is a single target: The object is assigned to that
target.

<P>
</LI>
<LI>If the target list is a comma-separated list of targets: The object
must be a sequence with the same number of items as there are
targets in the target list, and the items are assigned, from left to
right, to the corresponding targets.  (This rule is relaxed as of
Python 1.5; in earlier versions, the object had to be a tuple.  Since
strings are sequences, an assignment like "<tt class="samp">a, b = "xy"</tt>" is
now legal as long as the string has the right length.)

<P>
</LI>
</UL>

<P>
Assignment of an object to a single target is recursively defined as
follows.

<P>


<UL>
<LI>If the target is an identifier (name):

<P>

<UL>
<LI>If the name does not occur in a <tt class="keyword">global</tt> statement in the current
code block: the name is bound to the object in the current local
namespace.
<a id='l2h-473' xml:id='l2h-473'></a>
<P>
</LI>
<LI>Otherwise: the name is bound to the object in the current global
namespace.

<P>
</LI>
</UL>
<P>
The name is rebound if it was already bound.  This may cause the
reference count for the object previously bound to the name to reach
zero, causing the object to be deallocated and its
destructor<a id='l2h-483' xml:id='l2h-483'></a> (if it has one) to be called.

<P>
</LI>
<LI>If the target is a target list enclosed in parentheses or in square
brackets: The object must be a sequence with the same number of items
as there are targets in the target list, and its items are assigned,
from left to right, to the corresponding targets.

<P>
</LI>
<LI>If the target is an attribute reference: The primary expression in the
reference is evaluated.  It should yield an object with assignable
attributes; if this is not the case, <tt class="exception">TypeError</tt> is raised.  That
object is then asked to assign the assigned object to the given
attribute; if it cannot perform the assignment, it raises an exception
(usually but not necessarily <tt class="exception">AttributeError</tt>).
<a id='l2h-474' xml:id='l2h-474'></a>
<P>
</LI>
<LI>If the target is a subscription: The primary expression in the
reference is evaluated.  It should yield either a mutable sequence
object (such as a list) or a mapping object (such as a dictionary). Next,
the subscript expression is evaluated.
<a id='l2h-475' xml:id='l2h-475'></a><a id='l2h-476' xml:id='l2h-476'></a>
<P>
If the primary is a mutable sequence object (such as a list), the subscript
must yield a plain integer.  If it is negative, the sequence's length
is added to it.  The resulting value must be a nonnegative integer
less than the sequence's length, and the sequence is asked to assign
the assigned object to its item with that index.  If the index is out
of range, <tt class="exception">IndexError</tt> is raised (assignment to a subscripted
sequence cannot add new items to a list).
<a id='l2h-477' xml:id='l2h-477'></a><a id='l2h-478' xml:id='l2h-478'></a>
<P>
If the primary is a mapping object (such as a dictionary), the subscript must
have a type compatible with the mapping's key type, and the mapping is
then asked to create a key/datum pair which maps the subscript to
the assigned object.  This can either replace an existing key/value
pair with the same key value, or insert a new key/value pair (if no
key with the same value existed).
<a id='l2h-479' xml:id='l2h-479'></a><a id='l2h-480' xml:id='l2h-480'></a>
<P>
</LI>
<LI>If the target is a slicing: The primary expression in the reference is
evaluated.  It should yield a mutable sequence object (such as a list).  The
assigned object should be a sequence object of the same type.  Next,
the lower and upper bound expressions are evaluated, insofar they are
present; defaults are zero and the sequence's length.  The bounds
should evaluate to (small) integers.  If either bound is negative, the
sequence's length is added to it.  The resulting bounds are clipped to
lie between zero and the sequence's length, inclusive.  Finally, the
sequence object is asked to replace the slice with the items of the
assigned sequence.  The length of the slice may be different from the
length of the assigned sequence, thus changing the length of the
target sequence, if the object allows it.
<a id='l2h-481' xml:id='l2h-481'></a>
<P>
</LI>
</UL>

<P>
(In the current implementation, the syntax for targets is taken
to be the same as for expressions, and invalid syntax is rejected
during the code generation phase, causing less detailed error
messages.)

<P>
WARNING: Although the definition of assignment implies that overlaps
between the left-hand side and the right-hand side are `safe' (for example
"<tt class="samp">a, b = b, a</tt>" swaps two variables), overlaps <em>within</em> the
collection of assigned-to variables are not safe!  For instance, the
following program prints "<tt class="samp">[0, 2]</tt>":

<P>
<div class="verbatim"><pre>
x = [0, 1]
i = 0
i, x[i] = 1, 2
print x
</pre></div>

<P>

<p><br /></p><hr class='online-navigation' />
<div class='online-navigation'>
<!--Table of Child-Links-->
<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>

<UL CLASS="ChildLinks">
<LI><A href="augassign.html">6.3.1 Augmented assignment statements</a>
</ul>
<!--End of Table of Child-Links-->
</div>

<DIV CLASS="navigation">
<div class='online-navigation'>
<p></p><hr />
<table align="center" width="100%" cellpadding="0" cellspacing="2">
<tr>
<td class='online-navigation'><a rel="prev" title="6.2 Assert statements"
  href="assert.html"><img src='../icons/previous.png'
  border='0' height='32'  alt='Previous Page' width='32' /></A></td>
<td class='online-navigation'><a rel="parent" title="6. Simple statements"
  href="simple.html"><img src='../icons/up.png'
  border='0' height='32'  alt='Up One Level' width='32' /></A></td>
<td class='online-navigation'><a rel="next" title="6.3.1 Augmented assignment statements"
  href="augassign.html"><img src='../icons/next.png'
  border='0' height='32'  alt='Next Page' width='32' /></A></td>
<td align="center" width="100%">Python Reference Manual</td>
<td class='online-navigation'><a rel="contents" title="Table of Contents"
  href="contents.html"><img src='../icons/contents.png'
  border='0' height='32'  alt='Contents' width='32' /></A></td>
<td class='online-navigation'><img src='../icons/blank.png'
  border='0' height='32'  alt='' width='32' /></td>
<td class='online-navigation'><a rel="index" title="Index"
  href="genindex.html"><img src='../icons/index.png'
  border='0' height='32'  alt='Index' width='32' /></A></td>
</tr></table>
<div class='online-navigation'>
<b class="navlabel">Previous:</b>
<a class="sectref" rel="prev" href="assert.html">6.2 Assert statements</A>
<b class="navlabel">Up:</b>
<a class="sectref" rel="parent" href="simple.html">6. Simple statements</A>
<b class="navlabel">Next:</b>
<a class="sectref" rel="next" href="augassign.html">6.3.1 Augmented assignment statements</A>
</div>
</div>
<hr />
<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
</DIV>
<!--End of Navigation Panel-->
<ADDRESS>
See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
</ADDRESS>
</BODY>
</HTML>