node12.html | tut.html | node14.html | Python Tutorial | node2.html
Previous:
10. What Now? (node12.html)
Up:
Python Tutorial (tut.html)
Next:
B. Floating Point Arithmetic: (node14.html)
---
- A.1 Line Editing (node13.html#SECTION0013100000000000000000)
  A.2 History Substitution (node13.html#SECTION0013200000000000000000)
  A.3 Key Bindings (node13.html#SECTION0013300000000000000000)
  A.4 Commentary (node13.html#SECTION0013400000000000000000)
---
# A. Interactive Input Editing and History Substitution
Some versions of the Python interpreter support editing of the current
input line and history substitution, similar to facilities found in
the Korn shell and the GNU Bash shell. This is implemented using the
GNU Readline library, which supports Emacs-style and vi-style
editing. This library has its own documentation which I won't
duplicate here; however, the basics are easily explained. The
interactive editing and history described here are optionally
available in the Unix and CygWin versions of the interpreter.
This chapter does not document the editing facilities of Mark
Hammond's PythonWin package or the Tk-based environment, IDLE,
distributed with Python. The command line history recall which
operates within DOS boxes on NT and some other DOS and Windows flavors
is yet another beast.
# A.1 Line Editing
If supported, input line editing is active whenever the interpreter
prints a primary or secondary prompt. The current line can be edited
using the conventional Emacs control characters. The most important
of these are: C-A (Control-A) moves the cursor to the beginning
of the line, C-E to the end, C-B moves it one position to
the left, C-F to the right. Backspace erases the character to
the left of the cursor, C-D the character to its right.
C-K kills (erases) the rest of the line to the right of the
cursor, C-Y yanks back the last killed string.
C-underscore undoes the last change you made; it can be repeated
for cumulative effect.
# A.2 History Substitution
History substitution works as follows. All non-empty input lines
issued are saved in a history buffer, and when a new prompt is given
you are positioned on a new line at the bottom of this buffer.
C-P moves one line up (back) in the history buffer,
C-N moves one down. Any line in the history buffer can be
edited; an asterisk appears in front of the prompt to mark a line as
modified. Pressing the Return key passes the current line to
the interpreter. C-R starts an incremental reverse search;
C-S starts a forward search.
# A.3 Key Bindings
The key bindings and some other parameters of the Readline library can
be customized by placing commands in an initialization file called
~/.inputrc. Key bindings have the form
```text

key-name: function-name
```
or
```text

"string": function-name
```
and options can be set with
```text

set option-name value
```
For example:
```text

# I prefer vi-style editing:
set editing-mode vi

# Edit using a single line:
set horizontal-scroll-mode On

# Rebind some keys:
Meta-h: backward-kill-word
"\C-u": universal-argument
"\C-x\C-r": re-read-init-file
```
Note that the default binding for Tab in Python is to insert a
Tab character instead of Readline's default filename completion
function. If you insist, you can override this by putting
```text

Tab: complete
```
in your ~/.inputrc. (Of course, this makes it harder to
type indented continuation lines.)
Automatic completion of variable and module names is optionally
available. To enable it in the interpreter's interactive mode, add
the following to your startup file:A.1 (#foot1534)
```text

import rlcompleter, readline
readline.parse_and_bind('tab: complete')
```
This binds the Tab key to the completion function, so hitting
the Tab key twice suggests completions; it looks at Python
statement names, the current local variables, and the available module
names. For dotted expressions such as `string.a`, it will
evaluate the the expression up to the final "." and then
suggest completions from the attributes of the resulting object. Note
that this may execute application-defined code if an object with a
__getattr__() method is part of the expression.
A more capable startup file might look like this example. Note that
this deletes the names it creates once they are no longer needed; this
is done since the startup file is executed in the same namespace as
the interactive commands, and removing the names avoids creating side
effects in the interactive environments. You may find it convenient
to keep some of the imported modules, such as os, which turn
out to be needed in most sessions with the interpreter.
```text

# Add auto-completion and a stored history file of commands to your Python
# interactive interpreter. Requires Python 2.0+, readline. Autocomplete is
# bound to the Esc key by default (you can change it - see readline docs).
#
# Store the file in ~/.pystartup, and set an environment variable to point
# to it: "export PYTHONSTARTUP=/max/home/itamar/.pystartup" in bash.
#
# Note that PYTHONSTARTUP does *not* expand "~", so you have to put in the
# full path to your home directory.

import atexit
import os
import readline
import rlcompleter

historyPath = os.path.expanduser("~/.pyhistory")

def save_history(historyPath=historyPath):
import readline
readline.write_history_file(historyPath)

if os.path.exists(historyPath):
readline.read_history_file(historyPath)

atexit.register(save_history)
del os, atexit, readline, rlcompleter, save_history, historyPath
```
# A.4 Commentary
This facility is an enormous step forward compared to earlier versions
of the interpreter; however, some wishes are left: It would be nice if
the proper indentation were suggested on continuation lines (the
parser knows if an indent token is required next). The completion
mechanism might use the interpreter's symbol table. A command to
check (or even suggest) matching parentheses, quotes, etc., would also
be useful.


node13.html | tut.html | node15.html | Python Tutorial | node2.html
Previous:
A. Interactive Input Editing (node13.html)
Up:
Python Tutorial (tut.html)
Next:
C. History and License (node15.html)
---
- B.1 Representation Error (node14.html#SECTION0014100000000000000000)
---
# B. Floating Point Arithmetic: Issues and Limitations
Floating-point numbers are represented in computer hardware as
base 2 (binary) fractions. For example, the decimal fraction
```text

0.125
```
has value 1/10 + 2/100 + 5/1000, and in the same way the binary fraction
```text

0.001
```
has value 0/2 + 0/4 + 1/8. These two fractions have identical values,
the only real difference being that the first is written in base 10
fractional notation, and the second in base 2.
Unfortunately, most decimal fractions cannot be represented exactly as
binary fractions. A consequence is that, in general, the decimal
floating-point numbers you enter are only approximated by the binary
floating-point numbers actually stored in the machine.
The problem is easier to understand at first in base 10. Consider the
fraction 1/3. You can approximate that as a base 10 fraction:
```text

0.3
```
or, better,
```text

0.33
```
or, better,
```text

0.333
```
and so on. No matter how many digits you're willing to write down, the
result will never be exactly 1/3, but will be an increasingly better
approximation to 1/3.
In the same way, no matter how many base 2 digits you're willing to
use, the decimal value 0.1 cannot be represented exactly as a base 2
fraction. In base 2, 1/10 is the infinitely repeating fraction
```text

0.0001100110011001100110011001100110011001100110011...
```
Stop at any finite number of bits, and you get an approximation. This
is why you see things like:
```text

>>> 0.1
0.10000000000000001
```
On most machines today, that is what you'll see if you enter 0.1 at
a Python prompt. You may not, though, because the number of bits
used by the hardware to store floating-point values can vary across
machines, and Python only prints a decimal approximation to the true
decimal value of the binary approximation stored by the machine. On
most machines, if Python were to print the true decimal value of
the binary approximation stored for 0.1, it would have to display
```text

>>> 0.1
0.1000000000000000055511151231257827021181583404541015625
```
instead! The Python prompt (implicitly) uses the builtin
repr() function to obtain a string version of everything it
displays. For floats, `repr( float )` rounds the true
decimal value to 17 significant digits, giving
```text

0.10000000000000001
```
`repr( float )` produces 17 significant digits because it
turns out that's enough (on most machines) so that
`eval(repr( x )) == x` exactly for all finite floats
x, but rounding to 16 digits is not enough to make that true.
Note that this is in the very nature of binary floating-point: this is
not a bug in Python, it is not a bug in your code either, and you'll
see the same kind of thing in all languages that support your
hardware's floating-point arithmetic (although some languages may
not display the difference by default, or in all output modes).
Python's builtin str() function produces only 12
significant digits, and you may wish to use that instead. It's
unusual for `eval(str( x ))` to reproduce x, but the
output may be more pleasant to look at:
```text

>>> print str(0.1)
0.1
```
It's important to realize that this is, in a real sense, an illusion:
the value in the machine is not exactly 1/10, you're simply rounding
the display of the true machine value.
Other surprises follow from this one. For example, after seeing
```text

>>> 0.1
0.10000000000000001
```
you may be tempted to use the round() function to chop it
back to the single digit you expect. But that makes no difference:
```text

>>> round(0.1, 1)
0.10000000000000001
```
The problem is that the binary floating-point value stored for "0.1"
was already the best possible binary approximation to 1/10, so trying
to round it again can't make it better: it was already as good as it
gets.
Another consequence is that since 0.1 is not exactly 1/10, adding 0.1
to itself 10 times may not yield exactly 1.0, either:
```text

>>> sum = 0.0
>>> for i in range(10):
... sum += 0.1
...
>>> sum
0.99999999999999989
```
Binary floating-point arithmetic holds many surprises like this. The
problem with "0.1" is explained in precise detail below, in the
"Representation Error" section. See
The Perils of Floating
Point (http://www.lahey.com/float.htm) for a more complete account of other common surprises.
As that says near the end, ``there are no easy answers.'' Still,
don't be unduly wary of floating-point! The errors in Python float
operations are inherited from the floating-point hardware, and on most
machines are on the order of no more than 1 part in 2**53 per
operation. That's more than adequate for most tasks, but you do need
to keep in mind that it's not decimal arithmetic, and that every float
operation can suffer a new rounding error.
While pathological cases do exist, for most casual use of
floating-point arithmetic you'll see the result you expect in the end
if you simply round the display of your final results to the number of
decimal digits you expect. str() usually suffices, and for
finer control see the discussion of Pythons's `%` format
operator: the `%g`, `%f` and `%e` format codes
supply flexible and easy ways to round float results for display.
# B.1 Representation Error
This section explains the ``0.1'' example in detail, and shows how
you can perform an exact analysis of cases like this yourself. Basic
familiarity with binary floating-point representation is assumed.
Representation error refers to that some (most, actually)
decimal fractions cannot be represented exactly as binary (base 2)
fractions. This is the chief reason why Python (or Perl, C, C++,
Java, Fortran, and many others) often won't display the exact decimal
number you expect:
```text

>>> 0.1
0.10000000000000001
```
Why is that? 1/10 is not exactly representable as a binary fraction.
Almost all machines today (November 2000) use IEEE-754 floating point
arithmetic, and almost all platforms map Python floats to IEEE-754
"double precision". 754 doubles contain 53 bits of precision, so on
input the computer strives to convert 0.1 to the closest fraction it can
of the form J/2**N where J is an integer containing
exactly 53 bits. Rewriting
```text

1 / 10 ~= J / (2**N)
```
as
```text

J ~= 2**N / 10
```
and recalling that J has exactly 53 bits (is `>= 2**52` but
`< 2**53`), the best value for N is 56:
```text

>>> 2L**52
4503599627370496L
>>> 2L**53
9007199254740992L
>>> 2L**56/10
7205759403792793L
```
That is, 56 is the only value for N that leaves J with
exactly 53 bits. The best possible value for J is then that
quotient rounded:
```text

>>> q, r = divmod(2L**56, 10)
>>> r
6L
```
Since the remainder is more than half of 10, the best approximation is
obtained by rounding up:
```text

>>> q+1
7205759403792794L
```
Therefore the best possible approximation to 1/10 in 754 double
precision is that over 2**56, or
```text

7205759403792794 / 72057594037927936
```
Note that since we rounded up, this is actually a little bit larger than
1/10; if we had not rounded up, the quotient would have been a little
bit smaller than 1/10. But in no case can it be exactly 1/10!
So the computer never ``sees'' 1/10: what it sees is the exact
fraction given above, the best 754 double approximation it can get:
```text

>>> .1 * 2L**56
7205759403792794.0
```
If we multiply that fraction by 10**30, we can see the (truncated)
value of its 30 most significant decimal digits:
```text

>>> 7205759403792794L * 10L**30 / 2L**56
100000000000000005551115123125L
```
meaning that the exact number stored in the computer is approximately
equal to the decimal value 0.100000000000000005551115123125. Rounding
that to 17 significant digits gives the 0.10000000000000001 that Python
displays (well, will display on any 754-conforming platform that does
best-possible input and output conversions in its C library -- yours may
not!).


C. History and License

node14.html | tut.html | node16.html | Python Tutorial | node2.html
Previous:
B. Floating Point Arithmetic: (node14.html)
Up:
Python Tutorial (tut.html)
Next:
About this document ... (node16.html)
---
- C.1 History of the software (node15.html#SECTION0015100000000000000000)
  C.2 Terms and conditions for accessing or otherwise using Python (node15.html#SECTION0015200000000000000000)
---
# C. History and License
# C.1 History of the software
Python was created in the early 1990s by Guido van Rossum at Stichting
Mathematisch Centrum (CWI, see http://www.cwi.nl/) in the Netherlands
as a successor of a language called ABC. Guido remains Python's
principal author, although it includes many contributions from others.
In 1995, Guido continued his work on Python at the Corporation for
National Research Initiatives (CNRI, see http://www.cnri.reston.va.us/)
in Reston, Virginia where he released several versions of the
software.
In May 2000, Guido and the Python core development team moved to
BeOpen.com to form the BeOpen PythonLabs team. In October of the same
year, the PythonLabs team moved to Digital Creations (now Zope
Corporation; see http://www.zope.com/). In 2001, the Python
Software Foundation (PSF, see http://www.python.org/psf/) was
formed, a non-profit organization created specifically to own
Python-related Intellectual Property. Zope Corporation is a
sponsoring member of the PSF.
All Python releases are Open Source (see
http://www.opensource.org/ for the Open Source Definition).
Historically, most, but not all, Python releases have also been
GPL-compatible; the table below summarizes the various releases.
Note:
GPL-compatible doesn't mean that we're distributing
Python under the GPL. All Python licenses, unlike the GPL, let you
distribute a modified version without making your changes open source.
The GPL-compatible licenses make it possible to combine Python with
other software that is released under the GPL; the others don't.
Thanks to the many outside volunteers who have worked under Guido's
direction to make these releases possible.
# C.2 Terms and conditions for accessing or otherwise using Python
PSF LICENSE AGREEMENT FOR PYTHON 2.3
1. This LICENSE AGREEMENT is between the Python Software Foundation
(``PSF''), and the Individual or Organization (``Licensee'') accessing
and otherwise using Python 2.3 software in source or binary
form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, PSF
hereby grants Licensee a nonexclusive, royalty-free, world-wide
license to reproduce, analyze, test, perform and/or display publicly,
prepare derivative works, distribute, and otherwise use Python
2.3 alone or in any derivative version, provided, however, that
PSF's License Agreement and PSF's notice of copyright, i.e.,
``Copyright © 2001-2003 Python Software Foundation; All
Rights Reserved'' are retained in Python 2.3 alone or in any
derivative version prepared by Licensee.
3. In the event Licensee prepares a derivative work that is based on
or incorporates Python 2.3 or any part thereof, and wants to
make the derivative work available to others as provided herein, then
Licensee hereby agrees to include in any such work a brief summary of
the changes made to Python 2.3.
4. PSF is making Python 2.3 available to Licensee on an ``AS IS''
basis. PSF MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, PSF MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 2.3 WILL
NOT INFRINGE ANY THIRD PARTY RIGHTS.
5. PSF SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
2.3 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR
LOSS AS A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON
2.3, OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE
POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
7. Nothing in this License Agreement shall be deemed to create any
relationship of agency, partnership, or joint venture between PSF and
Licensee. This License Agreement does not grant permission to use PSF
trademarks or trade name in a trademark sense to endorse or promote
products or services of Licensee, or any third party.
8. By copying, installing or otherwise using Python 2.3, Licensee
agrees to be bound by the terms and conditions of this License
Agreement.
BEOPEN.COM LICENSE AGREEMENT FOR PYTHON 2.0
BEOPEN PYTHON OPEN SOURCE LICENSE AGREEMENT VERSION 1
1. This LICENSE AGREEMENT is between BeOpen.com (``BeOpen''), having an
office at 160 Saratoga Avenue, Santa Clara, CA 95051, and the
Individual or Organization (``Licensee'') accessing and otherwise
using this software in source or binary form and its associated
documentation (``the Software'').
2. Subject to the terms and conditions of this BeOpen Python License
Agreement, BeOpen hereby grants Licensee a non-exclusive,
royalty-free, world-wide license to reproduce, analyze, test, perform
and/or display publicly, prepare derivative works, distribute, and
otherwise use the Software alone or in any derivative version,
provided, however, that the BeOpen Python License is retained in the
Software, alone or in any derivative version prepared by Licensee.
3. BeOpen is making the Software available to Licensee on an ``AS IS''
basis. BEOPEN MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, BEOPEN MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE SOFTWARE WILL NOT
INFRINGE ANY THIRD PARTY RIGHTS.
4. BEOPEN SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF THE
SOFTWARE FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS
AS A RESULT OF USING, MODIFYING OR DISTRIBUTING THE SOFTWARE, OR ANY
DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
5. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
6. This License Agreement shall be governed by and interpreted in all
respects by the law of the State of California, excluding conflict of
law provisions. Nothing in this License Agreement shall be deemed to
create any relationship of agency, partnership, or joint venture
between BeOpen and Licensee. This License Agreement does not grant
permission to use BeOpen trademarks or trade names in a trademark
sense to endorse or promote products or services of Licensee, or any
third party. As an exception, the ``BeOpen Python'' logos available
at http://www.pythonlabs.com/logos.html may be used according to the
permissions granted on that web page.
7. By copying, installing or otherwise using the software, Licensee
agrees to be bound by the terms and conditions of this License
Agreement.
CNRI LICENSE AGREEMENT FOR PYTHON 1.6.1
1. This LICENSE AGREEMENT is between the Corporation for National
Research Initiatives, having an office at 1895 Preston White Drive,
Reston, VA 20191 (``CNRI''), and the Individual or Organization
(``Licensee'') accessing and otherwise using Python 1.6.1 software in
source or binary form and its associated documentation.
2. Subject to the terms and conditions of this License Agreement, CNRI
hereby grants Licensee a nonexclusive, royalty-free, world-wide
license to reproduce, analyze, test, perform and/or display publicly,
prepare derivative works, distribute, and otherwise use Python 1.6.1
alone or in any derivative version, provided, however, that CNRI's
License Agreement and CNRI's notice of copyright, i.e., ``Copyright
© 1995-2001 Corporation for National Research Initiatives;
All Rights Reserved'' are retained in Python 1.6.1 alone or in any
derivative version prepared by Licensee. Alternately, in lieu of
CNRI's License Agreement, Licensee may substitute the following text
(omitting the quotes): ``Python 1.6.1 is made available subject to the
terms and conditions in CNRI's License Agreement. This Agreement
together with Python 1.6.1 may be located on the Internet using the
following unique, persistent identifier (known as a handle):
1895.22/1013. This Agreement may also be obtained from a proxy server
on the Internet using the following URL:
http://hdl.handle.net/1895.22/1013.''
3. In the event Licensee prepares a derivative work that is based on
or incorporates Python 1.6.1 or any part thereof, and wants to make
the derivative work available to others as provided herein, then
Licensee hereby agrees to include in any such work a brief summary of
the changes made to Python 1.6.1.
4. CNRI is making Python 1.6.1 available to Licensee on an ``AS IS''
basis. CNRI MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR
IMPLIED. BY WAY OF EXAMPLE, BUT NOT LIMITATION, CNRI MAKES NO AND
DISCLAIMS ANY REPRESENTATION OR WARRANTY OF MERCHANTABILITY OR FITNESS
FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF PYTHON 1.6.1 WILL NOT
INFRINGE ANY THIRD PARTY RIGHTS.
5. CNRI SHALL NOT BE LIABLE TO LICENSEE OR ANY OTHER USERS OF PYTHON
1.6.1 FOR ANY INCIDENTAL, SPECIAL, OR CONSEQUENTIAL DAMAGES OR LOSS AS
A RESULT OF MODIFYING, DISTRIBUTING, OR OTHERWISE USING PYTHON 1.6.1,
OR ANY DERIVATIVE THEREOF, EVEN IF ADVISED OF THE POSSIBILITY THEREOF.
6. This License Agreement will automatically terminate upon a material
breach of its terms and conditions.
7. This License Agreement shall be governed by the federal
intellectual property law of the United States, including without
limitation the federal copyright law, and, to the extent such
U.S. federal law does not apply, by the law of the Commonwealth of
Virginia, excluding Virginia's conflict of law provisions.
Notwithstanding the foregoing, with regard to derivative works based
on Python 1.6.1 that incorporate non-separable material that was
previously distributed under the GNU General Public License (GPL), the
law of the Commonwealth of Virginia shall govern this License
Agreement only as to issues arising under or with respect to
Paragraphs 4, 5, and 7 of this License Agreement. Nothing in this
License Agreement shall be deemed to create any relationship of
agency, partnership, or joint venture between CNRI and Licensee. This
License Agreement does not grant permission to use CNRI trademarks or
trade name in a trademark sense to endorse or promote products or
services of Licensee, or any third party.
8. By clicking on the ``ACCEPT'' button where indicated, or by copying,
installing or otherwise using Python 1.6.1, Licensee agrees to be
bound by the terms and conditions of this License Agreement.
ACCEPT
CWI LICENSE AGREEMENT FOR PYTHON 0.9.0 THROUGH 1.2
Copyright © 1991 - 1995, Stichting Mathematisch Centrum
Amsterdam, The Netherlands. All rights reserved.
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted,
provided that the above copyright notice appear in all copies and that
both that copyright notice and this permission notice appear in
supporting documentation, and that the name of Stichting Mathematisch
Centrum or CWI not be used in advertising or publicity pertaining to
distribution of the software without specific, written prior
permission.
STICHTING MATHEMATISCH CENTRUM DISCLAIMS ALL WARRANTIES WITH REGARD TO
THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND
FITNESS, IN NO EVENT SHALL STICHTING MATHEMATISCH CENTRUM BE LIABLE
FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT
OF OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.


About this document ...

node15.html | tut.html | Python Tutorial | node2.html
Previous:
C. History and License (node15.html)
Up:
Python Tutorial (tut.html)
---
# About this document ...
Python Tutorial,
July 29, 2003, Release 2.3
This document was generated using the LaTeX2HTML (http://saftsack.fs.uni-bayreuth.de/~latex2ht/) translator.
LaTeX2HTML (http://saftsack.fs.uni-bayreuth.de/~latex2ht/) is Copyright ©
1993, 1994, 1995, 1996, 1997, Nikos
Drakos (http://cbl.leeds.ac.uk/nikos/personal.html), Computer Based Learning Unit, University of
Leeds, and Copyright © 1997, 1998, Ross
Moore (http://www.maths.mq.edu.au/~ross/), Mathematics Department, Macquarie University,
Sydney.
The application of LaTeX2HTML (http://saftsack.fs.uni-bayreuth.de/~latex2ht/) to the Python
documentation has been heavily tailored by Fred L. Drake,
Jr. Original navigation icons were contributed by Christopher
Petrilli.
---
## Comments and Questions
General comments and questions regarding this document should
be sent by email to python-docs@python.org (mailto:python-docs@python.org). If you find specific errors in
this document, either in the content or the presentation, please
report the bug at the Python Bug
Tracker (http://sourceforge.net/bugs/?group_id=5470) at SourceForge (http://sourceforge.net/).
Questions regarding how to use the information in this
document should be sent to the Python news group, comp.lang.python (news:comp.lang.python), or the Python mailing list (http://www.python.org/mailman/listinfo/python-list) (which is gated to the newsgroup and
carries the same content).
For any of these channels, please be sure not to send HTML email.
Thanks.


Contents

node1.html | tut.html | node3.html | Python Tutorial
Previous:
Front Matter (node1.html)
Up:
Python Tutorial (tut.html)
Next:
1. Whetting Your Appetite (node3.html)
---
## Contents
Table of Contents
- Front Matter (node1.html)
  1. Whetting Your Appetite (node3.html)
  2. Using the Python Interpreter (node4.html)
  - 2.1 Invoking the Interpreter (node4.html#SECTION004100000000000000000)
  - 2.1.1 Argument Passing (node4.html#SECTION004110000000000000000)
  2.1.2 Interactive Mode (node4.html#SECTION004120000000000000000)
  2.2 The Interpreter and Its Environment (node4.html#SECTION004200000000000000000)
  - 2.2.1 Error Handling (node4.html#SECTION004210000000000000000)
  2.2.2 Executable Python Scripts (node4.html#SECTION004220000000000000000)
  2.2.3 Source Code Encoding (node4.html#SECTION004230000000000000000)
  2.2.4 The Interactive Startup File (node4.html#SECTION004240000000000000000)
  3. An Informal Introduction to Python (node5.html)
  - 3.1 Using Python as a Calculator (node5.html#SECTION005100000000000000000)
  - 3.1.1 Numbers (node5.html#SECTION005110000000000000000)
  3.1.2 Strings (node5.html#SECTION005120000000000000000)
  3.1.3 Unicode Strings (node5.html#SECTION005130000000000000000)
  3.1.4 Lists (node5.html#SECTION005140000000000000000)
  3.2 First Steps Towards Programming (node5.html#SECTION005200000000000000000)
  4. More Control Flow Tools (node6.html)
  - 4.1 if Statements (node6.html#SECTION006100000000000000000)
  4.2 for Statements (node6.html#SECTION006200000000000000000)
  4.3 The range() Function (node6.html#SECTION006300000000000000000)
  4.4 break and continue Statements, and else Clauses on Loops (node6.html#SECTION006400000000000000000)
  4.5 pass Statements (node6.html#SECTION006500000000000000000)
  4.6 Defining Functions (node6.html#SECTION006600000000000000000)
  4.7 More on Defining Functions (node6.html#SECTION006700000000000000000)
  - 4.7.1 Default Argument Values (node6.html#SECTION006710000000000000000)
  4.7.2 Keyword Arguments (node6.html#SECTION006720000000000000000)
  4.7.3 Arbitrary Argument Lists (node6.html#SECTION006730000000000000000)
  4.7.4 Lambda Forms (node6.html#SECTION006740000000000000000)
  4.7.5 Documentation Strings (node6.html#SECTION006750000000000000000)
  5. Data Structures (node7.html)
  - 5.1 More on Lists (node7.html#SECTION007100000000000000000)
  - 5.1.1 Using Lists as Stacks (node7.html#SECTION007110000000000000000)
  5.1.2 Using Lists as Queues (node7.html#SECTION007120000000000000000)
  5.1.3 Functional Programming Tools (node7.html#SECTION007130000000000000000)
  5.1.4 List Comprehensions (node7.html#SECTION007140000000000000000)
  5.2 The del statement (node7.html#SECTION007200000000000000000)
  5.3 Tuples and Sequences (node7.html#SECTION007300000000000000000)
  5.4 Dictionaries (node7.html#SECTION007400000000000000000)
  5.5 Looping Techniques (node7.html#SECTION007500000000000000000)
  5.6 More on Conditions (node7.html#SECTION007600000000000000000)
  5.7 Comparing Sequences and Other Types (node7.html#SECTION007700000000000000000)
  6. Modules (node8.html)
  - 6.1 More on Modules (node8.html#SECTION008100000000000000000)
  - 6.1.1 The Module Search Path (node8.html#SECTION008110000000000000000)
  6.1.2 ``Compiled'' Python files (node8.html#SECTION008120000000000000000)
  6.2 Standard Modules (node8.html#SECTION008200000000000000000)
  6.3 The dir() Function (node8.html#SECTION008300000000000000000)
  6.4 Packages (node8.html#SECTION008400000000000000000)
  - 6.4.1 Importing * From a Package (node8.html#SECTION008410000000000000000)
  6.4.2 Intra-package References (node8.html#SECTION008420000000000000000)
  6.4.3 Packages in Multiple Directories (node8.html#SECTION008430000000000000000)
  7. Input and Output (node9.html)
  - 7.1 Fancier Output Formatting (node9.html#SECTION009100000000000000000)
  7.2 Reading and Writing Files (node9.html#SECTION009200000000000000000)
  - 7.2.1 Methods of File Objects (node9.html#SECTION009210000000000000000)
  7.2.2 The pickle Module (node9.html#SECTION009220000000000000000)
  8. Errors and Exceptions (node10.html)
  - 8.1 Syntax Errors (node10.html#SECTION0010100000000000000000)
  8.2 Exceptions (node10.html#SECTION0010200000000000000000)
  8.3 Handling Exceptions (node10.html#SECTION0010300000000000000000)
  8.4 Raising Exceptions (node10.html#SECTION0010400000000000000000)
  8.5 User-defined Exceptions (node10.html#SECTION0010500000000000000000)
  8.6 Defining Clean-up Actions (node10.html#SECTION0010600000000000000000)
  9. Classes (node11.html)
  - 9.1 A Word About Terminology (node11.html#SECTION0011100000000000000000)
  9.2 Python Scopes and Name Spaces (node11.html#SECTION0011200000000000000000)
  9.3 A First Look at Classes (node11.html#SECTION0011300000000000000000)
  - 9.3.1 Class Definition Syntax (node11.html#SECTION0011310000000000000000)
  9.3.2 Class Objects (node11.html#SECTION0011320000000000000000)
  9.3.3 Instance Objects (node11.html#SECTION0011330000000000000000)
  9.3.4 Method Objects (node11.html#SECTION0011340000000000000000)
  9.4 Random Remarks (node11.html#SECTION0011400000000000000000)
  9.5 Inheritance (node11.html#SECTION0011500000000000000000)
  - 9.5.1 Multiple Inheritance (node11.html#SECTION0011510000000000000000)
  9.6 Private Variables (node11.html#SECTION0011600000000000000000)
  9.7 Odds and Ends (node11.html#SECTION0011700000000000000000)
  9.8 Exceptions Are Classes Too (node11.html#SECTION0011800000000000000000)
  9.9 Iterators (node11.html#SECTION0011900000000000000000)
  9.10 Generators (node11.html#SECTION00111000000000000000000)
  10. What Now? (node12.html)
  A. Interactive Input Editing and History Substitution (node13.html)
  - A.1 Line Editing (node13.html#SECTION0013100000000000000000)
  A.2 History Substitution (node13.html#SECTION0013200000000000000000)
  A.3 Key Bindings (node13.html#SECTION0013300000000000000000)
  A.4 Commentary (node13.html#SECTION0013400000000000000000)
  B. Floating Point Arithmetic: Issues and Limitations (node14.html)
  - B.1 Representation Error (node14.html#SECTION0014100000000000000000)
  C. History and License (node15.html)
  - C.1 History of the software (node15.html#SECTION0015100000000000000000)
  C.2 Terms and conditions for accessing or otherwise using Python (node15.html#SECTION0015200000000000000000)
  About this document ... (node16.html)
End of Table of Contents


1. Whetting Your Appetite

node2.html | tut.html | node4.html | Python Tutorial | node2.html
Previous:
Contents (node2.html)
Up:
Python Tutorial (tut.html)
Next:
2. Using the Python (node4.html)
---
# 1. Whetting Your Appetite
If you ever wrote a large shell script, you probably know this
feeling: you'd love to add yet another feature, but it's already so
slow, and so big, and so complicated; or the feature involves a system
call or other function that is only accessible from C ...Usually
the problem at hand isn't serious enough to warrant rewriting the
script in C; perhaps the problem requires variable-length strings or
other data types (like sorted lists of file names) that are easy in
the shell but lots of work to implement in C, or perhaps you're not
sufficiently familiar with C.
Another situation: perhaps you have to work with several C libraries,
and the usual C write/compile/test/re-compile cycle is too slow. You
need to develop software more quickly. Possibly perhaps you've
written a program that could use an extension language, and you don't
want to design a language, write and debug an interpreter for it, then
tie it into your application.
In such cases, Python may be just the language for you. Python is
simple to use, but it is a real programming language, offering much
more structure and support for large programs than the shell has. On
the other hand, it also offers much more error checking than C, and,
being a very-high-level language, it has high-level data types
built in, such as flexible arrays and dictionaries that would cost you
days to implement efficiently in C. Because of its more general data
types Python is applicable to a much larger problem domain than
Awk or even Perl, yet many things are at least as easy
in Python as in those languages.
Python allows you to split up your program in modules that can be
reused in other Python programs. It comes with a large collection of
standard modules that you can use as the basis of your programs -- or
as examples to start learning to program in Python. There are also
built-in modules that provide things like file I/O, system calls,
sockets, and even interfaces to graphical user interface toolkits like Tk.
Python is an interpreted language, which can save you considerable time
during program development because no compilation and linking is
necessary. The interpreter can be used interactively, which makes it
easy to experiment with features of the language, to write throw-away
programs, or to test functions during bottom-up program development.
It is also a handy desk calculator.
Python allows writing very compact and readable programs. Programs
written in Python are typically much shorter than equivalent C or
C++ programs, for several reasons:
- the high-level data types allow you to express complex operations in a
single statement;
- statement grouping is done by indentation instead of begin/end
brackets;
- no variable or argument declarations are necessary.
Python is extensible: if you know how to program in C it is easy
to add a new built-in function or module to the interpreter, either to
perform critical operations at maximum speed, or to link Python
programs to libraries that may only be available in binary form (such
as a vendor-specific graphics library). Once you are really hooked,
you can link the Python interpreter into an application written in C
and use it as an extension or command language for that application.
By the way, the language is named after the BBC show ``Monty Python's
Flying Circus'' and has nothing to do with nasty reptiles. Making
references to Monty Python skits in documentation is not only allowed,
it is encouraged!
Now that you are all excited about Python, you'll want to examine it
in some more detail. Since the best way to learn a language is
using it, you are invited here to do so.
In the next chapter, the mechanics of using the interpreter are
explained. This is rather mundane information, but essential for
trying out the examples shown later.
The rest of the tutorial introduces various features of the Python
language and system through examples, beginning with simple
expressions, statements and data types, through functions and modules,
and finally touching upon advanced concepts like exceptions
and user-defined classes.


2. Using the Python Interpreter

node3.html | tut.html | node5.html | Python Tutorial | node2.html
Previous:
1. Whetting Your Appetite (node3.html)
Up:
Python Tutorial (tut.html)
Next:
3. An Informal Introduction (node5.html)
---
- 2.1 Invoking the Interpreter (node4.html#SECTION004100000000000000000)
  - 2.1.1 Argument Passing (node4.html#SECTION004110000000000000000)
  2.1.2 Interactive Mode (node4.html#SECTION004120000000000000000)
  2.2 The Interpreter and Its Environment (node4.html#SECTION004200000000000000000)
  - 2.2.1 Error Handling (node4.html#SECTION004210000000000000000)
  2.2.2 Executable Python Scripts (node4.html#SECTION004220000000000000000)
  2.2.3 Source Code Encoding (node4.html#SECTION004230000000000000000)
  2.2.4 The Interactive Startup File (node4.html#SECTION004240000000000000000)
---
# 2. Using the Python Interpreter
# 2.1 Invoking the Interpreter
The Python interpreter is usually installed as
/usr/local/bin/python on those machines where it is available;
putting /usr/local/bin in your Unix shell's search path
makes it possible to start it by typing the command
```text

python
```
to the shell. Since the choice of the directory where the interpreter
lives is an installation option, other places are possible; check with
your local Python guru or system administrator. (E.g.,
/usr/local/python is a popular alternative location.)
Typing an end-of-file character (Control-D on Unix,
Control-Z on Windows) at the primary prompt causes the
interpreter to exit with a zero exit status. If that doesn't work,
you can exit the interpreter by typing the following commands:
"import sys; sys.exit()".
The interpreter's line-editing features usually aren't very
sophisticated. On Unix, whoever installed the interpreter may have
enabled support for the GNU readline library, which adds more
elaborate interactive editing and history features. Perhaps the
quickest check to see whether command line editing is supported is
typing Control-P to the first Python prompt you get. If it beeps, you
have command line editing; see Appendix A (node13.html#interacting) for an
introduction to the keys. If nothing appears to happen, or if
`P` is echoed, command line editing isn't available; you'll
only be able to use backspace to remove characters from the current
line.
The interpreter operates somewhat like the Unix shell: when called
with standard input connected to a tty device, it reads and executes
commands interactively; when called with a file name argument or with
a file as standard input, it reads and executes a script from
that file.
A third way of starting the interpreter is
"python -c command [arg] ...", which
executes the statement(s) in command, analogous to the shell's
-c option. Since Python statements often contain spaces
or other characters that are special to the shell, it is best to quote
command in its entirety with double quotes.
Note that there is a difference between "python file" and
"python <file". In the latter case, input requests from the
program, such as calls to input() and raw_input(), are
satisfied from file. Since this file has already been read
until the end by the parser before the program starts executing, the
program will encounter end-of-file immediately. In the former case
(which is usually what you want) they are satisfied from whatever file
or device is connected to standard input of the Python interpreter.
When a script file is used, it is sometimes useful to be able to run
the script and enter interactive mode afterwards. This can be done by
passing -i before the script. (This does not work if the
script is read from standard input, for the same reason as explained
in the previous paragraph.)
## 2.1.1 Argument Passing
When known to the interpreter, the script name and additional
arguments thereafter are passed to the script in the variable
`sys.argv`, which is a list of strings. Its length is at least
one; when no script and no arguments are given, `sys.argv[0]` is
an empty string. When the script name is given as `'-'` (meaning
standard input), `sys.argv[0]` is set to `'-'`. When
-c command is used, `sys.argv[0]` is set to
`'-c'`. Options found after -c command are
not consumed by the Python interpreter's option processing but left in
`sys.argv` for the command to handle.
## 2.1.2 Interactive Mode
When commands are read from a tty, the interpreter is said to be in
interactive mode. In this mode it prompts for the next command
with the primary prompt, usually three greater-than signs
(">`>`> "); for continuation lines it prompts with the
secondary prompt, by default three dots ("... ").
The interpreter prints a welcome message stating its version number
and a copyright notice before printing the first prompt:
```text

python
Python 1.5.2b2 (#1, Feb 28 1999, 00:02:06) [GCC 2.8.1] on sunos5
Copyright 1991-1995 Stichting Mathematisch Centrum, Amsterdam
>>>
```
Continuation lines are needed when entering a multi-line construct.
As an example, take a look at this if statement:
```text

>>> the_world_is_flat = 1
>>> if the_world_is_flat:
... print "Be careful not to fall off!"
...
Be careful not to fall off!
```
# 2.2 The Interpreter and Its Environment
## 2.2.1 Error Handling
When an error occurs, the interpreter prints an error
message and a stack trace. In interactive mode, it then returns to
the primary prompt; when input came from a file, it exits with a
nonzero exit status after printing
the stack trace. (Exceptions handled by an except clause in a
try statement are not errors in this context.) Some errors are
unconditionally fatal and cause an exit with a nonzero exit; this
applies to internal inconsistencies and some cases of running out of
memory. All error messages are written to the standard error stream;
normal output from the executed commands is written to standard
output.
Typing the interrupt character (usually Control-C or DEL) to the
primary or secondary prompt cancels the input and returns to the
primary prompt.2.1 (#foot107)Typing an interrupt while a command is executing raises the
KeyboardInterrupt exception, which may be handled by a
try statement.
## 2.2.2 Executable Python Scripts
On BSD'ish Unix systems, Python scripts can be made directly
executable, like shell scripts, by putting the line
```text

#! /usr/bin/env python
```
(assuming that the interpreter is on the user's PATH) at the
beginning of the script and giving the file an executable mode. The
"#!" must be the first two characters of the file. On some
platforms, this first line must end with a Unix-style line ending
("\n"), not a Mac OS ("\r") or Windows
("\r\n") line ending. Note that
the hash, or pound, character, "#", is used to start a
comment in Python.
The script can be given a executable mode, or permission, using the
chmod command:
```text

$ chmod +x myscript.py
```
## 2.2.3 Source Code Encoding
It is possible to use encodings different than ASCII in Python source
files. The best way to do it is to put one more special comment line
right after the `#!` line to define the source file encoding:
```text

# -*- coding: iso-8859-1 -*-
```
With that declaration, all characters in the source file will be treated as
`iso-8859-1`, and it will be
possible to directly write Unicode string literals in the selected
encoding. The list of possible encodings can be found in the
Python Library Reference (../lib/lib.html), in the section
on codecs.
If your editor supports saving files as `UTF-8` with an UTF-8
signature (aka BOM - Byte Order Mark), you can use that instead of an
encoding declaration. IDLE supports this capability if
`Options/General/Default Source Encoding/UTF-8` is set. Notice
that this signature is not understood in older Python releases (2.2
and earlier), and also not understood by the operating system for
`#!` files.
By using UTF-8 (either through the signature or an encoding
declaration), characters of most languages in the world can be used
simultaneously in string literals and comments. Using non-ASCII
characters in identifiers is not supported. To display all these
characters properly, your editor must recognize that the file is
UTF-8, and it must use a font that supports all the characters in the
file.
## 2.2.4 The Interactive Startup File
When you use Python interactively, it is frequently handy to have some
standard commands executed every time the interpreter is started. You
can do this by setting an environment variable named
PYTHONSTARTUP to the name of a file containing your start-up
commands. This is similar to the .profile feature of the
Unix shells.
This file is only read in interactive sessions, not when Python reads
commands from a script, and not when /dev/tty is given as the
explicit source of commands (which otherwise behaves like an
interactive session). It is executed in the same namespace where
interactive commands are executed, so that objects that it defines or
imports can be used without qualification in the interactive session.
You can also change the prompts `sys.ps1` and `sys.ps2` in
this file.
If you want to read an additional start-up file from the current
directory, you can program this in the global start-up file using code
like "if os.path.isfile('.pythonrc.py'):
execfile('.pythonrc.py')". If you want to use the startup file in a
script, you must do this explicitly in the script:
```text

import os
filename = os.environ.get('PYTHONSTARTUP')
if filename and os.path.isfile(filename):
execfile(filename)
```


3. An Informal Introduction to Python

node4.html | tut.html | node6.html | Python Tutorial | node2.html
Previous:
2. Using the Python (node4.html)
Up:
Python Tutorial (tut.html)
Next:
4. More Control Flow (node6.html)
---
- 3.1 Using Python as a Calculator (node5.html#SECTION005100000000000000000)
  - 3.1.1 Numbers (node5.html#SECTION005110000000000000000)
  3.1.2 Strings (node5.html#SECTION005120000000000000000)
  3.1.3 Unicode Strings (node5.html#SECTION005130000000000000000)
  3.1.4 Lists (node5.html#SECTION005140000000000000000)
  3.2 First Steps Towards Programming (node5.html#SECTION005200000000000000000)
---
# 3. An Informal Introduction to Python
In the following examples, input and output are distinguished by the
presence or absence of prompts (">`>`> " and "... "): to repeat
the example, you must type everything after the prompt, when the
prompt appears; lines that do not begin with a prompt are output from
the interpreter. Note that a secondary prompt on a line by itself in an example means
you must type a blank line; this is used to end a multi-line command.
Many of the examples in this manual, even those entered at the
interactive prompt, include comments. Comments in Python start with
the hash character, "#", and extend to the end of the
physical line. A comment may appear at the start of a line or
following whitespace or code, but not within a string literal. A hash
character within a string literal is just a hash character.
Some examples:
```text

# this is the first comment
SPAM = 1 # and this is the second comment
# ... and now a third!
STRING = "# This is not a comment."
```
# 3.1 Using Python as a Calculator
Let's try some simple Python commands. Start the interpreter and wait
for the primary prompt, ">`>`> ". (It shouldn't take long.)
## 3.1.1 Numbers
The interpreter acts as a simple calculator: you can type an
expression at it and it will write the value. Expression syntax is
straightforward: the operators `+`, `-`, `*` and
`/` work just like in most other languages (for example, Pascal
or C); parentheses can be used for grouping. For example:
```text

>>> 2+2
4
>>> # This is a comment
... 2+2
4
>>> 2+2 # and a comment on the same line as code
4
>>> (50-5*6)/4
5
>>> # Integer division returns the floor:
... 7/3
2
>>> 7/-3
-3
```
Like in C, the equal sign ("=") is used to assign a value to a
variable. The value of an assignment is not written:
```text

>>> width = 20
>>> height = 5*9
>>> width * height
900
```
A value can be assigned to several variables simultaneously:
```text

>>> x = y = z = 0 # Zero x, y and z
>>> x
0
>>> y
0
>>> z
0
```
There is full support for floating point; operators with mixed type
operands convert the integer operand to floating point:
```text

>>> 3 * 3.75 / 1.5
7.5
>>> 7.0 / 2
3.5
```
Complex numbers are also supported; imaginary numbers are written with
a suffix of "j" or "J". Complex numbers with a nonzero
real component are written as "(real+imagj)", or can
be created with the "complex(real, imag)" function.
```text

>>> 1j * 1J
(-1+0j)
>>> 1j * complex(0,1)
(-1+0j)
>>> 3+1j*3
(3+3j)
>>> (3+1j)*3
(9+3j)
>>> (1+2j)/(1+1j)
(1.5+0.5j)
```
Complex numbers are always represented as two floating point numbers,
the real and imaginary part. To extract these parts from a complex
number z, use `z .real` and `z .imag`.
```text

>>> a=1.5+0.5j
>>> a.real
1.5
>>> a.imag
0.5
```
The conversion functions to floating point and integer
(float(), int() and long()) don't
work for complex numbers -- there is no one correct way to convert a
complex number to a real number. Use `abs( z )` to get its
magnitude (as a float) or `z.real` to get its real part.
```text

>>> a=3.0+4.0j
>>> float(a)
Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: can't convert complex to float; use e.g. abs(z)
>>> a.real
3.0
>>> a.imag
4.0
>>> abs(a) # sqrt(a.real**2 + a.imag**2)
5.0
>>>
```
In interactive mode, the last printed expression is assigned to the
variable `_`. This means that when you are using Python as a
desk calculator, it is somewhat easier to continue calculations, for
example:
```text

>>> tax = 12.5 / 100
>>> price = 100.50
>>> price * tax
12.5625
>>> price + _
113.0625
>>> round(_, 2)
113.06
>>>
```
This variable should be treated as read-only by the user. Don't
explicitly assign a value to it -- you would create an independent
local variable with the same name masking the built-in variable with
its magic behavior.
## 3.1.2 Strings
Besides numbers, Python can also manipulate strings, which can be
expressed in several ways. They can be enclosed in single quotes or
double quotes:
```text

>>> 'spam eggs'
'spam eggs'
>>> 'doesn\'t'
"doesn't"
>>> "doesn't"
"doesn't"
>>> '"Yes," he said.'
'"Yes," he said.'
>>> "\"Yes,\" he said."
'"Yes," he said.'
>>> '"Isn\'t," she said.'
'"Isn\'t," she said.'
```
String literals can span multiple lines in several ways. Continuation
lines can be used, with a backslash as the last character on the line
indicating that the next line is a logical continuation of the line:
```text

hello = "This is a rather long string containing\n\
several lines of text just as you would do in C.\n\
Note that whitespace at the beginning of the line is\
significant."

print hello
```
Note that newlines would still need to be embedded in the string using
`\n`; the newline following the trailing backslash is
discarded. This example would print the following:
```text

This is a rather long string containing
several lines of text just as you would do in C.
Note that whitespace at the beginning of the line is significant.
```
If we make the string literal a ``raw'' string, however, the
`\n` sequences are not converted to newlines, but the backslash
at the end of the line, and the newline character in the source, are
both included in the string as data. Thus, the example:
```text

hello = r"This is a rather long string containing\n\
several lines of text much as you would do in C."

print hello
```
would print:
```text

This is a rather long string containing\n\
several lines of text much as you would do in C.
```
Or, strings can be surrounded in a pair of matching triple-quotes:
`"""` or `' ' '`. End of lines do not need to be escaped
when using triple-quotes, but they will be included in the string.
```text

print """
Usage: thingy [OPTIONS]
-h Display this usage message
-H hostname Hostname to connect to
"""
```
produces the following output:
```text

Usage: thingy [OPTIONS]
-h Display this usage message
-H hostname Hostname to connect to
```
The interpreter prints the result of string operations in the same way
as they are typed for input: inside quotes, and with quotes and other
funny characters escaped by backslashes, to show the precise
value. The string is enclosed in double quotes if the string contains
a single quote and no double quotes, else it's enclosed in single
quotes. (The print statement, described later, can be used
to write strings without quotes or escapes.)
Strings can be concatenated (glued together) with the
`+` operator, and repeated with `*`:
```text

>>> word = 'Help' + 'A'
>>> word
'HelpA'
>>> '<' + word*5 + '>'
'<HelpAHelpAHelpAHelpAHelpA>'
```
Two string literals next to each other are automatically concatenated;
the first line above could also have been written "word = 'Help'
'A'"; this only works with two literals, not with arbitrary string
expressions:
```text

>>> import string
>>> 'str' 'ing' # <- This is ok
'string'
>>> string.strip('str') + 'ing' # <- This is ok
'string'
>>> string.strip('str') 'ing' # <- This is invalid
File "<stdin>", line 1, in ?
string.strip('str') 'ing'
^
SyntaxError: invalid syntax
```
Strings can be subscripted (indexed); like in C, the first character
of a string has subscript (index) 0. There is no separate character
type; a character is simply a string of size one. Like in Icon,
substrings can be specified with the slice notation: two indices
separated by a colon.
```text

>>> word[4]
'A'
>>> word[0:2]
'He'
>>> word[2:4]
'lp'
```
Slice indices have useful defaults; an omitted first index defaults to
zero, an omitted second index defaults to the size of the string being
sliced.
```text

>>> word[:2] # The first two characters
'He'
>>> word[2:] # All but the first two characters
'lpA'
```
Unlike a C string, Python strings cannot be changed. Assigning to an
indexed position in the string results in an error:
```text

>>> word[0] = 'x'
Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: object doesn't support item assignment
>>> word[:1] = 'Splat'
Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: object doesn't support slice assignment
```
However, creating a new string with the combined content is easy and
efficient:
```text

>>> 'x' + word[1:]
'xelpA'
>>> 'Splat' + word[4]
'SplatA'
```
Here's a useful invariant of slice operations:
`s[:i] + s[i:]` equals `s`.
```text

>>> word[:2] + word[2:]
'HelpA'
>>> word[:3] + word[3:]
'HelpA'
```
Degenerate slice indices are handled gracefully: an index that is too
large is replaced by the string size, an upper bound smaller than the
lower bound returns an empty string.
```text

>>> word[1:100]
'elpA'
>>> word[10:]
''
>>> word[2:1]
''
```
Indices may be negative numbers, to start counting from the right.
For example:
```text

>>> word[-1] # The last character
'A'
>>> word[-2] # The last-but-one character
'p'
>>> word[-2:] # The last two characters
'pA'
>>> word[:-2] # All but the last two characters
'Hel'
```
But note that -0 is really the same as 0, so it does not count from
the right!
```text

>>> word[-0] # (since -0 equals 0)
'H'
```
Out-of-range negative slice indices are truncated, but don't try this
for single-element (non-slice) indices:
```text

>>> word[-100:]
'HelpA'
>>> word[-10] # error
Traceback (most recent call last):
File "<stdin>", line 1, in ?
IndexError: string index out of range
```
The best way to remember how slices work is to think of the indices as
pointing between characters, with the left edge of the first
character numbered 0. Then the right edge of the last character of a
string of n characters has index n, for example:
```text

+---+---+---+---+---+
| H | e | l | p | A |
+---+---+---+---+---+
0 1 2 3 4 5
-5 -4 -3 -2 -1
```
The first row of numbers gives the position of the indices 0...5 in
the string; the second row gives the corresponding negative indices.
The slice from i to j consists of all characters between
the edges labeled i and j, respectively.
For non-negative indices, the length of a slice is the difference of
the indices, if both are within bounds. For example, the length of
`word[1:3]` is 2.
The built-in function len() returns the length of a string:
```text

>>> s = 'supercalifragilisticexpialidocious'
>>> len(s)
34
```
## 3.1.3 Unicode Strings
Starting with Python 2.0 a new data type for storing text data is
available to the programmer: the Unicode object. It can be used to
store and manipulate Unicode data (see http://www.unicode.org/)
and integrates well with the existing string objects providing
auto-conversions where necessary.
Unicode has the advantage of providing one ordinal for every character
in every script used in modern and ancient texts. Previously, there
were only 256 possible ordinals for script characters and texts were
typically bound to a code page which mapped the ordinals to script
characters. This lead to very much confusion especially with respect
to internationalization (usually written as "i18n" --
"i" + 18 characters + "n") of software. Unicode
solves these problems by defining one code page for all scripts.
Creating Unicode strings in Python is just as simple as creating
normal strings:
```text

>>> u'Hello World !'
u'Hello World !'
```
The small "u" in front of the quote indicates that an
Unicode string is supposed to be created. If you want to include
special characters in the string, you can do so by using the Python
Unicode-Escape encoding. The following example shows how:
```text

>>> u'Hello\u0020World !'
u'Hello World !'
```
The escape sequence `\u0020` indicates to insert the Unicode
character with the ordinal value 0x0020 (the space character) at the
given position.
Other characters are interpreted by using their respective ordinal
values directly as Unicode ordinals. If you have literal strings
in the standard Latin-1 encoding that is used in many Western countries,
you will find it convenient that the lower 256 characters
of Unicode are the same as the 256 characters of Latin-1.
For experts, there is also a raw mode just like the one for normal
strings. You have to prefix the opening quote with 'ur' to have
Python use the Raw-Unicode-Escape encoding. It will only apply
the above `\uXXXX` conversion if there is an uneven number of
backslashes in front of the small 'u'.
```text

>>> ur'Hello\u0020World !'
u'Hello World !'
>>> ur'Hello\\u0020World !'
u'Hello\\\\u0020World !'
```
The raw mode is most useful when you have to enter lots of
backslashes, as can be necessary in regular expressions.
Apart from these standard encodings, Python provides a whole set of
other ways of creating Unicode strings on the basis of a known
encoding.
The built-in function unicode() provides
access to all registered Unicode codecs (COders and DECoders). Some of
the more well known encodings which these codecs can convert are
Latin-1, ASCII, UTF-8, and UTF-16.
The latter two are variable-length encodings that store each Unicode
character in one or more bytes. The default encoding is
normally set to ASCII, which passes through characters in the range
0 to 127 and rejects any other characters with an error.
When a Unicode string is printed, written to a file, or converted
with str(), conversion takes place using this default encoding.
```text

>>> u"abc"
u'abc'
>>> str(u"abc")
'abc'
>>> u""
u'\xe4\xf6\xfc'
>>> str(u"")
Traceback (most recent call last):
File "<stdin>", line 1, in ?
UnicodeEncodeError: 'ascii' codec can't encode characters in position 0-2: ordinal not in range(128)
```
To convert a Unicode string into an 8-bit string using a specific
encoding, Unicode objects provide an encode() method
that takes one argument, the name of the encoding. Lowercase names
for encodings are preferred.
```text

>>> u"".encode('utf-8')
'\xc3\xa4\xc3\xb6\xc3\xbc'
```
If you have data in a specific encoding and want to produce a
corresponding Unicode string from it, you can use the
unicode() function with the encoding name as the second
argument.
```text

>>> unicode('\xc3\xa4\xc3\xb6\xc3\xbc', 'utf-8')
u'\xe4\xf6\xfc'
```
## 3.1.4 Lists
Python knows a number of compound data types, used to group
together other values. The most versatile is the list, which
can be written as a list of comma-separated values (items) between
square brackets. List items need not all have the same type.
```text

>>> a = ['spam', 'eggs', 100, 1234]
>>> a
['spam', 'eggs', 100, 1234]
```
Like string indices, list indices start at 0, and lists can be sliced,
concatenated and so on:
```text

>>> a[0]
'spam'
>>> a[3]
1234
>>> a[-2]
100
>>> a[1:-1]
['eggs', 100]
>>> a[:2] + ['bacon', 2*2]
['spam', 'eggs', 'bacon', 4]
>>> 3*a[:3] + ['Boe!']
['spam', 'eggs', 100, 'spam', 'eggs', 100, 'spam', 'eggs', 100, 'Boe!']
```
Unlike strings, which are immutable, it is possible to change
individual elements of a list:
```text

>>> a
['spam', 'eggs', 100, 1234]
>>> a[2] = a[2] + 23
>>> a
['spam', 'eggs', 123, 1234]
```
Assignment to slices is also possible, and this can even change the size
of the list:
```text

>>> # Replace some items:
... a[0:2] = [1, 12]
>>> a
[1, 12, 123, 1234]
>>> # Remove some:
... a[0:2] = []
>>> a
[123, 1234]
>>> # Insert some:
... a[1:1] = ['bletch', 'xyzzy']
>>> a
[123, 'bletch', 'xyzzy', 1234]
>>> a[:0] = a # Insert (a copy of) itself at the beginning
>>> a
[123, 'bletch', 'xyzzy', 1234, 123, 'bletch', 'xyzzy', 1234]
```
The built-in function len() also applies to lists:
```text

>>> len(a)
8
```
It is possible to nest lists (create lists containing other lists),
for example:
```text

>>> q = [2, 3]
>>> p = [1, q, 4]
>>> len(p)
3
>>> p[1]
[2, 3]
>>> p[1][0]
2
>>> p[1].append('xtra') # See section 5.1
>>> p
[1, [2, 3, 'xtra'], 4]
>>> q
[2, 3, 'xtra']
```
Note that in the last example, `p[1]` and `q` really refer to
the same object! We'll come back to object semantics later.
# 3.2 First Steps Towards Programming
Of course, we can use Python for more complicated tasks than adding
two and two together. For instance, we can write an initial
sub-sequence of the Fibonacci series as follows:
```text

>>> # Fibonacci series:
... # the sum of two elements defines the next
... a, b = 0, 1
>>> while b < 10:
... print b
... a, b = b, a+b
...
1
1
2
3
5
8
```
This example introduces several new features.
- The first line contains a multiple assignment: the variables
`a` and `b` simultaneously get the new values 0 and 1. On the
last line this is used again, demonstrating that the expressions on
the right-hand side are all evaluated first before any of the
assignments take place. The right-hand side expressions are evaluated
from the left to the right.
- The while loop executes as long as the condition (here:
`b < 10`) remains true. In Python, like in C, any non-zero
integer value is true; zero is false. The condition may also be a
string or list value, in fact any sequence; anything with a non-zero
length is true, empty sequences are false. The test used in the
example is a simple comparison. The standard comparison operators are
written the same as in C: `<` (less than), `>` (greater than),
`==` (equal to), `<=` (less than or equal to),
`>=` (greater than or equal to) and `!=` (not equal to).
- The body of the loop is indented: indentation is Python's
way of grouping statements. Python does not (yet!) provide an
intelligent input line editing facility, so you have to type a tab or
space(s) for each indented line. In practice you will prepare more
complicated input for Python with a text editor; most text editors have
an auto-indent facility. When a compound statement is entered
interactively, it must be followed by a blank line to indicate
completion (since the parser cannot guess when you have typed the last
line). Note that each line within a basic block must be indented by
the same amount.
- The print statement writes the value of the expression(s) it is
given. It differs from just writing the expression you want to write
(as we did earlier in the calculator examples) in the way it handles
multiple expressions and strings. Strings are printed without quotes,
and a space is inserted between items, so you can format things nicely,
like this:
```text

>>> i = 256*256
>>> print 'The value of i is', i
The value of i is 65536
```
A trailing comma avoids the newline after the output:
```text

>>> a, b = 0, 1
>>> while b < 1000:
... print b,
... a, b = b, a+b
...
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987
```
Note that the interpreter inserts a newline before it prints the next
prompt if the last line was not completed.


4. More Control Flow Tools

node5.html | tut.html | node7.html | Python Tutorial | node2.html
Previous:
3. An Informal Introduction (node5.html)
Up:
Python Tutorial (tut.html)
Next:
5. Data Structures (node7.html)
---
- 4.1 if Statements (node6.html#SECTION006100000000000000000)
  4.2 for Statements (node6.html#SECTION006200000000000000000)
  4.3 The range() Function (node6.html#SECTION006300000000000000000)
  4.4 break and continue Statements, and
  else Clauses on Loops (node6.html#SECTION006400000000000000000)
  4.5 pass Statements (node6.html#SECTION006500000000000000000)
  4.6 Defining Functions (node6.html#SECTION006600000000000000000)
  4.7 More on Defining Functions (node6.html#SECTION006700000000000000000)
  - 4.7.1 Default Argument Values (node6.html#SECTION006710000000000000000)
  4.7.2 Keyword Arguments (node6.html#SECTION006720000000000000000)
  4.7.3 Arbitrary Argument Lists (node6.html#SECTION006730000000000000000)
  4.7.4 Lambda Forms (node6.html#SECTION006740000000000000000)
  4.7.5 Documentation Strings (node6.html#SECTION006750000000000000000)
---
# 4. More Control Flow Tools
Besides the while statement just introduced, Python knows
the usual control flow statements known from other languages, with
some twists.
# 4.1 if Statements
Perhaps the most well-known statement type is the
if statement. For example:
```text

>>> x = int(raw_input("Please enter an integer: "))
>>> if x < 0:
... x = 0
... print 'Negative changed to zero'
... elif x == 0:
... print 'Zero'
... elif x == 1:
... print 'Single'
... else:
... print 'More'
...
```
There can be zero or more elif parts, and the
else part is optional. The keyword `elif' is
short for `else if', and is useful to avoid excessive indentation. An
if ... elif ... elif ... sequence
is a substitute for the switch or
case statements found in other languages.
# 4.2 for Statements
The for statement in Python differs a bit from
what you may be used to in C or Pascal. Rather than always
iterating over an arithmetic progression of numbers (like in Pascal),
or giving the user the ability to define both the iteration step and
halting condition (as C), Python's
for statement iterates over the items of any
sequence (a list or a string), in the order that they appear in
the sequence. For example (no pun intended):
```text

>>> # Measure some strings:
... a = ['cat', 'window', 'defenestrate']
>>> for x in a:
... print x, len(x)
...
cat 3
window 6
defenestrate 12
```
It is not safe to modify the sequence being iterated over in the loop
(this can only happen for mutable sequence types, such as lists). If
you need to modify the list you are iterating over (for example, to
duplicate selected items) you must iterate over a copy. The slice
notation makes this particularly convenient:
```text

>>> for x in a[:]: # make a slice copy of the entire list
... if len(x) > 6: a.insert(0, x)
...
>>> a
['defenestrate', 'cat', 'window', 'defenestrate']
```
# 4.3 The range() Function
If you do need to iterate over a sequence of numbers, the built-in
function range() comes in handy. It generates lists
containing arithmetic progressions:
```text

>>> range(10)
[0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
```
The given end point is never part of the generated list;
`range(10)` generates a list of 10 values, exactly the legal
indices for items of a sequence of length 10. It is possible to let
the range start at another number, or to specify a different increment
(even negative; sometimes this is called the `step'):
```text

>>> range(5, 10)
[5, 6, 7, 8, 9]
>>> range(0, 10, 3)
[0, 3, 6, 9]
>>> range(-10, -100, -30)
[-10, -40, -70]
```
To iterate over the indices of a sequence, combine
range() and len() as follows:
```text

>>> a = ['Mary', 'had', 'a', 'little', 'lamb']
>>> for i in range(len(a)):
... print i, a[i]
...
0 Mary
1 had
2 a
3 little
4 lamb
```
# 4.4 break and continue Statements, and
else Clauses on Loops
The break statement, like in C, breaks out of the smallest
enclosing for or while loop.
The continue statement, also borrowed from C, continues
with the next iteration of the loop.
Loop statements may have an `else` clause; it is executed when
the loop terminates through exhaustion of the list (with
for) or when the condition becomes false (with
while), but not when the loop is terminated by a
break statement. This is exemplified by the following loop,
which searches for prime numbers:
```text

>>> for n in range(2, 10):
... for x in range(2, n):
... if n % x == 0:
... print n, 'equals', x, '*', n/x
... break
... else:
... # loop fell through without finding a factor
... print n, 'is a prime number'
...
2 is a prime number
3 is a prime number
4 equals 2 * 2
5 is a prime number
6 equals 2 * 3
7 is a prime number
8 equals 2 * 4
9 equals 3 * 3
```
# 4.5 pass Statements
The pass statement does nothing.
It can be used when a statement is required syntactically but the
program requires no action.
For example:
```text

>>> while True:
... pass # Busy-wait for keyboard interrupt
...
```
# 4.6 Defining Functions
We can create a function that writes the Fibonacci series to an
arbitrary boundary:
```text

>>> def fib(n): # write Fibonacci series up to n
... """Print a Fibonacci series up to n."""
... a, b = 0, 1
... while b < n:
... print b,
... a, b = b, a+b
...
>>> # Now call the function we just defined:
... fib(2000)
1 1 2 3 5 8 13 21 34 55 89 144 233 377 610 987 1597
```
The keyword def introduces a function definition. It
must be followed by the function name and the parenthesized list of
formal parameters. The statements that form the body of the function
start at the next line, and must be indented. The first statement of
the function body can optionally be a string literal; this string
literal is the function's documentation
string, or docstring.
There are tools which use docstrings to automatically produce online
or printed documentation, or to let the user interactively browse
through code; it's good practice to include docstrings in code that
you write, so try to make a habit of it.
The execution of a function introduces a new symbol table used
for the local variables of the function. More precisely, all variable
assignments in a function store the value in the local symbol table;
whereas variable references first look in the local symbol table, then
in the global symbol table, and then in the table of built-in names.
Thus, global variables cannot be directly assigned a value within a
function (unless named in a global statement), although
they may be referenced.
The actual parameters (arguments) to a function call are introduced in
the local symbol table of the called function when it is called; thus,
arguments are passed using call by value (where the
value is always an object reference, not the value of
the object).4.1 (#foot1448) When a function calls another function, a new local symbol table is
created for that call.
A function definition introduces the function name in the current
symbol table. The value of the function name
has a type that is recognized by the interpreter as a user-defined
function. This value can be assigned to another name which can then
also be used as a function. This serves as a general renaming
mechanism:
```text

>>> fib
<function object at 10042ed0>
>>> f = fib
>>> f(100)
1 1 2 3 5 8 13 21 34 55 89
```
You might object that `fib` is not a function but a procedure. In
Python, like in C, procedures are just functions that don't return a
value. In fact, technically speaking, procedures do return a value,
albeit a rather boring one. This value is called `None` (it's a
built-in name). Writing the value `None` is normally suppressed by
the interpreter if it would be the only value written. You can see it
if you really want to:
```text

>>> print fib(0)
None
```
It is simple to write a function that returns a list of the numbers of
the Fibonacci series, instead of printing it:
```text

>>> def fib2(n): # return Fibonacci series up to n
... """Return a list containing the Fibonacci series up to n."""
... result = []
... a, b = 0, 1
... while b < n:
... result.append(b) # see below
... a, b = b, a+b
... return result
...
>>> f100 = fib2(100) # call it
>>> f100 # write the result
[1, 1, 2, 3, 5, 8, 13, 21, 34, 55, 89]
```
This example, as usual, demonstrates some new Python features:
- The return statement returns with a value from a function.
return without an expression argument returns `None`.
Falling off the end of a procedure also returns `None`.
- The statement `result.append(b)` calls a method of the list
object `result`. A method is a function that `belongs' to an
object and is named `obj.methodname`, where `obj` is some
object (this may be an expression), and `methodname` is the name
of a method that is defined by the object's type. Different types
define different methods. Methods of different types may have the
same name without causing ambiguity. (It is possible to define your
own object types and methods, using classes, as discussed later
in this tutorial.)
The method append() shown in the example, is defined for
list objects; it adds a new element at the end of the list. In this
example it is equivalent to "result = result + [b]", but more
efficient.
# 4.7 More on Defining Functions
It is also possible to define functions with a variable number of
arguments. There are three forms, which can be combined.
## 4.7.1 Default Argument Values
The most useful form is to specify a default value for one or more
arguments. This creates a function that can be called with fewer
arguments than it is defined
```text

def ask_ok(prompt, retries=4, complaint='Yes or no, please!'):
while True:
ok = raw_input(prompt)
if ok in ('y', 'ye', 'yes'): return 1
if ok in ('n', 'no', 'nop', 'nope'): return 0
retries = retries - 1
if retries < 0: raise IOError, 'refusenik user'
print complaint
```
This function can be called either like this:
`ask_ok('Do you really want to quit?')` or like this:
`ask_ok('OK to overwrite the file?', 2)`.
The default values are evaluated at the point of function definition
in the defining scope, so that
```text

i = 5

def f(arg=i):
print arg

i = 6
f()
```
will print `5`.
Important warning: The default value is evaluated only once.
This makes a difference when the default is a mutable object such as a
list, dictionary, or instances of most classes. For example, the
following function accumulates the arguments passed to it on
subsequent calls:
```text

def f(a, L=[]):
L.append(a)
return L

print f(1)
print f(2)
print f(3)
```
This will print
```text

[1]
[1, 2]
[1, 2, 3]
```
If you don't want the default to be shared between subsequent calls,
you can write the function like this instead:
```text

def f(a, L=None):
if L is None:
L = []
L.append(a)
return L
```
## 4.7.2 Keyword Arguments
Functions can also be called using
keyword arguments of the form "keyword = value". For
instance, the following function:
```text

def parrot(voltage, state='a stiff', action='voom', type='Norwegian Blue'):
print "-- This parrot wouldn't", action,
print "if you put", voltage, "Volts through it."
print "-- Lovely plumage, the", type
print "-- It's", state, "!"
```
could be called in any of the following ways:
```text

parrot(1000)
parrot(action = 'VOOOOOM', voltage = 1000000)
parrot('a thousand', state = 'pushing up the daisies')
parrot('a million', 'bereft of life', 'jump')
```
but the following calls would all be invalid:
```text

parrot() # required argument missing
parrot(voltage=5.0, 'dead') # non-keyword argument following keyword
parrot(110, voltage=220) # duplicate value for argument
parrot(actor='John Cleese') # unknown keyword
```
In general, an argument list must have any positional arguments
followed by any keyword arguments, where the keywords must be chosen
from the formal parameter names. It's not important whether a formal
parameter has a default value or not. No argument may receive a
value more than once -- formal parameter names corresponding to
positional arguments cannot be used as keywords in the same calls.
Here's an example that fails due to this restriction:
```text

>>> def function(a):
... pass
...
>>> function(0, a=0)
Traceback (most recent call last):
File "<stdin>", line 1, in ?
TypeError: function() got multiple values for keyword argument 'a'
```
When a final formal parameter of the form `** name` is
present, it receives a dictionary containing all keyword arguments
whose keyword doesn't correspond to a formal parameter. This may be
combined with a formal parameter of the form
`* name` (described in the next subsection) which receives a
tuple containing the positional arguments beyond the formal parameter
list. (`* name` must occur before `** name`.)
For example, if we define a function like this:
```text

def cheeseshop(kind, *arguments, **keywords):
print "-- Do you have any", kind, '?'
print "-- I'm sorry, we're all out of", kind
for arg in arguments: print arg
print '-'*40
keys = keywords.keys()
keys.sort()
for kw in keys: print kw, ':', keywords[kw]
```
It could be called like this:
```text

cheeseshop('Limburger', "It's very runny, sir.",
"It's really very, VERY runny, sir.",
client='John Cleese',
shopkeeper='Michael Palin',
sketch='Cheese Shop Sketch')
```
and of course it would print:
```text

-- Do you have any Limburger ?
-- I'm sorry, we're all out of Limburger
It's very runny, sir.
It's really very, VERY runny, sir.
----------------------------------------
client : John Cleese
shopkeeper : Michael Palin
sketch : Cheese Shop Sketch
```
Note that the sort() method of the list of keyword argument
names is called before printing the contents of the `keywords`
dictionary; if this is not done, the order in which the arguments are
printed is undefined.
## 4.7.3 Arbitrary Argument Lists
Finally, the least frequently used option is to specify that a
function can be called with an arbitrary number of arguments. These
arguments will be wrapped up in a tuple. Before the variable number
of arguments, zero or more normal arguments may occur.
```text

def fprintf(file, format, *args):
file.write(format % args)
```
## 4.7.4 Lambda Forms
By popular demand, a few features commonly found in functional
programming languages and Lisp have been added to Python. With the
lambda keyword, small anonymous functions can be created.
Here's a function that returns the sum of its two arguments:
"lambda a, b: a+b". Lambda forms can be used wherever function
objects are required. They are syntactically restricted to a single
expression. Semantically, they are just syntactic sugar for a normal
function definition. Like nested function definitions, lambda forms
can reference variables from the containing scope:
```text

>>> def make_incrementor(n):
... return lambda x: x + n
...
>>> f = make_incrementor(42)
>>> f(0)
42
>>> f(1)
43
```
## 4.7.5 Documentation Strings
There are emerging conventions about the content and formatting of
documentation strings.
The first line should always be a short, concise summary of the
object's purpose. For brevity, it should not explicitly state the
object's name or type, since these are available by other means
(except if the name happens to be a verb describing a function's
operation). This line should begin with a capital letter and end with
a period.
If there are more lines in the documentation string, the second line
should be blank, visually separating the summary from the rest of the
description. The following lines should be one or more paragraphs
describing the object's calling conventions, its side effects, etc.
The Python parser does not strip indentation from multi-line string
literals in Python, so tools that process documentation have to strip
indentation if desired. This is done using the following convention.
The first non-blank line after the first line of the string
determines the amount of indentation for the entire documentation
string. (We can't use the first line since it is generally adjacent
to the string's opening quotes so its indentation is not apparent in
the string literal.) Whitespace ``equivalent'' to this indentation is
then stripped from the start of all lines of the string. Lines that
are indented less should not occur, but if they occur all their
leading whitespace should be stripped. Equivalence of whitespace
should be tested after expansion of tabs (to 8 spaces, normally).
Here is an example of a multi-line docstring:
```text

>>> def my_function():
... """Do nothing, but document it.
...
... No, really, it doesn't do anything.
... """
... pass
...
>>> print my_function.__doc__
Do nothing, but document it.

No, really, it doesn't do anything.
```


5. Data Structures

node6.html | tut.html | node8.html | Python Tutorial | node2.html
Previous:
4. More Control Flow (node6.html)
Up:
Python Tutorial (tut.html)
Next:
6. Modules (node8.html)
---
- 5.1 More on Lists (node7.html#SECTION007100000000000000000)
  - 5.1.1 Using Lists as Stacks (node7.html#SECTION007110000000000000000)
  5.1.2 Using Lists as Queues (node7.html#SECTION007120000000000000000)
  5.1.3 Functional Programming Tools (node7.html#SECTION007130000000000000000)
  5.1.4 List Comprehensions (node7.html#SECTION007140000000000000000)
  5.2 The del statement (node7.html#SECTION007200000000000000000)
  5.3 Tuples and Sequences (node7.html#SECTION007300000000000000000)
  5.4 Dictionaries (node7.html#SECTION007400000000000000000)
  5.5 Looping Techniques (node7.html#SECTION007500000000000000000)
  5.6 More on Conditions (node7.html#SECTION007600000000000000000)
  5.7 Comparing Sequences and Other Types (node7.html#SECTION007700000000000000000)
---
# 5. Data Structures
This chapter describes some things you've learned about already in
more detail, and adds some new things as well.
# 5.1 More on Lists
The list data type has some more methods. Here are all of the methods
of list objects:
An example that uses most of the list methods:
```text

>>> a = [66.6, 333, 333, 1, 1234.5]
>>> print a.count(333), a.count(66.6), a.count('x')
2 1 0
>>> a.insert(2, -1)
>>> a.append(333)
>>> a
[66.6, 333, -1, 333, 1, 1234.5, 333]
>>> a.index(333)
1
>>> a.remove(333)
>>> a
[66.6, -1, 333, 1, 1234.5, 333]
>>> a.reverse()
>>> a
[333, 1234.5, 1, 333, -1, 66.6]
>>> a.sort()
>>> a
[-1, 1, 66.6, 333, 333, 1234.5]
```
## 5.1.1 Using Lists as Stacks
The list methods make it very easy to use a list as a stack, where the
last element added is the first element retrieved (``last-in,
first-out''). To add an item to the top of the stack, use
append(). To retrieve an item from the top of the stack, use
pop() without an explicit index. For example:
```text

>>> stack = [3, 4, 5]
>>> stack.append(6)
>>> stack.append(7)
>>> stack
[3, 4, 5, 6, 7]
>>> stack.pop()
7
>>> stack
[3, 4, 5, 6]
>>> stack.pop()
6
>>> stack.pop()
5
>>> stack
[3, 4]
```
## 5.1.2 Using Lists as Queues
You can also use a list conveniently as a queue, where the first
element added is the first element retrieved (``first-in,
first-out''). To add an item to the back of the queue, use
append(). To retrieve an item from the front of the queue,
use pop() with `0` as the index. For example:
```text

>>> queue = ["Eric", "John", "Michael"]
>>> queue.append("Terry") # Terry arrives
>>> queue.append("Graham") # Graham arrives
>>> queue.pop(0)
'Eric'
>>> queue.pop(0)
'John'
>>> queue
['Michael', 'Terry', 'Graham']
```
## 5.1.3 Functional Programming Tools
There are three built-in functions that are very useful when used with
lists: filter(), map(), and reduce().
"filter(function, sequence)" returns a sequence (of
the same type, if possible) consisting of those items from the
sequence for which `function ( item )` is true. For
example, to compute some primes:
```text

>>> def f(x): return x % 2 != 0 and x % 3 != 0
...
>>> filter(f, range(2, 25))
[5, 7, 11, 13, 17, 19, 23]
```
"map(function, sequence)" calls
`function ( item )` for each of the sequence's items and
returns a list of the return values. For example, to compute some
cubes:
```text

>>> def cube(x): return x*x*x
...
>>> map(cube, range(1, 11))
[1, 8, 27, 64, 125, 216, 343, 512, 729, 1000]
```
More than one sequence may be passed; the function must then have as
many arguments as there are sequences and is called with the
corresponding item from each sequence (or `None` if some sequence
is shorter than another). If `None` is passed for the function,
a function returning its argument(s) is substituted.
Combining these two special cases, we see that
"map(None, list1, list2)" is a convenient way of
turning a pair of lists into a list of pairs. For example:
```text

>>> seq = range(8)
>>> def square(x): return x*x
...
>>> map(None, seq, map(square, seq))
[(0, 0), (1, 1), (2, 4), (3, 9), (4, 16), (5, 25), (6, 36), (7, 49)]
```
"reduce(func, sequence)" returns a single value
constructed by calling the binary function func on the first two
items of the sequence, then on the result and the next item, and so
on. For example, to compute the sum of the numbers 1 through 10:
```text

>>> def add(x,y): return x+y
...
>>> reduce(add, range(1, 11))
55
```
If there's only one item in the sequence, its value is returned; if
the sequence is empty, an exception is raised.
A third argument can be passed to indicate the starting value. In this
case the starting value is returned for an empty sequence, and the
function is first applied to the starting value and the first sequence
item, then to the result and the next item, and so on. For example,
```text

>>> def sum(seq):
... def add(x,y): return x+y
... return reduce(add, seq, 0)
...
>>> sum(range(1, 11))
55
>>> sum([])
0
```
Don't use this example's definition of sum(): since summing
numbers is such a common need, a built-in function
`sum( sequence )` is already provided, and works exactly like
this.
New in version 2.3.
## 5.1.4 List Comprehensions
List comprehensions provide a concise way to create lists without resorting
to use of map(), filter() and/or lambda.
The resulting list definition tends often to be clearer than lists built
using those constructs. Each list comprehension consists of an expression
followed by a for clause, then zero or more for or
if clauses. The result will be a list resulting from evaluating
the expression in the context of the for and if clauses
which follow it. If the expression would evaluate to a tuple, it must be
parenthesized.
```text

>>> freshfruit = [' banana', ' loganberry ', 'passion fruit ']
>>> [weapon.strip() for weapon in freshfruit]
['banana', 'loganberry', 'passion fruit']
>>> vec = [2, 4, 6]
>>> [3*x for x in vec]
[6, 12, 18]
>>> [3*x for x in vec if x > 3]
[12, 18]
>>> [3*x for x in vec if x < 2]
[]
>>> [[x,x**2] for x in vec]
[[2, 4], [4, 16], [6, 36]]
>>> [x, x**2 for x in vec] # error - parens required for tuples
File "<stdin>", line 1, in ?
[x, x**2 for x in vec]
^
SyntaxError: invalid syntax
>>> [(x, x**2) for x in vec]
[(2, 4), (4, 16), (6, 36)]
>>> vec1 = [2, 4, 6]
>>> vec2 = [4, 3, -9]
>>> [x*y for x in vec1 for y in vec2]
[8, 6, -18, 16, 12, -36, 24, 18, -54]
>>> [x+y for x in vec1 for y in vec2]
[6, 5, -7, 8, 7, -5, 10, 9, -3]
>>> [vec1[i]*vec2[i] for i in range(len(vec1))]
[8, 12, -54]
```
To make list comprehensions match the behavior of for
loops, assignments to the loop variable remain visible outside
of the comprehension:
```text

>>> x = 100 # this gets overwritten
>>> [x**3 for x in range(5)]
[0, 1, 8, 27, 64]
>>> x # the final value for range(5)
4
```
# 5.2 The del statement
There is a way to remove an item from a list given its index instead
of its value: the del statement. This can also be used to
remove slices from a list (which we did earlier by assignment of an
empty list to the slice). For example:
```text

>>> a = [-1, 1, 66.6, 333, 333, 1234.5]
>>> del a[0]
>>> a
[1, 66.6, 333, 333, 1234.5]
>>> del a[2:4]
>>> a
[1, 66.6, 1234.5]
```
del can also be used to delete entire variables:
```text

>>> del a
```
Referencing the name `a` hereafter is an error (at least until
another value is assigned to it). We'll find other uses for
del later.
# 5.3 Tuples and Sequences
We saw that lists and strings have many common properties, such as
indexing and slicing operations. They are two examples of
sequence data types. Since Python is an evolving language,
other sequence data types may be added. There is also another
standard sequence data type: the tuple.
A tuple consists of a number of values separated by commas, for
instance:
```text

>>> t = 12345, 54321, 'hello!'
>>> t[0]
12345
>>> t
(12345, 54321, 'hello!')
>>> # Tuples may be nested:
... u = t, (1, 2, 3, 4, 5)
>>> u
((12345, 54321, 'hello!'), (1, 2, 3, 4, 5))
```
As you see, on output tuples are alway enclosed in parentheses, so
that nested tuples are interpreted correctly; they may be input with
or without surrounding parentheses, although often parentheses are
necessary anyway (if the tuple is part of a larger expression).
Tuples have many uses. For example: (x, y) coordinate pairs, employee
records from a database, etc. Tuples, like strings, are immutable: it
is not possible to assign to the individual items of a tuple (you can
simulate much of the same effect with slicing and concatenation,
though). It is also possible to create tuples which contain mutable
objects, such as lists.
A special problem is the construction of tuples containing 0 or 1
items: the syntax has some extra quirks to accommodate these. Empty
tuples are constructed by an empty pair of parentheses; a tuple with
one item is constructed by following a value with a comma
(it is not sufficient to enclose a single value in parentheses).
Ugly, but effective. For example:
```text

>>> empty = ()
>>> singleton = 'hello', # <-- note trailing comma
>>> len(empty)
0
>>> len(singleton)
1
>>> singleton
('hello',)
```
The statement `t = 12345, 54321, 'hello!'` is an example of
tuple packing: the values `12345`, `54321` and
`'hello!'` are packed together in a tuple. The reverse operation
is also possible:
```text

>>> x, y, z = t
```
This is called, appropriately enough, sequence unpacking.
Sequence unpacking requires that the list of variables on the left
have the same number of elements as the length of the sequence. Note
that multiple assignment is really just a combination of tuple packing
and sequence unpacking!
There is a small bit of asymmetry here: packing multiple values
always creates a tuple, and unpacking works for any sequence.
# 5.4 Dictionaries
Another useful data type built into Python is the dictionary.
Dictionaries are sometimes found in other languages as ``associative
memories'' or ``associative arrays''. Unlike sequences, which are
indexed by a range of numbers, dictionaries are indexed by keys,
which can be any immutable type; strings and numbers can always be
keys. Tuples can be used as keys if they contain only strings,
numbers, or tuples; if a tuple contains any mutable object either
directly or indirectly, it cannot be used as a key. You can't use
lists as keys, since lists can be modified in place using their
append() and extend() methods, as well as slice and
indexed assignments.
It is best to think of a dictionary as an unordered set of
key: value pairs, with the requirement that the keys are unique
(within one dictionary).
A pair of braces creates an empty dictionary: `{}`.
Placing a comma-separated list of key:value pairs within the
braces adds initial key:value pairs to the dictionary; this is also the
way dictionaries are written on output.
The main operations on a dictionary are storing a value with some key
and extracting the value given the key. It is also possible to delete
a key:value pair
with `del`.
If you store using a key that is already in use, the old value
associated with that key is forgotten. It is an error to extract a
value using a non-existent key.
The `keys()` method of a dictionary object returns a list of all
the keys used in the dictionary, in random order (if you want it
sorted, just apply the `sort()` method to the list of keys). To
check whether a single key is in the dictionary, use the
`has_key()` method of the dictionary.
Here is a small example using a dictionary:
```text

>>> tel = {'jack': 4098, 'sape': 4139}
>>> tel['guido'] = 4127
>>> tel
{'sape': 4139, 'guido': 4127, 'jack': 4098}
>>> tel['jack']
4098
>>> del tel['sape']
>>> tel['irv'] = 4127
>>> tel
{'guido': 4127, 'irv': 4127, 'jack': 4098}
>>> tel.keys()
['guido', 'irv', 'jack']
>>> tel.has_key('guido')
True
```
The dict() contructor builds dictionaries directly from
lists of key-value pairs stored as tuples. When the pairs form a
pattern, list comprehensions can compactly specify the key-value list.
```text

>>> dict([('sape', 4139), ('guido', 4127), ('jack', 4098)])
{'sape': 4139, 'jack': 4098, 'guido': 4127}
>>> dict([(x, x**2) for x in vec]) # use a list comprehension
{2: 4, 4: 16, 6: 36}
```
# 5.5 Looping Techniques
When looping through dictionaries, the key and corresponding value can
be retrieved at the same time using the items() method.
```text

>>> knights = {'gallahad': 'the pure', 'robin': 'the brave'}
>>> for k, v in knights.items():
... print k, v
...
gallahad the pure
robin the brave
```
When looping through a sequence, the position index and corresponding
value can be retrieved at the same time using the
enumerate() function.
```text

>>> for i, v in enumerate(['tic', 'tac', 'toe']):
... print i, v
...
0 tic
1 tac
2 toe
```
To loop over two or more sequences at the same time, the entries
can be paired with the zip() function.
```text

>>> questions = ['name', 'quest', 'favorite color']
>>> answers = ['lancelot', 'the holy grail', 'blue']
>>> for q, a in zip(questions, answers):
... print 'What is your %s? It is %s.' % (q, a)
...
What is your name? It is lancelot.
What is your quest? It is the holy grail.
What is your favorite color? It is blue.
```
# 5.6 More on Conditions
The conditions used in `while` and `if` statements above can
contain other operators besides comparisons.
The comparison operators `in` and `not in` check whether a value
occurs (does not occur) in a sequence. The operators `is` and
`is not` compare whether two objects are really the same object; this
only matters for mutable objects like lists. All comparison operators
have the same priority, which is lower than that of all numerical
operators.
Comparisons can be chained. For example, `a < b == c` tests
whether `a` is less than `b` and moreover `b` equals
`c`.
Comparisons may be combined by the Boolean operators `and` and
`or`, and the outcome of a comparison (or of any other Boolean
expression) may be negated with `not`. These all have lower
priorities than comparison operators again; between them, `not` has
the highest priority, and `or` the lowest, so that
`A and not B or C` is equivalent to `(A and (not B)) or C`. Of
course, parentheses can be used to express the desired composition.
The Boolean operators `and` and `or` are so-called
short-circuit operators: their arguments are evaluated from
left to right, and evaluation stops as soon as the outcome is
determined. For example, if `A` and `C` are true but
`B` is false, `A and B and C` does not evaluate the
expression `C`. In general, the return value of a short-circuit
operator, when used as a general value and not as a Boolean, is the
last evaluated argument.
It is possible to assign the result of a comparison or other Boolean
expression to a variable. For example,
```text

>>> string1, string2, string3 = '', 'Trondheim', 'Hammer Dance'
>>> non_null = string1 or string2 or string3
>>> non_null
'Trondheim'
```
Note that in Python, unlike C, assignment cannot occur inside expressions.
C programmers may grumble about this, but it avoids a common class of
problems encountered in C programs: typing `=` in an expression when
`==` was intended.
# 5.7 Comparing Sequences and Other Types
Sequence objects may be compared to other objects with the same
sequence type. The comparison uses lexicographical ordering:
first the first two items are compared, and if they differ this
determines the outcome of the comparison; if they are equal, the next
two items are compared, and so on, until either sequence is exhausted.
If two items to be compared are themselves sequences of the same type,
the lexicographical comparison is carried out recursively. If all
items of two sequences compare equal, the sequences are considered
equal. If one sequence is an initial sub-sequence of the other, the
shorter sequence is the smaller (lesser) one. Lexicographical
ordering for strings uses the ASCII ordering for individual
characters. Some examples of comparisons between sequences with the
same types:
```text

(1, 2, 3) < (1, 2, 4)
[1, 2, 3] < [1, 2, 4]
'ABC' < 'C' < 'Pascal' < 'Python'
(1, 2, 3, 4) < (1, 2, 4)
(1, 2) < (1, 2, -1)
(1, 2, 3) == (1.0, 2.0, 3.0)
(1, 2, ('aa', 'ab')) < (1, 2, ('abc', 'a'), 4)
```
Note that comparing objects of different types is legal. The outcome
is deterministic but arbitrary: the types are ordered by their name.
Thus, a list is always smaller than a string, a string is always
smaller than a tuple, etc. Mixed numeric types are compared according
to their numeric value, so 0 equals 0.0, etc.5.1 (#foot677)