For Dummies

by Stef Maruch and Aahz Maruch

John Wiley & Sons 2006 !"! #a$es%
&S'()*+,0!+-++,6!6
.oo/in$ for a #o0erful yet easy1to1read #ro$rammin$ lan$ua$e2 3hen slither u# to
4ython5 3his friendly reference introduces you to 4ython6 the #ortable6 interacti7e
lan$ua$e that combines $reat #o0er 0ith clear synta89
3able of :ontents
4ython for Dummies
&ntroduction
4art & 1 ;ettin$ Started
:ha#ter - 1 &ntroducin$ 4ython
:ha#ter 2 1 ;ettin$ your <ands on the =eyboard>?sin$ <el#6 &nteracti7e Mode6
and &D.@
:ha#ter " 1 'asic @lements and Synta8
:ha#ter ! 1 ;rand 3our of the 4ython .an$ua$e
:ha#ter A 1 Wor/in$ .i/e a 4ro$rammer
4art && 1 'uildin$ 'loc/s
:ha#ter 6 1 So 3his Strin$ Wal/s into a 'ar
:ha#ter + 1 :ountin$ your Way to Fun and 4rofit
:ha#ter , 1 4rocessin$ .ists and 3u#les
:ha#ter * 1 Di7in$ into Dictionaries
4art &&& 1 Structures
:ha#ter -0 1 Stayin$ in :ontrol
:ha#ter -- 1 Fun 0ith Functions
:ha#ter -2 1 'uildin$ A##lications 0ith Modules and 4ac/a$es
:ha#ter -" 1 ;ettin$ :lassy
:ha#ter -! 1 &ntroducin$ (e01Style :lasses
:ha#ter -A 1 Feelin$ @8ce#tional
:ha#ter -6 1 3ac/lin$ Some Ad7anced Features
4art &B 1 .ibraries
:ha#ter -+ 1 ?sin$ 4ythonCs 4rimary Ser7ices
:ha#ter -, 1 4rocessin$ 3e8t
:ha#ter -* 1 Di$$in$ into Dis/ Data
:ha#ter 20 1 Accessin$ the &nternet
4art B 1 3he 4art of 3ens
:ha#ter 2- 1 3en :ritical 4ython &dioms
:ha#ter 22 1 3en ;reat Desources
-
4art B& 1 A##endi8es
A##endi8 A 1 ;ettin$ and &nstallin$ 4ython
A##endi8 ' 1 4ython Bersion Differences
&nde8
.ist of Fi$ures
.ist of 3ables
.ist of .istin$s
.ist of Sidebars
Introduction
:on$ratulations5 EouCre ready to disco7er the easiest1to1read #o0erful #ro$rammin$
lan$ua$e>or maybe the most #o0erful6 easy1to1read #ro$rammin$ lan$ua$e9 3hatCs
4ython6 of course9
With Python For Dummies6 you can ferret out Fust a little or a lot9 And 0ith 4ython6 you
can 0rite a little #ro$ram that #ic/s a random Guote from a file6 or you can 0rite a set of
#ro$rams that runs a com#le8 business9
3his boo/ is for you 0hether youCre a student6 youCre a hobbyist6 you need to understand
more about 0hat your #ro$rammer co10or/ers are tal/in$ about6 or youCre ta/in$ the first
ste#s on a ne0 career #ath9
Python For Dummies $i7es you e7erythin$ you need to $et to an ad7anced1be$inner le7el
of 4ython #ro$rammin$9 And it #oints you to other resources so you can ta/e your 4ython
#ro$rammin$ s/ills e7en further9
About This Book
Python For Dummies is a reference book, which means
you can read it in any order, and you don't have to read
every chapter or section. However, to some extent, later
chapters about more complex ython features rely on
information introduced in earlier chapters. !o if you
don't understand somethin" you see in a later chapter,
"o to #hapter $, or "o to the chapter on that feature to
find out more. %ou can also look in the index to find a
term or feature you want to know more about.
2
#onventions &sed in This Book
3his boo/ contains 4ython code e8am#les9 All code e8am#les are in monospaced font
so they are easy to reco$nize9 Anythin$ that you need to ty#e is also indicated in
monospaced font so you /no0 e8actly 0hich commas should be ty#ed and 0hich
commas are #art of the surroundin$ sentence9
4ython interacti7e mode e8am#les include this #rom#t) >>>9 &f you donCt see the #rom#t6
you can assume the code 0as 0ritten in a te8t editor9
'oolish Assumptions
We ma/e the follo0in$ assum#tions about readers of this boo/)
%ou know how to use your computer and its operatin" system.
&tCs hel#ful but not necessary to /no0 ho0 to set en7ironment 7ariables on your
com#uter9 &tCs also hel#ful to ha7e a Web bro0ser 0ith access to the &nternet9
%ou have and know how to use a text editor that can produce plain A!#II
text or files that end with the .txt extension.
&f you donCt ha7e a te8t editor that can do this6 0e include instructions for settin$
u# 4ythonCs &D.@ #ro$rammin$ en7ironment to 0or/ 0ith the e8am#les in this
boo/9
%ou have had a minimal amount of exposure to pro"rammin".
We really do mean minimal. &f you had a #ro$rammin$ class in hi$h school6 or
0rote a fe0 'AS&: #ro$rams at one time6 or e7en if you ha7e used <3M. ta$s6
that counts9
&f you ha7e absolutely no e8#erience 0ith #ro$rammin$6 you can still find out
#lenty from this boo/6 but 0e recommend that you also loo/ at a boo/ or Web
tutorial desi$ned to introduce #ro$rammin$ to be$inners9 EouCll benefit from the
e8tended e8#lanations of some conce#ts that 0e donCt ha7e the s#ace to discuss in
detail here9
%ou mi"ht have done some pro"rammin" in another lan"ua"e.
4ro$rammin$ /no0led$e is not reGuired for this boo/6 but #eo#le 0ho ha7e
#ro$rammed in other lan$ua$es ha7e their o0n sets of issues 0hen transitionin$
to 4ython6 and 0e #ro7ide some material for such #eo#le9
"
%ou know little to nothin" about ython.
&f you /no0 4ython6 this boo/ 0ill still be hel#ful as a reference or a source of
ti#s and tric/s you may not be a0are of9
How This Book Is (r"ani)ed
3his boo/ $i7es you an o7er7ie0 of 4ythonH the lo0do0n about all of its maFor #arts6
structures6 and librariesH and a $lim#se into some more ad7anced features9 Eou also find
out 0here to $o to disco7er more9
Part I: Getting Started
&n this #art6 0e introduce 4ython and situate it amon$ the myriad other #ro$rammin$
lan$ua$es a7ailable9 4ython is $ood for some thin$s and not for othersH you find out
0hich is 0hich9 We #ro7ide a hands1on introduction to some of 4ythonCs abilities6 usin$
its hel#ful interacti7e mode and its &D.@ #ro$rammin$ en7ironment9 We briefly describe
each of 4ythonCs basic buildin$ bloc/s and sho0 ho0 all these bloc/s come to$ether by
dissectin$ a 0or/in$ #ro$ram9 We s/etch an o7er7ie0 of ho0 #rofessional #ro$rammers
desi$n #ro$rams and debu$ code and sho0 you ho0 to #ut these #ractices to 0or/ to
ma/e your o0n #ro$rammin$ life easier9
Part II: Building Blocks
4ython has si8 basic data ty#es and many 0ays to 0or/ 0ith each of them9 &n this #art6
0e describe ho0 to 0or/ 0ith strin$s chun/s of te8t%6 numbers6 lists and tu#les both of
0hich store multi#le data elements%6 dictionaries 0hich associate one element 0ith
another%6 and sets 0hich al0ays contain uniGue elements6 ne7er du#licates%9
Part III: Structures
4ython code usually comes in chun/s6 both small and bi$6 and each chun/ does a
#articular thin$9 3his #art also includes a brief introduction to some ad7anced features
and the ne0 features of 4ython 29A9
Part IV: Libraries
4ython comes 0ith e7erythin$ you need to 0rite a 7ery #o0erful #ro$ram6 and other
#eo#le ha7e already sol7ed lots of #ro$rammin$ conundrums for you9 &ts libraries include
#rimary ser7ices such as communication 0ith the o#eratin$ system6 te8t #rocessin$ tools6
7arious 0ays of readin$ and 0ritin$ information to dis/6 and &nternet access methods9
!
Part V: The Part of Tens
All For Dummies boo/s include 3he 4art of 3ens9 &n this #art6 0e $i7e you ten useful but
not1so1ob7ious #ro$rammin$ idioms and ten resources 0here you can find out more
about 4ython9
Part VI: Appendixes
<ere you find instructions on ho0 to install 4ython and its documentation6 as 0ell as a
list of ne0 features introduced 0ith each ne0 7ersion of 4ython since 2909
&cons a##ear throu$hout the boo/ to indicate s#ecial material9 <ereCs 0hat they mean)
3i# A 3i# e8#lains ho0 to do somethin$ a little bit more easily and efficiently9
Warnin$ A Warnin$ $i7es you a heads1u# about tric/y stuff or common mista/es that
mi$ht cause data loss or some other sort of headache9 &tCs best to read Warnin$s
to ma/e sure a tric/y feature doesnCt I$etcha9I
3@:<(&:A.
S3?FF
A 3echnical Stuff icon fla$s te8t thatCs of interest to readers 0ho li/e
to /no0 about the inner 0or/in$s or history of a subFect9 Eou donCt
need to read 3echnical Stuff material9 After youC7e internalized a
little about a subFect6 readin$ this te8t mi$ht hel# you understand it
from a different an$le9
D@M@M'@D Demember icons hi$hli$ht im#ortant conce#ts or #ieces of information to
/ee# in mind9
*here to +o from Here
&f you 0ant an o7er7ie0 of 4ythonCs history and 0hat it can do6 $o to :ha#ter -9 &f youCre
ne0 to 4ython and 0ant to start 0or/in$ 0ith it ri$ht a0ay6 $o to :ha#ter 29 &f you 0ant
a brief o7er7ie0 of all of 4ythonCs buildin$ bloc/s6 $o to :ha#ter "9 &f you /no0 some
4ython and you 0ant a refresher or additional info on some of its tools6 $o to the s#ecific
cha#ters youCre interested in9
A
art I, +ettin" !tarted
#hapter -ist
:ha#ter -) &ntroducin$ 4ython
:ha#ter 2) ;ettin$ your <ands on the =eyboard>?sin$ <el#6 &nteracti7e Mode6 and
&D.@
:ha#ter ") 'asic @lements and Synta8
:ha#ter !) ;rand 3our of the 4ython .an$ua$e
:ha#ter A) Wor/in$ .i/e a 4ro$rammer
3he A
th
Wa7e 'y Dich 3ennant
I3he en$ineers li7ed on Jolt and cheese stic/s #uttin$ this #roducts to$ether6 but if you
0anted to Fust Jcola and cheese stic/sK in the ?sers Documentation6 thatCs o/ay too9 WeCre
#retty loose around here9I
In this part
Eou $et an o7er7ie0 of the 4ython #ro$rammin$ lan$ua$e6 an introduction to its
interacti7e and de7elo#er en7ironment6 and a 0al/throu$h of the buildin$ bloc/s that
ma/e u# 4ython #ro$rams9
6
:ha#ter - describes the history of 4ython and all the e8citin$ thin$s itCs bein$ used for
today9 Eou find out 0hy com#uters are both the fastest and dumbest thin$s around9 'est
of all6 you disco7er 0hy itCs called Python any0ay9
:ha#ter 2 lets you tal/ to 4ython 7ia its interacti7e mode and &D.@ en7ironment9 Eou
0rite a fe0 basic #ro$rams and find out ho0 to $et 4ython to carry out commands for
you6 ho0 to $et 4ython to tell you thin$s6 and ho0 to im#ort tools that let you do e7en
more9
:ha#ter " introduces you to 4ythonCs data ty#es and code bloc/s6 the chun/s you use to
build #ro$rams9
:ha#ter ! sho0s you a 0or/in$ #ro$ram9 Eou see ho0 all the chun/s of a 4ython
#ro$ram tal/ to each other6 and you find out somethin$ about the desi$n #hiloso#hies
behind 4ython #ro$rams9
:ha#ter A lets you try on a #ro$rammerCs hat to understand ho0 #ro$rammers 0or/ and
0hy they ma/e the desi$n decisions they do9 ?nfortunately6 it doesnCt e8#lain the
rele7ance of caffeinated sodas to this #rocess>youCll ha7e to fi$ure that out for yourself9%
3hereCs also a 7ery useful section on strate$ies for debu$$in$ #ro$rams6 0hich is a hu$e
#art of e7ery #ro$rammerCs Fob9
#hapter ., Introducin" ython
Welcome to 4ython5 &f youCre the ty#e of #erson 0ho 0ants to /no0 0hat youCre $ettin$
into6 this cha#ter is for you9 We $i7e you a Guic/ history of 4ython and its community of
de7elo#ers9 Eou find out 0hat 4ython is and isnCt $ood for the IisI section is much
lon$er than the IisnCtI section% and the most im#ortant #rinci#les of $ood 4ython
#ro$rammin$9 &f youCre ne0 to #ro$rammin$6 youCll see ho0 itCs 7ery similar to a tas/
youCre #robably familiar 0ith9
The /i"ht Tool for the 0ob
4ython is a $eneral1#ur#ose6 hi$h1le7el lan$ua$e that can be e8tended and embedded
included in a##lications as a tool for 0ritin$ macros%9 3hat ma/es 4ython a smart choice
for many #ro$rammin$ #roblems6 both small and lar$e6 and not so $ood for a cou#le of
com#utin$ tas/s9
Good uses of Python
4ython is ideal for #roFects that reGuire Guic/ de7elo#ment9 &t su##orts multi#le
#ro$rammin$ #hiloso#hies6 so itCs $ood for #ro$rams that reGuire fle8ibility9 3he many
#ac/a$es and modules already 0ritten for 4ython #ro7ide 7ersatility and sa7e you time9
The story of ython
+
;uido 7an Dossum created 4ython and is affectionately besto0ed 0ith the title
I'ene7olent Dictator For .ifeI by the 4ython community9 &n the late -*,0s6 ;uido li/ed
features of se7eral #ro$rammin$ lan$ua$es6 but none of them had all the features he
0anted9 S#ecifically6 he 0anted a lan$ua$e that had the follo0in$ features)
!criptin" lan"ua"e, A script is a #ro$ram that controls other #ro$rams9 Scri#tin$
lan$ua$es are $ood for Guic/ de7elo#ment and #rototy#in$ because theyCre $ood
at #assin$ messa$es from one com#onent to another and at handlin$ fiddly stuff
li/e memory mana$ement so that the #ro$rammer doesnCt ha7e to9 4ython has
$ro0n beyond scri#tin$ lan$ua$es6 0hich are used mostly for small a##lications9
3he 4ython community #refers to call 4ython a dynamic programming language9
Indentation for statement "roupin", 4ython s#ecifies that se7eral statements are
#art of a sin$le $rou# by indentin$ them9 3he indented $rou# is called a code
block. Other lan$ua$es use different synta8 or #unctuation for statement
$rou#in$9 For e8am#le6 the : #ro$rammin$ lan$ua$e uses { to be$in an
instruction and } to end it9 &ndentation is considered $ood #ractice in other
lan$ua$es also6 but 4ython 0as one of the first to enforce indentation9 &ndentation
ma/es code easier to read6 and code bloc/s set off 0ith indentation ha7e fe0er
be$inLend 0ords and #unctuation to accidentally lea7e out 0hich means fe0er
bu$s%9
Hi"h1level data types, :om#uters store e7erythin$ in -s and 0s6 but humans need
to 0or/ 0ith data in more com#le8 forms6 such as te8t9 A lan$ua$e that su##orts
such com#le8 data is said to ha7e high-level data types. A hi$h1le7el data ty#e is
easy to mani#ulate9 For e8am#le6 4ython strin$s can be searched6 sliced6 Foined6
s#lit6 set to u##er1 or lo0ercase6 or ha7e 0hite s#ace remo7ed9 <i$h1le7el data
ty#es in 4ython6 such as lists and dicts 0hich can store other data ty#es%6
encom#ass much more functionality than in other lan$ua$es9
2xtensibility, An e8tensible #ro$rammin$ lan$ua$e can be added to9 3hese
lan$ua$es are 7ery #o0erful because additions ma/e them suitable for multi#le
a##lications and o#eratin$ systems9 @8tensions can add data ty#es or conce#ts6
modules6 and #lu$1ins9 4ython is e8tensible in se7eral 0ays9 A core $rou# of
#ro$rammers 0or/s on modifyin$ and im#ro7in$ the lan$ua$e6 0hile hundreds of
other #ro$rammers 0rite modules for s#ecific #ur#oses9
Interpreted, &nter#reted lan$ua$es run directly from source code that humans
$enerate 0hereas #ro$rams 0ritten in compiled languages, like C++, must be
translated to machine code before they can run%9 &nter#reted lan$ua$es run more
slo0ly because the translation ta/es #lace on the fly6 but de7elo#ment and
debu$$in$ is faster because you donCt ha7e to 0ait for the com#iler9 &nter#reted
lan$ua$es are easier to run on multi#le o#eratin$ systems9 &n the case of 4ython6
itCs easy to 0rite code that 0or/s on multi#le o#eratin$ systems>0ith no need to
ma/e modifications9
4eo#le ar$ue o7er 0hether 4ython is an inter#reted or com#iled lan$ua$e9
Althou$h 4ython 0or/s li/e an inter#reted lan$ua$e in many 0ays6 its code is
com#iled before e8ecution li/e Ja7a%6 and many of its ca#abilities run at full
machine s#eed because theyCre 0ritten in :>lea7in$ you free to focus on ma/in$
,
your a##lication 0or/9 ;uido be$an 0ritin$ 4ython durin$ his :hristmas 7acation
in -*,*6 and o7er the ne8t year6 he added to the #ro$ram based on feedbac/ from
collea$ues9 <e released it to the #ublic in February -**- by #ostin$ to the ?senet
system of ne0s$rou#s9 &n ;uidoCs 0ords) I3he rest is in the MiscL<&S3MDE file9I
'ast development
<i$h1le7el features ma/e 4ython a 0ise alternati7e for #rototy#in$ and fast de7elo#ment
of com#le8 a##lications)
4ython is inter#reted6 so 0ritin$ 0or/in$ #ro$rams and fi8in$ mista/es in
#ro$rams is fast9
3@:<(&:A.
S3?FF
4ro$rams 0ritten in inter#reted lan$ua$es can be tested as
soon as theyCre 0ritten6 0ithout 0aitin$ for the code to
com#ile9
4ython ta/es care of such fiddly details as memory mana$ement behind the
scenes9
4ython has debu$$in$ features built in9
D@M@M'@D All these features ma/e 4ython a $ood lan$ua$e for
Mff1the1cuff6 Guic/ #ro$rammin$
4rototy#in$ s/etchin$ the desi$n basics of com#le8 #ro$rams6 or
testin$ #articular solutions%
A##lications that chan$e6 build on themsel7es6 and add ne0
features freGuently
ro"rammin" styles
4ython is a multi-paradigm lan$ua$e meanin$ it su##orts more than one style or
#hiloso#hy of #ro$rammin$%9 3his ma/es it $ood for a##lications that benefit from a
fle8ible a##roach to #ro$rammin$9 4ython includes tools for the follo0in$ #aradi$ms)
MbFect1oriented #ro$rammin$ MM4 for short% is one of the #o#ular #ro$rammin$
styles that 4ython su##orts9 MM4 brea/s u# code into indi7idual units that #ass
messa$es bac/ and forth9
3i# MbFect1oriented #ro$rammin$ is $ood for a##lications that ha7e multi#le
#arts that need to communicate 0ith each other9
4ython has features in common 0ith the follo0in$ lan$ua$es9 &f you /no0 these
lan$ua$es6 youCll find features in 4ython that you are familiar 0ith6 ma/in$
4ython easier to learn)
o 0ava, An obFect1oriented lan$ua$e es#ecially for a##lications used o7er
net0or/s
*
o erl, A #rocedural lan$ua$e used for te8t mani#ulation6 system
administration6 Web de7elo#ment6 and net0or/ #ro$rammin$
o Tcl, ?sed for ra#id #rototy#in$6 scri#tin$6 ;?&s6 and testin$
o !cheme, A functional #ro$rammin$ lan$ua$e a lan$ua$e that focuses on
#erformin$ actions and calculations by usin$ functions9
For more about functions6 see :ha#ter --6 and for an intro to functional
#ro$rammin$6 see :ha#ter -69%
D@M@M'@D Python For Dummies includes a brief introduction to obFect1oriented
#ro$rammin$ :ha#ter -"%6 an o7er7ie0 of usin$ 4ython for Web
de7elo#ment :ha#ter 20%6 and ti#s for scri#tin$ and testin$9
3ersatility
4ython modules collections of features for #erformin$ tas/s% let 4ython 0or/ 0ith
4ultiple operatin" systems and user interfaces
3i# With Python For Dummies6 you can 0rite and run #ro$rams on Windo0s6
Mac6 and ?ni8 includin$ .inu8%9 4ython #ro$rammers ha7e also 0ritten
code for other o#eratin$ systems6 from cell #hones to su#ercom#uters9
!pecial kinds of data 5such as ima"es and sound6
4ython comes 0ith dozens of built1in modules9 (e0 modules can be 0ritten in either
4ython or :L:NN9
#ompanies that use ython
3he main #ortal to 4ython and the 4ython community is htt#)LL0009#ython9or$9 3his
#ortal contains a #a$e that lists some com#anies that use 4ython6 includin$
Eahoo5 for Eahoo5 Ma#s%
;oo$le for its s#ider and search en$ine%
inu! "eekly #e$s %published by using a Web a##lication 0ritten in 4ython%
&ndustrial .i$ht & Ma$ic used in the #roduction of s#ecial effects for such
mo7ies as &he Phantom 'enace and &he 'ummy (eturns%9
Mther commercial uses include financial a##lications6 educational soft0are6 $ames6 and
business soft0are9
#onvenience
Most #ro$rammin$ lan$ua$es offer con7enience features6 but none boast the combination
of con7enience and #o0er that 4ython offers)
-0
ython can be embedded in other applications and used for creatin" macros.
For e8am#le6 4ython is embedded in 4aint Sho# 4ro , and later 7ersions as a
scri#tin$ lan$ua$e9
ython is free for anyone to use and distribute 5commercially or
noncommercially6, so any indi7idual or com#any can use it 0ithout #ayin$
license fees9
ython has powerful text manipulation and search features for applications
that process a lot of text information.
%ou can build lar"e applications with ython, even thou"h it doesn't check
pro"rams before they run. &n technical terms6 4ython doesnCt ha7e compile-time
checking. 4ython su##orts lar$e #ro$rams by connectin$ multi#le modules
to$ether and bundlin$ them into #ac/a$es9 @ach module can be built and tested
se#arately9
ython includes support for testin" and error1checkin" both of individual
modules and of whole pro"rams.
Soeties! Python isn"t so hot
4ython by itself isnCt best for a##lications that need to interface closely 0ith the
com#uterCs hard0are because
ython is an interpreted language.
&nter#reted lan$ua$es are slo0er than com#iled lan$ua$es9
ython is a high-level language that uses many layers to communicate 0ith the
com#uterCs hard0are and o#eratin$ system9
D@M@M'@D 4ython mi$ht not be the best choice for buildin$ the follo0in$ ty#es of
a##lications and systems)
+raphics1intensive applications, such as action "ames
'ut some $ames use 4ython because s#ecialized modules can be 0ritten to
interface 0ith hard0are9 3he pygame module is one such #ac/a$e9 Modern
com#uters are e8tremely fast6 0hich means itCs more im#ortant to be able to 0rite
clean code Guic/ly than to $et ma8imum s#eed out of the soft0are6 e8ce#t for the
most $ra#hics1intensi7e $ames9%
The foundations of an operatin" system
The ython developer community
4ython has attracted many users 0ho collecti7ely ma/e u# a community that
4romotes 4ython
Discusses and im#lements im#ro7ements to the lan$ua$e
--
Su##orts ne0comers
@ncoura$es standards and con7entions that im#ro7e 4ythonCs usability and
readability
Balues simplicity and fun %after all, Python 0as named after Monty 4ython6 the
'ritish comedy trou#e%
3he 4ython community has created 0ords to describe its #hiloso#hy)
Pythonic identifies code that meets the follo0in$ criteria)
&t includes interfaces or features that 0or/ 0ell 0ith 4ython9
&t ma/es $ood use of 4ython idioms standard 0ays of #erformin$ tas/s% and
sho0s understandin$ of the lan$ua$e9
)npythonic code is rou$hly translated from other lan$ua$es instead of follo0in$ 4ythonCs
#hiloso#hy9
Pythonistas are /no0led$eable users of 4ython es#ecially users 0ho #romote the
lan$ua$e%9
#ookin" &p ro"rams
Writin$ #ro$rams is a little bit li/e 0or/in$ 0ith reci#es9 For e8am#le6 you can
*rite a recipe to make bread from scratch.
&n 4ython6 you can build a #ro$ram from scratch6 0ritin$ all your o0n code and
usin$ only 4ythonCs basic built1in functions9
&se the product of one recipe in another recipe 5for example, a recipe for
turkey stuffin" uses bread as an in"redient6.
After you 0rite #ro$ram that #erforms a basic tas/6 you can insert it into other
#ro$rams the same 0ay you add any in$redient to a reci#e9
Buy premade bread.
4ython comes 0ith many modules, 0hich are sets of #ro$rams other #eo#le ha7e
0ritten that you can #lu$ into your #ro$ram6 Fust li/e you can buy bread at the
store 0ithout ba/in$ it yourself9
4ythonCs e7en better than bread because most 4ython modules are free*
-2
When you 0rite a #ro$ram6 you are tellin$ the com#uter to do somethin$9 Python For
Dummies $i7es you ste#1by1ste# instructions that hel# you understand ho0 to 0rite the
0ay a com#uter Ithin/s9I
D@M@M'@D ?nli/e you6 com#uters are #retty stu#id9 3hey can do only a fe0 thin$s9
All the actions that humans ma/e them do are the result of the com#uterCs
doin$ those fe0 thin$s o7er and o7er6 in different combinations6 7ery
Guic/ly9
Training your assistant
&ma$ine that youCre a ba/er6 and you ha7e ta/en on an a##rentice ba/er 0ho is as stu#id
as a com#uter9 &f you 0ant to sho0 your ba/er ho0 to ma/e bread from scratch6 you need
to start 0ith 7ery basic ste#s9 EouC7e already started by #uttin$ 0arm 0ater and su$ar in a
small bo0l9 3hen you and the a##rentice ha7e this con7ersation)
%ou, IAdd a #ac/a$e of yeast9I
Apprentice, I& canCt find a #ac/a$e of yeast9I
%ou, I3he refri$erator is o7er there9 &nside the refri$erator is a little #ac/a$e
labeled +east. ;o $et it9I
3he a##rentice $ets the #ac/a$e and says6 I(o0 0hat2I
%ou, I4ut the #ac/a$e in the bo0l9I
3he a##rentice #uts the #ac/a$e in the bo0l9
%ou, I<ey5 M#en the #ac/a$e first5I
'y no0 you mi$ht doubt the 0isdom of hirin$ an a##rentice ba/er 0ho needs to be told
thin$s that seem com#letely ob7ious to you9 'ut if you #erse7ere6 youCll come out ahead9
&f this a##rentice is li/e a com#uter6 then after finally fi$urin$ out ho0 to ba/e bread in
your /itchen6 your ne0 ba/er 0ill be able to #re#are -00 loa7es a minute5
#obining ingredients
When your a##rentice ba/er /no0s all the #rocedures in7ol7ed in ba/in$ bread6 such as
findin$ the in$redients on the shel7es6 findin$ the #ots and #ans6 mi8in$ in$redients6 and
o#eratin$ the o7en6 you can assi$n other tas/s that use those same #rocedures9 'a/in$
bread in7ol7es combinin$ in$redients in a bo0l6 so if you need to combine in$redients
for another reci#e6 the a##rentice already /no0s ho0 to do that9 So 0hen you 0ant to
e8#lain ho0 to ma/e coo/ies6 you can no0 say Icombine su$ar6 flour6 and butter in a
bo0lI 0ithout e8#lainin$ 0here to find the bo0ls or the su$ar9
D@M@M'@D &n 4ython6 after youC7e 0ritten a #ro$ram to do somethin$6 you can im#ort
it into another #ro$ram9 So the more you 0or/ 0ith 4ython6 the faster
youCll be able to 0rite #ro$rams9
-"
#hapter 7, +ettin" your Hands on the
8eyboard9&sin" Help, Interactive
4ode, and I:-2
(verview
@7en if you ha7enCt used 4ython or another #ro$rammin$ lan$ua$e before6 itCs easy to $et
u# and runnin$ 0ith 4ython9 Eou donCt e7en ha7e to /no0 ho0 to 0rite a com#lete
#ro$ram because you can run 4ython in interactive mode. &n interacti7e mode6 you can
tell 4ython 0hat to do one instruction at a time6 or you can 0rite small #ortions of code to
see ho0 4ython handles them9 &n this 0ay you can learn by doin$6 tryin$ thin$s out at
your o0n #ace9
&f youC7e 0or/ed 0ith other #ro$rammin$ lan$ua$es6 youCre #robably ea$er to $et into
the 0or/in$s of 4ython and see ho0 it com#ares9 3his cha#ter introduces you to some of
the tools youCll use as you de7elo# 4ython #ro$rams6 as 0ell as some of 4ythonCs basic
synta89
Deady for a full1on de7elo#ment e8#erience2 Mr Fust curious 0hat a debugger is2 3hen
$o on to the I&D.@ Musin$sI section about 4ythonCs 7ery o0n de7elo#ment en7ironment6
&D.@ &nte$rated De7e.o#ment @n7ironment%9 3his com#rehensi7e set of tools su##orts
you 0hen you are 0ritin$6 testin$6 and findin$ or fi8in$ mista/es in #ro$rams9
3i# &n most of this boo/6 you read and e8#eriment on your o0nH itCs structured so that
you can #ic/ u# information 0ithout readin$ seGuentially9 <o0e7er6 if youCre ne0 to
#ro$rammin$6 you mi$ht find it useful to read all of this cha#ter and try some
e8am#les before $oin$ on to the rest of the boo/9 &n the follo0in$ sections6 you $et a
$ood Ihands1onI foundation 0ith 4ythonCs inter#reter6 0hich 0ill ma/e you more
comfortable 0hen you mo7e on to 0ritin$ your o0n #ro$rams9
3i# &f you 0ant to $et an o7er7ie0 of 4ythonCs features6 Fum# ahead to :ha#ter "9 WeCll
be 0aitin$ for you here 0hen you 0ant to find out more about interacti7e mode or
the &D.@ editorLdebu$$er9
&f you need to install 4ython6 A##endi8 A has the instructions9
Two *ays to Interact with ython
Mne of the reasons 4ython is easy to use is that it comes 0ith tools that hel# you desi$n6
0rite6 and debu$ your #ro$rams9
3his cha#ter describes t0o of these tools)
-!
Interactive mode, &n interacti7e mode6 you ty#e instructions to 4ython one line
at a time>much the same 0ay that an o#eratin$ system shell% acce#ts
instructions from a command line9 Eou can also 0rite short multiline #ro$rams or
im#ort code from te8t files or from 4ythonCs builtin modules9 &nteracti7e mode
includes e8tensi7e hel#6 too9 With interacti7e mode6 you can e8#lore 4ythonCs
abilities9
I:-2, 3he &D.@ de7elo#ment en7ironment includes 4ythonCs interacti7e mode
and more>tools for 0ritin$ and runnin$ #ro$rams and for /ee#in$ trac/ of
names9
&D.@ is 0ritten in 4ython and sho0s off 4ythonCs considerable abilities9
+oin" (ne1on1(ne in Interactive 4ode
Eou can do most anythin$ in interacti7e mode that you can do in a 4ython #ro$ram>
e7en 0rite multiline #ro$rams9 3hin/ of interacti7e mode as
A sandbo8 for e8#erimentin$ safely 0ith 4ython
A tutor
A tool to find and fi8 #roblems bu$s% in your #ro$rams
Warnin$ Eou canCt sa7e 0hat you ty#e in interacti7e mode9 &f you 0ant to /ee# a co#y of
0hat you 0rote6 sa7e your code and results in a file on your com#uter9
Eou can use interacti7e mode as a calculator9 Eou can mani#ulate te8t and ma/e
assi$nments in interacti7e mode9 Finally6 you can im#ort modules6 functions6 or #arts of a
lon$er #ro$ram and test them9 3hese features can hel# you
@8#eriment 0ith 4ython obFects 0ithout 0ritin$ lon$ #ro$rams9
Debu$ #ro$rams by im#ortin$ #arts of your #ro$ram one at a time9
Starting interacti$e ode
3o start 4ythonCs interacti7e mode6 follo0 these ste#s)
-9 (pen a command window.
o &f youCre usin$ Mac MS O6 open the &erminal application and select File
#e$ ,hell.
o &f youCre usin$ Windo0s6 open the Command Prompt $indo$.
o &f youCre usin$ ?(&O6 either open a ne$ shell $indo$ or -ust type in your
e!isting shell $indo$.
29 Type python9
When 4ython o#ens6 you see the te8t sho0n in Fi$ure 21-9
-A
When 4ythonCs interacti7e mode starts u#6 it tells you 0hat 7ersion is runnin$6 the date
the 7ersion 0as released6 and a fe0 hints about 0hat to do ne8t9 3hen it dis#lays the
4ython #rom#t) >>>
Fi$ure 21-) 4ythonCs interacti7e mode in a 3erminal 0indo09
*hy computers are always sayin" ;Hello, *orld<;
I<ello6 WorldI #ro$rams are a com#uter #ro$rammin$ tradition9 Accordin$ to the free
&nternet encyclo#edia Wi/i#edia htt#)LL00090i/i#edia9or$%6 the first instance of a
com#uter #ro$ram that #rinted I<ello6 WorldI occurred in -*+"6 in a boo/ called .
&utorial /ntroduction to the anguage 0, by 'rian =erni$han9 Since then6 a I<ello6
World5I #ro$ram has been 0ritten for almost e7ery com#uter lan$ua$e9 Wi/i#edia lists
more than -+0 I<ello6 World5I #ro$rams 0ritten in lan$ua$es from !;. and ActionScri#t
to ?(&O shell and O?.9
Mne reason that I<ello6 WorldI #ro$rams are #o#ular is that a #ro$ram that #rints a sin$le
statement is usually the shortest 0or/in$ #ro$ram in a lan$ua$e9
&n 4ython6 the shortest 0or/in$ #ro$ram is one line lon$9
&n Ja7a6 the #ro$ram is fi7e lines lon$9
ArenCt you $lad youCre usin$ 4ython2
%ollo&ing the rules of engageent
3he basic method for 0or/in$ 0ith interacti7e mode is sim#ly this)
-9 Type a statement or expression.
29 ress the /eturn or 2nter key.
When you #ress Deturn6 4ython inter#rets your in#ut and res#onds if 0hat you ty#ed
calls for a res#onse or if the inter#reter doesnCt understand 0hat you ty#ed9
&n the follo0in$ e8am#le6 the statement tells 4ython to #rint a strin$9 'ecause the
statement doesnCt s#ecify 0here to #rint the strin$6 4ython #rints it to the screen the
default beha7ior in interacti7e mode%9
>>> print "Hello, World!"
Hello, World!
-6
3his statement is a 0hole 4ython #ro$ram5 4retty sim#le6 eh2 When you use interacti7e
mode6 4ython #rocesses each line of code you ty#e as soon as you #ress Deturn unless it
sees that you are 0ritin$ a multiline chun/ of code%6 and the results a##ear underneath9
Seeing inforation about a Python ob'ect
&n interacti7e mode6 there are t0o 0ays to see information about an obFect)
3y#e the obFect or its name% and #ress Deturn9
3y#e the print command and the obFect or its name% and #ress Deturn9
What you see de#ends on 0hat the obFect is9
With some data ty#es inte$ers and lists6 for e8am#le%6 the t0o methods of seein$
the 7alue $i7e the same result>as in this e8am#le6 in 0hich the name stores a list)
>>> x = [3,2]
>>> x
[3, 2]
>>> print x
[3, 2]
With strin$s6 the result of ty#in$ print name and #ressin$ Deturn is sli$htly
different from the result you $et by ty#in$ name and #ressin$ Deturn9 When you
Fust ty#e name and #ress Deturn6 the 7alue is surrounded by Guotation mar/s6 but
0hen you ty#e print name and #ress Deturn6 there are no Guotation mar/s9 3o
find out 0hy6 see the sidebar6 IDe#resentin$ dataI9%
3his e8am#le sho0s the difference bet0een usin$ Fust the name and usin$ the
print statement 0ith the name)
>>> x = "mystring"
>>> x
"mystring"
>>> print x
mystring
When the name refers to a code bloc/ for e8am#le6 a function6 module6 or class
instance%6 loo/in$ at the name sho0s you information such as the /ind of data6 the
name6 and the stora$e location9
3his e8am#le creates a class called essage and dis#lays information about the
class)
>>> class essage!
""" pass
"""
>>> essage
#class $$$main$$$"essage at %x&'d(%>
>>> print essage
-+
$$main$$"essage
/epresentin" data
Why do you sometimes see different results 0hen you ty#e name and 0hen you ty#e
print name2 Just ty#in$ name and #ressin$ Deturn is a shortcut for usin$ the function
repr)* to dis#lay the result6 0hereas the print command uses the function str)* to
dis#lay the result9
&n technical terms6 0hen you ty#e an obFect name6 literal6 e8#ression6 or statement and
#ress Deturn6 4ython evaluates the ob-ect9 3hat is6 4ython runs the code and
returnsLdis#lays the result9
Accordin$ to 4ythonCs built1in documentation6 the function str)* returns a IniceI strin$
re#resentation of an obFect9 3he function repr)* returns the IcanonicalI strin$
re#resentation of the obFect9 <ereCs the difference bet0een a IniceI and a IcanonicalI
re#resentation of a floatin$ #oint number)
>>> 3"2 + canonical
3"2%%%%%%%%%%%%%%2
>>> str)3"2* + nice
,3" 2,
>>> repr)3"2* + canonical
,3"2%%%%%%%%%%%%%%2,
>>> print 3"2 + nice
3"2
3he canonical re#resentation usually tries to be a chun/ of te8t that6 0hen #asted into the
inter#reter6 re1creates the obFect9 3his e8am#le sho0s ho0)
>>> myt-ple = )3, .*
>>> mylist = [/, "2", myt-ple]
>>> print repr)mylist*
[/, ,2,, )3, .*]
>>> mylist == [/, ,2,, )3, .*]
0r-e
(ote that some obFects6 such as files6 canCt be re1created by repr)*9 Eou can still use the
out#ut of repr)* as debu$$in$ info 0hen 0or/in$ 0ith such obFects9%
<ereCs an e8am#le of 0hat str)* and repr)* return 0hen you $i7e them a class as an
ar$ument)
>>> class essage!
""" pass
"""
>>> str)essage*
,$$main$$"essage,
>>> repr)essage*
,#class $$main$$"essage at %x&'e.%>,
-,
Seeing the result of the last expression
When you ty#e an e8#ression by itself in interacti7e mode6 or 0hen 4ython returns an
e8#ression as a result of somethin$ you ty#ed6 4ython also stores the 7alue of the
e8#ression in a s#ecial name) $ an underscore character%9 3his name is a7ailable only in
interacti7e mode9 3o see the 7alue stored6 ty#e $9
>>> "Hello, World!"
,Hello, World!,
>>> $
,Hello, World!,
3@:<(&:A.
S3?FF
(ote that $ doesnCt store the results of any statements assi$nments
such as x=2& or commands such as print%9 &n the follo0in$ e8am#le6
$ continues to hold the 7alue of the e8#ression e7en after a statement
0as ty#ed)
>>> "Hello, 1-rse!"
,Hello, 1-rse!,
>>> x = 3&
>>> $
,Hello, 1-rse!,
Warnin$ DonCt rely on $ in lon$ se$ments of code9 3he 7alue stored in $ may chan$e
une8#ectedly if you arenCt #ayin$ close attention to the difference bet0een
statements and e8#ressions9
(anipulating strings and lists
Eou can use 4ythonCs interacti7e mode to see a fe0 of the interestin$ tric/s 4ython can do
0ith strin$ and list data9 We co7er strin$s and lists in :ha#ters 6 and ,9%
(f printin", commas, and space
When you 0ant to #rint se7eral strin$s6 or a strin$ and the 7alue of a name6 you can use a
comma to stand for a sin$le s#ace in the #rinted out#ut9 3he follo0in$ e8am#le sho0s the
comma in action)
>>> y = "02e meaning of 3ife, t2e 4ni5erse, and 65eryt2ing is"
>>> x = .2
>>> print y, x
02e meaning of 3ife, t2e 4ni5erse, and 65eryt2ing is .2
4easurin" and splittin" strin"s
3he function len)* returns the len$th of a strin$6 as illustrated here)
>>> x = "s-percalifragilisticexpialidocio-s"
>>> len)x*
3.
D@M@M'@D len)* 0or/s 0ith other seGuence data ty#es6 too>for e8am#le6 if you
-*
$i7e it a list as an ar$ument6 it returns the number of items in the list9
3he method split)* brea/s a strin$ into se#arate 0ords and returns a list
of the 0ords6 li/e this)
>>> x = "02is is an ex7parrot!"
>>> x"split)*
[,02is,, ,is,, ,an,, ,ex7parrot!,]
3@:<(&:A.
S3?FF
3he split)* method actually brea/s a strin$ 0here7er it finds 0hite
s#ace6 so sometimes it doesnCt brea/ the strin$ 0here you e8#ect>
for e8am#le)
>>> ,one and8or t9o,
[,one,, ,and8or,, ,t9o,]
)sing interacti$e ode as a calculator
3he 4ython inter#reter can be used li/e a calculator9 &f you Fust 0ant to do sim#le
calculations6 you can ty#e numbers and o#erators and #ress Deturn to see the result6 as in
the follo0in$ e8am#le)
>>> )/ : 3* ; )2 : 2*
/<
>>> / : 3 ; 2 : 2
=
Warnin$ DonCt use an eGuals si$n =% 0hen doin$ calculations li/e these9 &n 4ython6 an
eGuals si$n $i7es a name to a 7alue9 &f you use = to try to $et the result of a
calculation6 4ython $i7es you an error messa$e)
>>> / : 3 ; 2 : 2 =
>ile "#stdin>", line /
/ : 3 ; 2 : 2 =
?
@yntax6rror! in5alid syntax
Eou can also use names to do math in the 4ython inter#reter9 3his is easier 0hen doin$
calculations 0ith se7eral ste#s6 li/e the follo0in$)
>>> x = / : 3
>>> y = 2 : 2
>>> x ; y
/<
Warnin$ &f you ty#e all 0hole numbers inte$ers% 0hen youCre doin$ arithmetic6 4ython
returns the result in inte$ers9 &f you 0ant #recise results in calculations
in7ol7in$ di7ision6 be sure that at least one of the numbers in a calculation is a
decimal number6 or ty#e the statement from $$f-t-re$$ import di5ision
before doin$ your calculations9 Doin$ the latter im#orts the true di7ision feature
from a s#ecial module called $$f-t-re$$6 0hich contains im#ro7ements that
0ill be automatically acti7ated in later 7ersions of 4ython9 3o find out more
20
about usin$ 4ython to do di7ision6 see :ha#ter +9
3hese e8am#les sho0 ho0 to $et correct di7ision results)
>>> /383 + 02at can,t (e rig2t
.
>>> /3"%83 + 02at,s more liAe it"
."333333333333333
>>> from $$f-t-re$$ import di5ision
>>> /383
."333333333333333
*orking &ith built+in functions
&n addition to the standard arithmetic o#erators such as : and ;6 you ha7e access to a
number of math functions and other functions built into the 4ython inter#reter6 and more
such functions are a7ailable in the mat2 module9
D@M@M'@D Functions are #ieces of code that
:arry out s#ecific o#erations9
Deturn the results of those o#erations9
3o 0or/ 0ith a function6 you need to call it6 and you usually need to #ass it one or more
arguments>data you 0ant it to act on9 Eou call a function by addin$ #arentheses at the
end of the function name9 Any ar$uments you #ass to the function $o inside the
#arentheses9
+ettin" help on a function
3o $et hel# on built1in functions6 ty#e 2elp 0ith the name of the function in #arentheses9
3he hel# usually tells you ho0 many ar$uments the function ta/es9 &f an ar$ument is in
sGuare brac/ets []%6 itCs an o#tional ar$ument9 &f you lea7e out an o#tional ar$ument6 a
default 7alue is used9
3he hel# for ro-nd)*6 dis#layed here6 sho0s that ro-nd)* ta/es one reGuired ar$ument
and one o#tional ar$ument the number of di$its to the ri$ht of the decimal #oint6 0hich
defaults to %%)
>>> 2elp)ro-nd*
Help on (-ilt7in f-nction ro-nd!
ro-nd)"""*
ro-nd)n-m(er[, ndigits]* 7> floating point n-m(er
2-
Bo-nd a n-m(er to a gi5en precision in decimal digits )defa-lt %
digits*"
02is al9ays ret-rns a floating point n-m(er" Crecision may (e
negati5e"
3he follo0in$ e8am#les call a built1in function named ro-nd)*6 0hich ta/es a decimal
or floatin$ #oint% number as an ar$ument9 &t rounds off the number to the nearest 0hole
number and returns the result9
>>> ro-nd)="=*
/%"%
>>> ro-nd)="3*
="%
,xaining naes
When 0or/in$ in interacti7e mode6 you sometimes need to be reminded 0hat names
youC7e $i7en to obFects9 3he dir)* function6 0hich is built into interacti7e mode6 lists the
names such as names of data obFects6 module names6 and function names% that are stored
in the interacti7e modeCs namespace at any #articular #oint in your codin$ session9
#amespace is a 4ython term for a list of names that a #articular #art of a #ro$ram /no0s
about9%
3i# Eou can also use the dir)* function to e8amine the contents of modules9
2xaminin" the namespace
3he follo0in$ e8am#le sho0s 0hat ha##ens 0hen you start 4ythonCs interacti7e mode
so you ha7e not defined anythin$ yet%6 use dir)* to see 0hat is defined6 and then $i7e a
7alue to a name and use dir)* a$ain)
D pyt2on
Cyt2on 2"&(/ )r2&(/!.E%3', F-n 2% 2%%<, /<!/E!&&*
>>> dir)*
[,$$(-iltins$$,, ,$$doc$$,, ,$$$name$$$,]
>>> too$many$cats = "Gmpossi(le!"
>>> dir)*
[,$$(-iltins$$,, ,$$doc$$,, ,$$$name$$$,, ,too$$$many$$$cats,]
After you $i7e a 7alue the name too$many$cats6 the names#ace remembers that name
and $i7es you the 7alue if you as/ for it6 li/e this)
>>> too$many$cats
,Gmpossi(le,
22
2xaminin" a module
3he $$(-iltins$$ module defines some e8ce#tions error1handlin$ code%6 functions6
and constants9 3o see 0hatCs in the $$(-iltins$$ module6 sim#ly ty#e
dir)$$(-iltins$$*9
3here are a lot of thin$s in that $$(-iltins$$ module5 3he follo0in$ e8am#le sho0s the
contents of the credits constant for 4ython 29A9 A constant6 li/e a name6 stores data6 but
the data inside a constant shouldnCt be chan$ed9%
>>> credits
02anAs to HWG, H1BG, IeJpen"com, Kope Horporation and a cast of
t2o-sands
for s-pporting Cyt2on de5elopment" @ee 999"pyt2on"org for more
information"
3he ca#italized names in the PPbuiltinsPP module are e!ceptions6 messa$es that 4ython
sends 0hen it encounters errors and other unusual conditions9 3hese are all #art of a
module called exceptions6 0hich you can see if you ty#e one of the names into
interacti7e mode)
>>> Lrit2metic6rror
#type ,exceptions"Lrit2metic6rror,]
*riting ultiline progras in interacti$e ode
Eou can 0rite multiline #ro$rams or #arts of #ro$rams in interacti7e mode9 <o0e7er6
note that interacti7e mode doesnCt let you sa7e your 0or/6 so you mi$ht also 0ant to sa7e
the code in a te8t file9
3he follo0in$ e8am#le #ro$ram #rints some /ilometerLmile con7ersions9 <ereCs ho0 it
loo/s 0hen ty#ed into a te8t editor9 &f you donCt understand e7erythin$ the code does6
donCt 0orry9 Strin$ formattin$ is e8#lained in :ha#ter 69%
for miles in range)/%, E%, /%*!
Am = miles ; /"<%=
print "Dd miles 77> D3"2f Ailometers" D )miles, Am*
(ote that some lines are indented9 &ndentation is 7ery im#ortant in 4ython because itCs
ho0 4ython tells 0hen you are usin$ a code bloc/ se7eral lines of code that are $rou#ed
to$ether%9 Four s#aces is standard for one le7el of indentation the lines startin$ 0ith Am
and print%6 ei$ht s#aces for t0o le7els6 and so on9
<ereCs ho0 the same #ro$ram loo/s 0hen you start to ty#e it in interacti7e mode9 When
you #ress Deturn after the first line6 the inter#reter reco$nizes that youCre 0ritin$ a code
bloc/ and dis#lays a continuation #rom#t) M three dots%9 @7en thou$h you see a
continuation #rom#t6 you still need to indent the lines that are #art of the code bloc/6 so
donCt for$et to add four s#aces before startin$ the Am assi$nment and the print statement9
2"
>>> for miles in range)/%, E%, /%*!
""" Am = miles ; /"<%=
""" print "Dd miles 77> D3"2f Ailometers" D )miles, Am*
"""
3i# M/ay6 0e admit it) We sometimes ma/e our thumbs ha##ier by addin$ only t0o
s#aces 0hen 0eCre 0or/in$ in interacti7e mode9 For actual #ro$rams that others
mi$ht see6 thou$h6 itCs a ;ood &dea to use four s#aces9
When you are finished 0ith the code bloc/6 you #ress Deturn at the continuation #rom#t
0ithout ty#in$ anythin$9 3he inter#reter runs the code6 0hich $i7es this result)
/% miles 77> /<"%= Ailometers
2% miles 77> 32"/' Ailometers
3% miles 77> .'"2E Ailometers
.% miles 77> <."3< Ailometers
&% miles 77> '%".& Ailometers
<% miles 77> =<"&. Ailometers
When you run a code bloc/ in interacti7e mode6 the names youC7e defined in the
names#ace retain the 7alues they 0ere $i7en last9
>>> print Am
=<"&.
>>> print miles
<%
-uitting interacti$e ode
3o e8it 4ythonCs interacti7e mode6 #ress :ontrol1D on Mac or ?(&O% or :trl1Q on
Windo0s%9
&f you ty#e N-it6 4ython reminds you 0hat to do6 li/e this)
>>> N-it
,4se Htrl7O )i"e" 6J>* to exit",
3i# &f you ha7e 4ython 29A6 you can still use :ontrol1D or :ontrol1Q de#endin$ on your
o#eratin$ system% to Guit6 or you can ty#e N-it)* or exit)* both 0or/ on all
o#eratin$ systems%9 3he reminder if you ty#e N-it 0ithout the #arentheses is a little
different this is the reminder on ?(&O%)
>>> N-it
4se N-it)* or Htrl7O )i"e" 6J>* to exit
When you e8it interacti7e mode6 you return to the command #rom#t of your 3erminal
0indo0 or :ommand 4rom#t 0indo09
Warnin$ When you Guit the 4ython inter#reter6 all the 7alues youC7e $i7en names
disa##ear9 &f you 0ant to /ee# your 0or/6 co#y any code you 0ant to sa7e into
a te8t file9
2!
+ettin" Help
'eyond Python For Dummies, many other sources of 4ython hel# are a7ailable to you9
Mne of the most com#lete sources is 4ythonCs built1in hel# system9
3i# 3he hel# built into 4ython assumes that you ha7e some /no0led$e of #ro$rammin$
and about 4ython9 &f youCre ne0 to #ro$rammin$6 some of the hel# to#ics mi$ht loo/
#retty dauntin$9 'ut after you $et a handle on some of the terminolo$y6 it $ets easier5
.elp in interacti$e ode
Eou can access 4ythonCs hel# system from interacti7e mode9 3here are t0o 0ays to use
hel#9
2nterin" the help pro"ram
Eou can run the hel# system as a se#arate #ro$ram inside the 4ython interacti7e mode
en7ironment9 3he hel# system has its o0n #rom#t9 3o $o into hel# mode6 follo0 these
ste#s)
-9 Type 2elp)* at the ython prompt.
3he hel# #ro$ram o#ens6 and you see a 0elcome messa$e and some su$$ested
to#ics9 3hen it dis#lays the hel# #rom#t)
2elp>
29 Type the name of an item you want to know about.
For e8am#le6 you can $et hel# about the list data ty#e and its methods)
2elp> list
"9 To =uit help mode, type N-it at the help mode prompt.
When you Guit hel#6 you $o bac/ to 4ythonCs interacti7e mode6 and you see the
4ython #rom#t a$ain)
>>>
&sin" help without leavin" interactive mode
Eou can also use hel# to $et a ti# about a #articular item 0ithout lea7in$ interacti7e
mode9 3o $et hel# about a #articular item6 follo0 these ste#s)
2A
-9 At the ython prompt, type 2elp followed by the name of the item you want
to find out about in parentheses.
For e8am#le6 to $et hel# about the list data ty#e6 ty#e
>>> 2elp)list*
&f the information is less than one screenful6 you $o bac/ to the interacti7e mode
#rom#t automatically9
&f thereCs more information6 follo0 Ste# 29
29 If the information is lon"er than one screen, press the spacebar to see more.
When you finishe6 ty#e N to $o bac/ to the interacti7e mode #rom#t9
3i# Some installations of 4ython>for e8am#le6 the installation on Mac MS O -09"
4anther% or -09! 3i$er%>donCt come 0ith all the 4ython hel# installed9 &f you see a
messa$e in the hel# #ro$ram that documentation cannot be found6 you can install the
documentation follo0 ste#s -R" in the ne8t section6 I;ettin$ hel# in a Web
bro0serI% and tell 4ython 0here to loo/ for it9 Mne 0ay to do this6 if youCre usin$
Mac MS O or ?(&O6 is to set the CP0HJ1OJH@ environment variable to the folder
#ath containin$ the documentation9 3he 0ay you do this de#ends on 0hich ?(&O
shell o#eratin$ system% you are usin$9 <ereCs ho0 you do it in Mac MS OCs 3erminal
0indo06 usin$ the default bash shell re#lace the #ath 0ith the correct #ath for your
docs%)
export CP0HJ1OJH@=83i(rary8Cyt2onOocs
Getting help in a *eb bro&ser
&f you 0ant to /ee# 4ython documentation o#en in a se#arate 0indo0 0hile you 0or/6
youCre in luc/9 3he 4ython documentation is in <3M. format6 so you can /ee# it o#en in
a Web bro0ser 0indo09
Follo0 these ste#s to /ee# the 4ython documentation readily a7ailable for your use)
-9 (pen your *eb browser.
29 Type htt#)LL0009#ython9or$LdocL in your browser's address box and press
/eturn.
3his Web site archi7es documentation for e7ery 7ersion of 4ython that has been
released9 3he documentation for the most recent 7ersion is a7ailable at
htt#)LL0009#ython9or$LdocLcurrentL9
"9 'ollow the online instructions to download the correct version of the help
files.
26
!9 4ake a bookmark in your *eb browser to the location of the downloaded
help files.
Doin$ this sets u# the 4ython documentation so you can access it Guic/ly9
A9 To open the help files in your *eb browser while you're workin" with
ython, >ust select the help file bookmark from your *eb browser's
bookmark list.
&sin" !cripts and 4odules
'ecause 4ythonCs interacti7e mode doesnCt sa7e any of your 0or/ 0hen you Guit6 youCll
0ant to store your im#ortant 0or/ in te8t files9 3e8t files that contain 4ython code are
called scripts if they are 0hole #ro$rams% or modules if they contain chun/s of code
meant to be im#orted into other #ro$rams%9
'oth scri#ts and modules end 0ith the suffi8 "py9
3@:<(&:A.
S3?FF
Actually6 the distinction bet0een scri#ts and modules is fuzzier than
that because some modules include code that lets them stand on their
o0n or that $i7es information about their statusS and some
#ro$rams can be im#orted as modules9
/unning a script fro the coand line
When you run a 4ython scri#t from the command line of your shell or 3erminal #ro$ram6
it beha7es li/e other #ro$rams you run from the command line>0hen itCs finished
runnin$6 you $et another command #rom#t9 3o run a scri#t from the command line
indicated by the command #rom#t D%6 ty#e pyt2on and the name of the scri#t6 li/e this)
D pyt2on script"py
&f you run a scri#t from the command line6 you use the 7i modifier to tell 4ython to $o
into interacti7e mode after you run it9 3o create a scri#t and run it interacti7ely on a
command line6 follo0 these ste#s)
-9 &se a text editor to write your script.
For e8am#le6 you mi$ht ty#e the follo0in$ in a te8t editor)
print "testing 2o9 scripts and interacti5e mode comm-nicate"
x = &%%
print "02e 5al-e of x is ", x
29 !ave your script and "ive it a name.
2+
D@M@M'@D ?se the "py suffi8 for the name9
Mur scri#t is called tinyscript"py9
"9 To run the script from the command line, type pyt2on 7i followed by the
name of the script 5includin" the "py suffix6.
When you run the scri#t6 4ython e8ecutes its code and then enters interacti7e
mode you can tell because you see the >>> #rom#t%9
D pyt2on 7i tinyscript"py
testing 2o9 scripts and interacti5e mode comm-nicate
02e 5al-e of x is &%%
>>>
3he names that are #art of tinyscript"py are no0 a7ailable in interacti7e mode9
3o test this6 ty#e dir)* and #rint the 7alue of any of your scri#tCs names9
>>> dir)*
[,$$(-iltins$$,, ,$$$doc$$$,, ,$$$file$$$,, ,$$$name$$$,, ,x,]
>>> print x
&%%
Iporting a odule in interacti$e ode
'odules are te8t files containin$ 4ython code thatCs desi$ned to be used inside another
#ro$ram9 3o 0or/ 0ith a module6 you need to import it9 When you im#ort the module6
4ython runs the moduleCs code and stores the moduleCs name in the names#ace9
3here are t0o 0ays to im#ort modules) Eou can import the module name or you can
import one or more of the names defined inside the module.
3he follo0in$ e8am#les im#ort the module tinymod-le"py6 0hich includes the
follo0in$ function)
def tinyf-nction)x*!
print "testing 2o9 mod-les and interacti5e mode comm-nicate"
print "Po- passed me t2e parameter", x
Q = x;;2
print x, "sN-ared is", Q
ret-rn Q
Importin" by name
&m#ortin$ a module by name stores the module name in the names#ace9 'ut it does not
directly im#ort any names that are defined in the module9
2,
3o im#ort a module by name6 ty#e import follo0ed by the name of the module $ithout
the "py suffi86 li/e this)
>>> import tinymod-le
3o ma/e sure that the moduleCs name has been im#orted6 ty#e dir)*9
>>> dir)*
[,$$(-iltins$$,, ,$$$doc$$$,, ,$$$name$$$,, ,tinymod-le,]
3o use an item inside a module youC7e im#orted by name6 you need to tell 4ython both
the module name and the name of the item9 3he items inside modules are collecti7ely
called attributes of the module9% 3his is similar to handin$ someone a boo/ and tellin$
them to find a cha#ter inside it9
3o access an attribute of a module6 ty#e the module name6 a dot6 and the attribute name9
&n this e8am#le6 0e call the tinyf-nction)* attribute in the tinymod-le module6 and
0e $i7e a name to its result9 3his causes 4ython to run the code in the function9 <ereCs the
result)
>>> x = tinymod-le"tinyf-nction)2*
testing 2o9 mod-les and interacti5e mode comm-nicate
yo- passed me t2e parameter 2
2 sN-ared is .
3he tinyf-nction)* function also returns a 7alue9 3o see it6 0e #rint the name 0e $a7e
to the function)
>>> print x
.
Importin" items from inside a module
&m#ortin$ items from inside a module stores their names in the names#ace6 0hich $i7es
you direct access to the items>you donCt ha7e to ty#e the module name to use them9 'ut
this method doesnCt store the name of the module in the names#ace9
3o im#ort the function thatCs inside tinymod-le6 ty#e this)
>>> from tinymod-le import tinyf-nction
3o chec/ 0hatCs stored in the names#ace6 ty#e dir)*9 Note: &f you didnCt Guit 4ython
after doin$ the e8am#le in the #re7ious section6 I&m#ortin$ by name6I you mi$ht see
other names as 0ell 0hen you ty#e dir)*9
>>> dir)*
[,$$(-iltins$$,, ,$$$doc$$$,, ,$$$name$$$,, ,tinyf-nction,]
2*
3i# &m#ortin$ a module by name is the recommended 0ay of $ettin$ access to a module
and its functions9 Althou$h im#ortin$ items from inside a module is useful in some
situations6 this can cause #roblems if the items ha7e the same names as other items
youCre 0or/in$ 0ith9
)sing Python"s standard odules in interacti$e ode
4ython comes 0ith dozens of modules that add functionality 0hen you 0ant it but stay
out of your 0ay 0hen you donCt9
-istin" ython's modules
3o see the list of built1in modules6 follo0 these ste#s)
-9 In ython interactive mode, type 2elp)* and press /eturn to start the help
utility.
29 At the 2elp> prompt, type mod-les6 like this,
3" 2elp> mod-les
." Clease 9ait a moment 92ile G gat2er a list of all a5aila(le
mod-les"""
*hy modulari)in" is a "ood idea
Why doesnCt 4ython automatically im#ort all of its built1in modules2 First of all6
im#ortin$ all of its modules 0ould ta/e a .MMMM(; time9 Second6 if it did6 there 0ould
be thousands of names stored in the names#ace6 and you 0ouldnCt be able to $i7e those
names to your o0n data>or if you did use them6 you mi$ht $et une8#ected results9
'ecause you need to im#ort modules6 stuff you donCt use stays out of your 0ay6 li/e
storin$ your 0inter clothes in the attic until Mctober9
Whoa5 3hatCs a lot of modules9 'ut donCt 0orry9 Eou can dri7e a car 0ithout /no0in$
e8actly ho0 e7erythin$ under the hood 0or/s6 and the same $oes for 0or/in$ 0ith
4ython9 Python For Dummies e8#lains the 0or/in$s of many of 4ythonCs modules and
sho0s you 0here to $o to disco7er more about the rest9
3i# 3he list of modules differs de#endin$ on your 7ersion of 4ython6 your o#eratin$
system6 and the third1#arty modules that may ha7e been installed for 4ython9
-istin" the contents of an imported module
3he names inside a module mi$ht include 7alue assi$nments6 other modules that the
module im#orts6 functions6 classes6 and so on9
3o see the names that belon$ to a module youC7e im#orted>either a "py file you 0rote
yourself or one of 4ythonCs modules>ty#e dir)* 0ith the name of the module inside the
"0
#arentheses9 For e8am#le6 to im#ort the mat2 module that comes 0ith 4ython and list its
functions6 follo0 these ste#s)
-9 At the ython prompt, type import mat29
29 To list the names 5functions and constants6 that the mat2 module defines, type
dir)mat2*9
4ython dis#lays the contents of the mat2 module9
+ettin" interactive help for a module's functions
3he hel# information for a lar$e module can be many #a$es lon$9 &f you /no0 the
function you 0ant6 hereCs ho0 to $et hel# for that function s#ecifically)
-9 4ake sure the module has been imported.
29 Type 2elp) module_name " function_name *9
'e sure to include the #arentheses and the dot bet0een the module name and the
function name9
3his e8am#le sho0s the hel# for one of the functions in the mat2 module)
>>> 2elp)mat2"po9*
Help on (-ilt7in f-nction po9 in mod-le mat2!
po9)"""*
po9)x,y*
Bet-rn x;;y )x to t2e po9er of y*"
I:-2 4usin"s
&D.@ stands for /nteractive Deveopment 1nvironment. Mther com#uter lan$ua$es ha7e
such en7ironments too6 but theyCre usually called &D@s9 4ythonCs is called &D.@ after @ric
&dle of Monty 4ython fame9% &D.@ is an editin$ #ro$ram 0ritten entirely in 4ython by
;uido 7an Dossum9
3@:<(&:A.
S3?FF
&D.@ is installed 0hen you install any recent 7ersion of 4ython6 but
it doesnCt al0ays come 0ith 7ersions of 4ython that are #reinstalled
on your com#uter6 such as 0ith the Mac MS O9 Eou can find
instructions for installin$ 4ython in A##endi8 A9
0pening I1L,
When you o#en &D.@6 you see a 0indo0 called 4ython Shell6 as sho0n in Fi$ure 2129
De#endin$ on your 7ersion of &D.@6 you mi$ht also see other 0indo0sH you can safely
i$nore them for no09
"-
Fi$ure 212) &D.@Cs 4ython Shell 0indo0 on Mac MS9
3he 4ython Shell 0indo0 runs in interacti7e modeH it dis#lays the 4ython #rom#t6 >>>9
Typing stateents and progras in the Python Shell
&nteracti7e mode in &D.@ 0or/s much the same as interacti7e mode in a shell 0indo0
runnin$ 4ython9 <ere are some differences)
The code you type is colori)ed to make it easier to distin"uish one part of a
statement from another.
*hen you write multiline statements, I:-2 does not display the M
continuation prompt.
I:-2 automatically indents lines for you.
Fi$ure 21" sho0s &D.@Cs 4ython Shell 0indo0 0ith the milesL/ilometers con7ersion
#ro$ram 0e introduce in the section6 IWritin$ multiline #ro$rams in interacti7e mode6I
earlier in this cha#ter colorizin$ is not sho0n>itCs a blac/1and10hite boo/5%9
Fi$ure 21") A #ro$ram and its result in &D.@Cs 4ython Shell 0indo0 on Mac MS9
Getting ore help for I1L,
&D.@ also has built1in hel#>loo/ in the <el# menu9
A $ood I$ettin$ startedI Web #a$e for a recent 7ersion of &D.@ is here)
htt#)LL0009h/n9eecs9ber/eley9eduLTdyooL#ythonLidlePintro
3he follo0in$ #a$es ha7e additional documentation that youCll find useful6 but they are
based on earlier 7ersions)
"2
htt#)LL0009ai9u$a9eduLmcLidleLinde89html based on &D.@ -9092%
htt#)LL0009#ython9or$LidleLdoc based on &D.@ 09A%
#lever ython !hell features
<ere are a cou#le of time1sa7in$ features of &D.@Cs 4ython Shell)
uttin" your insertion point or cursor in a line of code and pressin" 2nter
inserts a copy of the code on a new line for editin".
Typin" the openin" parenthesis for a function call or method call pops up a
small box with a helpful tip or a list of expected ar"uments.
*riting and editing code &ith I1L,"s text editor
&D.@ includes a te8t editor for o#enin$6 editin$6 and creatin$ modules and scri#ts9 <ere
are some of its /ey features)
To open a new text editin" window, choose 'ile ?ew *indow.
To open an existin" module or script for editin", choose 'ile (pen.
The 'ormat menu available when you're workin" in the text editin" window
contains ython1specific formattin" commands such as Indent /e"ion.
To run a pro"ram or module, make sure it is open in the text editor and
choose /un /un 4odule 5on some versions, the command is 'ile /un
!cript6.
3he 4ython Shell restarts clearin$ any names that it 0as storin$ from the
#re7ious session% and 4ython e8ecutes the code9
Briefly eet a fe& other I1L, coands
&D.@ has Find commands in the Find menu or @dit menu% to search for te8t in the
frontmost &D.@ 0indo09 &t also has a Find in Files command that searches all files in the
4ython search #ath or a subset of those files9
With the 4ath 'ro0ser a7ailable from the File menu%6 you can e8amine and o#en any
4ython code that is in the 4ython #ath9 3he 4ath 'ro0ser is sho0n in Fi$ure 21!9% 3o
na7i$ate the #ath6 clic/ the : buttons to e8#and a folder9 3o o#en a "py file in the te8t
editor6 double1clic/ it9 3o hi$hli$ht a class or method in the "py file6 double1clic/ it in the
4ath 'ro0ser9
""
Fi$ure 21!) 3he &D.@ 4ath 'ro0ser9
1ebugging in I1L,
When you run code in &D.@Cs interacti7e mode6 it informs you of errors the same 0ay
youC7e seen 0hen usin$ interacti7e mode in a 3erminal or shell 0indo09
When you run code from the te8t editor6 &D.@ also informs you of errors9 De#endin$ on
the /ind of error and on your 7ersion of &D.@6 the error messa$e a##ears in a dialo$ bo8
or in the 4ython Shell 0indo09
Eou can use the &D.@ debu$$er to ste# throu$h your #ro$ram in 7arious 0ays and
dis#lay the 7alues of names9 3he &D.@ debu$$er is sho0n in Fi$ure 21A9
Warnin$ Mn the Mac MS6 the &D.@ debu$$er that comes 0ith 4ython 29! and earlier has
a bu$5%9 When you o#en the debu$$er 0indo06 you must immediately resize itH
other0ise6 &D.@ 0ill han$9
"!
Fi$ure 21A) 3he &D.@ debu$$er at 0or/9
"A
#hapter $, Basic 2lements and !yntax
3his cha#ter briefly introduces some of the bits and #ieces that ma/e u# the 4ython
#ro$rammin$ lan$ua$e9 Eou find out about names and the differences bet0een statements
and e8#ressions9 We introduce se7eral ty#es of data and o#erators that 0or/ on these data
ty#es9 We also e8#lain ho0 to include documentation in your #ro$ram as 0ell as ho0 to
understand error messa$es 4ython mi$ht $i7e you9 Finally6 you $et a taste of 7arious
/inds of control structures6 loo#s6 and other code bloc/s a7ailable in 4ython9
4akin" ?ames and !torin" 3alues
&n most #ro$rammin$ lan$ua$es6 there are 0ays to associate a name or 7ariable 0ith a
7alue9 <ereCs an e8am#le of such a statement in 4ython)
n-m = .&
Many #ro$rammin$ lan$ua$es call a statement such as n-m = .& Iassi$nin$ a 7alue to a
7ariable9I 'ut 4ython doesnCt really ha7e 7ariables you donCt need to /no0 0hy%6 so this
boo/ uses the term name instead of variable.
3@:<(&:A.
S3?FF
&n 4ython6 a name refers to an obFect9 A name is actually a label for a
memory location in the com#uter that stores somethin$>a 7alue6 a
chun/ of code6 or any sort of thin$ 4ython understands9 All these
Ithin$sI>anythin$ thatCs stored in a memory location>are called
ob-ects in 4ython9 3herefore6 4ython #ro$rammers often say that
0hen you enter a statement such as x = & in 4ython6 you are binding
a name x% to an ob-ect &%9 Eou can ha7e multi#le names for the
same obFect9
3he = symbol a sin$le eGuals si$n% tells 4ython to associate a name 0ith a 7alue9 When
ma/in$ an assi$nment6 the name is al0ays on the left6 and the 7alue is on the ri$ht6 as in
this e8am#le)
myname = "my5al-e"
When youC7e $i7en a name to a 7alue6 the name stands in for the 7alue 0hen you are
0ritin$ code9 For e8am#le6 if youC7e already created the assi$nment myname =
"my5al-e"6 the follo0in$ t0o statements do the same thin$>they assi$n the name
myne9name to the 7alue ,my5al-e,)
myne9name = "my5al-e"
myne9name = myname
"6
3here are other 0ays to $i7e a name to a 7alue9 For e8am#le6 you can $i7e a name to the
result of a calculation or the information that a function returns9 3he def statement
0hich defines a function% and the class statement 0hich defines a class% also create
names9
?amin" rules
Eou can use any names you 0ant6 as lon$ as they follo0 these rules)
?ames must start with either a letter or an underscore character 5 $ 6.
%ou can't use any of ython's reserved words or keywords.
3hese are 0ords that ha7e s#ecific meanin$s to 4ython6 such as if 0hich be$ins
an if statement%9
?ames are case1sensitive. n-m is different from 14 and n4m9
By convention, most ython pro"rammers use lowercase for names that
stand for values. 3hey use other rules for names that stand for functions and
classes>you can find out more about these con7entions in later cha#ters9
It's a +ood Idea to use meanin"ful names. &f you name e7erythin$ 0ith a sin$le
letter6 for e8am#le6 you may ha7e trouble rememberin$ 0hat the name stands for
later9
3@:<(&:A.
S3?FF
!tatements and expressions, !eein" the difference
4ython code consists of statements and e!pressions9 =no0in$ these
terms isnCt essential to 0ritin$ basic code6 but sometimes they hel#
you to understand an error in your code for e8am#le6 you canCt use a
statement 0here an e8#ression is reGuired%9
A literal is a chun/ of te8t in a 4ython #ro$ram that s#ecifies the
7alue for one of the basic 4ython data ty#es such as a strin$ or
number%9 When you run your #ro$ram6 4ython creates an obFect 0ith
the literalCs 7alue9
A statement is li/e a command>it tells 4ython to do somethin$9 For
e8am#le6 the statement x = 2& tells 4ython to $i7e the name x to the
7alue 2&6 and print x tells 4ython to dis#lay the 7alue of x9
An e!pression is one or more o#erations that #roduce a result9 3he
o#erations can in7ol7e names6 o#erators6 literals6 and function or
method calls9
&tCs easiest to sho0 the difference bet0een e8#ressions and statements
by e8am#le9 (ote in these e8am#les that 0hen you enter an
"+
e!pression in the inter#reter6 the inter#reter #rints it6 but 0hen you
enter a statement0hich doesnCt create any out#ut>e8ce#t for print
statements%6 nothin$ 7isible ha##ens)
>>> "monty pyt2on" + 02is is an expression and a
literal"
,monty pyt2on,
>>> x = 2& + 02is is a statement" 2& is a
literal"
>>> x + 02is is an expression"
2&
>>> 2 in [/, 2, 3] + 02is is also an expression"
0r-e
>>> def foo)*! + 02is is a statement"
""" ret-rn / + ret-rn is a statementR / is an
expression"
"""
>>> foo)* + foo is a nameR foo)* is an
expression"
/
(ote that 4ython allo0s you to #ut multi#le statements on a line by
se#aratin$ each statement 0ith a semicolon6 but you should a7oid
this because it ma/es #ro$rams less readable)
>>> x = /R y = 2
>>> x, y
)/, 2*
",
:ata Type :oes 4atter
When you 0rite com#uter #ro$rams6 you usually 0ant to $i7e the com#uter information
data% and ha7e it do thin$s 0ith the data and $i7e you results9 4ro$rammin$ lan$ua$es
li/e 4ython ha7e se7eral data types that you do different thin$s 0ith9
Eou decide 0hich data ty#e to use de#endin$ on 0hat you 0ant to do9 For e8am#le6 if
you 0ant to do mathematical calculations6 you mi$ht choose a number data ty#e9
3he follo0in$ list briefly introduces some of 4ythonCs data ty#es)
?umbers are for data that you 0ant to do math 0ith9
!trin"s are for te8t characters and for binary data9
!e=uences are for lists of related data that you mi$ht 0ant to sort6 mer$e6 and so
on9
:ictionaries are collections of data that associate a uniGue /ey 0ith each 7alue9
!ets are for doin$ set o#erations findin$ the intersection6 difference6 and so on%
0ith multi#le 7alues9
'iles are for data that is or 0ill be stored as a document on a com#uter9
2ueric data
4ython has four built1in numeric data ty#es6 as sho0n in 3able "1-9
3able "1-) 4ythonCs 'uilt1&n (umeric Data 3y#es
M#en table as s#readsheet
3y#e /ey0ord% @8am#le ?sed forS
4lain inte$ers int% and lon$
inte$ers long%
+ 6666666666. Whole numbers lon$ inte$ers
are 7ery lar$e 0hole numbers9%
Floatin$ #oint numbers
float%
-9-+-!2,A+-!2,A+-" Deal numbers
:om#le8 numbers complex% "N!F% &ma$inary numbers
Decimal numbers
decimal"Oecimal%
decimal9DecimalI-,-92I% :alculations reGuirin$ decimal
arithmetic
@8ce#t 0hen youCre doin$ di7ision 0ith inte$ers or usin$ the decimal module see
:ha#ter +%6 you donCt ha7e to 0orry about 0hat /ind of number data ty#e youCre usin$9
4ython con7erts numbers into com#atible ty#es automatically9 For e8am#le6 if you
multi#ly an inte$er and a floatin$ #oint number6 4ython automatically $i7es the ans0er as
a floatin$ #oint number)
>>> x = &
"*
>>> y = /"&
>>> x ; y
E"&
For more information about numbers and number data ty#es6 see :ha#ter +9
Se3uential data
SeGuential data ty#es contain multi#le #ieces of data6 each of 0hich is numbered6 or
inde!ed. @ach #iece of data inside a seGuence is called an element.
D@M@M'@D 3he cool thin$ about seGuential data ty#es is that you can mani#ulate the
0hole seGuence6 chun/s of the seGuence6 or indi7idual elements inside the
seGuence9
3hree seGuential data ty#es are built into 4ython)
-ists can store multi#le /inds of data both te8t and numbers6 for e8am#le%9 Eou
can chan$e elements inside a list6 and you can or$anize the data in 7arious 0ays
for e8am#le6 by sortin$%9
Tuples, li/e lists6 can include different /inds of data6 but they canCt be chan$ed9 &n
4ython terminolo$y6 they are immutable.
!trin"s store te8t or binary data9 Strin$s are immutable li/e tu#les%9
3able "12 introduces 4ythonCs built1in seGuential data ty#es9
3able "12) 4ythonCs 'uilt1in SeGuence Data 3y#es
M#en table as s#readsheet
Type
5?ame6
8ind 2xample &sed for@
str Strin$% &mmutable
x = "monty pyt2on"
Storin$ te8t
t-ple
3u#le%
&mmutable
x = )"a", 2, "33"*
Storin$ a set of items you 0ant fast
access to
list .ist% Mutable
x = ["2ere", "is",
"my", "list", .E]
Storin$ a set of items you 0ant to be
able to chan$e readily
3o see the data ty#e of a 4ython obFect6 use the type)* function6 li/e this)
>>> type ),foo,*
#type ,str,>
1ictionaries
4ythonCs dictionary its /ey0ord is dict% is a data ty#e that stores multi#le data items
elements% of different ty#es9 &n a dictionary6 each element is associated 0ith a uniGue
!0
key, 0hich is a 7alue of any immutable ty#e9 When you use a dict6 you use the /ey to
return the element associated 0ith the /ey9
Eou use a dictionary 0hen you 0ant to store and retrie7e items by usin$ a /ey that
doesnCt chan$e and 0hen you donCt care in 0hat order 4ython stores the items9 &n
dictionaries6 elements arenCt numbered9%
3i# <ereCs 0hat a 4ython dictionary is not) A 4ython dictionary bears only a small
resemblance to the /ind of dictionary that contains 0ords and their definitions9 &n
4ython6 a dictionary is more li/e a list of em#loyees and their em#loyee numbers9
'ecause each em#loyee number is uniGue6 you can loo/ u# that em#loyee by ty#in$
his or her number9
D@M@M'@D Dictionaries are mutable6 li/e lists6 but their /eys are immutable9
<ere is an e8am#le of a dictionary 0ith t0o /ey)7alue #airs)
s9allo9$5elocity = {"e-ropean"! ".E", "african"! "<="}
Eou can find out much more about usin$ dictionaries in :ha#ter *9
Sets
A set stores multi#le items6 0hich can be of different ty#es6 but each item in a set must be
uniGue9 Eou can use 4ython sets to find unions6 intersections6 differences6 and so on>Fust
li/e the sets that #robably annoyed you in school9
Mne use for sets is 0hen you ha7e re#etitious data and you 0ant to i$nore the re#etition9
For e8am#le6 ima$ine that you ha7e an address database and you 0ant to find out 0hich
cities are re#resented6 but you donCt need to /no0 ho0 many times each city a##ears in
the database9 A set 0ill list each city in the database only once9
3he synta8 for a set is a little different from the synta8 of the other data ty#es described
in this section9 Eou use the 0ord set follo0ed by a name or a $rou# of elements% in
#arentheses9 <ere is a set that finds each uniGue element in a list9 EouCll notice that the
elements are out of order in the set9 3hatCs because 4ython doesnCt store set elements in
al#hanumeric order the same is true for dicts%)
>>> mylist = [,spam,, ,lo5ely,, ,spam,, ,glorio-s,, ,spam,]
>>> set)mylist*
set)[,lo5ely,, ,glorio-s,, ,spam,]
%iles
4ython uses the file data ty#e to 0or/ 0ith files on your com#uter or on the &nternet9
(ote that the file ty#e is not the same as the actual file9 3he file ty#e is 4ythonCs
internal representation of a com#uter or &nternet file9
!-
D@M@M'@D 'efore 4ython can 0or/ 0ith an e8istin$ file or a ne0 file6 you need to
o#en the file inside 4ython9
3his e8am#le o#ens a file called myfile)
open)"myfile"*
Eou can do a lot 0ith files in 4ython9 :hec/ out 4art &B to find out more9
1ata types ha$e ethods
&n 4ython6 each data ty#e has built1in actions associated 0ith it6 0hich let you do 7arious
thin$s 0ith the data9 3hese actions are called methods. Methods are tailored to 0or/
efficiently 0ith their #articular data ty#es9
#allin" a method9An example
<ereCs an e8am#le of ho0 you use6 or call, a method on a #iece of data9 Strin$s te8t
characters inside Guotation mar/s% come 0ith a method called -pper)*6 0hich ma/es all
the characters u##ercase9 3o use the -pper)* method on a strin$6 follo0 these ste#s)
-9 +ive a name to the strin", like this,
2" >>> Qed = "lo9ercase string"
"9 Type the name, a dot, the method name, and a set of parentheses.
3his e8am#le chan$es the Qed strin$Cs characters to u##ercase)
>>> Qed"-pper)*
,3JW6BHL@6 @0BG1S,
3@:<(&:A.
S3?FF
&ncidentally6 you can also use methods 0ith 7alues that ha7enCt been
$i7en names9 For e8am#le6 the code ,2i,"-pper)* $i7es the result
,HG,9 Mne method thatCs commonly used this 0ay is the strin$
method Toin)*6 0hich combines strin$s9 Most of the time6 ho0e7er6
itCs $ood #ractice to $i7e names to 7alues before usin$ methods on
them9
assin" information to a method
3he #arentheses at the end of a method>for e8am#le6 -pper)*>tell 4ython to #erform
the action associated 0ith the method that is6 to call the method%9
3i# &f you for$et the #arentheses6 4ython $i7es you some information about the method
obFect instead6 as in this e8am#le)
>>> ,mystring,"-pper
#(-ilt7in met2od -pper of str o(Tect at %x'2%E/a%>
!2
3he #arentheses ha7e another use6 too9 When callin$ some methods6 you sometimes need
to include additional information about ho0 the method should act9 Eou #ut this
information also called the argument% inside the #arentheses9 3his is called passing data
or passing an argument% to the method9
For e8am#le6 hereCs ho0 you 0ould use a list method called append)* to $et 4ython to
add an item to a list)
-9 +ive a name to a list with several text strin"s like this,
2" >>> s2opping$list = [,eggs,, ,(acon,, ,spam,]
"9 To add an item to the s2opping$list list, type the list name, a dot, the
method name, and a new item inside parentheses, like this,
." >>> s2opping$list"append),(-tter,*
Eou can ty#e the list name a$ain to see the ne0 contents of the list)
>>> s2opping$list
[,eggs,, ,(acon,, ,spam,, ,(-tter,]
(perators Are !tandin" By
M#erators are another tool for 0or/in$ 0ith data9 EouCll reco$nize arithmetic symbols
such as : and 8 for addition and di7ision6 but 4ython also comes 0ith o#erators that cut
u# te8t6 chec/ 0hether t0o obFects ha7e the same 7alue6 and so on9 3his section
introduces se7eral /inds of 4ython o#erators)
Arithmetic, 3he math symbols 0eCre all familiar 0ith as 0ell as some less10ell1
/no0n ones9
#omparison, 3hese o#erators tell you 0hich of se7eral thin$s is bi$$er9
-o"ical or Boolean, 3hese o#erators test 0hether thin$s are true or false9
#onditional, 3his o#erator allo0s you to choose one of t0o 7alues based on a
lo$ical test9
Arithetic operators
4ython understands a 7ariety of math symbols9 <ere are a fe0 of them)
lus :%) Addition
arentheses )*%) ;rou#in$
Asterisk ;%) Multi#lication
:ouble asterisk ;;%) @8#onentiation ! to the #o0er of y%
3i# Some of these o#erators also 0or/ on data ty#es other than numbers6 but they may
0or/ differently9 For e8am#le6 : adds t0o numbers 2 : 2 $i7es the result .%6 but it
!"
concatenates strin$s ,2, : ,2, $i7es the result ,22,%9 Eou canCt use an o#erator
0ith t0o incom#atible data ty#es9 For e8am#le6 if you try to use : 0ith an inte$er
and a strin$6 4ython returns an error9
We discuss arithmetic o#erators in $reater detail in :ha#ter +9
#oparison operators
:om#arison o#erators test the relati7e sizes of t0o #ieces of data and $i7e either 0r-e or
>alse as the result9 3he symbols for these o#erators are as follo0s)
less than #%
$reater than >%
eGual to ==%
not eGual to != or #>%
Eou can use com#arison o#erators by themsel7es or in combination9 For e8am#le6 you
can test 0hether somethin$ is less than or eGual to somethin$ else by usin$ the o#erator
#=9
D@M@M'@D Eou use == t0o = symbols% to test 0hether somethin$ is IeGual toI
somethin$ else9 A sin$le = symbol $i7es a name to a 7alue9
Eou /no0 about com#arin$ the sizes of numbers>for e8am#le6 3 > 29 'ut 4ython can
com#are 7alues of most other data ty#es6 too9 3here are a fe0 ty#es you canCt com#are6
such as com#le8 numbers9% When you com#are items by usin$ these o#erators6 the result
is either 0r-e or >alse e8ce#t or some s#ecial data ty#es in third1#arty modules%9 <ere
are a cou#le of e8am#les)
Strin$s are com#ared usin$ al#habetical order6 but all ca#ital letters come before
are smaller than% all lo0ercase letters9
>>> ,a, # ,(,
0r-e
>>> ,K, # ,a,
0r-e
@ach item in a list or tu#le is com#ared a$ainst the item 0ith the same inde8
number in the other list or tu#le9
>>> [/] # [2]
0r-e
Also6 lists and tu#les are com#ared by len$th9
>>> [/, 2, 3] > [/, 2]
0r-e
!!
Boolean operators
4ython has three o#erators that test 0hether e8#ressions are true or false9 3hese are called
0oolean operators you mi$ht also see them referred to as logical operators%9
3he 'oolean o#erators 0or/ as follo0s)
and sto#s testin$ 0hen it encounters a false condition9
or sto#s testin$ 0hen it encounters a true condition9
4ython tests an e8#ression 0ith and and or o#erators from left to ri$ht and returns
the last 7alue tested9 3hese o#erators donCt return 0r-e and >alse unless the
e8#ressions themsel7es use com#arison o#erators9%
>>> ,/, and / and ,one,
,one,
>>> ,/, or / or ,one,
,/,
>>> )2 # 3* or )& > <*
0r-e
not returns 0r-e if the e8#ression is false and >alse if the e8#ression is true9
>>> not ,one,
>alse
Stuff li/e this is 0hy your $rammar teacher told you to a7oid double ne$ati7es9%
3i# &n 4ython6 false has a s#ecial meanin$9 &t refers to anythin$ that is zero or Iem#ty9I
For e8am#le6 the number 0 is false6 and so is a strin$ 0ith no characters ,,% and a
list 0ith no elements []%9 Eou usually use 'oolean o#erators to test for Iem#tiness9I
For more information about 'oolean o#erators6 see :ha#ter -09
#onditional operations
:onditional e8#ressions are ne0 in 4ython 29A9 3hey use this form)
U if H else P
3hey 0or/ li/e this) First6 : is e7aluated9 &f : is true6 then O is e7aluated to $i7e the
result9 Mther0ise6 E is e7aluated to $i7e the result9
3his e8am#le #rints ,(ar, because >alse e7aluates as false)
>>> print ,foo, if >alse else ,(ar,
,(ar,
For more information on conditional e8#ressions6 see :ha#ter -69
!A
0rder! please4
Eou #robably remember from math class that 0hen you do arithmetic6 multi#lication
ta/es #lace before addition for e8am#le6 " N 2 U A V -" because 2 U A is e7aluated first%9
.i/e0ise6 o#erations in 4ython ha##en in a s#ecific order6 0hich is called operator
precedence. As in arithmetic6 o#erations in #arentheses come first9
3able "1" describes o#erator #recedence in 4ython9 M#erators in hi$her ro0s are
e7aluated before o#erators in lo0er ro0s9 &f multi#le o#erators a##ear in a sin$le cell in
the table6 that means they are eGual in #recedence and are e7aluated from left to ri$ht
0hen they a##ear in an e8#ression9
3able "1") M#erator 4recedence
M#en table as s#readsheet
!ymbol Type of operator
)a,(*6 [a,(]6 {a!(} :reation of tu#les 7ia the comma o#erator%6 lists6 and dictionaries
s[i]6 s[i!T]6
s[i!T!A]
&nde8 and slice o#erations on seGuence data ty#es%H brac/ets are
also used to select ma##in$ elements
f)M*
Function calls
x;;y
@8#onentiation e7aluated ri$ht to left%
x;y, x8y, x88y, xDy
Multi#lication6 di7ision6 inte$er di7ision6 modulo remainder%
x:y6 x7y Addition6 subtraction
x#y6 x#=y6 x>y6 x>=y6
x==y6 x!=y
:om#arison and eGuality
x is y6 x is not y &dentity
x in y6 x not in y Membershi#
not x
.o$ical ne$ation
x and y
.o$ical and
x or y
.o$ical or
if8else
:onditional e8#ression
Special po&ers of the 5 sybol
3he = symbol mi$ht loo/ li/e an o#erator6 but in 4ython6 it isnCt9 3he = si$n is used for
assignment>associatin$ a 7alue 0ith a name9
D@M@M'@D &n 4ython6 donCt use = to $et the result of arithmetic o#erations in the 0ay
you do 0hen you use a calculator9 4ython stores the results of such
calculations automatically9 Also6 donCt use = to test 0hether one thin$ is the
same as another for that6 you use == or is%9
!6
If *e 4ay #omment@
4ython6 li/e almost all #ro$rammin$ lan$ua$es6 lets you add comments to your #ro$ram9
:omments are te8t in your #ro$ram that the 4ython inter#reter i$nores9 Why 0ould you
0ant to add stuff that the com#uter i$nores2 :omments hel# other #eo#le understand ho0
the #ro$ram 0or/s9 3hey also let you deci#her your o0n code si8 months later5
3o add a comment to your #ro$ram6 ty#e + a #ound si$n% and then ty#e your comment9
Eou can ty#e + either at the be$innin$ of a line of code or after the code9 &f you 0rite a
comment that s#ans more than one line6 use + at the be$innin$ of each line9
3he e8am#le belo0 sho0s comments in action)
+ 02ese are lines from onty Cyt2on,s "Carrot @Aetc2"
li5e$parrot = ",6,s pinin, for t2e fTords!" + ic2ael Calin
dead$parrot = "Iereft of life, ,e rests in peace!" + Fo2n Hleese
It pays to be con$entional
4ython #ro$rammers ha7e con7entions for ho0 they add comments to their #ro$rams9
3he con7entions ma/e the comments and code easier to read by other #ro$rammers9
<ere are some of the $uidelines for comments)
=ee# lines to fe0er than ,0 characters9
3his con7ention a##lies to the 0hole #ro$ram6 not Fust the comments9%
&ndent comments the same amount the code is indented9
For more information on indentin$6 see IDeci#herin$ :ode 'loc/s6I later in this
cha#ter9
?se inline comments comments that come after a line of code% s#arin$ly6 and
only to e8#lain thin$s that arenCt clear from readin$ the code9
3he most im#ortant con7ention for comments is this one from the Style ;uide for 4ython
:ode htt#)LL0009#ython9or$Lde7L#e#sL#e#1000,%)
:omments that contradict the code are 0orse than no comments9 Al0ays ma/e a #riority
of /ee#in$ the comments u#1to1date 0hen the code chan$es5
!+
1ocuenting your progra
4ython su##orts a s#ecial /ind of comment called a docstring.
As 0ith other comments6 you use docstrin$s to hel# others understand your code9 WhatCs
different about docstrin$s is that they 0or/ 0ith 4ythonCs hel# utility so that someone can
fi$ure out 0hat your code does 0ithout ha7in$ to loo/ at the actual file9
A docstrin$ is al0ays the first line in a function9 &t can be more than one line if you be$in
and end it 0ith three Guotation mar/s9 <ereCs an e8am#le docstrin$ for a function 0e
made u# called printme)*)
def printme)me*!
"""
Crints its arg-ment"
"""
<ereCs 0hat you see if you as/ for hel# on the printme)* function)
>>> 2elp)printme*
Help on f-nction printme in mod-le $$main$$!
printme(me)
Crints its arg-ment
For detailed instructions on 0ritin$ docstrin$s6 see :ha#ter --9
(opsies< &nderstandin" 2rror 4essa"es
When 4ython finds synta8 mista/es or other errors in your code6 it $i7es you error
messa$es to hel# you fi$ure out 0hat the #roblem is9 For e8am#le6 you $et this error
messa$e 0hen you try to use an eGuals si$n =% to do an arithmetic calculation)
>>> & 7 < =
>ile "#stdin>", line /
& 7< =
?
@yntax6rror! in5alid syntax
3he messa$es differ de#endin$ on the ty#e of error but usually include these ty#es of
information)
The filename
D@M@M'@D When you 0or/ in interacti7e mode6 the file is al0ays ,#stdin>,9
The line of code where ython first fi"ured out there was an error
The kind of error
!,
For a synta8 error6 a caret ?% #oints to the #roblem character or to the #lace 0here the
inter#reter first fi$ured out there 0as a #roblem%9
Some error messa$es include information about the conditions in 0hich the error
occurred this is called traceback information%9 3he messa$e you $et 0hen you try to
di7ide by zero is an e8am#le)
>>> x = %
>>> = 8 x
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
KeroOi5ision6rror! integer di5ision or mod-lo (y Qero
:ecipherin" #ode Blocks
&n 4ython6 you can 0rite chun/s of code6 or code blocks, that #erform a sin$le function or
$rou# to$ether se7eral related tas/s9 We discuss the se7eral /inds of code bloc/s and ho0
to 0rite them in the follo0in$ sections9
The bi" deal about indentation
&n many #ro$rammin$ lan$ua$es6 youCre encoura$ed>but not reGuired>to indent a
chun/ of code that 0or/s as a unit9 Some #ro$rammers are notoriously lazy about ma/in$
their code readable to humans6 and that means #ro$rams in those lan$ua$es may not
include indentation9
&n 4ython6 ho0e7er6 indentation is built into the inter#reter9 :ode thatCs #art of a bloc/
must be indented6 or else you $et an error messa$e9 3his is one of the features that ma/es
4ython es#ecially readable9
&ndentation is so im#ortant to 4ython that 4ythonistas #rinted u# a 31shirt)
Cyt2on!
programming
t2e 9ay
S-ido
indented it
#ode block syntax
3here are t0o sim#le synta8 rules to remember about code bloc/s)
!*
3he code on the first line of a code bloc/ al0ays ends 0ith a colon !%9
3he code underneath the first line of a code bloc/ is indented9
4ython #ro$rammers almost al0ays use four s#aces for the first le7el of indentation6 ei$ht
s#aces for the ne8t le7el a code bloc/ nested inside another code bloc/%6 and so on9
3he indentation must be the same for e7ery line of a bloc/9 Eou $et an
Gndentation6rror messa$e if you use6 for e8am#le6 four s#aces on one line of a bloc/
and three s#aces on another line in the same bloc/9
Basic code blocks: #ontrol structures and loops
'asic code bloc/s in 4ython be$in by testin$ 0hether a condition or e8#ression is true9
4ython carries out instructions de#endin$ on the result of the test9
&n the follo0in$ sections6 0e introduce se7eral /inds of control structures and loo#s and
#ro7ide an e8am#le of each9 DonCt 0orry if you donCt understand e7ery bit of the code in
the e8am#les ri$ht no0H itCs e8#lained in more detail in :ha#ter -09
If statements
An if statement carries out one or more tests in a s#ecified order9 3he first line al0ays
be$ins 0ith ifH subseGuent tests be$in 0ith elif 0hich stands for Ielse ifI%6 and you can
add an else clause that runs if all the tests fail9
<ereCs an e8am#le of an if statement that includes an else clause9 3he else! line is not
indented under the if! line because itCs #art of the structure of the if statement6 as
o##osed to bein$ one of the bloc/s inside the statement)
if statement == "We,re fres2 o-t of red 3eic2ester, sir"!
response = "J2, ne5er mind, 2o9 are yo- on 0ilsetV"
elif statement == "We 2a5e Hamem(ert, yessir"!
response = ">etc2 2it2er t2e fromage de la Ielle >rance!"
else!
response = "G,m going to 2a5e to s2oot yo-""
'or loops
A for loo# re#eats a bloc/ of instructions6 usually a s#ecific number of times9
3his e8am#le ta/es each item in little$list one at a time and #rints it9
>>> little$list = [,t2e,, ,N-icA,, ,(ro9n,, ,fox,]
>>> for t2e$item in little$list!
""" print t2e$item, ";",
"""
t2e ; N-icA ; (ro9n ; fox ;
A0
:hec/ out :ha#ter -0 for the lo0do0n on for loo#s9
*hile loops
A 92ile loo# re#eats an instruction as lon$ as a #articular condition is true9
3he follo0in$ e8am#le code #rints a number as lon$ as the countdo0n 7alue is $reater
than zero9 &t also subtracts - from the countdo0n 7alue each time around the loo#9
co-ntdo9n = /%
92ile co-ntdo9n!
print co-ntdo9n,
co-ntdo9n 7= /
print "(lastoff!"
<ereCs 0hat it #rints)
/% = ' E < & . 3 2 / (lastoff!
Try statements
A try clause attem#ts to run some code9 &t is accom#anied by one of the follo0in$)
Mne or more except clauses 0hich catch errors raised in the try bloc/%
A try L except statement can also ha7e an o#tional else clause9
A finally clause
3his clause runs automatically after the try clause and re1raises any errors9
3i# Startin$ in 4ython 29A6 a try clause can ha7e all the abo7e elements at once) try6
except6 else6 and finally9
<ereCs a try statement that recei7es some in#ut6 does one thin$ if the in#ut is an inte$er6
and does another thin$ if it isnCt)
-ser$inp-t = ra9$inp-t)"6nter an integer! "*
try!
n-m(er = int)-ser$inp-t*
print "Po- entered", n-m(er
except Wal-e6rror!
print "Gntegers, please!"
*ith blocks
3he 9it2 statement ne0 in 4ython 29A% e8ecutes a bloc/ in a #articular conte!t9 3his is
an ad7anced feature that 0e discuss in :ha#ter -69
A-
#ode blocks that create a naespace
Some 4ython code bloc/s set u# a s#ecial area to store the names they /no0 about9
#ames are labels for areas of com#uter stora$e that hold #articular 7alues or other
obFects9% 3hese areas are called namespaces.
@ach names#ace is self1contained6 so names from different #arts of a #ro$ram donCt bum#
into each other9 3his feature lets 4ython #ro$rammers create modular code that can be
e8tended in many different directions 0ithout ha7in$ to 0orry about 0hether their ne0
code uses the same names as code in other bloc/s6 modules6 or #ro$rams9
Se7eral /inds of code bloc/s create names#aces9 <ere is a brief introduction to some of
them9
'unctions
A function is li/e a blender or a bread ma/er9 Eou #ut data into it6 it does thin$s 0ith the
information6 and it returns a result9
<ere is a small function you may note there are no s#aces at the end of the te8t strin$s9
3he comma stands for a sin$le s#ace%)
>>> def myf-nction)x*!
""" y = x;;x
""" print x, "raised to t2e po9er of", x, "is", y
""" ret-rn y
"""
And hereCs ho0 you mi$ht call it9
>>> res-lt = myf-nction)&*
& raised to t2e po9er of & is 3/2&
>>> res-lt
3/2&
4odules
A module is a te8t file that can contain any /ind of 4ython code6 but a module usually
or$anizes tools that 0or/ in a #articular 0ay9 Sometimes it also includes names that store
#articular 7alues9 Eou can ma/e a module a7ailable to another #ro$ram by importing it9
3@:<(&:A.
S3?FF
Modules are the /ey to 4ythonCs #ortability and #o0er9 4ython itself
is made u# of modules9
For e8am#le6 4ython has a mat2 module that includes a number of s#ecialized
mathematical tools6 and it also defines some names6 includin$ pi9 <ereCs ho0 you im#ort
it)
A2
>>> import mat2
<ereCs ho0 you access the name pi that it defines)
>>> mat2"pi
3"/./&=2<&3&'=E=3/
3his boo/ co7ers many of the im#ortant modules that come 0ith 4ython9 For instructions
on 7ie0in$ the list of modules that 4ython comes 0ith6 see :ha#ter 29
#lasses
A class is similar to both a factory and a blue#rint in that it ma/es co#ies of itself>but
the co#ies are 0hat do the actual 0or/9 <ere is an e8am#le of a class)
class @ayy1ame!
def $$init$$)self, myname*!
self"myname = myname
def say)self*!
print "Hello, my name is", self"myname
Eou use a class to create obFects called instances that can do s#ecific thin$s9 3his code
creates an instance of the @ayy1ame class)
name/ = @ayy1ame)"La2Q"*
An instance has access to the classCs methods 0hich are Fust functions attached to a
class%9 3his code a##lies the say)* method to the name/ instance)
>>> name/"say)*
Hello, my name is La2Q
:lasses are useful because they can combine both data and methods that o#erate on that
data9 4ythonCs data ty#es>lists6 strin$s6 and so on>are based on classes9
A"
#hapter A, +rand Tour of the ython
-an"ua"e
&n this cha#ter6 0e #resent and analyze a 0hole 4ython #ro$ram so you can see ho0 all
the #arts 0or/ to$ether9
3i# Eou may 0ant to /ee# a boo/mar/ on the #ro$ram so you can fli# bac/ and forth
bet0een the 0hole #ro$ram and the discussion9
The spider.py ro"ram
Mur sam#le #ro$ram .istin$ !1-% finds all the #a$es 0ithin a Web site9 When you run it
from the command line6 it #rints the results to stdo-t the o#eratin$ systemCs standard
out#ut stream%9 Eou can also use it as a module to ma/e it a buildin$ bloc/ in a lar$er
#ro$ram9
D@M@M'@D 3he #ro$ram doesnCt chec/ lin/s to Web #a$es e8ternal to the site9
3his #ro$ram has three #arts)
The import statements
The function and class definitions
The body of the pro"ram, 0hich calls the functions and class
.istin$ !1-) s#ider9#y
+++++++++++++++++++++++++++++++++++++++++++++++
+ program! spider"py
+ a-t2or! aa2Q
+ 5ersion! /"/
+ date! F-ne 2%%<
+ description! start on command line 9it2 4B3 arg-ment"
+ >inds pages 9it2in a 9e( site"
+++++++++++++++++++++++++++++++++++++++++++++++
+ 02ese mod-les do most of t2e 9orA"
import sys
import -rlli(2
import -rlparse
import 2tmlli(, formatter
from c@tringGJ import @tringGJ
def log$stdo-t)msg*!
"""Crint msg to t2e screen""""
print msg
A!
def get$page)-rl, log*!
"""Betrie5e 4B3 and ret-rn contents, log errors""""
try!
page = -rlli(2"-rlopen)-rl*
except -rlli(2"4B36rror!
log)"6rror retrie5ing! " : -rl*
ret-rn ,,
(ody = page"read)*
page"close)*
ret-rn (ody
def find$linAs)2tml*!
"""Bet-rn a list of linAs in 2tml""""
+ We,re -sing t2e parser T-st to
9riter = formatter"O-m(Writer)@tringGJ)**
f = formatter"L(stract>ormatter)9riter*
parser = 2tmlli("H03Carser)f*
parser"feed)2tml*
parser"close)*
ret-rn parser"anc2orlist
class @pider!
"""
02e 2eart of t2is program, finds all linAs 9it2in a 9e( site"
r-n)* contains t2e main loop"
process$page)* retrie5es eac2 page and finds t2e linAs"
"""
def $$init$$)self, start4B3, log=1one*!
+ 02is met2od sets initial 5al-es
self"4B3s = set)*
self"4B3s"add)start4B3*
self"incl-de = start4B3
self"$linAs$to$process = [start4B3]
if log is 1one!
+ 4se log$stdo-t f-nction if no log pro5ided
self"log = log$stdo-t
else!
self"log = log
def r-n)self*!
+ Crocesses list of 4B3s one at a time
92ile self"$linAs$to$process!
-rl = self"$linAs$to$process"pop)*
self"log)"Betrie5ing! " : -rl*
self"process$page)-rl*
def -rl$in$site)self, linA*!
+ H2ecAs 92et2er t2e linA starts 9it2 t2e (ase 4B3
ret-rn linA"starts9it2)self"incl-de*
def process$page)self, -rl*!
+ Betrie5es page and finds linAs in it
AA
2tml = get$page)-rl, self"log*
for linA in find$linAs)2tml*!
+ Handle relati5e linAs
linA = -rlparse"-rlToin)-rl, linA*
self"log)"H2ecAing! " : linA*
+ aAe s-re t2is is a ne9 4B3 9it2in c-rrent site
if linA not in self"4B3s and self"-rl$in$site)linA*!
self"4B3s"add)linA*
self"$linAs$to$process"append)linA*
if $$name$$ == ,$$main$$,!
+ 02is code r-ns 92en script is started from command line
start4B3 = sys"arg5[/]
spider = @pider)start4B3*
spider"r-n)*
for 4B3 in sorted)spider"4B3s*!
print 4B3
2xaminin" a ython ro"ram
First6 0e discuss ho0 the #ro$ram is or$anized9 3hen 0e sho0 you some of the 4ython
features the s#ider uses9
Setting up the structure
3he to# of spider"py contains a bunch of import statements9 .oo/in$ there $i7es you a
Guic/ idea of 0hat the #ro$ram does and ho0 it 0or/s6 because most 4ython #ro$rams
rely hea7ily on im#orted modules9
&f you /no0 the modules that come 0ith 4ython6 youCll /no0 from loo/in$ at the import
statements that this #ro$ram is desi$ned to read and #rocess information from ?D.s
Web site addresses%9 <ere is 0hat each module does in the #ro$ram)
3he sys module retrie7es a startin$ ?D. from the command line 0hen
spider"py is run as a scri#t9 :ha#ter -+ co7ers the sys module9%
-rlli(2 retrie7es data from ?D.s9See :ha#ter 209%
3he -rlparse module slices and dices ?D.s and #uts them bac/ to$ether9 See
:ha#ter 209%
2tmlli( and formatter are im#orted on the same line because theyCre used
to$ether to #arse information out of <3M. filesH in this #ro$ram6 0e use them
only to $et the lin/s anchors or <D@Fs%9 See :ha#ter 209%
from c@tringGJ import @tringGJ im#orts an obFect that #retends a strin$ is a
file9 See :ha#ter -,9%
A6
3i# (ote the fromMimport synta89 We recommend a7oidin$ fromMimport ;
because it can clutter u# your #ro$ram 0ith conflictin$ names6 but fromM
import synta8 is a##ro#riate 0hen the module e8#orts a sin$le class6 as here9
Initiali6ing the spider
Do0n near the bottom of the #ro$ram is this statement)
if $$name$$ == ,$$main$$,!
All the code after that statement runs only 0hen you start the #ro$ram from the command
line9
3@:<(&:A.
S3?FF
&n 4ython #ro$rams6 this code often contains testin$ instructions9 &f
ours did6 ty#in$ pyt2on spider"py at the command #rom#t 0ould
cause spider"py to test itself9 &n our #ro$ram6 the code #rocesses a
command1line ar$ument9 Eou can start the #ro$ram from the
command #rom#t and $i7e it a ?D. to e8amine)
D pyt2on spider"py 2ttp!88pyt2onfood"com8spider7test8
'et0een the to# the import statements% and the bottom the command1line code% lies
the meat of the module9 3he spider"py scri#t contains these bloc/s of code)
3hree functions) log$stdo-t)*6 get$page)*6 and find$linAs)*
Mne class) @pider
&f you loo/ bac/ do0n at the bottom6 you notice the follo0in$ line)
spider = @pider)start4B3*
3his line creates an instance of the @pider class9 3his means the @pider class is the heart
of this module9
D@M@M'@D When tryin$ to understand 0hat a 4ython scri#t does6 itCs best to start at
the bottom and 0or/ your 0ay u# because classes and functions ha7e to be
created and named before they are called before the #ro$ram as/s them to
run%9 So in a 4ython #ro$ram6 any def statements 0hich create functions%
and class statements 0hich create classes% al0ays come before
statements that actually run the code inside the functions and classes they
define9
/unning the spider
Fi$ure !1- sho0s 0hich #arts of the spider"py #ro$ram tal/ to each other #ass
information%9 Eou mi$ht find Fi$ure !1- useful 0hile readin$ this section or readin$ the
#ro$ram itself9
A+
Fi$ure !1-) &nformation #assin$ in the s#ider9#y #ro$ram9
/eadin" the spider web
&n the S#ider class6 the process$page)* method is se#arate from r-n)* because r-n)*
is easier to understand 0hen you donCt ha7e to loo/ at all the code in process$page)* at
the same time9 3his choice e8em#lifies t0o reasons behind 4ythonCs modular desi$n
#hiloso#hy9
&tCs a $ood idea to se#arate out chun/s of code that do different thin$s)
Se#aratin$ tas/s into chun/s ma/es it #ossible to use each chun/ on its o0n9
Deadin$ a chun/ of code that does only one thin$ is easier than readin$ a chun/ of
code that does multi#le thin$s9
The workin"s of the !pider class
3o see ho0 the heart of the spider"py #ro$ram #rocesses information6 loo/ at the
@pider class9 3o use this class6 you ha7e to create an instance of it9
D@M@M'@D &nstances are obFects created from classes see :ha#ter -" for the details%)
A class is li/e a template.
An instance is li/e a document created from that tem#late9
3he #arts of the S#ider class #erform the follo0in$ tas/s)
3he $$init$$)* method sets u# the instance9
A,
3he r-n)* method does the real 0or/9 &tCs a sim#le loo# that
o Processes ne0 #a$es from the self"$linAs$to$process list% until there
are no more #a$es
o Calls the process$page)* method each time throu$h the loo#6 usin$ a
ne0 item from the self"linAs$to$process list9
3he process$page)* method contains a loo# that includes an if statement9 See
:ha#ter -0 to find more about if statements and loo#s9%
3he loo# sends a ?D. to the get$page)* function6 0hich o#ens the Web #a$e6
reads it6 and returns its contents9 3hen the loo# sends the contents of the Web #a$e
to the find$linAs)* function6 0hich lo$s and returns a list containin$ all the
lin/s in that ?D.9
3he statement if linA not in self"4B3s and self"-rl$in$ site)linA*!
chec/s 0hether this lin/ is already in the self"4B3s set and 0hether itCs #art of
the Web site 0eCre analyzin$9 3his s#ider only chec/s lin/s internal to the Web
site of the ori$inal ?D.9 &f you 0ant to chec/ lin/s to other Web sites6 you need
some different code here9% &f the lin/ #asses the tests6 itCs added to the self"4B3s
set and the self"$linAs$to$process list9
:esi"nin" for expansion
3o understand another desi$n decision in the spider"py #ro$ram6 loo/ at the
-rl$in$site)* method9 &t chec/s 0hether the lin/ is #art of the Web site9
Ma/in$ -rl$in$site)* a se#arate method doesnCt ma/e it easier to read the #ro$ram6
because the method has only one line of code9 We decided to ma/e a se#arate method for
another reason) doin$ so ma/es it easier to subclass @pider9 ,ubclassing is ma/in$ a ne0
class that shares most of the features of a class but either overrides or e!tends some of its
functionality9 :ha#ter -" has more about subclassin$9% Mne 0ay to subclass @pider is to
e8tend the beha7ior of -rl$in$site)* so that it 0or/s 0ith both <334 and <334S
?D.s at the same time9 3he current #ro$ram handles only one ty#e at a time9% <a7in$
-rl$in$site)* se#arate from process$page)* means that such a subclass is easier to
0rite9 3his illustrates another $ood #ro$rammin$ #ractice9
D@M@M'@D When youCre desi$nin$ a #ro$ram6 thin/ about the #ossibility that someone
mi$ht 0ant to customize or subclass your #ro$ram in the future9 'ut donCt
o7erdesi$n or add features before theyCre needed9 4ython #ro$rams are
easy to chan$e6 so you can Guic/ly add features 0hen necessary9%
3@:<(&:A.
S3?FF
3he process$page)* method combines the ?D.s returned from
find$linAs)* 0ith the base ?D. s#ecified by -rl9 We could ha7e
#ut this functionality into the find$linAs)* function9 'ut lea7in$ it
out ma/es find$linAs)* more $enerally useful>0e or others% can
reuse it in #ro$rams that 0or/ 0ith relati7e ?D.s in a different 0ay
from this one9 3his is an e8am#le of the desi$n #hiloso#hy described
in the #recedin$ #ara$ra#h9
A*
&sin" Buildin" Blocks
3his section describes ho0 the spider"py #ro$ram uses 4ythonCs most im#ortant
buildin$ bloc/s and tools>functions and methods6 loo#s6 containers6 names6 strin$s6 and
error chec/in$9
%unction and ethod tidbits
3he spider"py #ro$ram illustrates /ey #rinci#les to /ee# in mind 0hen 0ritin$ functions
and methods9
&nderstandin" default parameters
3he $$init$$)* method has the #arameter log=1one9 3his is called a default parameter9
See :ha#ter --9% &t means that 0hen you ma/e an instance of the @pider class6 you can
s#ecify a #arameter for log6 but you donCt ha7e to9 &f you donCt6 the instance automatically
uses 1one as the 7alue for log9
Default #arameters $i7e you choices and ma/e your code more fle8ible9 'ecause of the
default lo$ #arameter6 a number of different o#tions for lo$$in$ can be used 0ith the
S#ider class9
D@M@M'@D 3he other side of the coin is that if you use a default #arameter6 you need
to 0rite code to test for the default 7alue9 &n the S#ider class6 this code is
#art of the $$init$$)* method9 &t assi$ns the log$stdo-t)* function to
self"log if the user doesnCt s#ecify a 7alue for log%9 &n contrast6
get$page)* reGuires a log ar$ument and therefore doesnCt need to chec/
for a default 7alue9
/eco"ni)in" bare naked functions
D@M@M'@D Most functionLmethod calls ha7e self or a module name in front of them6
follo0ed by a dot9 When youCre readin$ a #ro$ram6 if you see a bare
function or method or class%>one 0ithout self or a module name>it
usually means one of these)
&t 0as defined in the module li/e get$page)* and find$linAs)*
are in this #ro$ram%9
&t 0as im#orted by usin$ the fromM import synta8 li/e
@tringGJ%9
&t is a built1in function li/e sorted)*6 do0n at the bottom%9
D@M@M'@D Functions and methods are essentially the same thin$>a code bloc/ that
60
#erforms an action and returns a result9 <ereCs the difference)
A function is by itself in a module9
A method is #art of a class9
:ha#ters "6 --6 and -" describe ho0 to use functions6 methods6 and
classes9
Looping around
3he spider"py scri#t contains three loo#s)
30o for loo#s
D@M@M'@D 4ython #ro$rammers $enerally fa7or for loo#s6 because for loo#s
can both assi$n 7alues and #ro7ide one element at a time9
Mne 92ile loo#
3i# A 92ile loo# is often better 0hen you are both addin$ and deletin$ elements6
so 0e used a 92ile loo# in the section 0here the r-n)* method deletes
elements from the self"$linAs$to$process list 7ia the list method pop)*%
and also adds elements to the list 7ia process$page)*%9
:ha#ter -0 sho0s you more 0ays to use loo#s9
#ollections of data
Sets6 lists6 and dicts are 4ythonCs data ty#es for dealin$ 0ith collections of data6 es#ecially
if the data chan$e 0hile the #ro$ram is runnin$9
-ists
.ists described more fully in :ha#ter ,% are most efficient6 0hich is one reason 0e used
a list self"$linAs$to$process% to /ee# trac/ of all the lin/s 0eCre #rocessin$9 .ists
are also $ood 0hen you need to
Maintain elements in a #articular order9
Allo0 du#licate elements9
!ets
Sets are a $ood 0ay of handlin$ data 0hen you 0ant to i$nore or a7oid du#licates9
3i# We used a set for the #rimary ?D. data in the @pider class self"4B3s% because 0e
0anted only one co#y of each ?D.9 :ha#ter * sho0s more 0ays to use sets9
6-
:icts
Dicts are $ood for data that 0ill be stored and accessed by /eys rather than ordered
al#habetically or numerically9
3i# &f 0e had 0anted to associate some data 0ith each ?D. in the Web #a$e6 0e 0ould
ha7e used a dict9 :ha#ter * sho0s you ho09
2aing naes
&f a $ood name is one that hel#s you understand 0hat the named obFect is doin$6 then
there are some $ood names and some not1so1$ood names in spider"py9 An early draft of
our #ro$ram had functions named get$linAs)* and find$linAs)*9 3hose names donCt
really ma/e clear the differences bet0een the t0o functions6 so 0e renamed
get$linAs)* to get$page)*9
3i# 4ro$rammers sometimes choose terse and not 7ery e8#lanatory names on #ur#ose to
indicate that you shouldnCt #ay much attention to the name because itCs Fust a
tem#orary name used to con7ey information for e8am#le6 itCs used as an ar$ument to
a function or method%9 Sometimes a tem#orary name ma/es a fe0 lines of code
easier to read9 3a/e6 for e8am#le6 the lines of code that use the name f in the
find$linAs)* function)
f = formatter"L(stract>ormatter)9riter*
parser = 2tmlli("H03Carser)f*
We could ha7e $otten rid of f by 0ritin$ the code this 0ay instead)
parser = 2tmlli("H03Carser)formatter"L(stract>ormatter)9riter**
'ut thatCs /ind of lon$ and hard to read6 so 0e decided it 0as better to s#lit the lines and
use a tem#orary name9
D@M@M'@D ;i7e users of your modules information about 0hich attributes6 functions6
classes6 and methods they should a7oid accessin$ directly6 #assin$ to other
functions6 subclassin$6 or re0ritin$9 Mr6 more colloGuially6 IDas ist nicht
fWr $efin$er#o/en5I% Sometimes this information is con7eyed by usin$ a
sin$le underscore character as the first character in a name6 0hich means
the obFect is private9 See :ha#ter -" for more about #ri7ate attributes9%
For e8am#le6 0e chose to ma/e self"$linAs$to$process a #ri7ate name
because itCs 7alid only inside the @pider class9 We could ha7e made
-rl$in$site)* a #ri7ate name for the same reason6 but 0e didnCt in order
to send the messa$e that itCs suitable for o7erridin$ in a subclass9
(anaging strings
3here are a lot of 0ays you can 0or/ 0ith strin$s in 4ython)
62
4ython strin$s ha7e many methods built in9
For e8am#le6 0e use the starts9it2)* strin$ method in the -rl$in$site)*
function9 ?nsur#risin$ly6 starts9it2)* chec/s 0hether a strin$ starts 0ith a
#articular substrin$9%
Many 4ython modules include additional strin$1handlin$ functions9
We use one of these in the process$page)* method) -rlparse" -rlToin)-rl,
linA*9 3he -rlToin)* function as the name su$$ests>see the benefits of
namin$ thin$s 0ell2% stic/s to$ether t0o #arts of a ?D.6 0hich 0e #ass in as t0o
strin$s6 -rl and linA9
D@M@M'@D 'efore you start 0ritin$ some s#ecial functionality to #rocess strin$s6
chec/ 0hether someone else has already done the 0or/ for you9 3he :heat
Sheet lists the most commonly used strin$ methods9
.andling errors
Mne error1handlin$ tool in the spider"py #ro$ram is this bloc/ of code in the
get$page)* function)
try!
page = -rlli(2"-rlopen)-rl*
except -rlli(2"4B36rror!
log)"6rror retrie5ing! " : -rl*
ret-rn ,,
3his is called a try L except bloc/ see :ha#ter -0%9 &ts #ur#ose is to catch errors from
the -rlli(2"-rlopen)* function6 0hich tries to o#en a remote ?D.9
*hat spider.py doesn't have
3he spider"py #ro$ram 0or/s as1is6 but itCs missin$ a fe0 elements that are necessary to
ma/e it a fully functional 4ython #ro$ram that follo0s the con7entions of $ood
#ro$rammin$)
Docstrin$s for each function and class method9
@rror chec/in$9 For e8am#le6 if you try to run the #ro$ram from the command
line 0ithout s#ecifyin$ a ?D.6 the #ro$ram fails messily9 <ereCs 0hat ha##ens)
D pyt2on spider"py
0race(acA )most recent call
last*!
>ile "spider"py", line =/,
in #mod-le>
start4B3 = sys"arg5[/]
Gndex6rror! list index o-t of
6"
range
Why are 0e sho0in$ a #ro$ram 0ithout these features 0hen 0e reiterate ad nauseum in
this boo/ that you should include these features in your #ro$ram2 'ecause lots of
#ro$rammers tal/ about the benefits of comments6 documentation6 and error1chec/in$6
but lots of #ro$rams some 0ritten by those same #ro$rammers% donCt do as $ood of a Fob
on those thin$s as they should9 3his is a IDo as 0e say6 not as 0e doI situation9
A com#lete 7ersion of the #ro$ram 0ith documentation and error chec/in$ is on our Web
site)
htt#)LL0009#ythonfood9comL
D@M@M'@D &tCs $ood #ractice to use try 0ith &LM functions and user in#ut or other
e8ternal in#ut9 For e8am#le6 0e could im#ro7e our #ro$ram by mo7in$ the
(ody = page"read)* line into the try bloc/>because e7en if you can
o#en a Web #a$e6 you mi$ht still ha7e trouble readin$ it9 Similarly6
$arba$e in the <3M. can cause the 2tmlli( moduleCs #arser to cho/e6 so
the line parser"feed)2tml* should be in a try bloc/ as 0ell6 li/e this)
try!
parser"feed)2tml*
except 2tmlli("H03Carse6rror!
log)"6rror finding linAs! " : -rl*
ret-rn []
finally!
parser"close)*
ret-rn parser"anc2orlist
3he sidebar6 IWhat s#ider9#y doesnCt ha7e6I describes another s#ot 0here error1chec/in$
0ould be useful9
6!
#hapter B, *orkin" -ike a ro"rammer
(verview
4rofessional #ro$rammers s#end as little as -0 #ercent of their 0or/in$ time 0ritin$
code9 3his cha#ter focuses on 0hat they do the rest of the time9 3hese #ractices $enerally
consume about 60 #ercent of a #ro$rammerCs time on a #roFect)
.naly2ing problems
Designing solutions and documenting decisions
Debugging
'aintaining and improving code
Warnin$ 3he final "0 #ercent of a #ro$rammerCs time is ta/en by meetin$s and 0asted
time9 Sometimes6 thereCs no difference bet0een meetin$s and 0asted time9%
The Three :s
&f youCre 0ritin$ a #ro$ram thatCs more than a fe0 lines lon$6 donCt Fust sit do0n and start
codin$9 Eou need to ta/e three ste#s to ma/e your #ro$ram the best it can be9 3hese are
the three Ds)
:ocument, Ma/in$ sure others can read your #ro$ram
:esi"n, Ma/in$ sure your #ro$ram is sol7in$ the ri$ht #roblem and is or$anized
so that itCs efficient and #otentially reusable
:ebu", Ma/in$ sure your #ro$ram doesnCt ha7e any mista/es in it and that it
res#onds a##ro#riately 0hen $i7en 0ron$ in#ut
1ocuenting
Documentation ma/es it #ossible to read6 use6 and maintain a #ro$ram)
&n #ro$rammin$6 documentation is all the 0ritin$ associated 0ith your #ro$ram
that isnCt code9
With a lan$ua$e li/e 4ython6 readability is a #rime 7irtue9 3hat means your code
is #art of the documentation6 too9 For e8am#le6 #ic/in$ $ood names is #art of
documentation5
D@M@M'@D 4ro$rammin$ starts and ends 0ith documentation)
6A
!tart by writin" the problem that your pro"ram is intended to
solve.
'efore you e7en start 0ritin$ your #ro$ram6 itCs a $ood idea to
0rite notes about the $oal of the #ro$ram9 4retend you need to
e8#lain it to someone else>and if you ha7e someone to read the
notes6 so much the better9
2nd by makin" sure that the documentation still matches the
pro"ram.
Warnin$ &f you donCt 0rite documentation6 you 0ill find it difficult to use or maintain
your #ro$ram after lettin$ it sit for si8 months e7en if youCre the only #erson
0ho uses the #ro$ram%9
1esigning
Desi$nin$ is actually shorthand for t0o intert0ined #arts of #ro$rammin$) analysis and
design9
*hat do you really wantC
.nalysis is the #rocess of determinin$ 0hat #roblem youCre tryin$ to sol7e9 &tCs similar to
the #rocess an architect ma/es you $o throu$h to remodel your /itchen) IWhat do you
really 0ant2I For e8am#le6 you mi$ht 0ant to 0rite a #ro$ram to automate your data
bac/u#s9 3hatCs a $eneral descri#tion6 but you need a more s#ecific list of tas/s you 0ant
the #ro$ram to carry out6 such as
<o0 often do you 0ant to ma/e bac/u#s2
Do you 0ant to bac/ u# all data or only data chan$ed since the last bac/u#2
<o0 lon$ do you 0ant to /ee# bac/u#s2
After you ha7e some s#ecific ideas of 0hat you 0ant6 the desi$n #hase starts9
3@:<(&:A.
S3?FF
&f youCre remodelin$ your /itchen6 then this is the #oint 0here the
architect dra0s u# a blue#rint9 3he blue#rint isnCt the /itchen itselfH
itCs the #lan that needs to be follo0ed to build the ne0 /itchen9 &f
youCre 0ritin$ a #ro$ram6 you start to build the outline of the
#ro$ram6 0hich is similar to a blue#rint9 &n fact6 #eo#le 0ho focus on
the analysis and desi$n of #ro$rams are often called soft$are
architects9
66
seudo1codin" your thou"hts
Mne 0ay to desi$n your #ro$ram is to create an outline of sorts6 usin$ 0hat is called
pseudo-code9 Eou 0rite a s/etch of 0hat your #ro$ram 0ill do6 usin$ the structures youCll
need to use 0hen you 0rite the #ro$ram such as class and function definitions and if
statements%6 but you donCt bother 0ith the synta8 details necessary to 0rite 0or/in$ code9
3@:<(&:A.
S3?FF
4seudo1code tends to resemble real 4ython #ro$rams6 so it ta/es less
effort to con7ert #seudo1code into 0or/in$ 4ython code9 When the
#seudo1codin$ #rocess is finished6 the details are easy to fill in9
<ereCs an e8am#le of #seudo1code that almost 0or/s as 4ython code)
if today == s-nday!
f-ll$(acA-p)*
else!
incremental$(acA-p)*
1ebugging
A bug is a mista/e in a #iece of soft0are that causes it to 0or/ im#ro#erly or to return
incorrect results9
3@:<(&:A.
S3?FF
Teachin" an old bu" new tricks
3his use of the 0ord bug 0as already common before soft0are 0as
in7ented>for e8am#le6 3homas @dison used it in -,+, to describe
#roblems 0ith his in7entions9 Some #eo#le 0ill tell you6 thou$h6 that
the term deri7es from an incident in 0hich an actual insect 0as found
to be causin$ $litches inside an early com#uter in -*!+9
Althou$h bug is older than 0ritin$ #ro$rams6 debugging has been an
inherent #art of 0ritin$ soft0are since #eo#le started 0ritin$
soft0are9 Mne of the first com#uter scientists6 Maurice Wil/es6 is
re#uted to ha7e said6 I& can remember the e8act instant 0hen &
realized that a lar$e #art of my life from then on 0as $oin$ to be
s#ent in findin$ mista/es in my o0n #ro$rams9I
The Den of ython
Writin$ a com#le8 #ro$ram is somethin$ li/e desi$nin$ a buildin$9 3he architectCs
constraints include time6 money6 $ood taste6 and the structural limits of the materials9
4ro$rammin$ also reGuires balancin$ multi#le needs>often includin$ time6 money6 the
feature reGuests of multi#le $rou#s of #eo#le6 and the a7ailability of sufficient Guantities
of caffeine9
6+
4ythonista 3im 4eters contributed -* $uidelines for $ood 4ython code9 We consider them
the best distillation of the 4ython #hiloso#hy of #ro$rammin$9 3heyCre on this Web #a$e)
htt#)LL0009#ython9or$LdocLhumorLXzen
3hese are desi$n #rinci#les6 not rules to be follo0ed blindly9 3heyCre meant to encoura$e
you to thin/9 &n some cases the #rinci#les may a##ear contradictory9 3hatCs a reflection of
the fact that #ro$rammin$ sometimes reGuires balancin$ conflictin$ reGuirements9 &tCs
li/e the old sayin$) I;ood6 fast6 chea#>#ic/ any t0o9I 3he #rinci#les can hel# you
decide ho0 to #rioritize these reGuirements9
3he #rinci#les 0ere ori$inally 0ritten to $uide the de7elo#ment of 4ython itself6 but they
also a##ly to 0ritin$ your o0n #ro$rams9 3hatCs ho0 0e discuss them here9
Some of the most im#ortant $uidelines are these)
Expliit is !etter than impliit. ;ood code is as self1e8#lanatory as #ossible)
?se names that e8#lain the #ur#ose of the obFects they re#resent9
&nclude comments in your code 0hen it isnCt ob7ious 0hat a #articular line or
bloc/ does9
A7oid hidden effects9 For e8am#le6 #rintin$ to the screen shouldnCt erase your
hard dri7e9%
"eada!ility ounts. A $ood #ro$ram is easy for a human to read and understand9 &f t0o
bloc/s of code #roduce the same result6 consider usin$ the one thatCs easier to read9
Sometimes cry#tic code runs faster6 but s#eed isnCt the #rimary $oal of most 4ython
#ro$rammin$9%
Errors should never pass silently. &f you 0rite code that doesnCt alert the user of errors6
the errors mi$ht cause the #ro$ram to $i7e incorrect results)
'uild e8#licit error chec/in$ into your code9
Write code to catch any errors that you ha7enCt thou$ht of9
De#ort errors to the user of your #ro$ram9
#here should !e one$and pre%era!ly only one$o!vious way to do it. 3his $uideline
I3hereCs only one 0ay6I for short% is the most #o#ular amon$ #eo#le in the 4ython
community9 3his is #artly in res#onse to the motto of 4erl #ro$rammers6 0hich is6
I3hereCs More 3han Mne Way 3o Do &t9I 3he 4ython community creates and #o#ularizes
standard codin$ idioms%preferred $ays of performing certain tas/s%9 ?sin$ standard
idioms sa7es time because the code is already mostly 0rittenH you Fust #lu$ in your data
and 7ariables9 Python For Dummies includes many standard idioms to $et you started9
3y#in$ import t2is at the 4ython #rom#t in 4ython 29-92 or hi$her 0ill #rint the entire
list)
6,
>>> import t2is
02e Ken of Cyt2on, (y 0im Ceters
Iea-tif-l is (etter t2an -gly"
6xplicit is (etter t2an implicit"
@imple is (etter t2an complex"
Homplex is (etter t2an complicated"
>lat is (etter t2an nested"
@parse is (etter t2an dense"
Beada(ility co-nts"
@pecial cases aren,t special eno-g2 to
(reaA t2e r-les"
Llt2o-g2 practicality (eats p-rity"
6rrors s2o-ld ne5er pass silently"
4nless explicitly silenced"
Gn t2e face of am(ig-ity, ref-se t2e
temptation to g-ess"
02ere s2o-ld (e one77 and prefera(ly only
one 77o(5io-s 9ay to do it"
Llt2o-g2 t2at 9ay may not (e o(5io-s at
first -nless yo-,re O-tc2
1o9 is (etter t2an ne5er"
Llt2o-g2 ne5er is often (etter t2an special eno-g2 to
;rig2t; no9"
Gf t2e implementation is 2ard to explain,
it,s a (ad idea"
Gf t2e implementation is easy to explain,
it may (e a good idea"
1amespaces are one 2onAing great idea 77
let,s do more of t2ose!
Most com#uter #ro$rams ha7e bu$s9 When you disco7er #roblems 0ith the 0ay your
#ro$ram 0or/s or the results it $i7es6 you debug to
Find the source of the mista/e9
Fi8 the lines of code causin$ the #roblem9
As you $et comfortable 0ith #ro$rammin$ and 4ython6 you $et a better sense for ho0 the
com#uter Ithin/s6I 0hich hel#s you fi$ure out bu$s more Guic/ly9 EouCll become familiar
0ith common causes for common #roblems li/e)
!yntax errors. Missin$ #unctuation is the most common synta8 mista/e9 For
e8am#le6 if you try to create a strin$ but for$et a Guotation mar/6 youCll $et an
error li/e this)
>>> mystring = "1o! 1ot t2e Xnig2ts 92o say ,1i,!
>ile "#stdin>", line /
mystring = "1o! 1ot t2e Xnig2ts 92o say ,1i,!
?
@yntax6rror! 6J3 92ile scanning single7N-oted string
3i# EouCll ha7e fe0er synta8 errors in your #ro$rams if you use a 4ython1 a0are
6*
te8t editor that #rints different synta8 in different colors9
3i#s for a7oidin$ common synta8 errors can be found throu$hout Python for
Dummies9
4isspelled names. &f you name an obFect and then miss#ell the name 0hen you
refer to it later6 youCll $et an error9 For e8am#le)
>>> l-m(erTacA = "G,m JX"
>>> print l-m(reTacA
0race(acA )most recent call last*!
>ile "#stdin>", line /, in V
1ame6rror! name ,l-m(reTacA, is not defined
&sin" the wron" types of values. For e8am#le6 if you ha7e a number in strin$
format #erha#s from the ra9$inp-t)* function6 0hich con7erts the in#ut into a
strin$% and you try to do arithmetic 0ith it6 youCll $et a result you didnCt e8#ect6
li/e this)
>>> x = ra9$inp-t)"6nter a n-m(er! "*
6nter a n-m(er! .&
>>> x ; 2
,.&.&,
#reatin" infinite loops. &f you create a loo# by usin$ a condition that ne7er
terminates6 your #ro$ram 0ill try to run fore7er6 li/e the brooms that the
SorcererCs A##rentice creates)
sorcerer = "asleep"
def maAe$(room)*!
print "anot2er (room!"
92ile sorcerer == "asleep"!
maAe$(room)*
3i# :ha#ter -0 sho0s you ho0 to create loo#s that you can control9
Tryin" to open files that don't exist or are empty, for example,
>>> myfile = open),foo"doc,*
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
GJ6rror! [6rrno 2] 1o s-c2 file or directory! ,foo"
Incorrect lo"ic for Boolean expressions
3o $et the scoo# on correct use of 'oolean e8#ressions in your #ro$rams6 see
:ha#ters " and -09
3he best 0ay to find out about common bu$s other than 0ritin$ your o0n #ro$rams% is
to loo/ at the bu$s other #eo#le ma/e9 3he comp"lang"pyt2on ne0s$rou# or the 4ython
tutor mailin$ list are $ood resources9 See :ha#ter 22 to find out ho0 to access these
resources9% 3he same errors come u# o7er and o7er6 and youCll soon be able to reco$nize
them on si$ht9
3i# For hel#ful debu$$in$ ti#s6 see IDebu$$in$ Strate$ies6I later in this cha#ter9
4aintainin" %our ro"rams
+0
M/ay6 youC7e 0ritten your #ro$ram9 (o0 0hat2 :hances are youCll 0ant to ma/e some
chan$es soon9 &n fact6 most #ro$rammers s#end far more time chan$in$ e8istin$
#ro$rams than 0ritin$ ne0 ones9 When you 0ant to u#date your code6 youCll li/ely be
tem#ted to chan$e it in a 0ay that doesnCt ta/e a lot of time9 'ut that mi$ht not be the best
0ay to $o about it in the lon$ run9
Su##ose youC7e 0ritten a #ro$ram to send yourself a daily e1mail 0ith the to# ten lines
from your calendar file9 &t mi$ht loo/ li/e .istin$ A1-9
.istin$ A1-) dailyPcalendar9#y
import smtpli( + get t2e mod-le for sending email
my$address = ,meYexample"com,
2eaders = [ ,@-(Tect! Oaily calendar,,
,>rom! , : my$address,
,0o! , : my$address,
] + t2is list spans fo-r lines for
reada(ility
entries = open),my$calendar,*"
msg = ,ZrZn,"Toin)2eaders* : ,ZrZn, : ,,"Toin)entries*
smtp = smtpli("@0C),mail,* + replace ,mail, 9it2 t2e name of yo-r
mail2ost
smtp"sendmail)my$address, [my$address], msg*
smtp"close)*
3hen you decide you 0ant to send yourself a bi$$er chun/ once a 0ee/9 3he sim#le6 easy
>and 0ron$>0ay to do it6 illustrated in .istin$ A126 is called cut-3n3-paste
programming9 (ote ho0 most of the lines of the #ro$ram are re#eated in the if and else
statements9 'y the 0ay6 another chan$e made in the #ro$ram 0as the addition of
sys"arg5 to $et a command1line ar$ument9 3hatCs not bad #ro$rammin$6 0e Fust 0anted
to #oint it out9%
.istin$ A12) calendar9#y
import smtpli(, sys
my$address = ,meYexample"com,
if sys"arg5[/] == ,9eeAly,!
2eaders = [ ,@-(Tect! WeeAly calendar,,
,>rom! , : my$address,
,0o! , : my$address,
]
entries = open),my$calendar,*"
msg = ,ZrZn,"Toin)2eaders* : ,,"Toin )entries*
smtp = smtpli("@0C),mail,*
smtp"sendmail)my$address, [my$address], msg*
smtp"close)*
else!
2eaders = [ ,@-(Tect! Oaily calendar,,
,>rom! , : my$address,
,0o! , : my$address,
]
+-
entries = open),my$calendar,*"readlines)*[!/%]
msg = ,ZrZn,"Toin)2eaders* : ,,"Toin)entries*
smtp = smtpli("@0C),mail,*
smtp"sendmail)my$address, [my$address], msg*
smtp"close)*
3he ri$ht 0ay to u#$rade your code a7oids this re#etition by ta/in$ the re#eated code and
turnin$ it into a chun/ that $ets called by another #art of the #ro$ram9 3his is called
refactoring the code9
3i# &f you remember al$ebra6 code refactorin$ is similar to al$ebraic factorin$H for
e8am#le6 brea/in$ the number -2 into its factors " U !9
Defactorin$ a #ro$ram 0or/s li/e this)
-9 'i"ure out the elements that are common to all the tasks the pro"ram
performs.
&n this e8am#le6 the common element is that both tas/s sending a daily calendar
and sending a $eekly calendar4 in7ol7e sendin$ an e1mail9
29 ut the common elements into one or more functions.
&n this e8am#le6 these tas/s $o into a function called send$calendar)*9
"9 ut the elements that are different for different tasks into an if8else block
5or perhaps a loop6.
&n this e8am#le6 the if8else bloc/ determines 0hether a daily or 0ee/ly
calendar is bein$ sent and ho0 many lines of the calendar to include9 &t #asses this
information to the send$calendar)* function as ar$uments9
3@:<(&:A.
S3?FF
ro"rammin" to the max
Smart #ro$rammers ha7e come u# 0ith a 7ariety of methods for
0ritin$ better #ro$rams9 Many of those methods are combined under
the umbrella of 1!treme Programming%5P49 Some #ro$rammers
ha7e al0ays 0anted to be as cool as s/ateboarders9 Maybe usin$ a
term li/e this hel#s9 Mr maybe not9%
3he idea behind O4 is sim#le) &f a #ro$rammin$ method is a ;ood
&dea6 ta/e it to the ma85 For e8am#le6 one of the best 0ays of $ettin$
bu$s out of a #ro$ram is to ha7e another #ro$rammer re7ie0 the
code9 Well6 0hy not ha7e the second #ro$rammer re7ie0 the code
$hile youCre $riting it6 &hat results in 0hat Ie8treme #ro$rammersI
+2
call pair programming9
Similarly6 if 0ritin$ unit tests is $ood6 maybe you should 0rite the
tests before you start 0ritin$ code9 3hatCs called test-driven
development9 3his Web #a$e6 I3est1Dri7en De7elo#ment in 4ythonI
by Jason Diamond6 has an e8am#le)
htt#)LL0009onlam#9comL#ubLaL#ythonL200!L-2L02LtddP#yunit9html
For more info about O46 see this Web site)
htt#)LL0009e8treme#ro$rammin$9or$
(ot sur#risin$ly6 there is also a lot of hy#e about O49 Wi/i#edia to
the rescue5 <ere is a balanced article about @8treme 4ro$rammin$)
htt#)LL0009en90i/i#edia9or$L0i/iL@8tremeP4ro$rammin$
*hy refactorC
Althou$h refactorin$ 0ill ta/e you lon$er the first time you chan$e your #ro$ram6 it 0ill
sa7e you time in the lon$ run6 and it 0ill also ma/e your #ro$ram more $enerally useful
and easier to read9 3he refactored 7ersion of the calendar"py #ro$ram in .istin$ A1- is
easy to e8tend>all you ha7e to do is 0rite t0o1line elif bloc/s9 Furthermore6 if you
0ant to chan$e the send$calendar)* functionality6 you ha7e to chan$e only one chun/
of code9 'ut if you e8tended the #ro$ram 7ia the cut1CnC1#aste method6 your #ro$ram
0ould $et lon$er 7ery Guic/ly6 and if you made chan$es to the code that reads the
calendar file and sends the e1mail6 youCd ha7e to ma/e those chan$es multi#le times9
A $eneral rule to use) Defactor if at least three lines of code are du#licated in your
#ro$ram9
3he refactored #ro$ram loo/s li/e .istin$ A1"9
.istin$ A1") refactoredPcalendar9#y
import smtpli(, sys
my$address = ,meYexample"com,
+ set -p and send t2e email
def send$calendar)address, n-m$entries, s-(Tect*!
2eaders = [ ,@-(Tect! , : s-(Tect,
,>rom! , : address,
,0o! , : address,
]
+"
entries = open),my$calendar,*"readlines)*[!n-m$entries]
msg = ,ZrZn,"Toin)2eaders* : ,ZrZn, : ,,"Toin )entries*
smtp = smtpli("@0C),mail,*
smtp"sendmail)my$address, [my$address], msg*
smtp"close)*
+ parse t2e command7line arg-ment
if sys"arg5[/] == ,9eeAly,!
send$calendar)my$address, &%, ,WeeAly calendar,*
else!
send$calendar)my$address, /%, ,Oaily calendar,*
+ood ro"ram :esi"n ractices
3here are a fe0 $ood #ractices to /ee# in mind 0hile youCre desi$nin$ and 0ritin$ your
#ro$ram9 3heyCll hel# 0ith documentin$6 debu$$in$6 and maintainin$ the #ro$ram later9
2aing naes
D@M@M'@D 3he names of 7alues and functions should be self1e8#lanatory to ma/e
your code easier to read9
For e8am#le6 if you 0ant to 0rite code that e8tracts a zi# code from a customer entry in a
database6 you mi$ht 0rite this)
c-stomer$Qip = get$Qip)Candora*
&t is easier to fi$ure out 0hat the #recedin$ line of code is doin$ than it is to fi$ure out the
follo0in$ code)
Q = getQ)Candora*
%ollo&ing con$entions
4ython itself doesnCt reGuire you to 0rite your code this 0ay6 but these con7entions ma/e
#ro$rams easier for #ro$rammers and you% to read9
3i# 3he con7entions are a7ailable on the pyt2on"org Web site under the name I4@4 ,)
Style ;uide for 4ython :ode9I See them here)
htt#)LL0009#ython9or$Lde7L#e#sL#e#1000,
3he follo0in$ con7entions are the most critical $uidelines9
?amin" rules
Follo0 these $uidelines 0hen namin$ obFects in your #ro$ram)
+!
+ive modules and packa"es short, lowercase names without underscores,
liAet2is
3@:<(&:A.
S3?FF
3he name of a module or #ac/a$e is also the name of a file on
the com#uter9 Some com#uters donCt handle lon$ filenames or
names 0ith s#ecial characters9 3his #ractice ma/es it easier
for users of other o#eratin$ systems to use your #ro$ram9
!tart class names with a capital letter and use embedded caps,
3iAe02is
3@:<(&:A.
S3?FF
3his format is sometimes called IStudly:a#sI9 'ecause6 0ell6
$ee/s ha7e to feel studly about somethin$9
2nd the names of error1type exceptions with 6rror9
3his hel#s anyone readin$ or debu$$in$ your #ro$ram to reco$nize e8ce#tions
ri$ht a0ay9
?ame functions and methods by usin" all lowercase characters.
?nderscores6 liAe$t2is6 are M=9
3@:<(&:A.
S3?FF
?sin$ different styles for names of different ty#es of obFect
hel#s distin$uish functions and methods from modules6
#ac/a$es6 and classes at a $lance9 3he underscore character
hel#s #eo#le read the name of the function or method if the
name includes more than one 0ord for e8am#le6 get$Qip is
sli$htly easier to read than getQip%9
&se all uppercase characters for constants, 3GX60HG@9
'ormattin" rules
3o im#ro7e readability6 follo0 these $uidelines 0hen formattin$ your code)
Indent each code block four spaces. Avoid tabs.
#ontinue lon" lines by surroundin" them with )*6 []6 or {}9
#ontinue strin"s by endin" the line with Z9
o ?se Z to continue strin$s only 0hen necessary9
o Ma/e sure to use an e8tra indent for continuation lines6 li/e so)
o parrot = "02is parrot is no more! He 2as ceased to
(e! He,s expired Z
o and gone to meet 2is maAer!"
ut spaces before and after =9
Warnin$ 'ut donCt use s#aces around = in default #arameters of functions and
methods9
+A
1on"t forget to coent4
&nclude comments as you 0rite the #ro$ram9 :omments should describe 0hy the code is
0ritten the 0ay it is and not Fust 0hat it does9
:hun/s of code6 such as functions6 are usually #receded by comments that describe the
0hole chun/ not comments that $o 0ith each line%9
3i# &f youC7e added comments to the #ro$ram6 collect them to$ether 0hen itCs time to
0rite
The main omment !lok at the be"innin" of the pro"ram.
3his bloc/ includes the ty#e of file6 the name of the #ro$rammer6 the date of
creation6 the #ur#ose of the file6 and usa$e instructions9
The dostrings that are used to build the pro"ram's help file.
:ebu""in" !trate"ies
Some strate$ies that #ro$rammers use to debu$ their code are as follo0s)
Three built1in functions 9 repr)*6 type)*6 and dir)* 9 aid debu""in" by
helpin" you fi"ure out what values and types your pro"ram uses.
See the follo0in$ section6 I'uilt1in functions6I to find out about these three useful
functions9
Traceback lo"s, print statements, and commentin" out lines of code help you
keep track of what's "oin" on when your pro"ram runs.
:ebu""er tools let you step throu"h your pro"ram one line, or one code bloc/6
at a time9 See I?sin$ a debu$$erI later in this cha#ter9
3he follo0in$ sections describe 0ays to use these strate$ies effecti7ely9
Built+in functions
Eour three best friends in debu$$in$ are the built1in functions repr)*6 type)*6 and
dir)*9
3he repr)* function $i7es you useful information about 0hat 4ython really thin/s is in a
7alueH it is essential for debu$$in$ #roblems 0ith strin$s because it sho0s the s#ecial
esca#e characters in strin$s6 li/e this see :ha#ter 6 for a full e8#lanation%)
+6
>>> mystring = "t2e Anig2ts 92o say ,1i!,"
>>> repr)mystring*
,"t2e Anig2ts 92o say Z,1i!Z,",
3he type)* and dir)* functions $i7e you additional information about a 7alue9 @7en
0hen the bu$ in your #ro$ram is a lo$ic error6 the sym#tom is often a 0ron$ 7alue
$ettin$ #assed around9 Findin$ out 0hat that 7alue is and 0here it came from usually
allo0s you to fi$ure out the bu$9
<ereCs a tri7ial case9 4ythonCs e8ce#tion #oints you in the ri$ht direction for fi$urin$ out
the error)
>>> price = ra9$inp-t),6nter price! ,*
6nter price! /2"==
>>> Nty = ra9$inp-t),6nter N-antity! ,*
6nter N-antity! 3
>>> price ; Nty
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
0ype6rror! can,t m-ltiply seN-ence (y non7int of type ,str,
3he error messa$e is clear enou$h6 but it doesnCt tell you 0hat the IseGuenceI and the
Inon1intI are9 What you mi$ht do ne8t is chec/ 0hat price and Nty are by usin$ repr)*
and type)*6 as sho0n in the follo0in$ e8am#le code9 So 0hereCs repr)*2 &n interacti7e
mode6 if you Fust ty#e the name6 4ython automatically uses repr)*9 Eou need to actually
ty#e repr)* only 0hen youCre debu$$in$ in scri#ts9%
>>> price, type)price*
),/2"==,, #type ,str,>*
>>> Nty, type)Nty*
),3,, #type ,str,>*
Ah1ha5 'oth price and Nty are strin$s9 3hatCs because the ra9$inp-t)* function
al0ays returns a strin$9% &n order to multi#ly them6 you need to turn them into numbers9
<ereCs ho0 you do it)
>>> price = float)price*
>>> Nty = int)Nty*
>>> price ; Nty
3'"=<=============
(o0 su##ose the user enters somethin$ that canCt be turned into a number9 3his 0ill
create another #roblem in the #ro$ram)
>>> price = float)ra9$inp-t),6nter price! ,**
6nter price! Sood dog!
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
Wal-e6rror! in5alid literal for float)*! Sood dog!
3i# 3he 0ay to handle this #roblem is to 0rite code that catches the e!ception and
++
reminds the user to enter a number9 We discuss ho0 to do this in :ha#ter -A9
Print stateents and traceback logs
When debu$$in$6 add print statements 0hene7er you $i7e a name to a 7alue or
mani#ulate somethin$9 EouCll Guic/ly disco7er at 0hat #oint the name ta/es on the 0ron$
7alue9
Warnin$ DonCt su##ress tracebacks 4ythonCs information about errors or unusual
conditions it encounters%9 &f you 0ant your #ro$ram to continue after an error
has occurred instead of Guittin$%6 log or print the tracebac/ and $o bac/ later9
Althou$h print statements are useful in sim#le #ro$rams6 0adin$ throu$h the out#ut is
difficult if you ha7e a lot of them9 &tCs also difficult to selecti7ely turn print statements
on and off9 3he logging module directs your debu$$in$ out#ut to a file for later #erusal9
3o control the amount of out#ut6 Fust chan$e the lo$$in$ le7el9
3i# :ha#ter -+ sho0s ho0 to use the logging module and also sho0s ho0 to use the >>
o#erator 0ith print to redirect out#ut to a file9
#oents
3o use comments for debu$$in$6 add lines to the code that #rint the 7alues of 7arious
names throu$hout the #ro$ram9 3hen a##end a comment li/e + for de(-gging to these
lines of code so you /no0 to remo7e them later9
3i# ?sin$ the comment character +% at the be$innin$ of a line of code disables that line9
&n some cases6 disablin$ indi7idual lines hel#s you trac/ do0n 0hich line of code is
the source of a #roblem9
)sing a debugger
A debu$$er lets you ste# throu$h your code one line at a time or one code bloc/ at a time9
&t dis#lays all the 7alues 4ython /ee#s trac/ of6 sho0in$ e8actly 0here 7alues chan$e9
pdb
3he pd( module is a debu$$er thatCs built into 4ython9
3@:<(&:A.
S3?FF
3he #ro$ram 0eCre debu$$in$ is called x"py6 and it loo/s li/e this)
print "02is f-nction creates a list""
def maAelist)*!
a = []
for i in range)/, 2%*!
a"append)i*
print "appending", i, "!", a
+,
ret-rn a
maAelist)*
3o use pd( from the command line6 follo0 these ste#s)
-9 At the command prompt, type pyt2on 7m pd( x "py6 where x "py is the name
of your module.
EouCll see somethin$ li/e this) 3he )/* on the first line indicates the first line of
the #ro$ram9 3he te8t follo0in$ 7> is the actual code of this line9 )Cd(* is the
#rom#t9
> 84sers8stef8x"py)/*#mod-le>)*
7> print "02is f-nction creates a list""
)Cd(*
29 To run the current line of the pro"ram and "o to the next line, type s9
@ach time you #ress s 0hich is short for Iste#I%6 you see the ne8t line number
and its code9 &n this e8am#le6 you also see the result of the print statement on the
first line9
)Cd(* s
02is f-nction creates a list"
> 84sers8stef8x"py)2*#mod-le>)*
7> def maAelist)*!
)Cd(*
3i# &f you ty#e s a$ain at this #oint6 the #ro$ram Fum#s to line ,)
)Cd(* s
> 84sers8stef8x"py)'*#mod-le>)*
7> maAelist)*
)Cd(*
3hatCs because the first time 4ython sees a function definition6 it reads defines%
the 0hole function9 3his #rocess is considered a sin$le ste#9
"9 *hen you want to check that the pro"ram is storin" the correct values, type
p and the name to see its value.
We $ot this result after 0eCd ste##ed throu$h the #ro$ram ten times)
)Cd(* p a
[/, 2]
3i# 3o see a7ailable commands 0hile you run pd(6 ty#e 2elp9 For hel# on a sin$le
command or to#ic6 ty#e hel# and the name of the command or to#ic6 li/e this)
)Cd(* 2elp a
a)rgs*
+*
Crint t2e arg-ments of t2e c-rrent f-nction"
3he most useful pd( commands are)
s step%>Dun the current line of the #ro$ram and $o to the ne8t line9
&f the line is a def statement for a function6 define the function if it hasnCt already
been defined%6 then $o to the first line after the function9 &f the line is a function
call, $o to the first line inside the function9
n next%>Dun the current line of the #ro$ram and $o to the ne8t line9 'ut if the
line is a function call6 run the 0hole function and $o to the ne8t line after the
function call9
c cont%>:ontinue runnin$ the #ro$ram until the ne8t brea/ #oint see the
follo0in$ section6 I'rea/ #ointsI%9
r ret-rn%>Dun the #ro$ram until the current function returns9
l list%>Dis#lay the source code around the current line9
a args%>Dis#lay the current functionCs ar$uments9
p print%6 ## pretty7print%>Dis#lay the 7alue of an e8#ression9
N N-it%>Yuit the debu$$er and the #ro$ram9
Break points
&f you /no0 that most of your #ro$ram is 0or/in$ but you sus#ect a #roblem in one #art6
you can set a break point 0here you thin/ the #roblem is9 &n pd(6 you do this by ty#in$ (
and the line number you 0ant to set a brea/ #oint at)
)Cd(* ( 3
IreaApoint / at 4sers8stef8x"py!3
&n pd(6 to run the #ro$ram until it comes to the brea/ #oint6 ty#e c for IcontinueI%9 3o
see the 7alues your #ro$ram is storin$ at this #oint6 ty#e p and the name 0hose 7alue you
0ant to see9
3he follo0in$ e8am#le sets a brea/ #oint at line A of our #ro$ram6 runs the #ro$ram until
it reaches the brea/ #oint6 and e8amines the 7alues at that #oint9 (ote that the brea/
occurs before 4ython runs line A9
)Cd(* ( &
IreaApoint 2 at 84sers8stef8x"py!&
)Cd(* c
appending 2 ! [/, 2]
> 84sers8stef8x"py)&*maAelist)*
7> a"append)i*
)Cd(* p a
[/, 2]
)Cd(* p i
3
,0
4art &&) 'uildin$ 'loc/s
#hapter -ist
:ha#ter 6) So 3his Strin$ Wal/s into a 'ar
:ha#ter +) :ountin$ your Way to Fun and 4rofit
:ha#ter ,) 4rocessin$ .ists and 3u#les
:ha#ter *) Di7in$ into Dictionaries
3he A
th
Wa7e 'y Dich 3ennant
IMs9 ;rets/y6 tell the em#loyees they can ha7e internet $ames on their com#uter a$ain9I
In this part
Eou disco7er ho0 to mani#ulate 4ythonCs many data ty#es6 from sim#le te8t strin$s6
throu$h all the different /inds of numbers you can 0or/ 0ith but donCt 0orry6 you 0onCt
ha7e to remember hi$h school al$ebra%6 to lists6 tu#les6 dictionaries6 and sets9
,-
#hapter E, !o This !trin" *alks into a
Bar
(verview
&n most com#uter lan$ua$es6 includin$ 4ython6 a string consists of te8t characters>Fust
one character6 a fe0 lines6 or a 0hole te8t file9 &n this cha#ter6 you find out ho0 strin$s
0or/ in 4ython6 includin$
3he 7arious 0ays to use Guotation mar/s to delimit strin$s
<o0 to use inde8 numbers and slices to $et at #arts of strin$s
Ma$ic 0ays of formattin$ strin$ out#ut
We also introduce you to the mysteries of ?nicode9
!trin"in" Them Alon"
&nside 4ython6 a strin$ literal is surrounded by Guotation mar/s6 0hich distin$uish it from
other /inds of data6 such as inte$ers or names9 Eou see the Guotation mar/s 0hen you
ty#e the name of a strin$ in the inter#reter9 'ut 0hen you print a strin$6 the Guotation
mar/s donCt a##ear9
>>> y = ,23.,
>>> y
,23.,
>>> print y
23.
3@:<(&:A.
S3?FF
3he 4ython inter#reter calls repr)* to dis#lay the result of an
e8#ression>this dis#lay itself is usually a 7alid e8#ression9 3he
print statement uses str)*6 0hich dis#lays a I#rettierI 7ersion9
:ha#ter 2 has more details9%
3he follo0in$ sections describe se7eral 0ays to Guote strin$s and ho0 to use s#ecial
characters inside strin$s or ho0 not to use them%9
7ust the 3uotes! a"a
Eou can surround a strin$ 0ith sin$le6 double6 or tri#le Guotes9 Which you use de#ends on
the strin$ contents and formattin$ you 0ant9
,2
(ne =uote or two
When you create a strin$6 4ython lets you to use either a #air of sin$le Guotes or a #air of
double Guotes9 'oth mean Ia strin$ is inside9I 3his e8am#le sho0s a double1Guoted strin$
and a sin$le1Guoted strin$)
>>> peng-in = "on top of t2e tele5ision set"
>>> 92at$it$is$doing =
&f your te8t includes sin$le Guotation mar/s or a#ostro#hes6 itCs easiest to ma/e it into a
strin$ by surroundin$ it 0ith double Guotes6 li/e this)
>>> Anig2ts = "We are t2e Xnig2ts W2o @ay
>>> print Anig2ts
We are t2e Xnig2ts W2o @ay ,1i,!
.i/e0ise6 if your te8t includes double Guotes6 itCs easiest to ma/e a strin$ by surroundin$
it 0ith sin$le ones9
Triple1scoop
3o ma/e a strin$ that #rints e8actly as you ty#e it6 use tri#le Guotes6 either sin$le """% or
double """%9 4ython #rints the strin$ 0ith line brea/s and s#aces e8actly as you enter
them6 as sho0n)
>>> spam = """
""" spam spam spam spam spam
""" and spam
""" """
>>> print spam
spam spam spam spam spam
and spam
3ri#le Guotes are most commonly used to create docstrings. A docstrin$ is a short
descri#tion of a code bloc/6 such as a function9 4ythonCs hel# function automatically
formats and returns the te8t of the docstrin$ 0hen you as/ for hel# on the code bloc/9 For
more about docstrin$s6 see :ha#ter --9
3i# 3ri#le Guotes are also useful for surroundin$ te8t that has both sin$le and double
Guotation mar/s9
*ays to escape
3o tell 4ython to $i7e s#ecial treatment to a character in a strin$ literal6 #recede it 0ith a
bac/slash character Z%6 also called the escape character.
,"
3able 61- lists some of the characters that do s#ecial thin$s 0hen #receded by a
bac/slash9 3hese are commonly called escape codes.%
3able 61-) Some 4ython @sca#e :odes
M#en table as s#readsheet
#haracter 4eanin"
Z as last character on a line 3e8t on the ne8t line $oes 0ith the te8t on this line9
ZZ
'ac/slash
Z,
Sin$le Guote
Z"
Double Guote
Ze
@sca#e /ey
Zn
.inefeed
Zt
3ab
Z% nn Mctal character nn is a t0o1di$it number%
Zx nn <e8adecimal character nn is a t0o1di$it number%
Mne 0ay to use the bac/slash is to tell 4ython to treat a Guotation mar/ as a re$ular
character rather than as a Istrin$ starter or ender6I as in this e8am#le)
>>> 92iteBa((it = ,W2ereZ,s my pocAet79atc2V,
>>> print 92iteBa((it
W2ere,s my pocAet79atc2V
3i# &tCs easier to read strin$s that donCt ha7e esca#e characters 0ithin the code6 so a7oid
them if you can9 &f you ha7e te8t 0ith both sin$le and double Guotes6 consider usin$
tri#le Guotes to desi$nate it as a strin$9
3o tell 4ython that a bac/slash is #art of your strin$ and not an esca#e character6 #recede
it 0ith a second bac/slash6 as sho0n)
>>> pat2 = "H!ZZLpplications"
>>> print pat2
H!ZLpplications
/a& strings
3o tell 4ython not to loo/ for any esca#e codes in a strin$6 s#ecify the strin$ as a ra$
string. Eou mi$ht 0ant to do this 0hen handlin$ Windo0s #athnames6 0hich include the
bac/slash character9
3i# Da0 strin$s also sim#lify regular e!pression searches6 0hich also use bac/slashes as
s#ecial characters9 See :ha#ter -,9
3o s#ecify a ra0 strin$6 ty#e r before the first Guotation mar/6 li/e this)
,!
>>> pat2 = r"H!ZLpplications"
>>> print pat2
H!ZLpplications
Warnin$ 3hereCs one case in 0hich ra0 strin$s arenCt com#letely ra09 &tCs an error to end
a ra0 strin$ 0ith a bac/slash because 4ython thin/s youCre usin$ the bac/slash
to esca#e the Guote mar/ that ends the strin$9 3o ty#e a strin$ that ends 0ith a
bac/slash6 you must use a re$ular strin$9 Eou can add it to the ra0 strin$ sim#ly
by ty#in$ it on the same line9 &f you ty#e se7eral strin$s on the same line6 you
donCt need to use a concatenation o#erator)
>>> print r,H!ZdataZmyprogams, ,ZZ,
H!ZdataZmyprogramsZ
Being &ordy
3here are se7eral 0ays to create a strin$ that 0ill s#an more than one line9
3o 0rite a strin$ that 0ill #rint e8act as you entered it6 surround the strin$ 0ith
tri#le1Guotes """ or """%9
3o 0rite te8t that 0ill #rint on se7eral lines6 add the linefeed esca#e code Zn
0here you 0ant a ne0 line to start6 li/e this)
>>> c2eese = "c2eeses a5aila(le!Znsa5oyardZn(o-rsin"
>>> print c2eese
c2eeses a5aila(le!
sa5oyard
(o-rsin
3o turn t0o strin$s on t0o lines into a sin$le strin$6 surround them 0ith
#arentheses9 We recommend this method for enterin$ lon$ strin$s because itCs
easy to read9 For e8am#le)
>>> x = )"2ello"
""" "9orld"*
>>> print x
2ello9orld
3o create a lon$ strin$6 ty#e a bac/slash character Z% at the end of a line9 What
you ty#e after you #ress Deturn counts as #art of the same line9
>>> longline = "t2is is a 5ery long line a 5ery long Z
""" line a 5ery long line"
>>> print longline
t2is is a 5ery long line a 5ery long line a 5ery long line
Warnin$ 3he end1of1line bac/slash doesnCt 0or/ if you add s#aces after the
bac/slash9
.o& a string looks inside Python
3o see ho0 4ython internally re#resents a strin$6 ty#e the name of the strin$ and #ress
Deturn9 &n this e8am#le6 4ython re#resents a ne0line character 0ith the esca#e character
Zn)
>>> modernlife = "as i 9as s-rfing on t2e airZnZ
,A
""" i sa9 a spam t2at 9asn,t
>>> modernlife
"as i 9as s-rfing on t2e airZni sa9 a spam t2at
When you as/ 4ython to print a strin$6 it inter#rets the ne0line character9 So the
modernlife strin$ is #rinted on t0o lines6 li/e this)
>>> print modernlife
as i 9as s-rfing on t2e air
i sa9 a spam t2at 9asn,t t2ere
8Please repeat8: String operators
Se7eral of 4ythonCs o#erators 0or/ 0ith strin$s9 3his section co7ers the follo0in$
o#erators)
#oncatenation :%) Stic/s strin$s to$ether9
/epeatin" ;%) :o#ies a strin$ se7eral times9
!i)e testin" #6 >%) Determines 0hich of t0o strin$s is bi$$er or smaller9
#ombine and repeat
3o concatenate strin$s6 ty#e the first strin$6 the : symbol6 and the second strin$6 li/e so)
>>> 2ello = "2ello"
>>> 9orld = "9orld"
>>> 2ello : 9orld
,2ello9orld,
3i# &f youCre 0or/in$ 0ith strin$ literals rather than strin$s that ha7e names6 you donCt
ha7e to use the : o#erator to stic/ them to$ether9 Eou can Fust #ut them ne8t to each
other on a line6 li/e so)
>>> "Gt don, mean a t2ing " "if it ain,t got t2at s9ing"
"Gt don, mean a t2ing if it ain,t got t2at s9ing"
3o re#eat a strin$6 ty#e the strin$6 the ; symbol6 and the number of times you 0ant to
re#eat the strin$6 as sho0n here)
>>> "Gt don, mean a t2ing " ; 3
"Gt don, mean a t2ing Gt don,t mean a t2ing Gt don, mean a t2ing"
3o concatenate and re#eat at the same time6 combine the o#erations6 li/e so)
>>> toaster/ = "9o-ld yo- liAe some toastV "
>>> toaster2 = "or 2o9 a(o-t m-ffinsVVV Zn"
>>> annoying$toaster = )toaster/ : toaster2*; 3
>>> print annoying$toaster
9o-ld yo- liAe some toastV or 2o9 a(o-t m-ffinsVVV
9o-ld yo- liAe some toastV or 2o9 a(o-t m-ffinsVVV
9o-ld yo- liAe some toastV or 2o9 a(o-t m-ffinsVVV
,6
3he au$mented assi$nment o#erators := and :; also 0or/ 0ith strin$s9 3hese o#erators
let you #erform an o#eration and $i7e the result to a name at the same time9 3hey are 7ery
useful in loo#s because they ma/e the assi$nment statement easy to read9
D@M@M'@D 3he : and ; o#erators 0or/ differently on strin$s than they do on numbers9
Eou canCt add a strin$ and a number to$ether>you must first con7ert the
strin$ to a number for e8am#le6 by usin$ the int)* or float)*
functions%9 And if you try to use ; on a strin$ and an inte$er6 you $et a
re#eated strin$6 not multi#lication6 li/e this)
>>> "&" ; <
,&&&&&&,
>>> int)"&"* : <
//
4ine's bi""er than yours< #omparin" strin"s
When youCre 0or/in$ 0ith numbers6 itCs usually ob7ious 0hat the smallest and lar$est
numbers are9 'ut itCs less clear 0hat smallest and largest mean 0hen youCre tal/in$ about
characters9
3@:<(&:A.
S3?FF
A characterCs AS:&& or ?nicode 7alue a number% determines the
characterCs order9 So it 0ould also be correct to tal/ about one
character comin$ IbeforeI smaller% or IafterI lar$er% another
character in a numbered list of characters9 3he follo0in$ list
describes ho0 4ython orders assi$ns sizes to% characters)
-etters at the be"innin" of the alphabet are smaller than
letters at the end.
L is smaller than K9
#apital letters come before 5are smaller than6 lowercase
letters.
P and K are both smaller than a9
:i"its are smaller than letters.
& is smaller than L9
4ost punctuation marks come before di"its or letters.
! is smaller than &9 3he e8ce#tions are curly braces {}%6 the
#i#e character [%6 and the tilde \%6 0hich are lar$er than
letters9
3o determine 0hich of t0o strin$s is lar$er6 use the # and > o#erators9
,+
>>> ,L, # ,K,
0r-e
>>> ,(, > ,a,
0r-e
>>> ,a, > ,Q,
0r-e
-oopin" throu"h strin"s9%ou can, but why would you want toC
'ecause a strin$ is a seGuence data ty#e6 you can use it in a loo#H that is6 you can
iterateover it9 'ut there are 7ery fe0 reasons to do this9 &n fact6 code that does this
#robably has a bu$9 4ython doesnCt ha7e a built1in error or 0arnin$ messa$e for iteratin$
o7er a strin$6 but e8ternal debu$$in$ tools such as 4y:hec/er often fla$ it as a bu$9
3he 4y:hec/er tool loo/s for common #roblems in 4ython code9 &t doesnCt come 0ith
4ython6 but you can do0nload it from htt#)LL0009#ychec/er9sourcefor$e9netL9
A fe& ore ethods for &orking &ith strings
Eou use a string method to #erform actions on a strin$9 3o use a strin$ method6 ty#e the
name of your strin$6 a dot6 and the method9 3hen inside #arentheses6 #ass any #arameters
that the method needs9 &n this e8am#le6 the #arameter is the strin$ you 0ant to count the
occurrences of)
>>> mystring = "mississippi"
>>> mystring"co-nt),s,*
.
Testin" the content of strin"s
4ython lets you test 0hether strin$s ha7e certain content9 3hese tests return 0r-e or
>alse 'oolean results%9
3o test 0hether te8t is any0here in a strin$6 ty#e the te8t youCre searchin$ for in Guotation
mar/s6 follo0ed by in and the name of the strin$9 3his e8am#le $i7es a name to a strin$
and tests for the strin$ ,goose, inside the strin$9
>>> mystring = ,t2e N-icA (ro9n fox,
>>> ,goose, in mystring
>alse
3o test 0hether te8t is not in the strin$6 use not in rather than in9
3i# 4ython 292 and earlier donCt ha7e the in /ey0ord9 &n those 7ersions6 you can test for
te8t in a strin$ by usin$ the find)* or co-nt)* method9
,,
3o test 0hether te8t is at the end of a strin$6 use the ends9it2)* method6 as sho0n here9
3he starts9it2)* method 0or/s the same 0ay but finds te8t at the be$innin$ of a
strin$9%
>>> mystring"ends9it2),fox,*
0r-e
#onvertin" data to a strin"
3o turn data other than a strin$ into a strin$6 use the built1in function str)*6 as in this
e8am#le6 0hich con7erts an inte$er to a strin$)
>>> str)23.&*
,23.&,
!ortin" a list of strin"s
3o sort a list of strin$s6 use the sort)* method of lists9 3y#e the name of the list6 a dot6
and sort)*6 li/e this)
>>> mylist = [,92isAey,, ,tango,, ,foxtrot,]
>>> mylist"sort)*
>>> mylist
[,foxtrot,, ,tango,, ,92isAey,]
3i# 'ecause small letters are Ibi$$erI than come after% ca#ital letters6 if you need to
al#habetize some te8t6 you should con7ert it to all lo0ercase first9 3o con7ert a strin$
to lo0ercase6 ty#e the name of the strin$6 a dot6 lo9er6 and #arentheses6 as sho0n)
>>> x = "0HG@ G@ L @0BG1S"
>>> x"lo9er)*
,t2is is a
'indin" out more about strin" methods
3i# For more information on strin$ methods6 ty#e 2elp)str* at the 4ython #rom#t9
3he strin$ methods 0or/ 0ith both re$ular strin$s and ?nicode strin$s see the u#comin$
section6 I?nra7elin$ ?nicodeI%9 3hey include the follo0in$ ty#es of actions)
:ase mani#ulation capitaliQe6 -pper6 lo9er6 s9apcase6 title%
:ountin$ co-nt>number of times substrin$ is in strin$%
Mani#ulatin$ te8t encodin$ encode6 decode%
Search and re#lace find6 replace6 rfind6 index6 rindex, translate%
3ests that return 'oolean 0r-e or >alse% 7alues starts9it26 ends9it26
isaln-m6 isalp2a6 isdigit6 islo9er6 isspace6 istitle6 is-pper%
Joinin$ and s#littin$ Toin6 partition6 rpartition6 split6 splitlines%
Formattin$ center6 lT-st6 lstrip6 rstring6 rT-st6 strip6 Qfill6
expandta(s%
,*
3i# 3he :heat Sheet attached to the front of this boo/ briefly describes ho0 most of the
abo7e methods 0or/9
The strin" module versus the str type
@arly 7ersions of 4ython im#lemented strin$ o#erations as functions in the string
module9 &n 4ython 2906 most of those functions 0ere du#licated as methods of the str
ty#e9 3he string module still 0or/s6 but use of the string module usually indicates an
old #ro$ram e8ce#t for string"maAetrans)*6 for 0hich there is no eGui7alent method%9
#at's #radle, Indexin" and !licin"
Strin$s and other seGuential data ty#es% are di7ided into #ieces called elements that are
stored in order in a seGuence%9 &n a strin$6 each character is one element9 Eou mani#ulate
the indi7idual elements by usin$ o#erations called inde!ing and slicing.
An inde8 number s#ecifies the location of a #articular element6 and a ran$e of inde8
numbers s#ecifies a slice of se7eral elements9
3his section describes the basics of inde8in$ and slicin$9 Eou also find out some shortcuts
and disco7er ho0 to use slices to ma/e co#ies of strin$s9
D@M@M'@D Strin$s canCt be chan$ed9 'ut you can use slicin$ to ma/e a ne0 strin$
based on #art of an e8istin$ strin$9
Basic syntax
Eou use inde8in$ to find an element of a seGuence obFect such as a character in a strin$%
based on the elementCs inde8 number9 Eou use slicin$ to find a ran$e of elements9
Indexin"
3o find an item corres#ondin$ to a #articular inde8 number6 ty#e the name of your strin$
or other seGuence obFect% follo0ed by an inde8 number in brac/ets9 (ote that the first
inde8 number is 09 3his e8am#le finds the third character6 0hich has the inde8 number 2)
>>> mystring = "tr-ly, madly, deeply"
>>> mystring[2]
,-,
!licin"
3o find items corres#ondin$ to a #articular slice6 you use the name of the strin$ and
brac/ets6 as abo7e9 &nside the brac/ets6 you enter a slice e8#ression) the be$innin$ of the
slice6 a colon6 and the end of the slice9 3he end of the slice means Iu# to but not
*0
includin$I this element9 &n the e8am#le belo06 fi7e elements are returned inde8 numbers
E6 '6 =6 /%6 and //%9
<ereCs an e8am#le)
>>> mystring[E!/2]
,madly,
A ste# sometimes called a stride% s/i#s o7er some items in the seGuence9 3o s#ecify a
ste#6 ty#e a second colon and the ste# number6 li/e so)
>>>> mystring = ,/23.&<E'=,
>>> mystring[%!=!2]
,/3&E=,
Ste#s arenCt su##orted in 7ersions of 4ython earlier than 29"9
%iguring out the tricks
Follo0in$ are some shortcuts you can use 0ith slicin$ and inde8in$ synta89 3he
e8am#les all use this strin$)
alp2a = ,a(cde,
3he be$innin$s and ends of slices are li/e noteboo/ di7iders>they sit bet$een
the elements9
&f you are countin$ from left to ri$ht 0hen inde8in$ or slicin$6 the first inde8
number is 06 not -6 as sho0n)
>>> alp2a = ,a(cde,
>>> alp2a[%]
,a,
>>> alp2a[%!3]
,a(c,
3i# When slicin$6 the first inde8 defaults to 09 &f you lea7e out the first inde86
4ython uses the first item in the seGuence6 li/e this)
>>> alp2a[!2]
,a(,
When slicin$6 the last inde8 defaults to Ithe len$th of the seGuence9I Eou can
access the last item 0hen slicin$ by lea7in$ out the number after the colon6 li/e
this)
>>>> alp2a[/!]
,(cde,
3i# &f you use a number lar$er than the size of the seGuence6 Ithe len$th of the
seGuenceI re#laces it9
>>> alp2a[3!/%]
,de,
*-
<o0e7er6 this doesnCt 0or/ 0ith inde8in$9 &f you use a number lar$er than the
size of the seGuence6 4ython raises an Gndex6rror9
>>> alp2a[/%]
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
Gndex6rror! string index o-t of range
&f you are slicin$6 and the second inde8 number is smaller than the first6 you $et
an em#ty seGuence for e8am#le6 an em#ty strin$%9
>>> alp2a[3!2]
,,
Eou can also count from ri$ht to left 0hen inde8in$ or slicin$9 3his is called
negative inde!ing9% When inde8in$6 the first inde8 number6 from the ri$ht6 is 7/6
the ne8t is 726 and so on>but the leftmost inde8 is still 09
>>> alp2a[7/]
,e,
&f you are ma/in$ a slice6 ho0e7er6 7/ #oints before the last element9 3o $et at the
last element6 you need to use I!]I)
>>> alp2a[73!7/]
,cd,
>>> alp2a[73!]
,cde,
3o $et the 0hole seGuence as a slice6 use [!] 0hich ma/es a co#y%9
>>> alp2a[!]
,a(cde,
S#ecifyin$ a ne$ati7e ste# 0hen slicin$ is one 0ay to re7erse a strin$9
>>> ,2ello,[!!7/]
,olle2,
Fi$ure 61- sho0s the relationshi# of inde8 numbers and elements in a strin$ or other
seGuence obFect9
Fi$ure 61-) Delationshi# of inde8es6 slice inde8es6 and elements in a seGuence obFect9
*2
#hanging the iutable string
Strin$s are immutable cannot be chan$ed%9 'ut you can use slicin$ and the : o#erator to
ma/e a ne0 strin$6 usin$ some of the content from an e8istin$ strin$9 3o ma/e a ne0
strin$ by slicin$6 follo0 this e8am#le6 0hich uses slicin$ to ta/e all but the first four
characters of the candy strin$ and concatenates it to the strin$ ,milA,)
>>> candy = ,darA c2ocolate (ars,
>>> morecandy = ,milA, : candy[.!]
>>> print morecandy
milA c2ocolate (ars
Interpolatin" Between the -ines
3o format the out#ut of strin$s6 you can use the strin$ methods mentioned in IFindin$ out
more about strin$ methods6I earlier in this cha#ter9 'ut there is another6 more common
0ay to format strin$s) the D o#erator9 When used 0ith strin$s6 this o#erator is sometimes
called the interpolation operator.
When 0e use the 0ord formatting6 0e arenCt referrin$ to 0ord #rocessorRty#e formattin$
>chan$in$ fonts6 colors6 styles6 and the li/e9 We mean s#ecifyin$ 0hat ha##ens 0hen a
7alue is inserted into a strin$9 For e8am#le6 0e mi$ht s#ecify ho0 many di$its to dis#lay
to the ri$ht of a decimal #oint9
3he inter#olation o#erator also lets you insert data in s#ecific #laces in a strin$9 3his
means you can calculate your data in one #art of your #ro$ram and #rint it or sa7e it to a
file in another #art9
)sing the interpolation operator
Eou can use the D o#erator in se7eral 0ays)
3o include a sin$le data item in a strin$
3o include multi#le data items in a strin$ by usin$ a tu#le
3o include multi#le data items in a strin$ by usin$ a dictionary as a ma##in$ /ey
4eanin"s of the formattin" codes
A formattin$ code consists of the D character follo0ed by a character called a conversion
type9 @ach character stands for a #articular ty#e of data to be included in a strin$9
*"
3he Ds formattin$ code to indicate strin$ data% is the most #o#ular code6 because it
0or/s on almost all ty#es of data>if you use somethin$ other than a strin$ as your data6
4ython con7erts it to a strin$ automatically9
<ere are some characters that stand for other /inds of data)
Dc) Sin$le character 0or/s 0ith an inte$er or sin$le1character strin$%
Dd6 Di) Si$ned inte$er decimal
Df6 D>) Floatin$ #oint decimal
Dr) A repr)* re#resentation of the data
DD) 4ercent si$nH used 0ith other codes as an esca#e character for a real #ercent
si$n6 as in the e8am#le belo0)
>>> "&%DD of not2ing is still Di" D %
,&%D of not2ing is still %,
(ptional modifiers of the formattin" code
Eou can add se7eral o#tional modifiers to D codes9 Eou must ty#e the formattin$
modifiers and code 0ithout s#aces and use this order)
-9 3he D o#erator
29 A mapping key in #arentheses described in IFormattin$ 0ith a dictionary6I later
in this cha#ter%9
"9 :on7ersion fla$s6 so1called because they affect ho0 some /inds of data are
con7erted 0hen theyCre included in the strin$9 3hey mostly s#ecify ho0 to handle
: and 77 si$ns9
3o find out more6 see the >JBL00G1S to#ic in 4ythonCs hel# utility by ty#in$
2elp)">JBL00G1S"*9
!9 3he minimum amount of s#ace to allo0 for the data minimum field $idth%>a
#ositi7e inte$er9
A9 <o0 many di$its to include to the ri$ht of the decimal #oint of a decimal number
precision%>a dot "% follo0ed by the #recision 7alue9
69 3he formattin$ code
3he first and last of the #recedin$ ste#s are reGuiredH the rest are o#tional9
3his e8am#le #rints #i to a #recision of -0 decimal #laces)
>>> import mat2
>>> "02e 5al-e of pi is a(o-t D"/%f" D mat2"pi
,02e 5al-e of pi is a(o-t 3"/./&=2<&3<,
*!
'ormattin" with one data item
&f you ha7e a sin$le data item for e8am#le6 mystring = "s9allo9"% and you 0ant to
include it in a strin$6 follo0 these ste#s to 0rite the code to do it)
-9 Type your strin" up to the point where you want your data to "o, like this,
2" >>>> "Ln Lfrican or 6-ropean
"9 (n the same line, type D followed by the formattin" codeF for example,
." >>> "Ln Lfrican or 6-ropean Ds
&n the abo7e e8am#le6 Ds indicates that you 0ill insert strin$ data9
A9 (n the same line, type the rest of your strin", a space, another D6 a space, and
the data item that you want to include.
Eour final line mi$ht loo/ somethin$ li/e this)
>>> "Ln Lfrican or 6-ropean DsV" D mystring
,Ln Lfrican or 6-ropean s9allo9V,
'ormattin" with multiple data items in a tuple
3o include multi#le #ieces of data in a strin$6 you use multi#le formattin$ codes and #ass
the ar$uments in a tu#le that is6 inside #arentheses6 0ith the 7alues se#arated by
commasH see :ha#ters " and , for a refresher on tu#les%9
3his section 0or/s 0ith line ! of the follo0in$ code6 0hich calculates and #rints a table
of #o0ers)
print "D2s D&s D/2s" D ),x,, ,x;;2,, ,x;;x,*
print "=" ; 2/
for x in range)/,<*!
print "D2d D&d D/2d" D )x, x;;2, x;;x*
3o insert multi#le data items into a strin$6 follo0 these ste#s)
-9 Type print6 followed by a formattin" code for each item you want to include,
like so,
2" print "D2s D&s D/2s"
3he numbers in this formattin$ code s#ecify minimum field 0idths9
"9 (n the same line, type a space, D6 a space, and a tuple that includes one data
item for each formattin" code in the strin", as shown here,
." print "D2s D&s D/2s" % ('x', 'x**2', 'x**x')
3he code #rints the follo0in$ results)
*A
x x;;2 x;;x
=====================
/ / /
2 . .
3 = 2E
. /< 2&<
& 2& 3/2&
&tCs easy to for$et to use tu#les 0hen formattin$ 0ith multi#le data items9 &f you
remember to do this consistently6 youCll be ahead in the debu$$in$ $ame9 @7en
e8#erienced 4ython #ro$rammers ma/e this mista/e6 so if you see an error messa$e li/e
this6 youCre in $ood com#any)
>>> ,Ds Ds, D ,t2e,, ,larc2,
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
0ype6rror! not eno-g2 arg-ments for format string
<ereCs the ri$ht 0ay to do it)
>>> ,Ds Ds, D ),t2e,, ,larc2,*
,t2e larc2,
'ormattin" with a dictionary
Eou can $et data out of a dictionary and include it in your strin$ by usin$ the D o#erator9
Eou use a mapping key to stand for the 7alue to be used from the dictionary9 Follo0 these
ste#s to create a line of code that $ets the 7alue of the mathematical constant e from a
dictionary and #rints it as #art of a strin$9
-9 Type your strin" up to the point where you want to include your data, like so,
2" "02e 5al-e of e is approximately
"9 Type D and 5in parentheses6 the dictionary key for the value you want to
include.
." "02e 5al-e of e is approximately %(e)
A9 Type the formattin" code 5so that the whole chunk of code looks somethin"
like this6,
<" "02e 5al-e of e is approximately D)e* f
+9 Type the rest of your strin", a space, the D operator, a space, and the name of
the dictionary.
'" "02e 5al-e of e is approximately D)e*f " % mydict
<ereCs the line of code in conte8t)
>>> mat2$const = {,pi,! 3"/./&=2, ,e,! 2"E/'2'2}
>>> "02e 5al-e of e is approximately D)e*f" D mat2$const
,02e 5al-e of e is approximately 2"E/'2'2,
*6
A foratting exaple using string ethods
Eou can also use strin$ methods to 0rite code that #rints a table of #o0ers6 similar to the
one in the #re7ious section6 IFormattin$ 0ith multi#le data items in a tu#le9I 3he
rT-st)* method ri$ht1Fustifies the strin$ 0ithin an area the size of the number of s#aces
s#ecified in its ar$ument9
(ote that this code has more lines than the code 0ritten 0ith the D o#erator and tu#les9 &f
youCre concerned about reducin$ the size of your #ro$rams6 the D o#erator mi$ht be the
0ay to $o9
x = ,x,
y = ,x;;2,
Q = ,x;;x,
print x, y"rT-st).*, Q"rT-st)<*
print "=" ; /.
for n in range)/,<*!
nn = str)n;;2*
nnn = str)n;;n*
print n, nn"rT-st).*, nnn"rT-st)<*
<ereCs 0hat it #rints)
x x;;2 x;;x
==============
/ / /
2 . .
3 = 2E
. /< 2&<
& 2& 3/2&
&nravelin" &nicode
So far6 you ha7e been usin$ strin$s that 0or/ 0ith @n$lish te8t and some Western
lan$ua$es6 li/e French and ;erman%9 'ut 0hat if you need to use Dussian or Ja#anese2
4ython 290 introduced a s#ecial strin$ ty#e called )nicode strings that let you mani#ulate
strin$s in any lan$ua$e or al#habet9
?nicode strin$s 0or/ mostly the same 0ay as re$ular strin$s9 <ere are a fe0 of their
uniGue features)
?nicode strin$s in 4ython are s#ecified 0ith a lo0ercase -9
&n most installations of 4ython6 a four1di$it he8adecimal number re#resents each
?nicode character9
De$ular AS:&&% characters use a t0o1di$it he8adecimal number9
*+
#reating a )nicode string
3o create a ?nicode strin$6 #recede the strin$ 0ith -6 li/e so)
>>> Q = -">r-it (ats pollinate t2e flo9ers of many fr-its""
3o create a ?nicode strin$ that uses a non1AS:&& ?nicode character6 follo0 these ste#s)
-9 Type - to specify a &nicode strin" and then start typin" the strin".
2" -,3i(ert
"9 To specify a character that you want to represent by usin" &nicode, type Z-
and the character's hexadecimal value, like so,
." -,3i(ert Z-%%e=
A9 Type the rest of the strin" and the endin" =uotation mark,
<" -,3i(ertZ-%%e= ,
3he 7alue %%e= stands for the Z character9
3@:<(&:A.
S3?FF
*hat is &nicode and why do we care about itC
When #eo#le started teachin$ com#uters ho0 to tal/6 the com#uter
$ee/s came u# 0ith a system called AS:&& American Standard :ode
for &nformation &nterchan$e%9 AS:&& characters are encoded by usin$
+ bits of information6 0hich allo0s for only -2, 0R-2+% characters9
3hat 0asnCt enou$h for non1@n$lish lan$ua$es6 accented characters6
and other common symbols9
@nter ?nicode9 ?nicode 0ill e7entually be able to encode e7ery
character set6 includin$ those for non1@uro#ean lan$ua$es6 al#habets
used by scholars6 and mathematical and lin$uistic symbols9 See
htt#)LL0009unicode9or$ to find out more9
3@:<(&:A.
S3?FF
-ocation, location, location
<o0 4ython stores and dis#lays your ?nicode strin$ de#ends on
your locale, $hich is Python3s idea of 0hat lan$ua$e and character
set youCre usin$9 3he locale also determines the default character
encodin$ that 4ython uses9 3he encoded strin$ must match that
encodin$9
<ereCs ho0 to see your default locale and encodin$)
>>> import locale
>>> locale"getdefa-ltlocale)*
[,en$4@,, ,-tf,]
*,
.ocales are tric/y because all re#eat6 all% character in#ut and out#ut
must $o throu$h the encodeLdecode #rocess9 When you #rint a
?nicode strin$6 4ython automatically tries to do this con7ersion so
that you see the characters you e8#ect9 <ereCs an e8am#le of this
con7ersion in action)
>>> print -,3i(ertZ-%%e=,
3i(ert]
'ut youCll see an error if you try #rintin$ a ?nicode strin$ that
contains characters that donCt e8ist in your current locale9 For
e8am#le6 if you try to #rint a <ebre0 character 0ith a locale that
doesnCt su##ort any <ebre0 encodin$s6 youCll see this error)
>>> print -,Z-%&d%, + He(re9 alep2 c2aracter
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
$$(-iltin$$"4nicode6ncode6rror! ,ascii, codec
can,t encode c2aracter -,Z-%&d%, in
position %! ordinal not in range)/2'*
(ote that many modern o#eratin$ systems su##ort multi#le
encodin$s6 so you mi$ht not see this error if you try it yourself9
A t&isty a6e of codes
?nicode lets you #rocess te8t by usin$ only one code9 'ut ?nicode canCt be used directly
0ith character in#ut and out#ut6 so you need to encode out#ut and decode in#ut9
'e$inners tend to thin/ of ?nicode as another encodin$ of the character set they are used
to usin$9 3hus6 they thin/ that they need to encode Ire$ularI te8t into ?nicode and
decode ?nicode into re$ular te8t9 3hatCs bac/0ard9 <ereCs the correct 0ay to thin/ about
it)
When you start usin$ ?nicode6 0hate7er re$ular character set youCre usin$ is a #art of
?nicode9 3herefore6 you need to encode ?nicode characters into your re$ular character
set6 and decode your re$ular character set into ?nicode9
,ncoding! decoding! and other )nicode ethods
All the re$ular strin$ methods also 0or/ 0ith ?nicode strin$s9 A cou#le of methods a##ly
es#ecially to ?nicode) encode)* and decode)*9
3he list of standard encodin$s is a7ailable at
htt#)LL0009#ython9or$Lde7LdocLde7elLlibLstandard1encodin$s9html9
**
#onvertin" &nicode to an encoded strin"
3o con7ert a ?nicode strin$ to an encodin$6 such as ?3F1, or .atin1-6 you use the
encode)* method9 Follo0 these ste#s)
-9 #reate a &nicode strin", like so,
2" y = -"3i(ertZ-%%e=, Z-%%e=galitZ-%%e=, fraternitZ-%%e="
"9 Type the name of the strin", a dot, encode6 and 5in parentheses6 the encodin"
you want to convert to.
." y"encode),-tf7',*
3his e8am#le sho0s the difference bet0een the encoded and #rinted strin$s)
>>> N = y"encode),-tf7',*
>>> N
,3i(ertZxc3Zxa=, Zxc3Zxa=galitZxc3Zxa=, fraternitZxc3Zxa=,
>>> print N
3i(ert], ]galit], fraternit]
3i# 4ythonCs file obFects and @tringGJ obFects donCt su##ort ra0 ?nicodeH the usual
0or/around is to encode ?nicode te8t as ?3F1, before sa7in$ it to a file or Strin$&M
obFect9
:ecodin" a strin" into &nicode
3he decode)* method6 ne0 in 4ython 2926 assumes that a strin$ is in the s#ecified
encodin$ and turns it into ?nicode9 3o decode a strin$ into ?nicode6 follo0 these ste#s)
-9 #reate an encoded strin", like so 5this strin" is encoded usin" &T'1G6,
2" N = ,3i(ertZxc3Zxa=,
"9 Type the name of the strin", a dot, decode6 and 5in parentheses6 the encodin"
that the strin" currently uses.
." N"decode),-tf7',*
The 4idas touch9&nicode versus str
&n 4ython6 ?nicode beha7es a bit li/e Midas6 the character in ;ree/ le$end 0ho turned
e7erythin$ he touched includin$ his dau$hter% into $old9 When you use a ?nicode strin$
and a re$ular strin$ to$ether6 the results are al0ays ?nicode9
>>> my-nicodestring = -"idas is coming! "
>>> mystring = "Oon,t to-c2 me, idas!"
>>> my-nicodestring : mystring
-"idas is coming! Oon,t to-c2 me,
idas!"
3his e8am#le sho0s the difference bet0een the encoded and decoded strin$s9
@ncoded strin$
-00
>>> ,3i(ertZxc3Zxa=,
Decoded ?nicode% strin$
-,3i(ertZxe=,
Zxe= is 4ythonCs shorthand 0ay of re#resentin$ ?nicode character Z-%%e=6 0hich
#rints as ]9
'oth strin$s loo/ the same 0hen #rinted)
>>> print N
3i(ert]
>>> print N"decode),-tf7',*
3i(ert]
-0-
#hapter H, #ountin" your *ay to 'un
and rofit
&n 4ython6 numbers come in se7eral different data ty#es9 :ha#ter " introduces the number
ty#es and their o#erators9 3his cha#ter $i7es you more information on inte$ers6 binary
floatin$ #oint numbers6 and com#le8 numbers6 and #ro7ides $uidance for usin$ 4ythonCs
au$mented assi$nment o#erators9 &t also introduces 4ythonCs built1in math modules6
includin$ the decimal module for doin$ true decimal arithmetic6 and the random module
for $eneratin$ random numbers9
Inte"ratin" Inte"ers
&nte$ers are #ositi7e and ne$ati7e 0hole numbers numbers 0ithout a 7alue to the ri$ht of
the decimal #oint%9 We $i7e you a brief o7er7ie0 of inte$ers in :ha#ter "H the follo0in$
sections describe some finer #oints about 4ythonCs inte$ers9
*hy Python has t&o kinds of integers
'ecause of ho0 com#uters store numbers in memory6 4ython uses t0o /inds of inte$ers)
De$ular inte$ers
.on$ inte$ers
&n the recent #ast6 most com#uters used "2 bits of memory to store an inte$er9 'ut
inte$ers lar$er than a certain 7alue 26-!+6!,"66!+6 to be e8act% ta/e u# more than "2 bits
of memory9 So 4ython uses a different mechanism to store them9 4ython re#resents lon$
inte$ers 0ith the suffi8 39
3@:<(&:A.
S3?FF
&n future 7ersions of 4ython6 all inte$ers 0ill be handled the same
0ay9 For no06 if youCre 0ritin$ #ro$rams that mani#ulate 7ery lar$e
inte$ers6 each 7ersion of 4ython handles inte$ers a bit differently9
Eour results may 7ary de#endin$ on the 7ersion9 &f youCre usin$
4ython 292 or later6 re$ular inte$ers automatically con7ert to lon$
inte$ers6 so you can mostly i$nore the issue9
A$oiding unexpected results &ith integer di$ision
&f you enter only inte$ers 0hen you do arithmetic6 4ython returns the results in inte$ers9
3his can $i7e une8#ected results if youCre doin$ di7ision 0ith the 8 o#erator>you $et
only the inte$er #art of the result9
3@:<(&:A.
S3?FF
&n math terms6 the 8 o#erator #erforms floor division, not true
di7ision9
-02
For e8am#le6 your math teacher 0ould not let you $et a0ay 0ith this result)
>>> /3 8 3
.
3i# &f you 0ant true di7ision6 use one of the follo0in$ solutions)
?se the decimal module6 li/e this)
>>> from decimal import Oecimal
>>> Oecimal)/3* 8 Oecimal)3*
Oecimal)"."333333333333333333333333333"*
3he decimal module 0as introduced in 4ython 29!9 See the section6 I3urnin$
4ython into a :alculator 0ith decimal6I later in this cha#ter6 for details9
Ma/e sure that at least one of the numbers in a calculation is a floating point
decimal% number6 li/e this)
>>> /3"% 8 3
."333333333333333
?se the di7ision feature from the $$f-t-re$$ module6 li/e this)
>>> from $$f-t-re$$ import di5ision
>>> /3 8 3
."333333333333333
?sin$ $$f-t-re$$ acti7ates code that 0ill become the default in 4ython "90H
in this case6 it acti7ates true di7ision for the 8 o#erator9 For inte$er di7ision6
use the 88 o#erator9
'loatin" Alon"
3he standard format for com#uters to store real numbers is called binary floating point,
0hich is different from the format most #eo#le are used to9 For e8am#le6 if you ty#e %"/
into 4ythonCs inter#reter6 you see that 4ythonCs internal re#resentation of the number is
different from 0hat you ty#ed)
>>> %"/
%"/%%%%%%%%%%%%%%%/
3@:<(&:A.
S3?FF
3his ha##ens because a com#uter canCt accurately re#resent some
decimal numbers as floats9 For more information than you really
need to /no0 about 0hy6 see A##endi8 ' of the 4ython 3utorial at
htt#)LL0009#ython9or$9 For detail nuts only: 3he decimal numbers
that can be re#resented accurately ha7e a fractional com#onent
containin$ only sums of #o0ers of t0o9%
-0"
Autoatic con$ersion
4ython automatically con7erts different ty#es of numbers so that you usually% donCt need
to thin/ about the com#atibility of different number ty#es9 For e8am#le6 if you do a math
o#eration 0ith both inte$ers and floats6 4ython con7erts the inte$ers to floats and $i7es
the result as a float9
%oratting floats
&f you donCt 0ant to loo/ at 0eird numbers 0ith -6 decimal #laces6 use the str)*
function to dis#lay the number as a strin$9
>>> ."/
."%==============<
>>> str)."/*
,."/,
Warnin$ Eou mi$ht be tem#ted to use the ro-nd)* function to handle floatin$ #oint
numbers9 'ut ro-nd)* reGuires you to s#ecify a #recision the number of di$its
to the ri$ht of the decimal #oint% and defaults to a #recision of 0 0hich
remo7es all the di$its to the ri$ht of the decimal #oint%9 3his #robably isnCt 0hat
you 0ant if youCre 0or/in$ 0ith decimal numbers5
Si6e liits on floats
4ythonCs binary floatin$ #oint numbers ha7e a finite ran$e9 4ython stores binary floats
usin$ at most -+ decimal di$its of accuracy9 &n addition6 the lar$est float you can store is
-9+*+6*P-0
"0,
0hich 4ython re#resents as -9+*+6*eN"0,%9 &f you try to calculate or
store a lar$er number6 you may $et a result such as this)
>>> x = 2"E=E<=e:3%'
>>> x
inf
.on$ inte$ers can be lar$er than floats6 so you mi$ht $et an Io7erflo0 errorI or incorrect
results 0hen usin$ lar$e inte$ers 0ith binary floats or 0ith the float)* function 0hich
con7erts numbers to binary floats%9 3he follo0in$ code attem#ts to con7ert -0
-6000
to a
float9 'ecause the resultin$ number is too bi$ for 4ython and the com#uter to handle6 it
raises an error)
>>> float)/%;;/%%%*
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
J5erflo96rror! long int too large to con5ert to float
3he follo0in$ code also $i7es an incorrect result because of the -+1di$it size limit on
floats9 A number doesnCt eGual itself #lus -6 no matter ho0 bi$ it is5%
>>> /%"% ;; /%% == )/%"% ;; /%%* : /
-0!
0r-e
Ima"inin" #omplex ?umbers
:om#le8 numbers ha7e a real and ima$inary #art6 both of 0hich are floats9
3@:<(&:A.
S3?FF
A com#le8 numeric literal is the sum of a real #art and an ima$inary
#art9
&n 4ython6 to s#ecify an ima$inary number6 or the ima$inary #art of a com#le8 number6
a##end T to the number9
3o se#arate the real or ima$inary #art of a com#le8 number6 ty#e x"real for the real #art
or x"imag for the ima$inary #art6 li/e this)
>>> x =)3:<T*
>>> x"real
3"%
>>> x"imag
<"%
Au"mented assi"nment
?se augmented assignment o#erators to #erform actions such as addition6 concatenation6
subtraction6 and multi#lication on an obFect and store the result usin$ the same name9 An
Iau$mentedI assi$nment statement has an e8tra feature>an addition or concatenation
o#eration>built in9% <ereCs 0hy)
Au$mented assi$nment statements are easier to debu$9
3he statement co-nter :=/ clearly uses only one obFect9 &f you use the statement
co-nter = co-nter : /6 you must read the statement carefully to ma/e sure the
t0o obFects are the same9 &f youCre tryin$ to debu$ someone elseCs thousand1line
#ro$ram6 youCll a##reciate the sim#licity5
Au$mented assi$nment statements are more efficient9
3hese statements e7aluate an obFect only once and chan$e mutable obFects in
#laceH re$ular assi$nment e7aluates an obFect t0ice and creates a ne0 co#y in the
#rocess9 3his can slo0 #erformance 0ith lar$e obFects9
3hese are the most commonly used au$mented assi$nment o#erators)
:= )addition or concatenation*!
co-nter := /
7= )s-(traction*!
co-nter 7= /
;= )m-ltiplication*!
co-nter ;= /
-0A
&sin" 4ath 4odules
Alon$ 0ith the arithmetic o#erators co7ered in :ha#ter "% and the basic math functions
of the $$(-iltin$$ module introduced in :ha#ter 2% thatCs al0ays a7ailable 0hen you
use 4ython6 4ython has se7eral modules that #ro7ide math functions9
3i# 3o im#ort any of the math modules6 ty#e import follo0ed by the name of the
module9 ?se the follo0in$ list to $uide you to the module you need)
/eal numbers, 3he mat2 module has most of the functions you need for real
numbers9 3o see all the functions6 ty#e this into the inter#reter)
>>> import mat2
>>> 2elp)mat2*
#omplex numbers, 3he cmat2 module6 for com#le8 numbers6 has most of
the same functions as the mat2 module but returns results as a com#le8
number ty#e for e8am#le6 3:<T>see I&ma$inin$ :om#le8 (umbers6I earlier
in this cha#ter%9
3he cmat2 module also returns 7alues for calculations such as the sGuare root
of a ne$ati7e number9 3he mat2 module treats such calculations as errors9%

Warnin$ &f youCre 0or/in$ 0ith both com#le8 and real numbers6 use the
module name such as cmat2"sNrt)* or mat2"sNrt)*% 0hen
callin$ a function9 Many of the t0o modulesC functions ha7e the
same names but 0or/ differently9 3he module name hel#s you /ee#
trac/ of 0hich function youCre usin$9
:ecimal numbers, 3he decimal module lets you 0or/ 0ith decimal
numbers rather than binary floatin$ #oint numbers9

3i# Decimal numbers $i7e more accurate results for many calculations9 See
I3urnin$ 4ython into a :alculator 0ith decimal6I later in this cha#ter9
/andom numbers, 3he random module includes tools for such tas/s as
$eneratin$ random numbers and choosin$ randomly from se7eral elements9
For a fun introduction to the tric/s u# the slee7e of the random module6 see
:ha#ter 2-9
Turnin" ython into a #alculator with decimal
3he decimal module6 ne0 in 4ython 29!6 su##orts decimal floatin$ #oint arithmetic9
&f youCre 0ritin$ a##lications that reGuire control o7er #recision and roundin$ such as
financial soft0are or statistics modules%6 this module is for you9 &ts results also match
calculations done by hand math educators ta/e note5%9
-06
3he decimal module $i7es more accurate results than binary floatin$ #oint math for
these ty#es of calculations) Calculating a percentage, modulo calculations 0hich return
the fractional result of di7ision%6 and e7uality tests.
.i/e other numbers6 decimal numbers are immutable9
3i# 3o im#ort the decimal module6 use this statement)
from decimal import Oecimal
/epresenting nubers by using the decial odule
3o create a decimal number6 ty#e the follo0in$6 substitutin$ your number or obFect inside
the #arentheses)
Oecimal)numerical_object*
3he numerical_object can be any of these ty#es of data)
An inte$er
Oecimal)3*
A calculation
Oecimal)3;&*
A number re#resented as a strin$
Oecimal)"3"2"*
A float con7erted to a strin$ 0ith the str)* function
>>> x = 3"2
>>> Oecimal)str)x**
Oecimal)"3"2"*
Warnin$ Eou canCt use floatin$ #oint numbers directly 0ith the decimal module9
3hey must be con7erted to strin$s first9
A three1item tu#le
>>> Oecimal))%, )3, /, .*, 72**
Oecimal)"3"/."*
3i# 3o create a decimal from a three1item tu#le6 use this format for the tu#le)
-9 3he first item in the tu#le is % for #ositi7e% or / for ne$ati7e%9
29 3he second item is another nested% tu#le containin$ the di$its of the
number6 one element for each di$it9
"9 3he third item is a #ositi7e or ne$ati7e inte$er s#ecifyin$ the
e8#onent9
Oecimal numbers 0or/ 0ith 4ythonCs re$ular math functions9 ;i7e them names and use
the names as ar$uments6 or insert them directly as ar$uments)
>>> po9)Oecimal)=*, 2*
-0+
Oecimal)"'/"*
Vie&ing and changing paraeters
3he decimal module has #arameters that control ho0 it 0or/s 0ith and dis#lays
numbers9 3o see the #arameters6 ty#e the follo0in$)
>>> import decimal
>>> decimal"getcontext)*
Hontext)prec=2', ro-nding=BJ41O$HL3>$6W61, 6min=7=========,
6max==========,
capitals=/, flags=[], traps=[Oi5isionIyKero, Gn5alidJperation,
J5erflo9]*
Mne of the #arameters is the ma8imum #recision of decimal numbers ho0 many di$its to
the ri$ht of the decimal #oint you see%9 3o chan$e the #recision #arameter6 ty#e
somethin$ li/e this)
>>> decimal"getcontext)*"prec = E
3i# &f you 0ant to chan$e the #recision of a s#ecific number 0ithout chan$in$ the
#recision #arameter for all the numbers6 use the N-antiQe)* method9 N-antiQe)*
rounds the number to a s#ecific number of decimal #laces9 3his e8am#le rounds to
t0o decimal #laces)
>>> data = Oecimal),E"32.,*
>>> data"N-antiQe)Oecimal),"%/,**
Oecimal)"E"32"*
-0,
#hapter G, rocessin" -ists and Tuples
.ists and tu#les are t0o of 4ythonCs compound data types6 also called container ob-ects9
:om#ound data ty#es $rou# collections of data9
4ython has se7eral /inds of com#ound data ty#es9 .ists and tu#les are se7uence ty#es
because each element of data is numbered seGuentially6 startin$ 0ith 09 SeGuence ty#es
su##ort o#erations called inde!ing and slicing for 0or/in$ 0ith indi7idual elements or
subsets of elements9 Eou can find out about inde8in$ and slicin$ in :ha#ter 69
A seGuence data ty#e is $ood 0hen you 0ant to o#erate on all the elements in a collection
or 0hen the order of elements in a collection is im#ortant9 &n contrast6 the dictionary data
ty#e>a mapping ty#e>is for random access to elements6 and a set is for com#arin$
collections of obFects9 Dictionaries and sets are co7ered in :ha#ter *9%
3his cha#ter sho0s you the synta8 for lists and tu#les6 0hen to use them6 ho0 to 0or/
0ith elements inside them6 ho0 to use them in loo#s6 and ho0 to a7oid some of the
common errors #ro$rammers ma/e 0hen 0or/in$ 0ith them9
Introducin" -ists and Tuples
3he follo0in$ sections describe the features and synta8 of lists and tu#les and e8#lain
0hen to use each9
*hat a list is
A list is a mutable data ty#e6 0hich means you can chan$e the contents of a list 0ithout
creatin$ a ne0 list9 3he elements of a list can be of different data ty#es9 A sin$le list can
contain numbers6 strin$s6 other lists6 tu#les>and e7en functions and classes9
&n 4ython6 a list literal the actual data6 not a name referrin$ to the data% is defined by
sGuare brac/ets surroundin$ zero or more elements9 @lements are se#arated by commas9
'elo0 are e8am#les of lists)
a$list = [,t2is,, ,is,, ,a,, ,list,]
empty$list = []
anot2er$list = [&]
.ists come 0ith a 7ariety of built1in methods that let you mani#ulate them9 For e8am#le6
to sort a list6 you 0rite code li/e this)
>>> mylist = [', 33, 2=, ., /, &, =']
>>> mylist"sort)*
>>> mylist
[/, ., &, ', 2=, 33, =']
-0*
*hat a tuple is
A tu#le is a seGuence data ty#e that can contain elements of different data ty#es9 3u#les
are different from lists because tu#les are immutable. &f you 0ant to chan$e the contents
of a tu#le6 you must create a ne0 tu#le that has the ne0 content you 0ant9
Warnin$ &f a tu#le contains a mutable element such as a list or dictionary%6 the mutable
element can be modified9 <o0e7er6 some of the ob7ious 0ays of chan$in$ the
mutable element 0ill cause errors because 4ython 0ill attem#t to modify the
tu#le9 We recommend that you a7oid chan$in$ mutable elements in tu#les9
3u#les donCt include a lot of s#ecial methods6 the 0ay strin$s and lists do9 'ut tu#les do
include methods that su##ort standard 4ython o#erators9 For e8am#le6 you can add
tu#les6 chec/ 0hether an item is inside a tu#le6 slice elements in a tu#le6 com#are a tu#le
to other data6 find a tu#leCs len$th6 and so on9
Many 4ython functions6 such as the time and date functions6 return tu#les9
#hoosin" between lists and tuples
.ists and tu#les loo/ similar at first $lance6 but they ha7e intrinsic differences)
A tu#le is immutable6 and a list is mutable9
3u#les are more memory1efficient9
.ists ha7e se7eral useful built1in methods9
3u#les are often better than lists for information that you donCt 0ant to chan$e6 for t0o
reasons) 3hey use less memory6 and because theyCre immutable% they 0onCt chan$e
une8#ectedly9
.ists are often better for information you 0ant to chan$e because there are more 0ays of
mani#ulatin$ them9
;uido 4ythonCs creator% and the 4ython community #romote the follo0in$ con7entions
for choosin$ bet0een lists and tu#les)
Tuples for hetero"eneous data, lists for homo"eneous data, ?se a tu#le if your
data includes se7eral different data ty#es6 such as names and addressesH use lists
for elements that are all of the same ty#e9
For e8am#le6 if youCre accessin$ a database6 the fields of a record mi$ht be
returned as a tu#le6 but the records themsel7es should be returned as a list9
3herefore the o7erall database 0ould be a list of tu#les9
Tuples for se=uence keys, &f you need to use a seGuence as a dictionary /ey6 you
must use a tu#le because dictionary /eys are immutable9
--0
Tuples for some functions, Some functions reGuire ar$uments to be #assed in
tu#les9
-ists for mutable ob>ects, A7oid usin$ mutable obFects in immutable containers
because errors and une8#ected results can occur if you attem#t to chan$e the
mutable obFects9
A tuple literal is defined in one of three 0ays)
A sin$le element follo0ed by a comma
Multi#le elements se#arated by commas
An em#ty set of #arentheses
When 4ython out#uts a tu#le6 it encloses the elements in #arentheses9 Eou can and
usually should% use #arentheses 0hen creatin$ a tu#le6 but you donCt ha7e to9 'elo0 are
e8am#les of tu#les9
>>> a$t-ple = ),t2is,, ,is,, ,a,, ,t-ple,*
>>> t-ple$2 = "t2is", "is", "anot2er", "t-ple"
>>> t-ple$2
),t2is,, ,is,, ,anot2er,, ,t-ple,*
>>> empty$t-ple = )*
A tu#le e8ce#t for an em#ty tu#le% must al0ays use a comma6 e7en if there is only one
element6 because the comma is the o#erator that defines a tu#le9
3i# 'ecause the comma is overloaded that is6 it does more than one thin$ in 4ython% and
because it has lo0 #recedence that is6 most other o#erations are e7aluated before
comma o#erations%6 itCs usually a ;ood &dea to add #arentheses to ma/e it clear that
you are usin$ a tu#le9
'elo0 are the results of usin$ the ; o#erator on a sin$le1element tu#le and on an inte$er9
>>> anot2er$t-ple = )3,*
>>> anot2er$t-ple ; 3
)3, 3, 3*
>>> not$a$t-ple = )3*
>>> not$a$t-ple ; 3
=
---
4anipulatin" !e=uence (b>ects
3he follo0in$ sections describe ho0 to com#are6 combine6 and search the contents of
lists6 tu#les6 and other seGuence obFects9
#oparing se3uence ob'ects
SeGuence obFects such as lists can be com#ared to other obFects of the same data ty#e9 A
com#arison tells you 0hether the obFects are eGual or 0hether one is smaller than the
other9 <ereCs ho0 it 0or/s)
3he first items of each seGuence are com#ared6 and then the second items6 and so
on9
&f an item inside a seGuence is itself a seGuence6 then each of its items is
com#ared a$ainst the item of the same number in the other seGuence9
&f all items of t0o seGuences are eGual6 the seGuences are eGual9
&f seGuence - is the same as the be$innin$ of seGuence 26 seGuence - is smaller
lesser%9
Strin$s are com#ared based on the AS:&& order of their characters9 :ha#ter 6 has
more information about character order9
3able ,1- sho0s the results of com#arisons bet0een seGuences9
3able ,1-) :om#arisons bet0een SeGuences
M#en table as s#readsheet
#omparison /eason
)/, 2, 3* # )/, 2, .*, [/, 2,
3] # [/, 2, .]
" is less than !
,LIH, # ,H, # ,Cascal, #
,Cyt2on,
AS:&& order of characters
)/, 2, .* > )/, 2, 3, .*, )/,
2* # )/, 2, 7/*
First seGuence is the same as the be$innin$ of
second seGuence
)/, 2, 3* == )/"%, 2"%, 3"%*
&nte$ers eGual their float eGui7alents
)/, 2, ),aa,, ,a(,** # )/, 2,
),a(c,, ,a,*, .*
Al#habetical order of characters in sub1seGuence
JaaK is smaller than JabcK%
&f you com#are obFects of different ty#es6 the ty#es are ordered al#habetically by their
names) .ists are smaller than strin$s6 0hich are smaller than tu#les9 3he rules for
com#arin$ obFects of different ty#es may chan$e in future 7ersions of 4ython9
--2
0perating on se3uence ob'ects
3he follo0in$ o#erators 0or/ on lists and tu#les9 Most of these o#erators also 0or/ on
other data ty#es)
Addition :%) :oncatenates the contents of lists to$ether to form a ne0 list6 or
concatenates the contents of tu#les to$ether to form a ne0 tu#le9 Eou canCt
concatenate a list and a tu#le9%
>>> [/, 2, 3] : [2, .]
[/, 2, 3, 2, .]
!e=uence multiplication ;%) De#eats the contents of a list or a tu#le9
Au"mented assi"nment := and ;=%) Simultaneously concatenates and assi$ns or
re#eats and assi$ns9 3he statement mylist := ne9list is the same as mylist =
mylist : ne9list9 3he former 0or/s sli$htly faster and is easier to read9
#omparison # >6 ==6 !=%) 3ests 0hether the contents of t0o or more lists or t0o
or more tu#les are the same9
#ontents test in%) 3he /ey0ord in determines 0hether a list or tu#le contains
the $i7en element and returns 0r-e or >alse6 as sho0n here)
>>> p2one$so-nds = ),(eep,, ,ring,, ,flig2t of t2e (-m(le(ee,*
>>> y = ,(eep, in p2one$so-nds
>>> y
0r-e
-istcraft, 4ethods, Indexes, and !lices
&n this section 0e describe im#ortant 0ays you can 0or/ 0ith lists9 Eou can turn other
data into lists6 count items in lists6 sort lists in 7arious orders6 and use inde8in$ and
slicin$ to chan$e6 add6 delete6 and mo7e indi7idual list items9
%unctions that &ork &ith or create lists
3he list)* function creates a co#y of a list9 &t also turns any other seGuence obFect or
iterable into a list9 An iterable is an obFect 0hose elements can be retrie7ed one at a
time9% 3his e8am#le turns a tu#le into a list)
>>> myt-ple = ),apple,, ,orange,, ,pear,*
>>> mylist = list)myt-ple*
>>> mylist
[,apple,, ,orange,, ,pear,]
&f you feed a strin$ to the list)* function6 it ma/es a se#arate list item out of each
character6 as in this e8am#le9
>>> mystring = "Ioo!"
>>> list)mystring*
--"
[,I,, ,o,, ,o,, ,!,]
3o find out the number of elements in a list6 use the len)* function it also 0or/s on
other data ty#es%9
>>> len)mylist*
3
(ethods of lists
A method is li/e a function e8ce#t that it Ibelon$sI 0ith a #articular obFect6 and 0hen
you call it6 you 7ualify it 0ith the name of the obFect9 3he method names are attributes of
the obFect9
-ist method syntax
3o call a list method6 ty#e the list name6 a dot6 the method name6 and #arentheses9 &n the
#arentheses6 #ass any ar$uments the method needs9 Some methods donCt reGuire or use
ar$uments9% <ereCs an e8am#le)
list$name"met2od$name)arg-ments*
The most popular list methods
3he follo0in$ are some of the most freGuently used list methods)
3o add an item to the end of a list6 use the append)* method9 3his method
chan$es the list in #lace9 &t returns 1one9
3his e8am#le adds the strin$ ,apple, to a list)
(asAet = [,apple,, ,(anana,, ,orange,]
(asAet"append),apple,*
3o find out the number of times a 7alue occurs in a list6 use the co-nt) value *
method9
3his e8am#le counts the number of times the strin$ ,apple, a##ears9
>>> (asAet"co-nt),apple,*
2
3o add to a list the contents of another seGuence obFect or iterable an obFect
0hose elements can be retrie7ed one at a time%6 use the extend)* method9 &f the
iterable is a strin$6 each character is added indi7idually9
3his e8am#le adds each character of the strin$ ,pear,9
--!
>>> x = [,apple,, ,apple,, ,(anana,, ,orange,]
>>> x"extend),pear,*
>>> x
[,apple,, ,apple,, ,(anana,, ,orange,, ,p,, ,e,, ,a,, ,r,]
3o delete the first occurrence of an item in a list6 use the remo5e)* method9 &t
raises a Wal-e6rror if the item isnCt found9
3his e8am#le remo7es the first ,apple, strin$9
>>> x"remo5e),apple,*
>>> x
[,apple,, ,(anana,, ,orange,, ,p,, ,e,, ,a,, ,r,]
3he sort)* and re5erse)* methods both chan$e the list itself9
o 3he sort)* methodCs default orderin$ is al#habetical for lists containin$
te8t6 numerical for lists containin$ numbers6 and so on9
o 3he re5erse)* method in7erts the #ositions of items in a list9

3i# 4ython 29! and later also su##ort these built1in functions)
o sorted)*6 0hich returns a sorted copy of the list or other iterable%9
o re5ersed)*6 0hich returns an iterator obFect that lets you use a loo#
to #rocess the items in the list in re7erse order9
3he follo0in$ e8am#les sho0 the use of the sort)* and re5erse)* methods on a
list of strin$s)
>>> x"sort)*
>>> x
[,a,, ,apple,, ,(anana,, ,e,, ,orange,, ,p,, ,r,]
>>> x"re5erse)*
>>> x
[,r,, ,p,, ,orange,, ,e,, ,(anana,, ,apple,, ,a,]
List indexing and slicing
.ist and tu#le elements ha7e inde8 numbers9 &nde8in$ and slicin$ o#erations on lists and
tu#les 0or/ mostly the same 0ay that they do 0ith strin$s9 <ereCs a Guic/ re7ie0 of ho0
inde8 numbers 0or/9 For more about inde8in$ and slicin$6 see :ha#ter 69
Wor/in$ from left to ri$ht6 the first element has the inde8 06 the ne8t has the inde8
-6 and so on9
3his e8am#le sho0s the items at inde8 0 and - of the list x9
--A
>>> x = [,apple,, ,(anana,, ,pear,]
>>> x[%]
,apple,
>>> x[/]
,(anana,
Wor/in$ from ri$ht to left6 the first element has the inde8 7/6 the ne8t one 726 and
so on>but the leftmost element is still 09
3his e8am#le sho0s the items at inde8 7/ and 729
>>> x[7/]
,pear,
>>> x[72]
,(anana,
3he be$innin$s and ends of slices sit bet$een the elements6 li/e noteboo/
di7iders9
3his e8am#le sho0s that slice %!/ contains Fust one element9
>>> x[%!/]
[,apple,]
How indexin" and slicin" are different with a list
&nde8in$ and slicin$ 0or/ sli$htly differently 0ith lists than they do 0ith strin$s and
tu#les because lists are mutable9 Eou can chan$e a list by usin$ inde8in$ and slicin$9
With a tu#le or a strin$6 you need to $i7e a ne0 name to the chan$ed obFect or reassi$n
the same name%9
/etrievin" items from a list with slicin"
Follo0in$ is a brief re7ie0 of slicin$ synta89 Eou can find more information in :ha#ter 69
3he synta8 for slicin$ is as follo0s)
seN-ence$o(Tect$name[firstindex!lastindex!step]
3hese are the rules for slicin$)
%ou can leave out the first slice index 5but not the colon followin" it6. &t
defaults to %9
%ou can leave out the last slice index. &t defaults to the last item of the seGuence9
3o access the last seGuence item in a slice6 if you donCt /no0 the len$th of the
seGuence6 lea7e the inde8 blan/9
--6
%ou can leave out the step and the colon precedin" it. 3he ste# defaults to /9
*hen you specify a ran"e, it be"ins with the first slice index specified and
ends !e%ore the last slice index specified. 3his is because slices #oint bet0een
elements9 So [%!2] retrie7es the first and second elements9
The notation [:] returns a shallow copy of the whole se=uence.
3he section6 I.ist references that une8#ectedly chan$e6I later in the cha#ter6 has
more on shallo0 co#yin$9
3he follo0in$ e8am#le code creates a list of numbers and then6 usin$ slice synta86 selects
and dis#lays all the e7en1numbered items9
>>> mylist = range)%,/%*
>>> mylist[!!2]
[%, 2, ., <, ']
#han"in" a list item by usin" its index number
Mne 0ay to chan$e the contents of a list is to assi$n a ne0 item to a #articular inde8
number also called an offset%9 3his re#laces 0hate7er is already at that inde8 number9
+otcha< Assi"nin" numbers and strin"s to slices
&f you assi$n to a slice6 you must assi$n an iterable9 3his means t0o thin$s)
-9 Eou canCt assi$n a number to a slice9
2" >>> mylist = [/, 2, 3, ., &, <]
3" >>> mylist [2!3] = '
." 0race(acA )most recent call last*!
&" >ile "#stdin>", line /, in V
<" 0ype6rror! can only assign an itera(le
+9 &f you assi$n a strin$ to a slice6 each letter becomes a se#arate list item9
'" >>> mylist[2!.] = ,t2ree,
=" >>> mylist
/%"[/, 2, ,t,, ,2,, ,r,, ,e,, ,e,, &, <]
//"9ay aro-nd t2is second pro(lem is to p-t t2e n-m(er
Mne 0ay around this second #roblem is to #ut the number or strin$ into a list9 3he
follo0in$ e8am#le assumes you 0ant to re#lace the numbers " and ! 0ith the strin$s
JthreeK and JfourK)
>>> mylist = [/, 2, 3, ., &, <]
>>> mylist[2!.] = [,t2ree,, ,fo-r,]
>>> mylist
[/, 2, ,t2ree,, ,fo-r,, &, <]
3o assi$n a ne0 item to a list by inde8 number6 follo0 these ste#s)
--+
-9 Type the list name and then, in s=uare brackets, type the index number, like
this,
2" mylist[/]
"9 (n the same line, type = and the new list element, so your line looks
somethin" like this,
." mylist[/] = new_list_element
&n the follo0in$ e8am#le6 the element at inde8 / the strin$ ,eggs,% is re#laced 0ith the
strin$ "lo5ely spam"9
>>> 3 = [,spam,, ,eggs,, ,2am,]
>>> 3[/] = ,lo5ely spam,
>>> 3
[,spam,, ,lo5ely spam,, ,2am,]
Eou canCt assi$n to an inde8 number that doesnCt e8ist9 4ython raises an Gndex6rror6 as
sho0n here)
>>> 3[3] = ,green eggs,
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
Gndex6rror! list assignment index o-t of range
3o add items to the end of a list6 use the append)* method)
>>> 3"append),green eggs,*
>>> 3
[,spam,, ,lo5ely spam,, ,2am,, ,green eggs,]
Assi"nin" to a list with slicin"
3o assi$n se7eral items in a ro0 to a list6 use a ran$e of inde8 numbers9
Assi$nin$ usin$ a slice follo0s these rules)
4ython first deletes the items currently assi$ned to those inde8 numbers and then
inserts the ne0 items9
Eou donCt ha7e to assi$n the same number of items that you delete9
Eou must assi$n an iterable see the sidebar6 I;otcha5 Assi$nin$ numbers and
strin$s to slicesI%9
3o assi$n items to a list slice6 follo0 these ste#s)
-9 Type the name of the list and, in brackets, type the slice notation, like this,
2" 3[/!.]
"9 (n the same line, type = and the items you want to assi"n.
--,
&f you assi$n items from another list6 your 0hole line mi$ht loo/ somethin$ li/e
this)
3[/!.] = [,spam,, ,spam,, ,spam,]
3he resultin$ list no0 loo/s li/e this)
[,spam,, ,spam,, ,spam,, ,spam,]
3he follo0in$ e8am#le mani#ulates a list of 0ords by usin$ slice assi$nment)
>>> 3 = [,spam,, ,eggs,, ,2am,, ,green eggs,]
>>> 3[!2] = )"don,t", "9ant"*
>>> 3
["don,t", ,9ant,, ,2am,, ,green eggs,]
>>> 3[2!] = )"green eggs", "and", "2am"*
>>> 3
["don,t", ,9ant,, ,green eggs,, ,and,, ,2am,]
-ist indexin" and slicin" operations
3he follo0in$ o#erations use the inde8in$ and slicin$ features of lists)
3o return the inde8 number of a list item6 use the index)* method9
&f the item isnCt in the list6 it raises a Wal-e6rror9
3his e8am#le returns the inde8 number of the second item in the list)
>>> mylist = [/, ,t9o,, 3]
>>> mylist"index),t9o,*
/
3o remo7e from a list the items% corres#ondin$ to the $i7en inde8 number or
slice6 use the /ey0ord del9
3his e8am#le deletes t0o items9
>>> mylist2 = [,(-sy signal,, ,fast (-sy signal,, ,no s-c2
n-m(er,, ,at t2e
tone, t2e time 9ill (e,]
>>> del mylist2[/!3]
>>> mylist2
[,(-sy signal,, ,at t2e tone, t2e time 9ill (e,]
3o insert an item before a #articular inde8 number6 use the insert)* method9
>>> (asAet"insert)%, ,peac2,*
>>> (asAet
[,peac2,, ,apple,, ,(anana,, ,orange,]
--*
3o remo7e and return an item at a #articular inde8 number6 use the pop)* method9
3he default inde8 number for pop)* is the last item in the list9 3his e8am#le
remo7es and returns the item ,(aAed (eans, in the list (reaAfast)
>>> (reaAfast = [,spam,, ,spam,, ,spam,, ,(aAed (eans,, ,spam,,
,spam,]
>>> (reaAfast"pop)3*
,(aAed (eans,
>>> (reaAfast
[,spam,, ,spam,, ,spam,, ,spam,, ,spam,]
3he follo0in$ code uses a 92ile loo# to return and delete all the list elements one
at a time)
>>> 92ile (reaAfast!
""" (reaAfast"pop)*
"""
,spam,
,spam,
,spam,
,spam,
,spam,
>>> (reaAfast
[]
!teerin" #lear of -ist +otcha's
3his section describes ho0 to a7oid some common list errors9
Siultaneous test9add9delete
&f youCre testin$ a list condition in a 92ile loo# or iteratin$ o7er a list in a for loo#6
a7oid addin$ and deletin$ list elements at the same time9 &tCs easy to lose trac/ of ho0 the
list is chan$in$9 An e8ce#tion is the use of pop)* in a 92ile loo# to remo7e all list
elements one by one9
List references that unexpectedly change
'ecause lists are mutable6 you can chan$e them 0ithout ma/in$ a co#y9 'ut if you
reference a sin$le list from se7eral #laces in your code6 it mi$ht chan$e 0hen you arenCt
e8#ectin$ it to9
!hallow copyin"
&f a container ob-ect an obFect>such as a list6 tu#le6 or dictionary>that holds other
obFects% contains lists6 then ma/in$ a co#y of the container obFect by usin$
ne9container = oldcontainer or ne9container = oldcontainer[!] doesnCt ma/e a
co#y of the lists it contains9 3he ne0 container continues to refer to the ori$inal lists9 3his
-20
is called shallo$ copying6 and 4ython uses it because amon$ other reasons% it sa7es
resources9 3he follo0in$ e8am#le illustrates shallo0 co#yin$9 3he larder list chan$es
0hen one of the lists inside the food list is chan$ed)
>>> (reaAfast = [,spam,, ,(aAed (eans,]
>>> (asAet = [,peac2,, ,apple,, ,goose(erries,]
>>> food = [(reaAfast, (asAet]
>>> larder = food
>>> larder
[[,spam,, ,(aAed (eans,], [,peac2,, ,apple,, ,goose(erries,]]
>>> del (asAet[%]
>>> larder
[[,spam,, ,(aAed (eans,], [,apple,, ,goose(erries,]]
:eep copyin"
3i# Sometimes you 0ant to ma/e a full6 or deep, co#y of a list or any item that contains
other items%9 3o do so6 im#ort the copy module and use the copy"deepcopy)*
function9 &n this e8am#le6 0hen you co#y the food list to the larder list by usin$ the
deepcopy)* function6 chan$in$ the contents of one of the lists in food doesnCt
chan$e the contents of larder9
>>> food
[[,spam,, ,(aAed (eans,], [,apple,, ,goose(erries,]]
>>> import copy
>>> larder = copy"deepcopy)food*
>>> larder
[[,spam,, ,(aAed (eans,], [,apple,, ,goose(erries,]]
>>> del (asAet[%]
>>> food
[[,spam,, ,(aAed (eans,], [,goose(erries,]]
>>> larder
[[,spam,, ,(aAed (eans,], [,apple,, ,goose(erries,]]
1isappearing lists
3he list methods append)* and sort)* chan$e a list in #lace but donCt return the list9
3hey return 1one9 DonCt use these methods in assi$nment statements or else the list mi$ht
disa##ear6 as in this e8am#le)
>>> 3 = ["my", "list"]
>>> 3 = 3"append),x,* + 9rong!
>>> print 3
1one
3o a##end to a list6 Fust use the append)* method by itself9 DonCt $i7e the result a name9
>>> 3 = ["my", "list"]
>>> 3"append),x,*
>>> print 3
[,my,, ,list,, ,x,]
-2-
That tricky asterisk
&f you re#eat ;% a list6 you $et a list 0ith multi#le co#ies of its elements9 'ut if you
re#eat ;% a list containing a list6 you $et multi#le shallo0 co#ies of the contained list9
3he follo0in$ e8am#les demonstrate both re#eatin$ a list and re#eatin$ a list that
contains a list)
A re#eated list)
>>> mylist = [3, ,(lind,, ,mice,]
>>> x = mylist ; 2
>>> x
[3, ,(lind,, ,mice,, 3, ,(lind,, ,mice,]
De#eatin$ a list containing a list)
>>> y = [mylist] ; 2
>>> y
[[3, ,(lind,, ,mice,], [3, ,(lind,, ,mice,]]
&n the #recedin$ e8am#les6 if you chan$e mylist6 the 7alue of y chan$es because y
contains references to mylist9 'ut the 7alue of x doesnCt chan$e because x only contains
co#ies of the elements of mylist9 <ereCs 0hat ha##ens)
We chan$e the first element of mylist)
>>> mylist[%] = ,t9o,
<ereCs the result)
y reflects the ne0 7ersion of mylist)
>>> y
[[,t9o,, ,(lind,, ,mice,], [,t9o,, ,(lind,, ,mice,]]
x doesnCt chan$e)
>>> x
[3, ,(lind,, ,mice,, 3, ,(lind,, ,mice,]
Perforance probles
Mani#ulatin$ lar$e lists can cause #erformance #roblems9 <ereCs ho0 to a7oid these
#roblems)
Avoid copyin" lon" lists.
For e8am#le6 a7oid usin$ loo#s that delete elements from the be$innin$ of a list
del mylist[%] or mylist"pop)%*% because doin$ so reGuires 4ython to ma/e
multi#le co#ies of the list9
Avoid makin" multiple copies of the elements of a list.
-22
:o#yin$ the list itself doesnCt ta/e a lot of time6 but co#yin$ the elements does9
Build lists when you need them. 4o#ulatin$ a list 0ith elements before you need
the list isnCt necessary6 and it mi$ht e7en 0aste memory9
Buildin" -ists, !tacks, and Iueues
3his section describes t0o often1used list tas/s) buildin$ a list one element at a time and
buildin$ stac/s and Gueues9
Building lists increentally
'ecause lists are mutable6 you can build them one element at a time9 &t is often useful to
build lists from other iterable obFects or to combine multi#le lists9 3he easiest 0ay of
doin$ this is to 0rite a for loo# and build the ne0 list 0ith the append)* method6 as in
the follo0in$ e8am#le)
3/ = [,spam,, ,spam,, ,spam,, ,(aAed (eans,, 1one, ,spam,, ,spam,]
32 = []
for i in 3/!
if i is not 1one!
32"append)i*
After you run the abo7e code6 the 7alue of 32 is ["spam", "spam", "spam", "(aAed
(eans", "spam", "spam"]9
Warnin$ &f youCre iteratin$ o7er a list in a for loo#6 itCs best not to add elements to or
delete elements from that list>doin$ so can introduce errors9 &tCs safer to use
code li/e the abo7e e8am#le to build a ne$ list and then chan$e the elements of
the ne0 list9
4ython #ro7ides se7eral other tools for buildin$ lists)
3o con7ert or co#y seGuences and other iterable obFects% to a list6 use the list)*
function described earlier in this cha#ter%9
Another 0ay to co#y a 0hole list or other seGuence and return a shallo0 co#y is
to use this slice notation) mylist[!]
4ython includes a feature called a list comprehension, 0hich 0or/s in much the
same 0ay as a list1buildin$ for loo# but is #ac/a$ed more com#actly9 See
:ha#ter -6 to find out about this ad7anced feature9%
3o loo# o7er t0o or more seGuences at the same time6 use the Qip)* function9 &t
returns a list of tu#les that associates the items in one seGuence 0ith the
corres#ondin$ items in another seGuence9 &t also truncates the resultin$ list to the
len$th of the shortest seGuence9
-2"
>>> a = [', 3, &, //]
>>> ( = ),eggs,, ,spam,*
>>> c = Qip)a, (*
>>> print c
[)', ,eggs,*, )3, ,spam,*]
&f you use Qip)* a$ain 0ith the ;args style #arameter6 you $et a list of tu#les that
corres#ond to the ori$inal seGuences you started 0ith but any items that 0ere
truncated are missin$%9
3i# 3he ;args style ar$ument is e8#lained in :ha#ter --9
<ereCs 0hat it could loo/ li/e)
>>> Qip);c*
[)', 3*, ),eggs,, ,spam,*]
3o $et tu#les of list inde8 numbers and their elements6 use the en-merate)*
iterator9
>>> a = [', 3, &, //]
>>> for G, item in en-merate)a*!
""" print )G, item*,
"""
)%, '* )/, 3* )2, &* )3, //*
Stacking and 3ueuing &ith lists
,tacks and 7ueues are conce#ts that describe ho0 items $et added to and remo7ed from
lists9 Stac/s and Gueues are not 4ython obFects6 but you can 0rite code in 0hich a list
beha7es li/e a stac/ or a Gueue9
A stack is li/e a s#rin$1loaded #late dis#enser 0here the last item on is the first item off
this is also called Ilast in6 first outI order6 0hich is inscribed in the ;reat 'oo/ of ;ee/y
Acronyms as I.&FMI%9 A Gueue6 as fol/s familiar 0ith 'ritish @n$lish /no06 is li/e a line
at a store chec/out counter) 3he first #erson in is the first ser7ed also called Ifirst in6 first
out6I or IF&FMI%9
Addin" items to a stack
3o add an item to the to# of a stac/6 use append)*9
3his e8am#le #uts si8 #lates on the #ile)
>>> plates = []
>>> for p in range)<*!
""" plates"append)p*
"""
>>> plates
-2!
[%, /, 2, 3, ., &]
/etrievin" items from a stack
3o retrie7e an item from the to# of a stac/6 use pop)* 0ithout an ar$ument so it defaults
to the last item in the list%9
3o retrie7e all the items6 use pop)* in a 92ile loo#9 ;et the #lates off the #ile6 last1on6
first1off6 li/e this)
>>> 92ile plates!
""" plates"pop)*
"""
&
.
3
2
/
%
Iueuin" up
3o use a list as a Gueue to #rocess items Iin the order in 0hich they 0ere recei7edI
anyone 0ho has tried to tal/ to a lar$e com#any on the tele#hone 0ill be familiar 0ith
that #hrase%6 follo0 these ste#s)
-9 &se append)* to add an item to the end of the =ueue.
&n the follo0in$ e8am#le6 0e create an em#ty list and then a##end si8 callers to it)
>>> callers = []
>>> for c in range)<*!
""" callers"append)c*
"""
>>> callers
[%, /, 2, 3, ., &]
29 &se pop)%* in a 92ile loop to retrieve an item from the front of the =ueue,
like this,
3" >>> 92ile callers!
." """ callers"pop)%*
&" """
<" %
E" /
'" 2
=" 3
/%".
//"&
Warnin$ 3o a7oid #erformance #roblems6 donCt use pop)%* 0ith a lar$e list more
than about -00 elements%9
-2A
Takin" Tuples in Hand
3his section describes some 0ays to 0or/ 0ith tu#les9 We co7er con7ertin$ other obFects
to tu#les6 se7eral 0ays of creatin$ tu#les6 usin$ tu#les to s0a# 7alues6 and efficiently
$i7in$ names to indi7idual items in tu#les9
#on$erting another ob'ect to a tuple
3o con7ert another iterable obFect to a tu#le6 use the t-ple)* function)
>>> mylist = [/, 2, 3]
>>> t-ple)mylist*
)/, 2, 3*
D@M@M'@D &f you con7ert a list to a tu#le6 remember that the ne0 tu#le cannot be
chan$ed9
Tuple packing
&f you ty#e some names se#arated by commas6 you create a tu#le9 3his is called tuple
packing. &t 0or/s on either side of an assi$nment statement9
3he follo0in$ e8am#le creates a tu#le containin$ t0o strin$s)
>>> N = ,(la2, (la2, (la2,
>>> r = ,SG1S6B,
>>> 92at$t2ey$2ear = N, r
>>> print 92at$t2ey$2ear
),(la2, (la2, (la2,, ,SG1S6B,*
3o create a tu#le containin$ more than t0o items6 Fust use multi#le comma o#erators9
3his e8am#le creates a tu#le containin$ four strin$s9
>>> N, r, N, r
),(la2, (la2, (la2,, ,SG1S6B,, ,(la2, (la2, (la2,, ,SG1S6B,*
Tuple unpacking
)npacking a tuple means $i7in$ a different name to each element of the tu#le9
3u#le un#ac/in$ is useful because many functions in 4ython6 such as the Qip)* function
described in the #re7ious I'uildin$ lists incrementallyI section6 return tu#les9 With tu#le
un#ac/in$6 you can easily $et at the indi7idual items in these tu#les9
3o unpack a tu#le6 Fust assi$n multi#le names on a sin$le line9 4ut the names you 0ant to
un#ac/ into on the left side of the assi$nment statement and #ut the tu#le on the ri$ht
side9 Eou need one name for each item in the tu#le9
-26
3he follo0in$ e8am#le un#ac/s a tu#le consistin$ of three lists)
>>> x = [),rocA cr-s2es,, ,scissors,*, ),paper co5ers,, ,rocA,*,
),scissors
c-t,, ,paper,*]
>>> rocA, paper, scissors = x
>>> print rocA
),rocA cr-s2es,, ,scissors,*
&f you donCt ha7e the same number of names as tu#le items6 you $et a Wal-e6rror6 as
sho0n here)
>>> rocA, paper = x
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
Wal-e6rror! too many 5al-es to -npacA
3i# Eou can actually un#ac/ any seGuence obFect in this 0ay9 3he follo0in$ e8am#le
un#ac/s a strin$)
>>> x = ,string,
>>> a, (, c, d, e, f = x
>>> a
,s,
>>> print a, (, c, d, e, f
s t r i n g
<o0e7er6 un#ac/in$ is most commonly used 0ith tu#les because there are better 0ays to
$et elements out of strin$s and lists9
)sing a tuple to s&ap $alues
'ecause of the s#ecial 0ay assi$nments 0or/ 0ith tu#les6 tu#les are the Pythonic 0ay of
s0a##in$ 7alues9
3his e8am#le s0a#s the 7alues associated 0ith t0o names)
>>> N = ,(la2, (la2, (la2,
>>> r = ,SG1S6B,
>>> N, r
),(la2, (la2, (la2,, ,SG1S6B,*
>>> N, r = r, N
>>> N, r
),SG1S6B,, ,(la2, (la2, (la2,*
-2+
#hapter J, :ivin" into :ictionaries
(verview
&n this cha#ter6 0e discuss dictionaries dicts for short% and sets6 t0o data ty#es that store
multi#le data elements9 <ere are some of the thin$s you can disco7er in this cha#ter)
What dictionaries and sets are and ho0 they differ from seGuences
Some of the most useful dictionary tools and set o#erations
<o0 to con7ert other ty#es of data into dictionaries and sets
Dictionaries are useful in the follo0in$ $eneral and s#ecific circumstances)
When you need random access to elements9
When you 0ant to focus on uniGueness9
'ut consider usin$ sets if you are usin$ 4ython 29" or later9 See ISettin$ 3hem
?#6I later in this cha#ter9
For ma##in$ se7eral s#ellin$s of a term to a #referred s#ellin$9
For usin$ a /ey to find a function to call /no0n as a dispatch table%9
For loo/in$ u# zi# codes or ban/ account numbers9
For 0or/in$ 0ith numeric inde8es 0ith only a fe0 nonconti$uous /eys6 0hen you
donCt need to use slicin$9
3@:<(&:A.
S3?FF
Data that fits the #recedin$ descri#tion is called sparse data9
Eou can also use a list in this case6 but a dict is more
memory1efficient6 0hich often ma/es thin$s faster9
:efinin" the :ictionary
<ereCs ho0 dictionaries dicts% com#are and contrast 0ith other 4ython data ty#es)
:ictionaries are a container type that stores data, like lists and tuples.
:ictionaries are a mapping data type 9 indexed by keys.
A dictionaryCs elements the items it contains% are /ey)7alue #airs9 &n contrast6 lists
and tu#les store data by usin$ numeric inde8es they are se7uence data types% and
su##ort inde8in$ and slicin$9
:ictionaries are mutable.
-2,
3hat means a dictionary can be modified in #lace>you donCt ha7e to create a
co#y of it to modify it as you do 0ith strin$s and tu#les%9
However, a dict's keys must be immutable.
#reating a dictionary
3he sim#lest dictionary is a #air of braces {}%6 0hich defines an empty dict9
D@M@M'@D 3o create a dictionary 0ith some data in it6 follo0 these ste#s)
-9 Type a left brace, a key, a colon, and a value 5the information
you want to associate with the key6, like this,
2" {"parrot"! "Cining for fTords"
3he /ey can be any immutable data ty#e6 such as a strin$ or
inte$er9 Most /eys are strin$s9 3he 7alue can be any data ty#e9
"9 'or each additional element in the dictionary, type a comma to
separate it from the previous value and then type another key,
a colon, and a value,
." {"parrot"! "Cining for fTords", "Colly"! "6x7parrot"
A9
3i# De#eat Ste# 2 for each element you 0ant to add9
To end
the dictionary, type a ri"ht brace, }
&f you added t0o elements6 your dictionary loo/s somethin$ li/e
this)
{"parrot"! "Cining for fTords", "Colly"! "6x7parrot"*
3@:<(&:A.
S3?FF
Hash strin"s or hash brownsC
Some other lan$ua$es ha7e dictionary structuresH they are called
thin$s li/e hashes, associative memories, or associative arrays. We
thin/ dictionaryis a friendlier term.
Dict /eys must be immutable because 4ython associates them 0ith a
uniGue number called a hash9 A hash 7alue or hash% is historically a
number $enerated from a strin$ of te8t9 'ecause the number and
strin$ #air are uniGue6 hashes #re7ent #roblems that mi$ht occur if
t0o different obFects ha7e the same 7alue9
<ashes are used for s#ace1efficient stora$e6 for security and
cry#to$ra#hy6 and so on9 Another benefit of hashin$ is that after the
hash is com#uted6 /eys can be loo/ed u# directly>thereCs no need
for the com#uter to search throu$h a 0hole list of /eys9 &n human
terms6 hashes hel# a com#uter be smart in the same 0ay a human is
-2*
smart 0hen she /no0s to Fum# to the end of a #hysical dictionary to
loo/ u# a term that starts 0ith 8.% &n 4ython6 this feature ma/es
dictionaries 7ery fast9
&n 4ython6 most immutable obFects ha7e a hash6 and the attributes of
all names#ace obFects are stored in dictionaries9
3@:<(&:A.
S3?FF
Some details about dictionary /eys)
=eys must be an immutable data ty#e>for e8am#le6 a strin$6
inte$er6 or tu#le9
&f you use a tu#le as a /ey6 the tu#le cannot ha7e any mutable
elements9
For e8am#le6 you canCt use a tu#le that contains a list9
Eou can ty#e a /ey directly into the dictionary6 or you can
ty#e the name of an obFect6 li/e this)
>>> x = "mydictAey"
>>> mydict = {x! "mydict5al-e"}
0rder in the dict
4ython doesnCt store dictionary elements in any #articular order9 &f you enter elements in
one order6 they may be stored in another essentially random% order inside 4ython9 <ereCs
an e8am#le)
>>> l-m(erTacA = {,sleep,! "Lll nig2t", ,9orA,! "Lll day"}
>>> l-m(erTacA
{,9orA,! ,Lll day,, ,sleep,! ,Lll nig2t,}
3he ste#s to ma/e a sorted list of dictionary /eys de#end on your 4ython 7ersion9
ython 7.A and later
&f you ha7e 4ython 29! or later6 follo0 these ste#s to $et a sorted usually al#hanumeric%
list of the /eys of a dictionary)
-9 Type a list name and = sorted6 followed by the name of your dict in
parentheses, like this,
2" >>> sorted$Aeys = sorted)l-m(erTacA*
"9 To see the sorted list of keys, type the name of the list.
." >>> sorted$Aeys
&" [,sleep,, ,9orA,]
-"0
2arlier versions
&f you ha7e 4ython 29" or earlier6 follo0 these ste#s to $et a sorted list of the /eys of a
dictionary)
-9 Type a name, an = si"n, the name of your dict, and "Aeys)*6 like so,
2" >>> list$of$Aeys = l-m(erTacA"Aeys)*
"9 &se the sort)* method to sort the list by typin" this on the next line,
substitutin" the name you created in !tep . for list$of$Aeys)
." >>> list$of$Aeys"sort)*
A9 Type the list name a"ain to see the sorted list of keys, like this,
<" >>> list$of$Aeys
E" [,sleep,, ,9orA,]
Warnin$ DonCt try to $i7e a name to the result of list$of$Aeys"sort)*9 3he sort)*
method chan$es the list in #lace but returns 1one6 not a list to find out more
about list methods and 0hat they return6 see :ha#ter ,%9
:oodlin" Around with :icts
3his section describes some of the common tas/s you can do 0ith dicts6 such as storin$6
e8tractin$6 addin$6 deletin$6 and searchin$ for /eys and 7alues9
Popular dict operations
3he main o#erations for a dictionary are storin$ a /ey and its associated 7alue and usin$
the /ey to e8tract the 7alue9
!torin" a value
3o store a /ey)7alue #air in an e8istin$ dictionary6 follo0 these ste#s)
-9 Type the name of the dict and a key in s=uare brackets, like this,
2" >>> mydict[,drac-la,]
D@M@M'@D 3he /ey can be ne0 or it can be a /ey thatCs already in the
dictionary9 &f you use an e8istin$ /ey6 the ne0 7alue re#laces the
old one9
"9 Type = and the value you want to store.
Eour line of code mi$ht loo/ li/e this)
>>> mydict[,drac-la,] = ,stoer,
3he follo0in$ e8am#le code creates a dictionary and then creates a ne0 /ey6 ,drac-la,6
and $i7es it the 7alue ,stoAer,)
>>> mydict = {,Ta((er9ocAy,! ,carroll,, ,s2erlocA 2olmes,! ,doyle,}
>>> mydict[,drac-la,] = ,stoAer,
-"-
>>> mydict
{,Ta((er9ocAy,! ,carroll,, ,drac-la,! ,stoAer,, ,s2erlocA 2olmes,!
,doyle,}
<ere6 the e8istin$ /ey ,drac-la, is $i7en a ne0 7alue6 ,oldman,)
>>> mydict[,drac-la,] = ,oldman,
>>> mydict
{,Ta((er9ocAy,! ,carroll,, ,drac-la,! ,oldman,, ,s2erlocA 2olmes,!
,doyle,}
2xtractin" a value
3here are t0o 0ays of e8tractin$ a 7alue based on a dictionary /ey9 3he best o#tion
de#ends on a cou#le of factors)
&f youCre certain the /ey is in the dictionary6 or if you 0ant to raise a Xey6rror
e8ce#tion 0hen the /ey is not in the dictionary6 use the sGuare brac/ets synta89
&f many of the /eys youCre searchin$ for arenCt in the dictionary6 or if you 0ant
4ython to return a 7alue you s#ecify rather than raise an e8ce#tion 0hen /eys
arenCt found6 use the get)* method9
#o raise an exeption on %ailure
&f you 0ant to raise an e8ce#tion if the /ey youCre searchin$ for doesnCt e8ist6 ty#e the
name of the dict follo0ed by a /ey in sGuare brac/ets6 li/e this)
>>> mydict[,Tane eyre,]
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
Xey6rror! ,Tane eyre,
#o return a value you spei%y on %ailure
3o return a default 7alue if the /ey doesnCt e8ist6 follo0 these ste#s)
-9 Type the name of the dict, a dot, get)6 and a key.
Eour code mi$ht loo/ li/e this)
>>> mydict"get),Tane eyre,
29 5(ptional6 Type a comma and a strin" you want to return if the key doesn't
exist.
&f you donCt s#ecify a strin$6 the default 7alue 1one is returned9
>>> mydict"get),Tane eyre,, ,Aey not fo-nd,
-"2
"9 2nd the line by typin" a ri"ht parenthesis, *
Eour com#leted line of code 0ill loo/ somethin$ li/e this if the /ey doesnCt e8ist)
>>> mydict"get),Tane eyre,, ,Aey not fo-nd,*
,Aey not fo-nd,
%inding out about dict ethods
Dictionaries come 0ith built1in methods that allo0 you to #erform the follo0in$ tas/s)
Detrie7e items from dicts by usin$ items)*6 Aeys)*6 and 5al-es)* methods9
?se dicts in loo#s 0ith iterAeys)*6 iter5al-es)*6 and iteritems)* methods9
3est 0hether a /ey is in a dict by usin$ the in /ey0ord9
Delete items from dicts by usin$ the del /ey0ord and the popitem)* and pop)*
methods9
Ma/e shallo0 co#ies of dicts by usin$ the copy)* method9
Add items to dicts by usin$ the setdefa-lt)* method9
/etrievin" items from dicts
3he Aeys)*6 5al-es)*6 and items)* methods are $ood for list1#rocessin$ o#erations
usin$ the contents of dictionaries9 3he pop)* and popitem)* methods retrie7e and delete
thin$s at the same time6 so theyCre $ood for #rocessin$ a tem#orary dictionary you donCt
need to /ee# or for #rocessin$ items one at a time until there arenCt any more9
items&'
3he items)* method retrie7es all the /ey)7alue #airs in a dictionary and returns them as
a list of tu#les9 @ach /ey)7alue #air is a tu#le9
3o retrie7e all the items in a dictionary6 ty#e the name of the dictionary6 a dot6 and
items)*)
>>> mydict = {,(ed price,! ,'%% po-nds,, ,(ed lengt2,! ,2 feet long,}
>>> print mydict"items)*
[),(ed lengt2,, ,2 feet long,*, ),(ed price,, ,'%% po-nds,*]
keys&'
3he Aeys)* method retrie7es all the /eys in the dictionary9 &t returns a list6 as sho0n
here)
>>> print mydict"Aeys)*
[,(ed lengt2,, ,(ed price,]
values&'
-""
3he 5al-es)* method retrie7es all the 7alues in the dictionary9 &t returns a list6 as sho0n
here)
>>> print mydict"5al-es)*
[,2 foot long,, ,'%% po-nds,]
popitem&'
3o retrie7e a sin$le /ey)7alue #air and remo7e it from the dict6 use the popitem)*
method6 li/e this)
>>> mydict"popitem)*
),(ed lengt2,, ,2 foot long,*
3i# Eou canCt use popitem)* to s#ecify 0hich /ey)7alue #air to retrie7e9 &tCs most often
used in a 92ile loo# 0hen you 0ant to #rocess items one at a time until there arenCt
any more but you donCt care 0hat order theyCre #rocessed in9
3@:<(&:A.
S3?FF
3he popitem)* method 0as added in 4ython 29-9
pop&'
3o remo7e a /ey)7alue #air and retrie7e only the 7alue6 use the pop)* method and #ass
the /ey in the #arentheses6 li/e this)
>>> mydict"pop),(ed price,*
,'%% po-nds,
+ettin" loopy with dicts
Eou can use a dictCs /eys6 7alues6 or /ey)7alue #airs in a loo#9 3his is called iterating
over the items9
3@:<(&:A.
S3?FF
3he Aeys)*6 5al-es)*6 and items)* methods also 0or/ in loo#s6
but the iterator methods are more efficient9
<ere are se7eral 0ays of loo#in$ 0ith a dict9
(eys
3o iterate o7er /eys in 4ython 292 and later6 create a for statement 0ith the follo0in$
synta86 substitutin$ the name of your dictionary you can also use a different name for the
iterator6 althou$h Aey is standard for keys%)
for Aey in mydict!
3@:<(&:A.
S3?FF
3he #recedin$ code 0or/s only in 4ython 292 and later9 &t is
eGui7alent to the follo0in$ in earlier 7ersions)
-"!
for Aey in mydict"Aeys)*!
)alues
3o iterate o7er 7alues6 use this synta8 in the for statement)
for 5al-e in mydict"iter5al-es)*!
(ey:value pairs
3o iterate o7er /ey)7alue #airs6 use the follo0in$ synta8)
for Aey, 5al-e in mydict"iteritems)*!
Testin" a dict
<o0 you test 0hether a sin$le /ey a##ears in the dict de#ends on your 7ersion of 4ython9
Eou mi$ht 0ant to do this if6 for e8am#le6 you 0anted to see if a customer number 0as
in your dictionary9%
Python *.* and newer
3o chec/ 0hether a sin$le /ey is in the dictionary6 use the /ey0ord in 0ithin an if
statement6 li/e this)
if ,(ed price, in mydict!
+lder versions
&f you are usin$ 4ython 29- or earlier6 use the 2as$Aey)* method instead)
if mydict"2as$Aey),(ed price,*!
:eletin" items from a dict
Eou can delete a s#ecific /ey)7alue #air from a dict by usin$ the del /ey0ord9 &f youCre
0or/in$ 0ith the dict in a loo# and doin$ somethin$ 0ith the dict data6 usin$ pop)* or
popitem)* is more efficientH they return and delete elements at the same time9
(ey:value
3o delete a /ey)7alue #air from a dictionary6 use the del /ey0ord and $i7e the /ey in
sGuare brac/ets9 For e8am#le)
del mydict[,(ed price,]
Individual elements
-"A
3o delete elements from a dict one at a time in a loo#6 use either of these methods6
de#endin$ on 0hether you 0ant the /ey)7alue #air or Fust the 7alue returned)
popitem)*) 3he popitem)* method returns the key9value pair and deletes the
#air from the dict9
92ile mydict!
Aey, 5al-e = mydict"popitem)*
pop)*) 3he pop)* method returns the value and deletes the /ey)7alue #air from
the dict9
for Aey in mylist!
if Aey in mydict!
5al-e = mydict"pop)Aey*
,ll elements
3o delete all the elements of a dict at once6 use the clear)* method9 3his remo7es all the
elements at once lea7in$ an em#ty dict% and returns 1one)
mydict"clear)*
4akin" a shallow copy of a dict
3o ma/e a shallo0 co#y of a dict6 use the copy)* method9
mycopy = mydict"copy)*
See the sidebar6 I?nderstandin$ shallo0 co#ies6I to find out more about shallo0 co#ies
of dicts9
+et or set, Addin" items to a dict
3he setdefa-lt)* method 4ythonistas call it get or set% is li/e get)*6 0hich e8tracts a
7alue by usin$ a /ey9 'ut setdefa-lt)* $oes one ste# further) &f the /ey is not found6 it
adds the /ey to the dict9
&nderstandin" shallow copies
3o understand shallo0 co#ies6 you need to /no0 somethin$ about ho0 4ython stores
information9 When you $i7e a name to an obFect such as a list that stores some 7alues6
4ython creates a reference the name% to that obFect the stored 7alues%9
>>> mylist = [,my,, ,list,]
(o06 say you create a dictionary that contains this list)
>>> mydict = {,myn-m(er,! /, ,alist,! mylist, ,myt-ple,! )/,2*}
-"6
&f you loo/ at the dict6 it loo/s li/e the 7alues stored in the list are stored in the dict6 too)
>>> mydict
{,myt-ple,! )/, 2*, ,alist,! [,my,, ,list,], ,myn-m(er,! /}
'ut in fact the dictionary is not storin$ the actual 7alues stored in the list9 &t is only
storin$ the reference to the list9
3hat means6 if you chan$e the listS
>>> mylist"append),c2anged,*
S your dict also chan$es9
>>> mydict
{,myt-ple,! )/, 2*, ,alist,! [,my,, ,list,, ,c2anged,], ,myn-m(er,! /}
When you ma/e a shallo0 co#y of somethin$6 you co#y only the references6 not the
actual 7alues that the references #oint to9 So if you ma/e a co#y of a dict by usin$ the
copy)* method6 the co#y reflects any chan$es made to the list that the dictionary is
referrin$ to9
>>> mycopy = mydict"copy)*
>>> mycopy
{,myt-ple,! )/, 2*, ,alist,! [,my,, ,list,, ,c2anged,], ,myn-m(er,! /}
3o ma/e a co#y of the actual 7alues so that these chan$es donCt occur6 im#ort the copy
module and use the deepcopy)* function9 See :ha#ter ,9
3he standard use for setdefa-lt)* is for addin$ a list or other mutable data ty#e% to the
dict and a##endin$ items to the list9 <ereCs ho0 the synta8 loo/s)
mydict"setdefa-lt)Aey, []*"append)5al-e*
<ereCs 0hat ha##ens)
-9 &f the /ey isnCt in the dict6 4ython adds the /ey and uses an em#ty list as the 7alue9
3hen it a##ends the 7alue you s#ecified to the list9
29 &f the /ey is in the dict6 4ython tries to a##end your 7alue to that /eyCs 7alue9 For
this to 0or/6 the 7alue must be a list because the append)* method 0or/s only
0ith lists9%
D@M@M'@D &f you donCt s#ecify a 7alue6 the 7alue 1one is used9
3he follo0in$ code creates a /ey6 /36 and #airs it 0ith a 7alue of an em#ty list9 3hen it
a##ends the strin$ ,complaints, to the list)
-"+
>>> rooms = {,/2L,! [,arg-ment clinic,], /2! [,a(-se,]}
>>> rooms"setdefa-lt)/3, []*"append),complaints,*
>>> rooms
{,/2L,! [,arg-ment clinic,], /2! [,a(-se,], /3! [,complaints,]}
3he follo0in$ code a##ends the strin$ ,don,t (ot2er, to the list that has the /ey /39
>>> rooms"setdefa-lt)/3, []*"append)"don,t (ot2er"*
>>> rooms
{,/2L,! [,arg-ment clinic,], /2! [,a(-se,], /3! [,complaints,, "don,t
(ot2er"]}
3he follo0in$ synta8 does the same thin$ 0ith a set9
mydict"setdefa-lt)Aey, sets"@et)**"add)5al-e*
Buildin" :ictionaries
&n 4ython6 most com#ound data obFects are created by #rocessin$ data in a loo# structure6
so youCll often build lists6 dictionaries6 and so on by 0ritin$ loo#s9 Follo0in$ are some
loo#y and non1loo#y 0ays of buildin$ dicts9
#on$erting other data types into a dict
Eou ha7e se7eral 0ays to con7ert other data ty#es into dicts9 3his section sho0s the
dict)* constructor6 the fromAeys)* method6 and a for loo#9
#onvertin" a list of tuples
3o con7ert a list of t0o1item tu#les or any iterable containin$ t0o1item iterables% to a
dict6 #ass the list to the dict)* method li/e this)
>>> list$of$t-ples = [),spam,, /*, ),eggs,, ,green,*]
>>> dict)list$of$t-ples*
{,eggs,! ,green,, ,spam,! /}
#onvertin" a se=uence
3o create a dict from a list or tu#le and an o#tional ma##in$ 7alue6 use the fromAeys)*
method9 3his 0or/s in 4ython 29" or later9% 3he items in the seGuence become the /eys6
and the ma##in$ 7alue 1one by default% is used for the 7alues9 &n this e8am#le6 each item
in the list is turned into a /ey and $i7en the 7alue ,(reaAfast,)
>>> mylist = [,spam,, ,eggs,, ,orange T-ice,]
>>> print dict"fromAeys)mylist, "(reaAfast"*
{,eggs,! ,(reaAfast,, ,orange T-ice,! ,(reaAfast,, ,spam,! ,(reaAfast,}
-",
Eou can do the same thin$ by usin$ the dict)* constructor and a list comprehension a
line of code that creates a list from a ran$e of items%9
>>> dict)[)i, ,(reaAfast,* for i in mylist]*
{,eggs,! ,(reaAfast,, ,orange T-ice,! ,(reaAfast,, ,spam,! ,(reaAfast,}
3i# &f you 0onCt be 0or/in$ 0ith 7alues later6 consider creatin$ a set rather than a dict9 A
set has only /eys6 no 7alues9 3o create a set from a list or tu#le6 Fust ty#e set)* and
include the list or tu#le in #arentheses9 For more information6 see ISettin$ 3hem
?#6I later in this cha#ter9
3o create a dict from a t0o1element iterable6 you can also use a list com#rehension9 3his
code builds a dict of #o0ers of 2)
>>> dict)[)x, x;;2* for x in )2, ., <*]*
{2! ., .! /<, <! 3<}
Eou can $et the lo0do0n on list com#rehensions in :ha#ter -69
Buildin" a dict with keyword ar"uments
&n 4ython 29" and later6 you can #ass /ey0ord ar$uments ;;A9args% to the dict)*
method and build a dictionary6 li/e this)
>>> sacA = dict)cats=E, Aits=E*
>>> sacA
{,Aits,! E, ,cats,! E}
For more about ;;A9args6 see :ha#ter --9
Buildin" a dict out of another dict by usin" a for loop
3o $o throu$h a dict 0hile buildin$ a second one6 use a for loo# and assi$n each #air in
the old dict to the ne0 dict6 li/e this)
>>> mydict = {,(ed price,! ,'%% po-nds,, ,(ed lengt2,! ,2 foot long,}
>>> ne9dict = {}
>>> for Aey in mydict!
""" 5al-e = mydict[Aey]
""" ne9dict[Aey] = 5al-e
"""
>>> ne9dict
{,(ed lengt2,! ,2 foot long,, ,(ed price,! ,'%% po-nds,}
3@:<(&:A.
S3?FF
&n 4ython 29- and earlier6 the in /ey0ord doesnCt 0or/ 0ith a
dictionary obFectH you need to use it 0ith a dictionary method9 So to
0rite the abo7e loo#6 you could use this synta8)
for Aey, 5al-e in mydict"items)*!
-"*
)pdating a dictionary
3o re#lace the 7alues in a dictionary 0ith ne0 7alues6 use the -pdate)* method9 3he ne0
/ey)7alue #airs can come from either another dictionary or other ma##in$ obFect% or an
iterable of key9value pairs such as a list of t0o1 item tu#les%9
3@:<(&:A.
S3?FF
3he iterable /ey)7alue% o#tion reGuires 4ython 29! or later9
Eou can also re#lace 7alues by usin$ /ey0ord ar$uments6 as in this e8am#le)
>>> rooms = {,/2L,! ,arg-ment clinic,, /2! ,a(-se,}
>>> rooms"-pdate)L/.=,2it on t2e 2ead lessons,*
>>> rooms
{,/2L,! ,arg-ment clinic,, /2! ,a(-se,, ,L/.,! ,2it on t2e 2ead
lessons,}
<ereCs code that u#dates one dict by usin$ /ey)7alue #airs from a second dict9 &f a /ey
a##ears in both dicts6 the second dictCs 7alues o7er0rite the first dictCs 7alues9 3he second
dict is not modified9
>>> rooms2 = {,L/.,! ,canceled (y >lying >ox,}
>>> rooms"-pdate)rooms2*
>>> rooms
{,/2L,! ,arg-ment clinic,, /2! ,a(-se,, ,L/.,! ,canceled (y >lying >ox,}
*hen (nly a :ict *ill :o
3his section $i7es brief e8am#les of some real10orld uses for dicts6 includin$ a $ame that
retrie7es 7alues associated 0ith /eys6 a cache for storin$ freGuently used items6 and a
0ay of findin$ du#licate /eys9
Storing and retrie$ing $alues
A dict is useful for storin$ and retrie7in$ immutable obFects and corres#ondin$ 7alues6
li/e #roduct #rices6 for e8am#le9 <ereCs a small $ame that uses a dict for this #ur#ose)
c2oice = ra9$inp-t)"H2oose scissors, rocA, or paper! "*
res-lts = {"scissors"! "c-t paper", "rocA"! "cr-s2es scissors",
"paper"! "co5ers
rocA"}
print c2oice, res-lts[c2oice]
<ereCs one round of the $ame)
H2oose scissors, rocA, or paper! paper
paper co5ers rocA
-!0
Eou can also use if8elif8else statements for this #ur#ose see :ha#ter -0%6 but a
dictionary is often better because itCs built 0hen a #ro$ram first runs 0hich is more
efficient% and itCs easier to read if a lot of /ey)7alue #airs are in7ol7ed9 &tCs also easier to
maintain and modify9
)sing a dict as a cache
&f youCre usin$ a for loo# to #rocess some items6 a dict can store the results for reuse9
3his ty#e of stora$e is called a cache. 3here are t0o 0ays to 0rite cachin$ code9 3he one
you use de#ends on 0hether youCre #rocessin$ a lot of different items or mostly multi#le
co#ies of similar items9
3i# 3he follo0in$ e8am#les refer to a function called getWal-e)*9 3his isnCt a function
built in to 4ythonH youCll ha7e to 0rite it yourself9
:ifferent items
&f many uniGue items #robably 0onCt be in the dict6 0rite code li/e this)
res-lt = []
cac2e = {}
for Aey in mylist!
if Aey in cac2e!
res-lt"append)cac2e[Aey]*
else!
5al-e = getWal-e)Aey*
cac2e[Aey] = 5al-e
res-lt"append)5al-e*
3i# We use a cache because the getWal-e)* function is e8#ensi7e that is6 it ta/es a lot
of time%9 <o0e7er6 you should a7oid o#timizin$ code 0hen you donCt need to>it
ma/es code harder to read9
!imilar items
3he follo0in$ code is efficient if youCre #rocessin$ many similar items6 but itCs harder to
read)
res-lt = []
cac2e = {}
for Aey in mylist!
if Aey in cac2e!
res-lt"append)cac2e[Aey]*
else!
+ Ldd to cac2e and append to res-lt
res-lt"append)cac2e"setdefa-lt)Aey, getWal-e)Aey***
3i# &f you thin/ that the /eys 0ill almost al0ays be in the dict6 the follo0in$ is e7en
more efficient9 3hatCs because try bloc/s ta/e 7ery little time if an e8ce#tion isnCt
raised6 but e8ce#tions ta/e a lot of time to #rocess)
-!-
res-lt = []
cac2e = {}
for Aey in mylist!
try!
res-lt"append)cac2e[Aey]*
except Xey6rror!
+ Ldd to cac2e and append to res-lt
res-lt"append)cac2e"setdefa-lt)Aey, getWal-e)Aey***
1ealing &ith duplicate keys
'ecause setdefa-lt)* returns the 7alue for a /ey6 itCs easy and efficient to 0rite a loo#
that con7erts a list of /ey)7alue tu#les into a dict in 0hich each /ey contains a list of
7alues9 3his is handy 0hen you e8#ect /ey du#lications9
3his code #rocesses a list of tu#les and finds that t0o 7alues share a /ey)
>>> 3 = [)/, ,pear tree,*, )&, ,golden rings,*, )/, ,partridge,*]
>>> d = {}
>>> for Aey,5al-e in 3!
""" d"setdefa-lt)Aey, []*"append)5al-e*
"""
>>> d
{/! [,pear tree,, ,partridge,], &! [,golden rings,]}
!ettin" Them &p
,ets are a data ty#e that su##orts mathematical o#erations li/e union6 intersection6
difference6 and symmetric difference9
*hat sets are and aren"t
<ereCs ho0 sets fit in 0ith the rest of 4ythonCs data ty#es)
3he set)* ty#e is built into 4ython 29! and later9 &f youCre usin$ 4ython 29"6 you
must im#ort the sets module before usin$ sets9 3he data ty#e in the sets module
is called @et)* 0ith a ca#ital ,%6 not set)*9
.i/e a dict6 a set is an unordered collection of elements9
?nli/e a dict6 a set contains only /eys that is6 uniGue6 immutable obFects%9 A set
does not ha7e 7alues6 and it is not a ma##in$ ty#e9
?nli/e a seGuence6 the elements in sets arenCt stored in any #articular order6 so
sets donCt su##ort inde8in$ or slicin$9
&n seGuences6 an element can occur multi#le times6 but a set contains only uniGue
elements6 no du#licates9
-!2
De$ular sets are mutable6 and you canCt use one as an element of another set or as
a dictionary /ey9 'ut see the section6 I&mmutable or frozen sets6I later in this
cha#ter9%
<ereCs an e8am#le of a set based on a list that contains some du#licate elements9 3he set
contains no du#licates9
>>> (asAet = [,apple,, ,orange,, ,apple,, ,pear,, ,orange,, ,(anana,]
>>> fr-its = set)(asAet*
>>> fr-its
set)[,orange,, ,pear,, ,apple,, ,(anana,]*
(ebership testing &ith sets
A set is useful for com#arin$ indi7idual items a$ainst a $rou# of elements9 For e8am#le6
if you ha7e a set that contains all states on the Atlantic coast6 you can chec/ 0hether a
user1entered state is on the Atlantic9
#heckin" elements
3o test 0hether an element is in a set6 use the in /ey0ord6 li/e this)
>>> ,aine, in atlantic$states
0r-e
>>> ,Jregon, in atlantic$states
>alse
#heckin" subsets and supersets
3o test 0hether one set is a subset or su#erset of another6 use the a##ro#riate method
listed belo09 'oth return 0r-e or >alse9
a"iss-(set)(*) 3ests 0hether all the elements of set a are also in set (9
a"iss-perset)(*) 3ests 0hether set a contains all the elements in set (9
%inding set eleents
Set operators and methods can be used to combine sets and find their intersections and
their uniGue elements9
3@:<(&:A.
S3?FF
Set o#erations ha7e corres#ondin$ methods9 &n some cases6 usin$ the
method synta8 rather than the o#erator creates easier1to1read code9
3he follo0in$ o#erations are the most commonly used9
-!"
:ifference
3he difference o#eration com#ares t0o sets and returns a set containin$ the elements that
are in the first set but not in the second set9 3he difference o#erator 7 uses this synta8)
a 7 (
3he difference method uses this synta8)
a"difference)(*
3he follo0in$ e8am#le finds the set of round thin$s that arenCt #in/)
>>> ro-ndt2ings = [,orange,, ,g-m(all,, ,egg,, ,tire,]
>>> pinAt2ings = [,lipsticA,, ,g-m(all,, ,(a(y (lanAet,]
>>> a = set)ro-ndt2ings*
>>> N = set)pinAt2ings*
>>> a 7 N
set)[,orange,, ,egg,, ,tire,]*
&nion
3he [ o#erator returns the union of the sets all the elements from both sets%9 3he union
method uses this synta8)
a"-nion)(*
3his e8am#le finds the set of all round thin$s and all #in/ thin$s)
>>> a [ N
set)[,lipsticA,, ,tire,, ,orange,, ,g-m(all,, ,egg,, ,(a(y (lanAet,]*
Intersection
3he ^ o#erator returns the intersection of the sets the elements that are #resent in both
sets%9 3he intersection method uses this synta8)
a"intersection)(*
3his e8am#le finds all the round #in/ thin$s)
>>> a ^ N
set)[,g-m(all,]*
!ymmetric difference
3he ? o#erator returns the symmetric difference of the sets>elements in
-!!
@8actly one set
#ot both sets
3he symmetric difference method uses this synta8)
a"symmetric$difference)(*
3his e8am#le finds all the thin$s that are either round or #in/ but not both)
>>> a ? N
set)[,orange,, ,egg,, ,lipsticA,, ,tire,, ,(a(y (lanAet,]*
Iutable or fro6en sets
4ython 29! has a built1in data ty#e called froQenset9 &tCs similar to set6 but itCs
immutable that is6 after youC7e created one6 you canCt chan$e it%9 'ecause a froQenset is
immutable6 it can be used as a dict /ey or as an element in a set9
&n the follo0in$ e8am#le6 a froQenset instance is used to associate a three1item set /ey
0ith the 7alue 1one)
>>> mylist = [,foo,, ,(ar,, ,spam,]
>>> s = froQenset)mylist*
>>> s
froQenset)[,foo,, ,(ar,, ,spam,]*
>>> d = {s! 1one}
>>> d
{froQenset)[,foo,, ,(ar,, ,spam,]*! 1one}
&f you try to use a re$ular set as a dict /ey6 4ython builds an immutable set from your set
and uses that set as the dict /ey instead9
3@:<(&:A.
S3?FF
4ython 29" has a similar subclass of sets called Gmm-ta(le@et9 &t is
a7ailable if you im#ort the sets module9
-!A
art III, !tructures
#hapter -ist
:ha#ter -0) Stayin$ in :ontrol
:ha#ter --) Fun 0ith Functions
:ha#ter -2) 'uildin$ A##lications 0ith Modules and 4ac/a$es
:ha#ter -") ;ettin$ :lassy
:ha#ter -!) &ntroducin$ (e01Style :lasses
:ha#ter -A) Feelin$ @8ce#tional
:ha#ter -6) 3ac/lin$ Some Ad7anced Features
3he A
th
Wa7e 'y Dich 3ennant
IWeCre here to clean the code9I
In this part
3his #art co7ers 4ythonCs code bloc/s6 the chun/s of code that mani#ulate data and return
results9
&f youC7e e7er seen a flo0 chart6 youCll be comfortable 0ith :ha#ter -06 0hich describes
if statements and loo#sS loo#sS loo#sS9
-!6
:ha#ter -- ta/es you inside the ma$ic bo8es called functions. EouCll disco7er ho0 to #ut
stuff into them and ho0 to $et stuff out of them9
Modules and #ac/a$es are the .e$o bloc/s of 4ython #ro$rams9 :ha#ter -2 sho0s you
ho0 to build and 0or/ 0ith both module files6 0hich store chun/s of code that 0or/
to$ether6 and #ac/a$es6 0hich are directories that contain related modules9
.uc/y :ha#ter -" inducts you into the tem#le of obFect1oriented #ro$rammin$9 :lasses6
li/e factories or tem#lates6 create other obFects that do the actual 0or/9 After you read
this cha#ter6 youCll understand 0hat itCs li/e to be a ca#italist baron 0ho controls the
means of #roduction9
:lasses are such an im#ortant conce#t that 0e couldnCt $et a0ay 0ith Fust one cha#ter
about them9 4ython 29A introduced ne$-style classes. Eou donCt ha7e to use them6 but if
you 0ant to6 :ha#ter -! is 0here they are9
What do you do 0hen somethin$ 0eird ha##ens in your 4ython #ro$ram2 :ha#ter -A
offers ad7ice9 <ere6 you find out ho0 to antici#ate and handle e8ce#tions in your
#ro$rams9
&f youC7e de7oured the rest of the cha#ters in this #art and youCre still hun$ry6 turn to
:ha#ter -69 <ere6 0e introduce some ad7anced features of 4ython #ro$rammin$9 @7en if
you donCt 0ant to use these features yourself yet6 youCll a##reciate bein$ able to reco$nize
them in other #eo#leCs #ro$rams9
-!+
#hapter .K, !tayin" in #ontrol
(verview
With 4ython6 you use control structures to determine 0hether a chun/ of code runs or
ho0 many times to run that code9
3@:<(&:A.
S3?FF
3his /ind of code is also called a compound statement. A com#ound
statement is a /ind of code block lines of code that #erform an
action%9
&n this cha#ter6 0e sho0 you
3he condition and com#arison o#erators that control structures use
3ests you can do on data to decide 0hether and ho0 code should run
<o0 to use if bloc/s to test se7eral s#ecific conditions
When and ho0 to use for and 92ile loo#s to e8ecute code re#eatedly
hin"s to 8now about #ontrol !tructures
3his section describes some $eneral thin$s you need to /no0 about ho0 control
structures 0or/9 &t a##lies to all the structures in this cha#ter9
A control structure starts 0ith a /ey0ord>if6 for6 try6 92ile6 or 9it29 3he first
line also contains an e8#ression and ends 0ith a colon9
Eou can nest control structures9 So an if statement can be nested inside a for
loo#6 and 7ice 7ersa9 Eou can also nest for in for and if in if9%
4ython uses indentation to $rou# statements to$ether9
@ach line 0ithin a code bloc/ must be indented by the same amount>the
con7ention is four s#aces for the first bloc/6 ei$ht s#aces for any bloc/ nested in
the first bloc/6 and so on9
When you enter a com#ound statement a statement 0ith more than one line% in
interacti7e mode see :ha#ter 2 for instructions%6 you need to end it 0ith a blan/
line a Deturn%9 3his tells the #arser that you ha7e ty#ed the last line of the bloc/9
-!,
All about #onditions and #omparisons
:ontrol structures use conditions and com#arisons to tell 4ython 0hen to carry out
actions9 A condition tests 0hether some e8#ression is true or false9 A comparison tests
0hether one 7alue is lar$er than6 eGual to6 or smaller than another9 3his section co7ers the
truth 7alues of obFects and the o#erators that you use for conditions and com#arisons9
The $alue of truth
&n 4ython6 e7ery obFect has a truth value>a 'oolean 7alue of true or false9
D@M@M'@D &n 4ython6 true and false donCt 0or/ Guite the same 0ay they do in the rest
of life9 For e8am#le6 any strin$ e8ce#t an em#ty strin$ e7aluates as true9
So you could tell 4ython ,G am a (illionaire,6 and it 0ould be true5
True and 'alse aren't true and false
4ython 2929- and later ha7e built1in 'oolean data ty#es 0r-e and >alse6 0hich are
associated 0ith the (ool)* built1in function9 Mther functions and methods also return
'oolean results6 such as isdigit)*9% :om#arison e8#ressions6 such as x # y6 also return
0r-e and >alse9
<istory $ee/s may be interested to /no0 that #re7ious 7ersions of 4ython used / and %
rather than 0r-e and >alse because thatCs ho0 it 0or/s in the : #ro$rammin$ lan$ua$e9
3he odd result of this is that the 0r-e and >alse data ty#es are inte$ers)
>>> / : 0r-e
2
&tCs im#ortant to remember that the 'oolean data types are not the same thin$ as the truth
7alues of obFects returned by 'oolean operators. "hen you check the truth value of
ob-ects by usin$ 'oolean o#erators for e8am#le6 by usin$ x and y%6 you are chec/in$
0hether the obFects are em#ty9 3he 'oolean o#erators return a 4ython obFect for
e8am#le6 in x and y6 the obFect x or the obFect y is returned%H they donCt necessarily
return 0r-e or >alse9
'alse ob>ects
All 4ython obFects e7aluate as true e8ce#t for null, empty, and 2ero obFects9 3he follo0in$
obFects e7aluate as false)
>alse one of the t0o 'oolean obFects%
Qero %% for any numerical data ty#e%
-!*
@m#ty strin$ ,,
@m#ty list []
@m#ty tu#le )*
@m#ty dictionary {}
@m#ty set set)*
1one a s#ecial 4ython obFect that stands for Ino 7alueI%
Testin" an ob>ect for truth
3estin$ 0hether an obFect is true or false is sim#le9 Just use an if bloc/)
-9 Type if followed by a literal or the name of an ob>ect. Then type a colon and
press /eturn,
2" >>> if "a"!
"9 Type four spaces, and then type somethin" for ython to do. ress /eturn
twice when you're finished.
." >>> if "a"!
&" """ print "yes!"
<" """
E" yes!
4ython #erforms the action only 0hen the obFect e7aluates as true9 3his test does not
assume that the obFect is any #articular data ty#e9 'ecause youCre not com#arin$ the
obFect a$ainst anythin$ else6 you can thin/ of it as Ilettin$ the obFect e7aluate itself9I
3@:<(&:A.
S3?FF
if name$of$o(Tect! is s2ort for if (ool)name$of$o(Tect*
== 0r-e"
Testin" the elements of a se=uence ob>ect
&n 4ython 29A6 ne0 built1in functions allo0 you to test the truth 7alues of multi#le
elements of a seGuence obFect such as a list% or other iterables at once9
all&'
3he all)* function returns 0r-e if all the elements are true9 &t also returns 0r-e if the
seGuence obFect is em#ty9 For e8am#le)
>>> mylist = [/, 2, 3]
>>> all)mylist*
0r-e
>>> myot2erlist = [%, 2, 3]
>>> all)myot2erlist*
>alse
>>> myemptylist = []
>>> all)myemptylist*
0r-e
-A0
any&'
3he any)* function returns 0r-e if at least one element is true the obFect must not be
em#ty%9 For e8am#le)
>>> any)mylist*
0r-e
>>> any)myot2erlist*
0r-e
>>> any)myemptylist*
>alse
Boolean operators
Eou use 'oolean o#erators to test the truth 7alues of obFects to test 0hether obFects are
em#ty%9 Eou can test more than one obFect at once6 and you can set u# conditions that
de#end on the truth 7alue of one obFect or the truth 7alue of all the obFects youCre testin$9
D@M@M'@D 3he 'oolean o#erators are e7aluated in this #riority order)
-9 not
29 and
"9 or
3he o#erators and and or are short-circuit operators. 4ython e7aluates e8#ressions 0ith
these o#erators from left to ri$ht and sto#s as soon as the outcome is determined9 4ython
returns the obFect it e7aluated last and s/i#s the rest of the e8#ression9
All about or
3he or o#erator sto#s e7aluatin$ as soon as it finds somethin$ thatCs true9 &n the follo0in$
e8am#le6 the first item is true6 so #rocessin$ sto#s there and 4ython returns the first 7alue9
>>> 3 or . or &
3
&n the ne8t e8am#le6 the first item is false6 but the second item is true6 so #rocessin$ sto#s
and 4ython returns the second 7alue)
>>> % or / or 2
/
&f no item e7aluates as true6 the last false% item is returned9
>>> % or [] or ,,
,,
-A-
2mbrace the power of and
3he and o#erator reGuires all the conditions to be met for the e8#ression to be true9
@7aluation sto#s either 0hen an obFect tests false or 0hen all items ha7e been tested9
3i# 3he follo0in$ e8am#les sho0 the results of t0o e8#ressions usin$ and)
3his e8am#le tests all the items and returns the last 7alue)
>>> 3 and . and &
&
3his e8am#le sto#s after testin$ the second item %% because it tests false)
>>> 3 and % and &
%
#oparison operators
:om#arison o#erators test 0hether somethin$ is eGual to andLor $reater than or less than
somethin$ else9 3able -01- lists the com#arison o#erators9
3able -01-) 4ythonCs :om#arison M#erators
M#en table as s#readsheet
(perator &sa"e 4eanin"
# x # y
x is less than y
#= x #= y
x is less than or eGual to y
> x > y
x is $reater than y
>= x >= y
x is $reater than or eGual to y
!=6 #> x != y6 x #> y x is not eGual to y
== x == y
x is eGual to y
D@M@M'@D All com#arison o#erators ha7e the same #riority9 Statements 0ith multi#le
com#arison o#erators are e7aluated from left to ri$ht9
The difference between e=uals and e=uals e=uals
&n 4ython6 = the assi$nment o#erator% $i7es a name to an obFect9 3he = o#erator is #art of
a statement9 &f you 0ant to test 0hether somethin$ is eGual to somethin$ else6 you must
use the == o#erator9
Is you is or is you ain't my babyC
3here are t0o s#ecial com#arisons) is and is not9 3hese donCt test the 7alues of x and yH
they test the identities of x and y>that is6 0hether x and y are bound to the same obFect9
Warnin$ 3o a7oid #roblems6 ma/e a habit of usin$ == and != to com#are obFectsC 7alues
-A2
rather than usin$ is and is not to com#are their identities9 ?sually6 you use is
and is not only 0hen you 0ant to test 0hether somethin$ has the s#ecial 7alue
1one9 3here is only one 1one9%
+et in<
3he com#arison o#erators in and not in chec/ 0hether a 7alue occurs in a seGuence
data ty#e a list6 tu#le6 or strin$%6 a dict6 or a set9
3he follo0in$ e8am#le chec/s for the te8t ,fox, in a set)
>>> data = set)["t2e", "N-icA", "(ro9n", "fox"]*
>>> if "fox" in data!
""" print "Hall o-t t2e 2o-nds!"
"""
Hall o-t t2e 2o-nds!
3i# &f your #ro$ram 0or/s 0ith lots of data6 itCs a ;ood &dea to use dicts or sets to store
the data9 Searchin$ dicts and sets is faster than searchin$ seGuences9
#omparatively speakin"
:om#arisons can be lin/ed in a chain9 3he follo0 e8am#le tests three 7alues9 'oth tests
must be true for the com#arison to be true9
>>> if / # 2 # 3!
""" print "yes!"
"""
yes!
3@:<(&:A.
S3?FF
.in/ed com#arisons can be hard to read9 &n some cases6 combinin$
com#arisons 0ith 'oolean o#erators and6 or6 not% and #arentheses
0ill im#ro7e readability of your code9 :om#are these #airs of
e8#ressions and decide 0hich are easier to read)
if a # ( and ( # c!
if a # ( # c!
if a # ( > c # d!
if )a # (* and )( > c* and )c # d*!
3he 'oolean o#erators ha7e lo0er #riorities than com#arison o#erators>that is6 they are
e7aluated after com#arison o#erators9 Eou can use #arentheses to ma/e sure com#arisons
are e7aluated in the order you 0ant9
'eelin" Iffy
An if statement is an instruction that 4ython carries out only if a condition is true9 Eou
often use a comparison operator to test the condition in an if statement9 3he condition
must be either true or false no $ray areas here5%9 3his is referred to as 0oolean
com#arison9
-A"
3i# Eou can translate an if statement into @n$lish as follo0s) I&f this is true6 then carry
out the instructions belo09I
*riting an if stateent
3o 0rite an if statement6 follo0 these ste#s)
-9 Type if6 a condition, and a colon, like so,
2" if 9eat2er == "raining"!
"9 (n the next line, type an instruction about what to do if the condition is true.
." if 9eat2er == "raining"!
&" (ring$-m(rella = "yes"
'e sure to indent this line and any other lines of the bloc/% four s#aces9
Warnin$ Eou mi$ht see sin$le1line code bloc/s combined on one line li/e this)
if 9eat2er == "raining"! (ring$-m(rella = "yes"
We donCt recommend usin$ this style in your o0n code9 &tCs harder to read6 and #robably
0onCt be allo0ed in 4ython "90 and later9
Adding another condition to an if block
&f you 0ant to test se7eral conditions6 you can include additional code bloc/s to an if
statement9 3hese bloc/s be$in 0ith the /ey0ord elif 0hich is short for Ielse ifI%9 3he
elif statement says6 essentially6 IMther0ise6 if this other thin$ is true6 then carry out this
other instruction9I
Warnin$ :rucial code that al0ays has to run doesnCt belon$ in if or elif code9 4ython
reads if bloc/s if and elif statements% in order9 As soon as it finds a true
condition6 it sto#s e7aluatin$9 3he rest of the bloc/ is not e8ecuted9
3o 0rite an if bloc/ that includes an elif statement6 follo0 these ste#s)
-9 *rite an if statement.
3i# ?se the instructions in the IWritin$ an if statementI section6 earlier in this
cha#ter9 Eour code mi$ht loo/ somethin$ li/e this)
if 9eat2er == "raining"!
(ring$-m(rella = "yes"
29 -ithout indenting. on the next line, type elif, a condition, and a colon 5:6.
3" if 9eat2er == "raining"!
." (ring$-m(rella = "yes"
&" elif 9eat2er == "9indy"!
-A!
3i# &f you are ty#in$ in a #ro$ram that automatically formats 4ython code6 you
mi$ht ha7e to #ress 'ac/s#ace or Delete one or more times to ma/e sure that
this line is not indented9 3his is called dedenting.
69 (n the next line, indent four spaces and type an instruction, like so,
E" if 9eat2er == "raining"!
'" (ring$-m(rella = "yes"
=" elif 9eat2er == "9indy"!
/%"(ring$TacAet = "yes"
Eou can ty#e more instructions9 'e sure to indent any additional instruction lines
four s#aces9
Adding an else stateent to an if block
An else statement al0ays comes last in an if bloc/9 &t means I&f none of the #recedin$
statements 0as true6 then carry out this final instruction9I
Warnin$ DonCt #ut critical code in an else statement9 3he else code $ets e8ecuted only
if none of the other statements in the if bloc/ is true9
3o 0rite an if bloc/ that includes an else statement6 follo0 these ste#s)
-9 *rite an if statement.
3i# &f you ha7e only one condition to test6 s/i# to Ste# "9
29 If you have additional conditions to test, write one or more elif statements.
?se the instructions in the section IAddin$ another condition to an if bloc/6I
earlier in this cha#ter9
"9 (n the next line, type else!9
3his te8t should line u# 0ith if9 Eou mi$ht ha7e to dedent if youCre ty#in$ in a
#ro$ram that formats 4ython code automatically9
!9 +o to the next line, indent four spaces, and type at least one instruction.
&" go$o-t = "no9! 92at are yo- 9aiting forV"
'e sure to indent any additional instruction lines four s#aces9
Eour com#leted code bloc/ mi$ht loo/ li/e this)
if 9eat2er == "raining"!
(ring$-m(rella = "yes"
elif 9eat2er == "9indy"!
(ring$TacAet = "yes"
else!
go$o-t = "no9! 92at are yo- 9aiting forV"
-AA
#obining tests
Eou donCt al0ays ha7e to 0rite elif statements 0hen you 0ant to test multi#le
conditions9 &f you 0ant to #erform the same action in more than one condition6 you can
combine the conditions in a sin$le if or elif statement9
3he code sni##ets in .istin$s -01- and -012 both test for the same conditions6 but the
e8am#le combinin$ multi#le conditions in the if statement is easier to read)
.istin$ -01-) elif bloc/
if age # /'!
print "Oisco-nt rate"
elif age > <&!
print "Oisco-nt rate"
else!
print "Ld-lt rate"
.istin$ -012) 30o conditions in an if statement
if )age # /'* or )age > <&*!
print "Oisco-nt rate"
else!
print "Ld-lt rate"
!tayin" in the -oop
:om#uters are $ood at doin$ thin$s o7er and o7er a$ain9 <umans tend to find re#etitious
tas/s borin$9 3hatCs 0hy 0e #ro$ram 0ith loops9 .oo#s are code bloc/s that tirelessly
re#eat until the tas/ is finished9 4ython has for loo#s and 92ile loo#s9 'oth /inds of
loo#s ha7e these thin$s in common)
3hey start 0ith a /ey0ord for or 92ile%6 follo0ed by an e8#ression and endin$
0ith a colon9
3hey are code bloc/s6 and the code inside them is indented9
3@:<(&:A.
S3?FF
3he ri$ht loo# for your tas/ de#ends on se7eral factors9 See the
section I:hoosin$ Eour .oo#I later in this cha#ter9
%or a Good Tie:
A for loo# is a 0ay to re#eat some instructions a code block% a number of times9 &n this
section6 0e e8#lain the 0or/in$s of the for loo# and discuss iterables6 0hich are obFects
you can use to $enerate a for loo#9
How for works
<ereCs a basic for loo#)
-A6
for myc2ar in "2ello!"!
print "t2e ascii 5al-e of", myc2ar, "is", ord)myc2ar*
3he #recedin$ e8am#le sho0s all the im#ortant features of a for loo#)
3he /ey0ord for
A name that holds a 7alue each time throu$h the loo# this name is sometimes
called the loop target%
3he /ey0ord in
3@:<(&:A.
S3?FF
(ote that in used in a for loo# 0or/s differently from the
'oolean o#erator in see the I;et in5I section earlier in this
cha#ter%9 <ere6 in is used to se#arate the loo# tar$et from the
iterable9
An iterable a seGuence or iterator obFect%>in this case6 the strin$ ,2ello!,
A colon
An indented statement
&n a for bloc/6 4ython $i7es the name to each element in the iterable6 one at a time6 in
order9 &t reuses the name each time throu$h the loo#9 After 4ython $i7es the name to a
ne0 element6 it e8ecutes the instructions in the code bloc/9
3he e8am#le at the be$innin$ of this section com#utes and #rints the AS:&& 7alue of each
character in a strin$ usin$ the ord)* function%)
t2e ascii 5al-e of 2 is /%.
t2e ascii 5al-e of e is /%/
t2e ascii 5al-e of l is /%'
t2e ascii 5al-e of l is /%'
t2e ascii 5al-e of o is ///
t2e ascii 5al-e of ! is 33
Iterables, "etcher iterables<
A for loo# 0or/s only 0ith obFects that ha7e6 or can $enerate6 multi#le elements9 Such
obFects are called iterables because a for loo# $enerates multi#le iterations6 or re#eats6
usin$ the elements in the obFect%9
3@:<(&:A.
S3?FF
Mani#ulatin$ an obFect 0ith a for loo# is also called iterating over a
se7uence or looping through a se7uence9
<ere are some of 4ythonCs obFects that can be used 0ith a for loo#)
for element in range)/,.*! + range
print element
for element in [/, 2, 3]! + list
print element
for Aey in {,one,!/, ,t9o,!2}! + dictionary
print Aey
for line in open)"myfile"txt"*! + text file
-A+
print line
for 5al-e in mydict"iter5al-es)*! + iterator o(Tect
print 5al-e
for Aey, 5al-e in mydict"iteritems)*! + t-ple -npacAing
print Aey, 5al-e
Home on the ran"e
&tCs common to use a for loo# to iterate o7er a seGuence of numbers by usin$ the function
range)*6 0hich $enerates lists of arithmetic #ro$ressions9
3o use the range)* function6 feed it the follo0in$ ar$uments)
DeGuired) An inte$er s#ecifyin$ the end of the ran$e
D@M@M'@D 3he range)* function $enerates a list of numbers up to but not
including the end1of1ran$e number9 For e8am#le6 if you 0ant a list
of all the sin$le di$its6 you 0ould use -06 not *6 as the end of the
ran$e)
>>> range)/%*
[%, /, 2, 3, ., &, <, E, ', =]
M#tional) An inte$er s#ecifyin$ the start of the ran$e9 &t $oes before the inte$er
that s#ecifies the end of the ran$e9 &f left out6 it defaults to 09
3his e8am#le sho0s a range)* function 0ith a startin$ number of 29
>>> range)2, /%*
[2, 3, ., &, <, E, ', =]
Jptional! Ln integer to add to t2e c-rrent n-m(er
M#tional) An inte$er to add to the current number to $enerate the ne8t number9
3his is called a ste#9% &f left out6 it defaults to -9
&f you include the ste#6 you must include the start1of1ran$e number9
3his e8am#le sho0s a range)* function 0ith a ste# of "9
>>> range)%, /%, 3*
[%, 3, <, =]
3i# Eou can use range)* 0ith ne$ati7e numbers6 too6 as sho0n here)
>>> range)7/%, 7/%%, 73%*
[7/%, 7.%, 7E%]
Howdy, xran"e1r<
-A,
3he xrange)* function is similar to range)*6 but instead of returnin$ a list6 it returns an
iterator obFect that $enerates the numbers in the ran$e9
.oo#s usin$ xrange)* are a bit faster and use less memory9
Eou can see 4ythonCs internal difference bet0een range)* and xrange)* by com#arin$
the follo0in$9 (ote that 4ython con7erts the 8ran$e% obFect to an internal IeGui7alentI)
>>> range)%, /%, 3*
[%, 3, <, =]
>>> xrange)%, /%, 3*
xrange)%, /2, 3*
&sin" the ran"e56 function with a list
3o iterate o7er the inde8 numbers of a seGuence such as a list%6 use a for statement 0ith
range)* and len)* 0hich finds the number of elements in a seGuence%6 li/e this)
for i in range)len)list$name**!
3he en-merate)* function6 ne0 in 4ython 29"6 0or/s similarly9 See the I(umbered and
a##ro7edI section6 later in this cha#ter6 to find out more9
Warnin$ &t isnCt safe to modify the list youCre iteratin$ o7er5 3o du#licate selected items
or other0ise modify items in a list youCre usin$ in a loo#6 either
?se a 92ile loo# see the ne8t section%9
:reate a ne0 list to store the modifications6 as sho0n in this e8am#le)
>>> man$from$st$i5es = [,9i5es,, ,sacAs,, ,cats,, ,Aits,]
>>> ne9list = []
>>> for i in man$from$st$i5es!
""" ne9list := [,E,, i]
"""
>>> ne9list
[,E,, ,9i5es,, ,E,, ,sacAs,, ,E,, ,cats,, ,E,, ,Aits,]
*hiling A&ay
A 92ile loo# #erforms an action an indefinite number of times6 as lon$ as a condition is
true9
Warnin$ &f the condition is al0ays true6 the 92ile loo# ne7er sto#s unless a ret-rn or
(reaA statement is encountered6 or an e8ce#tion is raised%9
3o 0rite a 92ile loo#6 follo0 these ste#s)
-A*
-9 Type 92ile6 a Boolean expression, and a colon 5 ! 6.
<ereCs an e8am#le)
92ile n-m(er$of$(ottles > %!
29 (n the next line, type four spaces and then type the action you want
repeated, like this,
3" 92ile n-m(er$of$(ottles > %!
." print n-m(er$of$(ottles, "(ottles of (eer on t2e 9all"
&f you add more lines6 be sure to indent them9
3i# A 92ile loo# is useful in a #ro$ram that 0aits for user in#ut9 3he #ro$ram in .istin$
-01" re#orts on the results of se7eral Icoin tosses9I 3he 92ile loo# chec/s 0hether
the user has as/ed to Guit the #ro$ram9
.istin$ -01") :oin toss #ro$ram
import random
2eadco-nt = tailco-nt = %
-serinp-t = ,,
print "1o9 tossing a coin""""
92ile -serinp-t"lo9er)* != "N"!
flip = random"c2oice)[,2eads,, ,tails,]*
if flip == ,2eads,!
2eadco-nt := /
print "2eads! t2e n-m(er of 2eads is no9 Dd" D 2eadco-nt
else!
tailco-nt := /
print "tails! t2e n-m(er of tails is no9 Dd" D tailco-nt
print "Cress ,N, to N-it",
-serinp-t = ra9$inp-t)"or anot2er Aey to toss again!"*
print "t2e total n-m(er of 2eads!", 2eadco-nt
print "t2e total n-m(er of tails!", tailco-nt
-60
#hoosin" %our -oop
4ython has t0o /inds of loo#s) $hile loo#s and for loo#s9 &n $eneral you should use a for
loo#6 but there are a fe0 s#ecific situations 0here a 92ile loo# is better9 3his section
e8#lains 0hen each ty#e 0or/s best9
*hat for"s for
4ython em#hasizes for loo#s6 0hich are 7ery fle8ible and #o0erful9
D@M@M'@D Most of the time6 0hen you 0ant to re#eat a bloc/ of code more than once6
you should use a for loo#9 ?se for loo#s in the follo0in$ situations)
*hen you want to iterate throu"h a se=uence one item at a
time
*hen you want to repeat a loop a certain number of times
*hen you're readin" a text file
D@M@M'@D A for statement has t0o #arts)
An iterable6 0hich #ro7ides elements one at a time
&n this for statement6 the iterable is range)/%*)
>>> for i in range)/%*!
A loo# tar$et a name%6 0hich is $i7en to each 7alue that the
iterator $enerates
&n the abo7e for statement6 the loo# tar$et is i9
3he for loo# is so fle8ible because there are many 0ays to use the loo# tar$et name in
the body of the loo#9 For e8am#le6 you can $i7e a ne0 7alue to the name inside the loo#
as lon$ as you donCt mind if that 7alue $oes a0ay 0hen the loo# restarts%9 3his code
$i7es a ne0 7alue to i)
>>> for i in range)&*!
""" if i # 3!
""" i = "more spam!"
""" else!
""" i = "(learg2!"
""" print i,
"""
more spam! more spam! more spam! (learg2! (learg2!
Warnin$ 3he other side of the coin is that if you $i7e a ne0 7alue to the loo# tar$et6 you
canCt e8#ect the 7alue to stic/9 3his code doesnCt #rint 0hat you mi$ht e8#ect6
-6-
because i $ets reassi$ned to a number 0hen the loo# restarts)
>>> for i in range)&*!
""" print i,
""" if i # 3!
""" i = "more spam!"
""" else!
""" i = "(learg2!"
"""
% / 2 3 .
*hy to &hile
3he 92ile loo# is useful for these situations)
2vent1driven pro"rams, Many #ro$rams 0ait for a user to ta/e an action such
as clic/in$ a mouse button%6 and then res#ond to the action9 Mften6 a main 92ile
loo# collects user actions events% and sends them to chun/s of code that act on
#articular e7ents event handlers%9
-oops that need to run an undetermined number of times, &f you donCt /no0
ho0 much data you need to #rocess>for e8am#le6 0hen youCre readin$ a binary
file>you mi$ht use a 92ile loo# that re#eats its action until it detects that there
is no more data9
rocessin" a container ob>ect while modifyin" it, 3he spider"py #ro$ram in
:ha#ter ! includes this /ind of 92ile bloc/9 3he bloc/ uses the pop)* list method
to remo7es items from the linAs$to$process list9 A 92ile loo# is used because
no matter ho0 lon$ linAs$to$process is6 it 0ill run as lon$ as there are items
left in the list9 <o0e7er6 itCs im#ortant that the 92ile bloc/ remo7es items from
the list9 &f it didnCt6 the code 0ould run fore7er9
92ile self"$linAs$to$process!
-rl = self"$linAs$to$process"pop)*
self"log)"Betrie5ing! " : -rl*
self"process$page)-rl*
3he 92ile loo#6 because it includes a 'oolean e8#ression6 can sto# une8#ectedly if it
encounters data such as 1one% that e7aluates as false9 3his 92ile loo# sto#s in the
middle of #rocessin$ the list because data is $i7en the 7alue 1one6 0hich e7aluates as
false)
>>> def process)a*!
""" print a,
"""
>>> mylist = [/, 2, 1one, ., &]
>>> data = mylist"pop)*
>>> 92ile data!
""" process)data*
""" data = mylist"pop)*
"""
& .
-62
3he correct 0ay to #rocess items from a list in a 0hile loo# is as follo0s)
>>> mylist = [/, 2, 1one, ., &]
>>> 92ile mylist!
""" process)mylist"pop)**
"""
& . 1one 2 /
-oopy !tatements and 'unctions
3his section describes some s#ecial statements that 0or/ 0ith loo#s9 &t also details
se7eral useful functions that 0or/ 0ith loo#s9 Some of these statements and functions
also 0or/ 0ith other code bloc/s9
)seful looping stateents
Se7eral statements hel# you $et the most out of loo#s9 @ach of the follo0in$ statements
0or/s as #art of a loo# code bloc/ and $oes on a line by itself9
Take a break9or else<
3he /ey0ord (reaA sto#s the #rocessin$ of a loo# and e8its the loo#9 Any code in the
bloc/ that comes after the (reaA statement is i$nored any else clause is also s/i##ed%9
&f the loo# is nested inside another code bloc/6 the #ro$ram $oes bac/ to the bloc/ that
the loo# 0as nested in9
&n a loo#6 the (reaA is usually #art of a nested if statement9 &n the follo0in$ e8am#le6
(reaA e8its the if loo# 0hen the element has the 7alue ,n,9
>>> y = "astring"
>>> for i in y!
""" if i == ,n,!
""" print "(roAe!"
""" (reaA
""" print i,
""" print ";",
"""
a ; s ; t ; r ; i ; (roAe!
%ou and who elseC
.oo#s6 li/e if statements6 can ha7e an else clause that e8ecutes 0hen the condition in
the loo# e7aluates as false9 Mne 0ay to use the else clause is 0ith a nested if sub1bloc/
that has a (reaA statement in it9 &t 0or/s li/e this)
-9 @ach time around the loo#6 the condition in the if statement is tested9
-6"
29 &f the condition is true6 the (reaA statement causes e7erythin$ else in the loo#
includin$ the else bloc/% to be s/i##ed9 :ontrol e8its the loo#9
"9 &f the condition is false6 the loo# starts o7er a$ain9
!9 &f the loo# iterator runs out before the if condition e7aluates as true6 the for
loo#Cs else clause $ets e8ecuted9
3he follo0in$ code determines 0hether a strin$ in this case6 ,larc2,% contains any
lo0ercase 7o0els)
mystring = "larc2"
5o9els = set),aeio-,*
for a in mystring!
if a in 5o9els!
print mystring, "2as a 5o9el"
(reaA
else!
print mystring, "does not 2a5e a 5o9el"
3he result is)
larc2 2as a 5o9el
-et's continue
When 4ython sees a contin-e statement in the middle of a loo# code bloc/6 it s/i#s the
rest of the code in the bloc/ and $oes bac/ to the to# of the loo#9 <ereCs ho0 it 0or/s9
3his code bloc/ #rints both IAI and Ifi7eI because the print n, statement is e8ecuted
each time throu$h the loo#9
>>> for n in range)/%*!
""" if n == &!
""" print "fi5e",
""" print n,
"""
% / 2 3 . fi5e & < E ' =
When 0e add contin-e to the if bloc/6 4ython s/i#s the last print n, statement 0hen
the loo# condition e7aluates as trueH therefore6 it #rints only Ifi7eI)
>>> for n in range)/%*!
""" if n == &!
""" print "fi5e",
""" contin-e
""" print n,
"""
% / 2 3 . fi5e < E ' =
3i# ?se contin-e statements s#arin$ly because they can ma/e your code hard to read6
es#ecially if they are nested in com#le8 structures9
-6!
Thanks, but I'll pass
3he pass /ey0ord tells the 4ython inter#reter to do nothin$9 &t is usually used in class
statements6 but youCll also find it useful in 92ile or for loo#s 0hen the #ro$ram reGuires
no action9 &n this e8am#le6 the arg-ment$clinic)* function does nothin$ if its ar$ument
is $reater than or eGual to A)
>>> def arg-ment$clinic)min-tes*!
""" if min-tes >= &!
""" pass
""" else!
""" print "1o it isn,t!"
"""
>>> min-tes = .
>>> arg-ment$clinic)min-tes*
1o it isn,t!
>>> min-tes = &
>>> arg-ment$clinic)min-tes* + not2ing 2appens
>>>
3i# 3he pass statement is also useful 0hen you are startin$ to build a #ro$ram9 Eou can
create the s/eleton of the #ro$ramCs code bloc/s by usin$ pass and then fill in 0hat
the bloc/s do later9 'ut donCt for$et to ta/e out pass5%
3his e8am#le code 0ill e7entually sol7e all the 0orldCs #roblems6 but for no0 itCs Fust a
#laceholder)
def grand$sol-tion)pro(lems*!
""" sol5e all t2e 9orld,s pro(lems 2ere """
+ We 9ill fig-re t2is o-t someday
pass
Loopy functions
3his section describes some functions that are es#ecially useful 0hen 0or/in$ 0ith
loo#s9
3@:<(&:A.
S3?FF
All the functions described in this section 0or/ 0ith iterables in
$eneral6 not Fust 0ith seGuences9
?umbered and approved
&n 4ython 29" and later6 use the en-merate)* function in a loo# to return the inde8
#osition% and 7alue of each element9 Follo0 these ste#s)
-9 Type the followin", substitutin" your own iterable for the example list,
2" for i, 5 in en-merate)[,tic,, ,tac,, ,toe,]*!
"9 (n the next line, indent four spaces and type some code that you want
ython to execute.
-6A
." for i, 5 in en-merate)[,tic,, ,tac,, ,toe,]*!
&" print i, 5
<ereCs the result of the code)
% tic
/ tac
2 toe
3@:<(&:A.
S3?FF
3echnically s#ea/in$6 en-merate)* returns an iterator that creates an
inde86 7alue% tu#le for each data item9 3he tu#les $enerated by the
#recedin$ code are )%, ,tic,*, )/, ,tac,*, )2, ,toe,*9
The two1loop tan"o
3he Qip)* function6 ne0 in 4ython 2906 loo#s o7er t0o or more seGuences at the same
time9 &t returns a list of tu#les in 0hich an item in each seGuence is #aired 0ith the
corres#ondin$ items in the other seGuences9
3i# 3hin/ of a zi##er zi##in$ to$ether t0o sets of teeth5
3o 0rite a for statement that zi#s t0o seGuences6 ty#e the follo0in$ substitutin$ your
o0n seGuence names%)
for a, ( in Qip)seN-ence$one, seN-ence$t9o*!
3he follo0in$ e8am#le uses the Qip)* function in a for statement to e8#lain the rules of
the $ame Iroc/6 #a#er6 scissorsI)
>>> mylist/ = [,rocA,, ,paper,, ,scissors,]
>>> mylist2 = [,scissors,, ,rocA,, ,paper,]
>>> mylist3 = [,paper,, ,scissors,, ,rocA,]
>>> for a, (, c in Qip)mylist/, mylist2, mylist3*!
""" print "Ds (eats Ds (-t not Ds" D )a,(,c*
"""
rocA (eats scissors (-t not paper
paper (eats rocA (-t not scissors
scissors (eats paper (-t not rocA
+entlemen and ladies, unpack your tuples
A for loo# is a con7enient 0ay to unpack the 7alues in a tu#le9 A canonical e8am#le of
tu#le un#ac/in$ uses the iteritems)* method of dictionaries6 0hich first turns each
/ey)7alue #air into a t0o1item tu#le9
3i# We use items)* in this e8am#le to sho0 ho0 the transformation to a list of t0o1item
tu#les ta/es #lace9 &n actual code you should use the iteritems)* method instead9
3he result is the same6 but itCs more efficient9
3his e8am#le sho0s ho0 un#ac/in$ 0or/s)
-66
>>> c2eese$in5entory = {,Bed Windsor,! ,t2e 5an (roAe do9n,,
,Haerp2illy,! ,on order,, ,Bed 3eicester,! ,fres2 o-t,}
>>> c2eese$in5entory"items)*
[),Bed Windsor,, ,t2e 5an (roAe do9n,*, ),Haerp2illy,, ,on
order,*, ),Bed 3eicester,, ,fres2 o-t,*]
Eou can use the follo0in$ for loo# 0ith the iteritems)* method to un#ac/ the tu#le
elements)
>>> for Aey, 5al-e in c2eese$in5entory"iteritems)*!
""" print Aey, "!", 5al-e
"""
Bed Windsor ! t2e 5an (roAe do9n
Haerp2illy ! on order
Bed 3eicester ! fres2 o-t
+oin" backward
3he re5ersed)* function returns an iterator that $oes throu$h the seGuence items
bac/0ard9 3he re5ersed)* function is ne0 in 4ython 29!9
3he follo0in$ e8am#le uses re5ersed)* 0ith the range)* function as its ar$ument to
count do0n throu$h the seGuence)
for f in re5ersed)range)/, //**!
print f,
print "(lastoff!"
<ereCs 0hat it #rints)
/% = ' E < & . 3 2 / (lastoff!
(ut of sorts
3he sorted)* function returns a ne0 sorted list 0hile lea7in$ the source list unchan$ed9
&t 0or/s 0ith both lists and immutable seGuence obFects9 3his function is ne0 in 4ython
29!9
>>> mylist = [/, /%, 2, =, 3, ', ., E, &, <]
>>> myne9list = sorted)mylist*
>>> myne9list
[/, 2, 3, ., &, <, E, ', =, /%]
>>> mylist + original list is -nc2anged
[/, /%, 2, =, 3, ', ., E, &, <]
3@:<(&:A.
S3?FF
&n contrast6 the list method sort)* chan$es the ori$inal list in #lace9
>>> mylist"sort)*
>>> mylist
[/, 2, 3, ., &, <, E, ', =, /%]
-6+
3o use the sorted)* function in a for statement6 ty#e the follo0in$ substitutin$ the
name of your seGuence obFect%)
>>> myt-ple = )"an", "african", "or", "e-ropean", "s9allo9", "V"*
>>> for f in sorted)myt-ple*!
""" print f,
"""
V african an e-ropean or s9allo9
#hapter .., 'un with 'unctions
. function is a bloc/ of code that #erforms a s#ecific action and returns a result9
&n this cha#ter6 you find out about callin$ functions6 0ritin$ functions and their
docstrin$s6 and #assin$ ar$uments to functions9 EouCre also inducted into the arcane
mysteries of the names#ace9
I -ove #hunky #ode
<ereCs ho0 functions ma/e your life easier as a #ro$rammer and ma/e thin$s easier on
#eo#le 0ho read and use your code6 too)
'unctions let you write code only once.
When you create code that you 0ant to reuse6 be sure to define it as a function9
3his sa7es you from ty#in$ the same code o7er a$ain 0hen you 0ant to use it in
another #ro$ram9
'unctions hide unnecessary complexity from the user.
(o one e7er has to care 0hat this function does unless itCs included in your
#ro$ram9 And e7en if someone does use the function6 they donCt ha7e to care ho$
it 0or/s6 as lon$ as it #erforms the 0ay its documentation says it 0ill9
'unctions make your code easier to understand.
&f you name a function accordin$ to 0hat its code does6 then someone readin$ the
#ro$ram Fust has to loo/ at the name to $et an understandin$ of 0hat the #ro$ram
is doin$ at that #oint9 Mf course6 you should also include comments in your
#ro$ram and comments and docstrin$s in your function to further e8#lain 0hatCs
ha##enin$9%
'unctions help you or"ani)e your pro"ram lo"ically.
-6,
Writin$ most of your code chun/s in functions hel#s you or$anize your #ro$ramCs
structure lo$ically6 and that can ma/e your #ro$rams easier to understand9
#alling a function
?sin$ a function is /no0n as calling the function9 When you call a function6 the
functionCs code runs and returns a result9
3o call a function6 follo0 these ste#s)
-9 Type a name to hold the result of the function followed by an e=uals si"n 5!6.
Eou donCt ha7e to do this6 but usually you 0ant to do somethin$ 0ith the function
result6 and itCs easier if a name has been $i7en to the result9
29 Type the name of the function.
"9 In parentheses, "ive the function information about what you want it to act
on.
;i7in$ a function information is called passing arguments9 Some functions donCt
ta/e any ar$uments6 but most do9
Eou can #ass the function a 7alue or a name9
&n the follo0in$ e8am#le6 the s-m)* function is $i7en one ar$ument) the name of a list
p-rc2ases%9 3he name total is $i7en to the result)
arameters versus ar"uments
&n this cha#ter6 0e use the terms parameter and argument 0hen discussin$ the data that a
function needs to do its 0or/9 <ereCs a 0ay to understand the difference)
A parameter is a #laceholder for the data9 When you are 0ritin$ a function6 you use
#arameters to tell the function to e8#ect data to be #assed9 3hen you use the #arameter
name inside the function to stand for that data9
An argumentis the actual data that3s passed 0hen you call the function9 <ereCs an
e8am#le)
>>> def a$f-nction)a$param*!
""" print "my parameter is a$param
and my arg-ment is",
repr)a$param*
"""
>>> a$f-nction)"my arg"*
my parameter is a$param and my arg-ment
is "my arg"
-6*
3@:<(&:A.
S3?FF
'unctions versus methods
WhatCs the difference bet0een a function and a method2 (ot much9 A
method is a /ind of function>both #erform a s#ecific action on some
information you $i7e them9 <o0e7er6 a method is associated 0ith a
#articular obFect and #erforms its action on that obFect9 Mften6 that
obFect is a data ty#e9 For e8am#le6 a list comes 0ith the append)*
method6 0hich lets you add items to the end of the list9 Whene7er
you create a ne0 list obFect by usin$ a statement such as my$list =
[/,2,3]6 the obFect my$list has access to all the methods for list
obFects9
Functions6 on the other hand6 stand on their o0n9 Eou donCt ha7e to
create an obFect in order to use one9
Eou call functions and methods usin$ different synta8)
3o use a function6 ty#e the function name)
my$f-nction)x*
3o use a method6 a##end it to the name of the obFect6
se#aratin$ the name and the method 0ith a dot6 li/e this)
my$list"append)x*
>>> p-rc2ases = [/3"%2, 2"==, .".&]
>>> total = s-m)p-rc2ases*
>>> print total
2%".<
1efining a %unction
?nless youCre usin$ a built1in function6 you need to define the function before you can
call it9 3hese are the basic ste#s for 0ritin$ a function)
-9 (n the first line, write the def statement for the function.
Follo0 these ste#s)
a9 "rite def and the function name.
b9 /n parentheses, add the names of parameters that the function $ill act on.
,eparate parameters $ith commas.
&f your function doesnCt ha7e #arameters6 it still needs the #arentheses9
c9 &ype a colon at the end of the statement.
Eour def statement mi$ht loo/ somethin$ li/e this)
-+0
def my$f-nction)arg/, arg2*!
29 5(ptional, but very important6 (n the next lines, write the docstrin" for the
function.
Follo0 these ste#s)
a9 On a ne$ line, indent four spaces and type three 7uotation marks %a triple
7uote4.
b9 &ype an e!planation of $hat the function does and ho$ to use it.
See the sidebar IWhatCs u#6 Doc2I to find out 0hat to include9
c9 On the ne!t line, indent four spaces and type a triple 7uote9
Eour function and its docstrin$ mi$ht loo/ somethin$ li/e this)
def my$f-nction)arg/, arg2*!
"""
Cerform my f-nction on arg/ -sing arg2" Bet-rn a list"
"""
"9 *rite the function's code.
&ndent each line of code four s#aces9 &f your function contains another
subordinate or nested code bloc/6 such as an if statement6 that bloc/Cs code must
be indented an additional four s#aces6 and so on9%
When youCre finished6 the function mi$ht loo/ li/e this but containin$ 4ython
code6 of course5%)
def my$f-nction)arg/, arg2*!
"""
my f-nction does t2is
"""
do somet2ing
if t2is!
do t2at
ret-rn somet2ing else
Gi$ing another nae to a function
After you im#ort a function6 you can $i7e it a ne0 name9 3he additional name refers to
the same obFect at the same location as the old name6 as this e8am#le sho0s)
>>> tinyf-nction
#f-nction tinyf-nction at %x</.3%>
>>> myf-nc = tinyf-nction
-+-
>>> myf-nc
#f-nction tinyf-nction at %x</.3%>
3i# &tCs im#ortant to remember the difference bet0een giving a ne$ name to a function
and calling a function $hile giving a name to the result. When you call a function6
you add #arentheses at the end of the function name9 3hese e8am#les sho0 the
difference)
>>> myf-nction = tinymod-le"tinyf-nction + gi5ing a ne9 name to a
f-nction
>>> myres-lt = tinymod-le"tinyf-nction)2* + calling a f-nction
*hat's up, :ocC
&f the first code in a function is a strin$6 it becomes the docstrin$ for the function9 3he
docstrin$ defines 0hat the function does and 0or/s 0ith 4ythonCs 2elp)* utility9 We
recommend 0ritin$ doc1strin$s for all your functions9
A docstrin$ usually s#ans multi#le lines6 so it be$ins and ends 0ith tri#le Guotes9
'y con7ention amon$ 4ython #ro$rammers6 a basic docstrin$ for a function loo/s li/e
this)
-9 3he first line the only line for a sim#le function% is a descri#tion of 0hat the
function does6 or a summary if the function does se7eral thin$s or has se7eral
o#tions9
For e8am#le6 ta/e this function that #rints somethin$)
def printme)me*!
print me
3his function does only one thin$6 so the docstrin$ mi$ht loo/ li/e this)
"""Crint t2e arg-ment"""
29 &f the function needs more than one line of documentation6 the second line should
be blan/9
"9 3he third and subseGuent lines e8#lain o#tions6 defaults for o#tional ar$uments6
and other usa$e notes9
Say 0e chan$e the printme)* function so it ta/es an o#tional ar$ument>a list of
0ords not to #rint)
def printme)me, (ad$9ord$list=1one*!
if (ad$9ord$list and me in (ad$9ord$list!
print "Ho9 dare yo-!"
else!
print me
-+2
We mi$ht $i7e it the follo0in$ docstrin$)
"""
Crint arg-ment" Jptionally c2ecA against list of 9ords not to print"
Xey9ord arg-ment!
(ad$9ord$list 77 list of 9ords not to print )defa-lt 1one*
"""
Eou can find out more about 4ythonCs docstrin$ con7entions by readin$ 4ython
@nhancement 4ro#osal 4@4% 2A+ at)
htt#)LL0009#ython9or$Lde7L#e#sL#e#102A+
/eturning $alues fro a function
(ames you define inside a function disa##ear after the function e8its9 3o $et 7alues out of
a function6 you must do t0o thin$s)
Include a ret-rn statement in the function with a name or value, like this,
def my$f-nction)(*!
a = ( : .2
ret"rn #
&se the function in an expression or in an assi"nment statement,
my$5al-e = my$f-nction)3*
3he name on the left side of the eGuals si$n in the assi$nment statement no0
stores the 7alue that the function returned6 as sho0n)
>>> my$5al-e = my$f-nction)3*
>>> print my$5al-e
.&
&f a function has no ret-rn statement6 or if the ret-rn statement doesnCt s#ecify 0hat to
return6 the function returns 1one a built1in name%9 <ereCs a function 0ithout a ret-rn
statement9
>>> def no$ret-rn$f-nction)(*!
""" print (
"""
>>> my$5al-e = no$ret-rn$f-nction)3*
3
>>> print my$5al-e
1one
So 0hy 0ould you e7er 0ant a function 0ithout a ret-rn statement2 Some functions
mani#ulate an item in #lace instead of returnin$ a ne0 item9 Some functions #erform an
-+"
action that doesnCt need to return a result for e8am#le6 sa7in$ a messa$e to a lo$%9 Such a
function mi$ht not need a ret-rn statement9
3i# 3he ret-rn statement not only #asses a 7alue out of the function6 it also sto#s
4ython from runnin$ the rest of the code in the function9 So ret-rn either should be
the last statement in the function or should be used in conditional code6 such as an if
bloc/6 to Fum# out of the function 0hen a certain condition is met9
Ar"ument #linic, assin" :ata
4arameters are #laceholders for information that you $i7e to a function so it can carry out
an action9
3here are many 0ays to s#ecify a functionCs #arameters9 3his section introduces
s#ecifyin$ #ositional #arameters6 default17alue #arameters6 and arbitrary numbers of
#arameters9 &t also describes ho0 to a7oid the Guir/s of default17alue #arameters and
mutable obFects9
Introducing paraeters and arguents
<ere are a fe0 thin$s to /no0 about function #arameters)
A function can have any number of parameters 5or no parameters6.
*hen you define a function, you specify how many parameters it has.
&t can ha7e a s#ecific number of #arameters or an indefinite number of
#arameters9
%ou can define default values for any or all of the parameters.
When you call a function6 you need to $i7e it a 7alue corres#ondin$ to each #arameter9
3his actual 7alue is called an argument.% <ere are a fe0 thin$s to /no0 about ar$uments)
Ar"uments are passed when you call the function.
If the parameter has a default value, you don't have to pass an ar"ument.
%ou can pass an ar"ument as a literal or as a name.
&f you #ass an ar$ument as a name6 the function acts on the obFect the name refers
to9
Specifying arguents &hen you call a function
3he basic 0ay of s#ecifyin$ ar$uments is to pass them 0hen you call the function9
-+!
3o #ass an ar$ument6 ty#e it bet0een the #arentheses of a function 0hen you call the
function6 li/e this)
>>> a$f-nction(my#rg)
3he follo0in$ e8am#le creates a function that #rints the 7alue of its ar$ument6 $i7es a
name to a tu#le6 and #asses the name to the function)
>>> def a$f-nction)x*!
""" print "yo- passed me t2e arg-ment", repr)x*
"""
>>> myarg = )/,2,3*
>>> a$f-nction)myarg*
yo- passed me t2e arg-ment )/, 2, 3*
3he follo0in$ e8am#le #asses the same function a strin$ literal 0ithout definin$ a name)
>>> a$f-nction)"2ello"*
yo- passed me t2e arg-ment ,2ello,
Specifying arguents &ith key&ords and default $alues
A function can ha7e default 7alues for some of the #arameters9 Such default17alue
#arameters are sometimes called key$ord arguments9% <ere are some circumstances in
0hich default17alue #arameters are useful)
A particular value will be used more often than others.
For e8am#le6 4ythonCs ro-nd)* function ta/es a reGuired number ar$ument and
an o#tional #recision ar$ument9 3he #recision #arameter defaults to 0 because6
most of the time6 0hen you round a number6 you 0ant the inte$er closest to the
number rather than a decimal9
The function is desi"ned to work in more than one way, dependin" on which
ar"uments are passed.
For e8am#le6 the open)* function o#ens a file for readin$ by default9 &f you 0ant
to o#en a file for 0ritin$6 you need to s#ecify a mode ar$ument6 ,9,9
When addin$ default17alue #arameters to function definitions6 follo0 these rules)
-9 Type any parameters that won't have keywords first.
4arameters 0ithout /ey0ords are called positional9
29 Type keyword ar"uments in the form keyword=value9
-+A
3he follo0in$ function definition has one reGuired #ositional% #arameter ingredient%
and t0o default17alue #arameters)
def recipes)ingredient, ser5ings=., mode="Wegetarian"*!
When callin$ a function that includes default17alue #arameters6 follo0 these rules)
-9 ass values for all positional parameters first.
?se the same order in 0hich the functionCs #arameters are defined9
29 ass values or names for any default1value parameters whose default values
you want to override.
<ere are some additional $uidelines for default17alue #arameters)
DonCt #ass information for default17alue #arameters 0hose default 7alues you
0ant to use9 For e8am#le6 this function call uses both defaults)
>>> recipes),s2iitaAe m-s2rooms,*
&f you include default17alue #arameters in the order in 0hich they 0ere defined6
you can Fust #ass their 7alues6 li/e this)
>>> recipes),ar-g-la,, ', "Harni5ore"*
&f you are includin$ default17alue #arameters in a different order or s/i##in$ some
#arameters6 use the keyword=value format6 as sho0n here)
>>> recipes),ar-g-la,, mode="1o pean-ts"*
A$oiding the 3uirks of default $alues
Default 7alues are useful as function #arameters6 but you need to be a0are of their Guir/s9
Immutable default values stay the same
4ython e7aluates default 7alues in function definitions only once>0hen the function is
defined6 that is6 0hen the def statement first runs9 Another 0ay to say this is that 4ython
binds the default to the parameter9% def is an e8ecutable statementH this is 0hy you ha7e
to define a function before you can call it9 After that6 if you chan$e the 7alue of a name
you used as a default in the function definition6 the function 0ill continue to use the
ori$inal 7alue 0hen the 7alue is an immutable data ty#e9 &n the e8am#le belo06 the def is
#assed the 7alue of the inte$er myn-m9 When myn-m is chan$ed later6 the function still
uses the old 7alue)
>>> myn-m = ' + Gntegers are imm-ta(le"
>>> def f)arg=myn-m*!
""" ret-rn arg
"""
>>> f)*
'
-+6
>>> myn-m = /% + We,re
>>> f)* + """(-t t2e f-nction still -ses '"
'
4utable default values can chan"e
When you use a mutable obFect such as a list6 dictionary6 or class instance% as a default
and chan$e the obFect inside the function6 then the ne8t time you call the function6 the
function uses the chan$ed obFect9 For e8am#le6 the follo0in$ function creates a list that
accumulates the ar$uments #assed to it9
>>> def f)N, mylist=[]*!
""" mylist"append)N*
""" ret-rn mylist
"""
>>> print f),a,*
[,a,]
>>> print f),(,*
[,a,, ,(,]
>>> print f),c,*
[,a,, ,(,, ,c,]
<ereCs 0hatCs $oin$ on)
-9 When the function is defined6 it creates an em#ty list obFect named mylist9
29 &nside the function6 the append)* method adds an item to the list9
3he append)* method chan$es the contents of the list in place: that is6 mylist
still refers to the same obFect after bein$ chan$ed9
"9 When the function is called a$ain6 it $rabs the same list from the same #lace and
uses the ne0 contents9
Assi"nment 5L6 always chan"es
Assi$nment al0ays causes a name to refer to a different obFect that is6 it rebinds%6 e7en if
the obFect is mutable9 So if you use assi$nment =% inside the function rather than the
append)* method6 mylist doesnCt accumulate ar$uments9
>>> def f)N, mylist=[]*!
""" mylist = mylist : N
""" ret-rn mylist
"""
>>> a = [/]
>>> f)a*
[/]
>>> a = [2]
>>> f)a*
[2]
-++
Au"mented assi"nment 5ML6 doesn't rebind mutable data types
Au$mented assi$nment o#erators := and ;=% rebind 0hen used 0ith an immutable data
ty#e6 but donCt rebind 0hen used 0ith a mutable data ty#e6 such as a list9 When used 0ith
a list6 := is the eGui7alent of the extend)* methodH it adds items to the end of a list9 So if
0e re0rite the function to use au$mented assi$nment6 the function e8tends mylist
0hich is mutable% by addin$ the ar$ument to the end of the list)
>>> def f)N, mylist=[]*!
""" mylist := N
""" ret-rn mylist
"""
>>> a = [/]
>>> f)a*
[/]
>>> a = [2]
>>> f)a*
[/, 2]
*orkin" on a copy of a mutable ob>ect
'ecause usin$ mutable obFects as ar$uments can ha7e une8#ected results6 youCre better
off o#eratin$ on a co#y of the obFect9 3his function creates a ne0 co#y of its list and then
adds a 7alue to each list element)
def f)mylist, data*!
ne9list = mylist[!] + maAe a copy of mylist
for i in range)len)mylist**!
ne9list[i] = mylist[i] : data
ret-rn ne9list
:allin$ the abo7e function doesnCt chan$e the ori$inal list)
>>> alist = [/, 2, 3]
>>> x = f)alist, &*
>>> print x
[<, E, ']
>>> print alist
[/, 2, 3]
&sin" a default value of ?one to redefine a mutable ob>ect
&f you 0ant a function to redefine a list as em#ty each time you call it6 use a default
#arameter of mylist=1one9 1one is immutable6 so the function 0onCt be referrin$ to a list
obFect that mi$ht chan$e9
3he follo0in$ code $i7es the #arameter mylist a default 7alue of 1one in its def
statement and then redefines mylist as an em#ty list inside the function)
-+,
def f)a, mylist=1one*!
if mylist is 1one!
mylist = []
mylist"append)a*
ret-rn mylist
When you call the abo7e function se7eral times6 it doesnCt accumulate ar$uments)
>>> a = /
>>> f)a*
[/]
>>> a = 2
>>> f)a*
[2]
Specifying a function &ith an arbitrary nuber of arguents
3o #ass an arbitrary number of ar$uments to a function6 use the #arameter ;args in the
def statement for the function9 <ere are ti#s and rules for usin$ ;args)
3he #arameter ;args stands for a set of #ositional ar$uments that arenCt e8#licitly
named in the function definition9
When you call the function and #ass it ar$uments6 ;args automatically creates a
tu#le out of the ar$uments9
3he #arameter ;args must come last in the function definition or ne8t1to1last if
there is also a ;;A9args #arameter%9
3o #ass an arbitrary number of keyword=value #airs to a function6 use the #arameter
;;A9args in the functionCs def statement9 <ereCs ho0 it 0or/s)
When you call the function and #ass the Aey9ord=5al-e #airs6 ;;A9args
automatically creates a dictionary from them9
3he #arameter ;;A9args must come last in the function definition9
3@:<(&:A.
S3?FF
3he names donCt ha7e to be ;args or ;;A9argsH 4ython cares only
that the ; or ;; o#erator comes first in the name9 'ut 4ythonistas
al0ays use ;args and ;;A9args9 3his consistency ma/es #ro$rams
easier to read by humans9
3his e8am#le #ro$ram sho0s ho0 ;args and ;;A9args 0or/ in a function that also has
t0o #ositional #arameters)
def a$f-nction)a, (, ;args, ;;A9args*!
print "a is", a
print "( is", (
print ";args is t2is t-ple!", args
print ";;A9args is t2is dictionary!", A9args
&t #roduces the follo0in$ result)
-+*
>>> a$f-nction)/, ,2,, ,t2ree,, ,(lind,, ,mice,, see="2o9", t2ey="r-n"*
a is /
( is 2
;args is t2is t-ple! ),t2ree,, ,(lind,, ,mice,*
;;A9args is t2is dictionary! {,see,! ,2o9,, ,t2ey,! ,r-n,}
)npacking arguents
3o #ass the elements of a list6 tu#le6 or dictionary as ar$uments in a function6 use the ;
o#erator for lists and tu#les% or the ;; o#erator for dictionaries% 0hen callin$ the
function to unpack the elements9
3o un#ac/6 you need these thin$s)
A function
3he function can ha7e any /ind of #arameters>#ositional or default6 ;args6 or
;;A9argsS or e7en no #arameters at all9
A list, tuple, or dictionary with the same number of elements as the number
of parameters in the function
&npackin" lists or tuples
3o #ass the elements of a list or tu#le as ar$uments in a function6 use this line of code
substitutin$ your function name and list or tu#le name%)
myf-nction)*my_list_or_t"ple*
3he follo0in$ code defines and calls a function6 #assin$ a list as its ar$ument6 usin$ the ;
o#erator)
>>> def f-nc$9it2$t2ree$args)a, (, c*!
""" print "t2e arg-ments are!", a, (, c
"""
>>> 9eapons = [,fear,, ,s-rprise,, ,r-t2less efficiency,]
>>> f-nc$9it2$t2ree$args);9eapons*
t2e arg-ments are! fear s-rprise r-t2less efficiency
&npackin" dictionaries
3o #ass the /ey)7alue #airs of a dictionary to a function6 use this line of code substitutin$
your function name and dict name%)
myf-nction)**mydict*
-,0
3he dictionary /eys must ha7e the same names as the functionCs #arameters9 3he
follo0in$ code #asses a dictionary to f-nc$9it2$t2ree$args)* usin$ the ;; o#erator9
3he dictionaryCs /eys match the ar$ument names)
>>> not$in$stocA = {"a"!"Bed 3eicester", "("!"Farls(erg",
"c"!"Hamem(ert"}
>>> f-nc$9it2$t2ree$args);;not$in$stocA*
t2e arg-ments are! Bed 3eicester Farls(erg Hamem(ert
*hat's in a ?amespace
A namespace, also called a symbol table or scope, is stora$e for the names of obFects
4ython /no0s about9
D@M@M'@D 3he most im#ortant thin$ to remember about function namespaces is this)
When you $i7e a name to a 7alue6 you are al0ays assi$nin$ 0ithin the
functionCs local names#ace unless
Eou e8#licitly say that the name is $lobal
Eou s#ecify that the name is an attribute of a #articular obFect
1isco$ering &here Python looks for naes
4ython has three basic layers of names#aces6 listed here in order of most s#ecific to most
$eneral9 4ython loo/s for names in this order and sto#s loo/in$ as soon as it finds the
name)
-9 .ocal names defined inside a class6 function6 or method%
29 ;lobal names defined inside a module>often function names and class names6
but can be other names6 too%
"9 'uilt1in names that are al0ays a7ailable%
&f 4ython canCt find a name in any of those #laces6 it raises a 1ame6rror e8ce#tion9 &f you
$et an Lttri(-te6rror6 that means that 4ython found the leftmost first% name but didnCt
find the name after the dot9 @ach obFect has its o0n names#ace that 4ython searches9 For
more information about obFect names#aces6 see :ha#ters -2 and -"9
)nderstanding function naespaces
When 4ython encounters a function definition in a chun/ of code6 it e!ecutes the
definition9 3hat #re#ares the function for bein$ called later9 When 4ython e8ecutes the
definition6 the follo0in$ thin$s ha##en)
3he functionCs name is stored in the current names#ace9
-,-
&f the function is #art of a module6 this is the moduleCs names#ace9 &f the function
0as im#orted directly6 it mi$ht be the main names#ace in interacti7e mode9
4ython creates a ne0 names#ace for storin$ any local names defined 0ithin the
function9
D@M@M'@D 4ython searches from local to $lobal for names6 but it doesnCt search from
$lobal to local9 3hat means $lobal names#aces donCt /no0 about the names
inside local names#aces9
3his beha7ior of 4ythonCs is useful for hidin$ com#le8ity9 &t also #re7ents bu$s that mi$ht
occur if all names 0ere automatically $lobal>if that 0ere true6 it 0ould be easy to use a
name t0ice 0ithout realizin$ it6 and une8#ected thin$s mi$ht ha##en9 When names are
automatically local6 they are less li/ely to conflict9
How local and "lobal names work with assi"nment
(ames are automatically local unless you tell 4ython to treat them as $lobal%9 3his
means that if you $i7e a name to a 7alue usin$ an eGuals si$n% inside a function6 0hen
you e8it the function6 4ython 0ill for$et about the name9 <ereCs a #ro$ram that
demonstrates this feature of names#aces usin$ ;rouchoCs famous sayin$9 Eou could ty#e
it into a te8t file and sa7e it 0ith the name gro-c2o"py)
+ gro-c2o"py
a$(ooA = "man,s (est friend"
print "o-tside of a dog, a (ooA is", a$(ooA
def a$dog)*!
a$(ooA = "too darA to read"
print "inside of a dog, it,s", a$(ooA
a$dog)*
print "9e,re (acA o-tside of t2e dog again"
print "and a (ooA is again", a$(ooA
Fi$ure --1- illustrates $lobal and local names9
-,2
Fi$ure --1-) A $lobal and a local name assi$nment9
&f 0e run the #ro$ram from the command line6 it has this out#ut)
D pyt2on gro-c2o"py
o-tside of a dog, a (ooA is man,s (est friend
inside of a dog, it,s too darA to read
9e,re (acA o-tside of t2e dog again
and a (ooA is again man,s (est friend
How local and "lobal names work with references
'ecause 4ython searches for names first locally and then $lobally6 you can reference a
$lobal name inside the function>assumin$ the function doesnCt contain a local name
thatCs the same as the $lobal name9 3his e8am#le #ro$ram 0e call it (rig2tdog"py% and
Fi$ure --12 sho0 that a function can access the name a$(ooA defined outside the
function)
+ (rig2tdog"py
a$(ooA = "man,s (est friend"
print "o-tside of a dog, a (ooA is", a$(ooA
def a$(rig2t$dog)*!
print "inside of 0HG@ dog, a (ooA is still", a$(ooA
a$(rig2t$dog)*
-,"
Fi$ure --12) A $lobal name referenced locally9
3his code6 run on the command line6 #roduces the follo0in$ result)
D pyt2on (rig2tdog"py
o-tside of a dog, a (ooA is man,s (est friend
inside of 0HG@ dog, a (ooA is still man,s (est friend
3@:<(&:A.
S3?FF
Eou can also define a function inside another function9 3his creates a
ne0 local names#ace for the nested function9 3his names#ace is
called a nested scope. (ested sco#es are mostly useful for functional
#ro$rammin$9 :ha#ter -6 has some information on functional
#ro$rammin$9% (ested sco#es 0or/ differently in 4ython 29- and
later than they 0or/ in earlier 7ersions9 We donCt co7er them in this
boo/9
Think globally! act locally
&tCs easy to e8#licitly tell a function that a name is $lobal) Eou Fust use the /ey0ord
glo(al 0ith the name9 &n the e8am#le #ro$ram belo06 0hich 0e call colors"py6
definin$ the name eggcolor as $lobal allo0s the function to chan$e the 7alue of that
name6 and the chan$ed 7alue remains in effect after 4ython e8its the function9 &n contrast6
the name meat6 0hich isnCt declared $lobal6 is chan$ed only inside the function9
+ colors"py
eggcolor = "green"
meat = "2am"
print eggcolor, "eggs and", meat
def (reaAfast)*!
glo(al eggcolor
eggcolor = "red"
meat = "(acon"
print eggcolor, "eggs and", meat
(reaAfast)*
-,!
print eggcolor, "eggs and", meat
&f you run this code on the command line6 you $et the follo0in$ result)
D pyt2on colors"py
green eggs and 2am
red eggs and (acon
red eggs and 2am
D@M@M'@D &tCs usually a 'ad &dea to use $lobal names because they are more li/ely to
cause name conflicts in com#le8 #ro$rams9
Sorting out odule naespaces
@ach module a file 0ith 4ython code6 endin$ in "py% has its o0n names#ace9 All the
functions defined in the module use the moduleCs names#ace as their $lobal names#ace9
3he functions 0onCt loo/ else0here e8ce#t for the built1in names#ace% for names that are
referenced 0ithin them9 3his means that the author of a module can use $lobal names in a
module 0ithout 0orryin$ about their conflictin$ 0ith $lobal names used else0here9 &n
other 0ords6 0hene7er you see I$lobalI used in 4ython6 thin/ Imodule $lobal9I
3i# For more about modules6 see :ha#ter -29
When a module im#orts another module6 the im#orted moduleCs name becomes #art of
the im#ortin$ moduleCs names#ace9 Eou can then access its functions and other
information by usin$ the module name6 a dot6 and the function name6 the same 0ay you
can 0hen you im#ort a module into interacti7e mode9
&ma$ine you ha7e a module called mymod"py that does nothin$ but im#ort another
module)
+ mod-le ,mymod,
import mat2
&f you im#ort this module into interacti7e mode6 you can #rint the mat2"pi constant by
ty#in$ this code)
>>> import mymod
>>> mymod"mat2"pi
3"/./&=2<&3&=
'ut the name mat2 and its constant pi are /no0n only inside the module9 3he
surroundin$ names#ace of interacti7e mode still doesnCt /no0 about the mat2 module)
>>> print mat2"pi
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
1ame6rror! name ,mat2, is not defined
3@:<(&:A.
S3?FF
&tCs #ossible to mani#ulate a moduleCs $lobal names by usin$ the
same notation used to refer to its functions6 modulename.itemname9
-,A
Eou should do this only if you /no0 0hat youCre doin$9 &tCs an
ad7anced feature 0e donCt co7er in this boo/9%
#hapter .7, Buildin" Applications with
4odules and acka"es
4ython #ro7ides 0ays to or$anize code into files and directories)
'odules are the files that contain the buildin$ bloc/s and $lue of your #ro$ram6
includin$ functions6 import statements6 classes6 and so on9
Packages or$anize modules in directory hierarchies that hel# users understand
ho0 e7erythin$ 0or/s to$ether9
3his cha#ter sho0s you ho0 you can use modules and #ac/a$es to or$anize your #roFects
and ta/e ad7anta$e of all the tools a7ailable for 4ython9
4odular -ivin", !torin" %our #ode in 'iles
4ython stron$ly encoura$es you to or$anize function definitions and other statements in
se#arate files9 3hese files are called modules. A module is a te8t file containin$ 4ython
definitions and statements9 3he filename is the module name 0ith the suffi8 "py
a##ended9
3@:<(&:A.
S3?FF
Some 4ython modules are 0ritten in lan$ua$es other than 4ython6
most commonly : or :NN9 Such a module is called an e!tension
module.
&n the follo0in$ sections6 0e $i7e you the lo0do0n on creatin$ your o0n modules6
$ettin$ access to the modules that come 0ith 4ython6 and usin$ modules in your
#ro$rams9
3@:<(&:A.
S3?FF
Better codin" throu"h modularity
Modules ha7e se7eral benefits that let you code more efficiently and
s#end less time stom#in$ bu$s)
4odules save time.
Eou can 0rite code once and use it in many #ro$rams9
4odules hide complexity.
-,6
@ach module creates its o0n names#ace6 so its names 0onCt
conflict 0ith names defined else0here9
4odules make debu""in" easier.
Storin$ chun/s of code in modules ma/es it #ossible to 0rite
shorter #ro$rams9 4ythonCs debu$$in$ tools s#ecify 0hich
module an error is found in9
Iporting a odule or its contents
3o access a moduleCs code6 you im#ort the module into either
Interactive mode
3i# &m#ortin$ a module in interacti7e mode is co7ered in :ha#ter 29
Another ython pro"ram
'oth these 0ays of im#ortin$ are similar9 3he only difference is 0here you ty#e
the import statement9
3he follo0in$ sections co7er ho0 to im#ort a module6 0hat 4ython does 0hen you
im#ort a module6 and 0ays of accessin$ the $oodies in a module9
Importin" a module
3o im#ort a module in interacti7e mode6 or in another 4ython #ro$ram6 ty#e import
follo0ed by the name of the module 0ithout the "py suffi86 li/e so)
import mod-lename
Initiali)in" a module
&m#ortin$ a module for the first time in a #articular #ro$ram6 or in interacti7e mode6
causes 4ython to #erform a series of actions called initiali2ing the module9 <ereCs ho0
initializin$ 0or/s)
-9 4ython creates a module names#ace that stores the names defined in the module9
29 4ython runs the code in the module9
"9 4ython stores the name of the module in the local names#ace9
3@:<(&:A.
S3?FF
&nitializin$ ha##ens only the first time the module is im#orted9 &f you
im#ort the module a$ain6 the module code doesnCt run6 but the im#ort
u#dates the current names#ace9
-,+
Accessin" functions and other items inside a module
When you im#ort a module6 all the functions and other information in the module
collecti7ely called the moduleCs attributes% are a7ailable to you9
3o access a module attribute6 ty#e the module name6 a dot6 and the attribute name9 &f you
are callin$ one of the moduleCs functions see :ha#ter --% or creatin$ a class instance see
:ha#ter -"%6 also #ass any ar$uments that are reGuired9 For e8am#le)
mymod-le"myf-nction)x*
3@:<(&:A.
S3?FF
(ther ways of accessin" module attributes
Eou can im#ort attributes from a module into the local names#ace
directly by usin$ one of the follo0in$ lines of code)
3o im#ort a s#ecific item directly6 ty#e from6 the module
name6 import6 and the item name6 as sho0n)
from mymod-le import myf-nction
3o im#ort all of a moduleCs functions directly6 ty#e from6 the
module name6 import6 and an asteris/ ;%6 a 0ildcard
character that stands for Iall9I For e8am#le)
from mymod-le import ;
Warnin$5 Most of the time itCs a 'ad &dea to use the import ; synta8
because
Eou canCt control 0hat youCre im#ortin$9
Eou ris/ #ollutin$ the local names#ace 0ith all the names
from the im#orted modules6 0hich ma/es debu$$in$ much
more difficult9
When you access module attributes throu$h the module name6 youCre
less li/ely to run into conflicts bet0een the names inside one module
and the names inside another module9 And your code 0ill be easier to
read9
For e8am#le6 you mi$ht ha7e t0o modules that each ha7e a function
to combine t0o 7alues in some 0ay9 &f each moduleCs function 0ere
named com(ine)*6 then if you tried to access each of these functions
directly6 you mi$ht accidentally use the 0ron$ one6 or readers of your
code mi$ht not /no0 0hich function you 0ere usin$ at any #articular
time9 'ut if you al0ays use mod-lename"com(ine)*6 then 0hich
function youCre usin$ is clear9
3hereCs one situation6 ho0e7er6 0hen itCs a##ro#riate to im#ort an
item from a module directly9 3hatCs 0hen a module is a 0ra##er
-,,
around a sin$le class or function9 For e8am#le6 the module
c@tringGJ contains a sin$le function called @tringGJ)*9 See
:ha#ter -* for details9% 3he sim#lest 0ay to use @tringGJ)* is to
im#ort it 0ith this line of code)
from c@tringGJ import @tringGJ
3i# &f you donCt remember the names of the functions inside a module6 use the dir)*
command in interacti7e mode to list them6 li/e this)
>>> dir)mymod-le*
Gi$ing a local nae to a odule
&n this section6 you find out t0o 0ays to $i7e a local name to a module or a moduleCs
functions) Eou can $i7e an e8tra name to a module or function6 or you can $i7e a module
a different name 0hen you im#ort it9
3his section also e8#lains the difference bet0een $i7in$ an e8tra name to a function and
callin$ the function 0hile $i7in$ a name to its result9
+ivin" an extra name to a module or function
3o $i7e an e8tra name to a function or module so that both names refer to the same
thin$%6 first ma/e sure the obFect has been im#ortedH then ty#e the ne0 name6 =6 and the
name of the function or module6 li/e this)
myf-nction = tinymod-le"tinyf-nction
Importin" a module usin" a different name
3o im#ort a module but not a function% usin$ a different name6 ty#e import6 the module
name6 as6 and the name you 0ant to use9 For e8am#le)
import tinymod-le as mymod
3i# Althou$h itCs not common6 you can also combine the from import and import as
synta86 as follo0s)
from tinymod-le import myf-nction as a$f-nction
D@M@M'@D &f you im#ort a module usin$ a different name6 the local names#ace 0onCt
/no0 the real module nameH it 0ill /no0 the module only by the name
you used to im#ort it9
D@M@M'@D 3he synta8 for $i7in$ a local name to a function is different from the
synta8 for callin$ a function and $i7in$ a name to the result9 When you
call a function6 you add #arentheses at the end of the function name)
-,*
myres-lt = tinymod-le"tinyf-nction)2*
/ules for &riting and naing odules
3he same rules a##ly to namin$ modules that a##ly to namin$ other 4ython obFects)
<y#hens and s#aces arenCt allo0ed6 and you canCt use a 4ython /ey0ord as the name9 &f
you do any of these thin$s6 youCll $et errors9
3he 4ython community uses the follo0in$ con7entions for 0ritin$ modules9 3he
con7entions ma/e 4ython code more standard and easier to read)
4odules have short, lowercase names.
4odules that exist mostly to export a sin"le class are named after the class.
&n this case6 the module and class ha7e the same name6 but the module name is
lo0ercase and the class name is ca#italized9
All import statements come at the be"innin" of a module.
The name of a non1public module 5or function, class, method, name, or
attribute6 should be"in with a sin"le leadin" underscore.
For e8am#le)
$my1onC-(licod-le
A non1#ublic name is not im#orted 0hen you ty#e from modulename import ;6
althou$h you can still im#ort it e8#licitly9 See :ha#ter -" for more about non1
#ublic names9
Warnin$ A7oid $i7in$ your module file the same name as a standard 4ython module9
Mther0ise6 the 0ron$ module mi$ht be im#orted9
(odule! odule! &here is the odule;
4ython /ee#s trac/ of module files and other files it needs in se7eral 0ays9
Mn most o#eratin$ systems6 the CP0HJ1CL0H en7ironment 7ariable lists the #aths
directories or folders% 0here 4ythonCs modules are stored9 CP0HJ1CL0H uses the same
format as the shell 7ariable CL0H9 3he format de#ends on the o#eratin$ system you are
usin$9 For e8am#le6 on ?(&O or Mac MS6 4ython mi$ht be installed in
8-sr8li(8pyt2on8 or 8-sr8local8li(8pyt2on89 Mn Windo0s it mi$ht be installed in
H!ZCrogram >ilesZCyt2on2&9
When you im#ort a module6 4ython searches #ossible module locations in the follo0in$
seGuence until 4ython finds a file 0ith that name and the suffi8 "py)
-*0
-9 3he current directory
29 3he directories listed in CP0HJ1CL0H
"9 3he directories in the 4A3< en7ironment 7ariable 0hich de#ends on your
o#eratin$ system and account setu#%
All the search #aths that 4ython /no0s are stored in the list sys"pat26 0hich is #art of
the sys module9 3his list stores these #ath names)
3he directory containin$ the in#ut scri#t or the current directory%
3he contents of the CP0HJ1CL0H 7ariable
3he default search #ath
3o modify sys"pat26 you use list methods9 Eou need to im#ort the sys module first9 3he
follo0in$ e8am#le a##ends a #ath to sys"pat2)
>>> import sys
>>> sys"pat2"append),8-fs8g-ido8li(8pyt2on,*
Warnin$ 'e careful not to remo7e im#ortant directories such as the directory in 0hich
4ython is installed6 or any subordinate directories% from the search #ath6 or
4ython may lose trac/ of its modules9
%inding &hat"s in standard odules
4ython comes 0ith a library of standard modules9 Many of these modules are co7ered in
4art &B and else0here in this boo/9
3i# &f you 0ant to find out the $ory details about any of the standard modules that 0e
donCt co7er6 see the 4ython .ibrary Deference at htt#)LL0009#ython9or$ itCs usually
also included 0hen you install 4ythonH instructions for installin$ 4ython
documentation are in A##endi8 A%9
3he built1in function dir)* returns a sorted list of the names a module defines9 3o use it6
ty#e dir follo0ed by the module name in #arentheses6 li/e this)
>>> dir)mod-lename*
3o $et hel# on a named item in a module6 ty#e 2elpH then ty#e in #arentheses% the
module name6 a dot6 and the item name9 For e8am#le)
>>> 2elp)mod-lename"f-nctionname*
-*-
*rappin" It &p in a acka"e
A #ac/a$e is a collection of related modules stored in a directory and subdirectories9 3his
section e8#lains 0hy #ac/a$es are useful6 the reGuirements for settin$ u# #ac/a$es6 and
the 0ays to im#ort #ac/a$es9
A NNnameNN is a NNnameNN, except when it's NNmainNN
Within a module6 the moduleCs name as a strin$% is stored in the $lobal name $$name$$9
'ut thereCs an e8ce#tion to this) &f the module file is run as a #ro$ram from the command
line6 4ython sets the moduleCs $$name$$ to ,$$main$$,9
3his feature is useful for includin$ code usually test code% in a module file that runs only
0hen you start the module from the command line by ty#in$ pyt2on modulename "py%9
3he code loo/s li/e this)
if $$name$$ == ,$$main$$,!
do something
When you include code that runs only under these circumstances6 you donCt ha7e to
remo7e the code 0hen you im#ort the module9 3hatCs because 0hen a module is
im#orted6 $$name$$ is the moduleCs name6 not ,$$main$$,9
3his code $oes outside any function definitions or im#ort statements in the module6
usually at the 7ery end of the module9
<ereCs an e8am#le of a small function and some test code for it9
def f)x*!
y = x;;x
ret-rn y
if $$name$$ == "$$main$$"!
print "testing""""
print "passing t2e 5al-e 2"
Q = f)2*
print "t2e f-nction ret-rns", Q
The purposes of packages
4ac/a$es are another 0ay of ta/in$ ad7anta$e of 4ythonCs ability to hide com#le8ity9
3i# 4ac/a$es ha7e some useful features)
-*2
A packa"e has its own namespace.
(ames defined 0ithin a #ac/a$e>includin$ module names>0onCt conflict
0ith names defined else0here9
acka"es can contain modules.
acka"es can contain subpacka"es.
4ac/a$es are ideal for storin$ and or$anizin$ a lot of related features9
/e3uireents for packages
3hese are the reGuirements and $uidelines for #ac/a$es)
A packa"e lives inside a directory, and its subpacka"es live inside
subdirectories of that directory 5"enerally speakin"6.
!tore the packa"e's main directory in either
o Mne of the t0o s#ecial #ac/a$e directories on your com#uter
o 3he directory of your a##lication
See IAbout s#ecial #ac/a$e directories6I later in this section9
0ust as a module file names the module, a packa"e directory names the
packa"e.
3hat allo0s you to im#ort items in the #ac/a$e by usin$ the import
packagename.modulename format9
A packa"e directory must contain a file called $$init$$"py9
&n the sim#lest case6 $$init$$"py is Fust an em#ty file9 'ut it often contains code
that initializes the #ac/a$e9 For e8am#le6 the best 0ay to im#ort s#ecific
submodules 0ith a #articular #ac/a$e or sub#ac/a$e is to load them in the
$$init$$"py file9
3he $$init$$"py file sometimes contains the $$all$$ list see ne8t item%9
Include an index of your packa"e's contents in a list named $$all$$9
3his list hel#s 4ython code run on different o#eratin$ systems9 When you include
module names in $$all$$6 the command from packagename import ; im#orts
only those modules9
3@:<(&:A.
S3?FF
&f no one 0ill e7er import ; from your #ac/a$e6 you donCt
need the list9
-*"
About special packa"e directories
When 4ython is installed6 it sets u# s#ecific directories for #ac/a$es9 &f you store
#ac/a$es in one of these s#ecial #ac/a$e directories6 youCre less li/ely to run into trouble
if your #ac/a$e names are the same as module names else0here on the 4ython #ath9
3here are t0o s#ecial directories for #ac/a$es)
li(8site7pyt2on8
3his directory is for #ac/a$es that 0or/ the same 0ay 0ith all 4ython 7ersions9
li(8pyt2onXX8site7pacAages8
3his directory is for #ac/a$es that de#end on the 4ython 7ersion9 55 chan$es to
re#resent the 4ython 7ersion number9
2xample packa"e structure
<ereCs an e8am#le structure for a #ac/a$e that handles $ra#hics9 More #ac/a$e hel# is
a7ailable at htt#)LL0009#ython9or$LdocLessaysL#ac/a$es9html9
grap2ics8 0op7le5el pacAage
$$init$$"py GnitialiQe t2e grap2ics pacAage
formats8 @-(pacAage for file format con5ersions
$$init$$"py
gifread"py
gif9rite"py
"""
effects8 @-(pacAage for grap2ics effects
$$init$$"py
specAle"py
s9irl"py
in5ert"py
"""
filters8 @-(pacAage for filters
$$init$$"py
noise"py
masA"py
"""
Iporting ites fro packages
Eou can im#ort items from #ac/a$es in se7eral 0ays9
3@:<(&:A.
S3?FF
&m#ortin$ 0ith #ac/a$es 0or/s in much the same 0ay as im#ortin$
0ith modules6 e8ce#t that you sometimes ha7e to include more le7els
of names9
-*!
Individual modules and packa"es
Eou can im#ort indi7idual modules and #ac/a$es in a cou#le of 0ays6 de#endin$ on ho0
they 0ill be used in your #ro$ram9
Importing !y %ull name
&f youCll be usin$ many #arts of a com#le8 #ac/a$e6 use the follo0in$ format to im#ort an
indi7idual item by its full name)
import grap2ics"effects"in5ert
3his ty#e of #ac/a$e im#ort statement has a cou#le of rules)
@ach name e8ce#t for the last must be a #ac/a$e9
3he last name must be a module or a #ac/a$eH it canCt be a class6 function6 or
named obFect attribute%9
3@:<(&:A.
S3?FF
3o call a function from a module im#orted by its full name6 ty#e the
full name of the module and then the function name6 li/e this)
grap2ics"filters"noise"edges)args*
Import !y using %rom
&f youCll be usin$ only a fe0 #arts of a #ac/a$e6 use the follo0in$ format to im#ort an
indi7idual item by its full name)
from grap2ics"filters"noise import edges
3i# 3his format 0or/s for im#ortin$ any of the follo0in$ obFects defined in the #ac/a$e)
submodule, subpackage, function, class, and named ob-ect.
<ere are a cou#le of e8am#les of im#ortin$ an indi7idual item)
3he follo0in$ e8am#le im#orts the noise module)
from grap2ics"filters import noise
&f you im#ort noise this 0ay6 you use this code to call its function)
noise"edges)args*
3he follo0in$ e8am#le im#orts the edges)* function)
from grap2ics"filters"noise import edges
&f you im#ort edges)* this 0ay6 you use this code to call it)
edges)args*
-*A
Import all items from a packa"e
&f youCre sure that it 0onCt cause names#ace conflicts for e8am#le6 if youCre usin$ one
small #ac/a$e in your #ro$ram and not im#ortin$ other modules or #ac/a$es%6 use the
follo0in$ format to im#ort all the items from a #ac/a$e)
from grap2ics import ;
?sin$ import ; im#orts the items in the $$all$$ list9
3@:<(&:A.
S3?FF
&f no $$all$$ list is defined6 the import ; statement im#orts these
names from the #ac/a$e)
3he #ac/a$e name
(ames found in import statements in the file
(ames of modules and sub#ac/a$es but not submodules%
(ames defined in $$init$$"py files
3he import ; statement does not im#ort any names 0ith a sin$le underscore #refi8 for
e8am#le6 $mymod-le%9
When #ac/a$es contain sub#ac/a$es6 thereCs no shortcut to refer to submodules of siblin$
#ac/a$es #ac/a$es defined at the same le7el%9 Eou need to use the full name of the
sub#ac/a$e packagename.subpackagename%9 4ython 29A has a shortcut for im#ortin$
from siblin$ modules9 3he shortcut is #art of the absolute im#ortin$ feature6 0hich is
co7ered in the follo0in$ section9
Absolute imports in ython 7.B
&n 4ython 29! and earlier6 ty#e the 0hole #ac/a$e and sub#ac/a$e hierarchy 0hen you
im#ort from a #ac/a$e for e8am#le6 from grap2ics"filters import noise%9 &f you
donCt6 someone readin$ your im#ort statement has no 0ay of /no0in$ 0hether it im#orts
another module from the #ac/a$e or a to#1le7el #ac/a$e thatCs #art of the 4ython
distribution9
3@:<(&:A.
S3?FF
Althou$h itCs #ossible to use relati7e im#orts in 4ython 29! and
earlier6 the rules are too com#licated to document in this boo/9
Absolute im#ortin$6 ne0 in 4ython 29A6 addresses this #roblem9 3hereCs no ambi$uity
about 0hich module is bein$ im#orted because 4ython searches for im#orted modules or
#ac/a$es on sys"pat2 only9 3o im#ort siblin$ modules in a #ac/a$e6 use relati7e im#orts
see the follo0in$ section%9 3o access absolute im#ortin$6 ty#e this code into your module
or into interacti7e mode)
from $$f-t-re$$ import a(sol-te$import
-*6
/elative imports in ython 7.B
When you turn on absolute im#ortin$ in 4ython 29A by usin$ from $$f-t-re$$ import
a(sol-te$import%6 ne0 synta8 is a7ailable for im#ortin$ other modules in the #ac/a$e
directory your module is in9 Follo0 these rules)
?se the fromMimport synta89
3y#e one or more dots in front of the name of the #ac/a$e or module youCre
im#ortin$ from)
o 3he first dot stands for the current moduleCs #ac/a$e9
o 3he second dot stands for the #ac/a$e containin$ the current moduleCs
#ac/a$e the #arent #ac/a$e%9
o 3he third dot stands for the #arent of the #arent6 and so on9
<ere are some relati7e im#ort statements9 &f you 0rite the s9irl"py module in the
#ac/a$e hierarchy described in I@8am#le #ac/a$e structure6I in this cha#ter%6 you
im#ort other modules in the #ac/a$e as follo0s)
3his statement im#orts s9irl"py Cs siblin$ module6 specAle"py)
from " import specAle
3his statement im#orts the gifread module)
from "formats import gifread
3his statement im#orts the edges)* function from the noise module in the
filters #ac/a$e)
from "filters"noise import edges
#hapter .$, +ettin" #lassy
(verview
3his cha#ter is about classes, a tool for creatin$ ne0 ty#es of obFects in 4ython9 When
you create a class6 you #ut data also called state% and beha7ior in one suitcase9 4ro$rams
based on these suitcases of data1#lus1beha7ior are easily customized9
4ython also uses classes to or$anize many of its o0n features9 For e8am#le6 4ythonCs
built1in data ty#es6 such as strin$s and lists6 are classes9 3he use of classes hides
com#le8ity from users 0ho donCt care about it9 Eou can use a list 0ithout 0orryin$ about
ho0 lists 0or/6 and you can #erform an action such as sortin$ a list 0ithout 0orryin$
about ho0 sortin$ 0or/s9 And if you e7er had to 0rite a sort function6 you /no0 thatCs a
$ood thin$9%
&n this cha#ter6 you find out ho0 to create and use these 4ython obFects)
-*+
:lasses6 subclasses6 and su#erclasses
:lass methods
:lass instances
:lass and instance attributes
Eou also find out 0hy classes are im#ortant to 4ythonCs modular desi$n9
Alley1((< !ome (b>ect1(riented ro"rammin"
#oncepts
4ython is a lan$ua$e that su##orts ob-ect-oriented programming OOP for short%9 &n MM4
#arlance6 ob-ects are bundles of data and actions methods% that o#erate on the data9 MM4
#ro$rams are built around such bundles9
3@:<(&:A.
S3?FF
&n contrast6 lan$ua$es such as : focus on procedural programming,
and the SchemeL<as/ell lan$ua$es focus on functional
programming. 4ython is a balanced lan$ua$e 0ith $ood su##ort for
both #rocedural and MM4 styles and some su##ort for functional
#ro$rammin$9
MbFects and functions arenCt mutually e8clusi7e>in 4ython6 methods are Fust functions
attached to obFects9 'ut considerin$ a #ro$ram in terms of dataLaction bundles is a
different a##roach than creatin$ data obFects and then usin$ se#arate actions on them9
We donCt describe obFect1oriented #ro$rammin$ in detail in this boo/6 but the follo0in$
conce#ts are im#ortant for understandin$ 4ython classes9
0b'ects
&n obFect1oriented #ro$rammin$6 an ob-ect is a thin$ that bundles data and beha7ior9
3o use a real10orld e8am#le6 ima$ine you ha7e a do$ you mi$ht not ha7e to ima$ine%9
3he do$ belon$s to a breed9
D@M@M'@D &f the do$ 0ere a 4ython obFect6 the breed 0ould be its type or
class9 As sho0n in I?sin$ multi#le inheritance6I later in this
cha#ter6 you can e7en create ImuttI ty#es9
3he do$ has characteristics associated 0ith it) its name6 a$e6 and so on9
D@M@M'@D &f the do$ 0ere a 4ython obFect6 these characteristics 0ould be its
data attributes9
3he do$ can do actions>run6 sit6 bar/6 mutilate shoes6 and so on9
D@M@M'@D &f your do$ 0ere a 4ython obFect6 these 0ould be its method
attributes. All of the attributes I$o 0ithI the do$ 0here7er it $oes9
-*,
.i/e0ise in 4ython6 if you ha7e an obFect>say6 a list>you use the name of the s#ecific
list obFect to access both
&ts data the items in the list%
3he actions that list obFects can do slice6 a##end6 and so on%
Inheriting! o$erriding! and extending
Subclasses inherit beha7iors6 abilities6 and #ro#erties from the $eneral parent% classes
they are based on9 For e8am#le6 .abrador Detrie7ers are a subclass of all do$s and inherit
the #ro#erties and abilities of do$s9
When a subclass chan$es the 0ay a #arent class 0or/s or chan$es its data attributes6 the
subclass is overriding the #ro#erties of the #arent class9 3he .ab is $entler than some
other /inds of do$s6 so a .ab class mi$ht be said to override the $entleness Guality of
do$s in $eneral9
When your subclass includes ne0 data or methods6 it is e!tending the #ro#erties of the
#arent class9 A .ab has the built1in s/ill of retrie7in$9 A .ab class mi$ht be said to e!tend
the abilities of do$s to include retrie7in$9
3i# Mne 0ay to thin/ of inheritance is to use the #hrase is a. A .ab is a do$H that means a
.ab inherits #ro#erties and abilities of do$s9
Polyorphis and duck+typing
&n some lan$ua$es6 a sin$le function or method 0or/s only 0ith s#ecific ty#es of obFects9
&n 4ython6 many tools 0or/ 0ith more than one ty#e of obFect9 For e8am#le6 the in
/ey0ord 0hich calls the s#ecial method $$contains$$)*% acts on lists6 tu#les6 and
dictionaries>obFects of different ty#es9 3his feature is called polymorphism9
4irror, mirror on the wall, what's the ob>ect of this allC
4ython terminolo$y $ets a little confusin$ at times6 es#ecially 0ith all the different thin$s
that the 0ord ob-ect can stand for9 &n 4ython6 the 0ord ob-ect refers to any item in a
4ython #ro$ram that has its o0n stora$e s#ace>from a sim#le name to a multi1me$abyte
dictionary or any of its elements% to a function6 module6 class6 or instance9 'ut in obFect1
oriented #ro$rammin$6 the 0ord ob-ect refers to any item that combines data and
beha7ior9 3hese items alon$ 0ith other items% are also obFects in 4ython9 S#ecifically6
they are called classes%or class ob-ects% and instances or instance ob-ects%9 Any
obFections2
4ythonCs #olymor#hism is based on names9 For e8am#le6 file obFects ha7e three basic
methods named read)*6 9rite)*6 and close)*9 &f you create a class that has those three
-**
methods6 then e7en thou$h your class isnCt officially a file obFect6 you can use instances
of your class in many of the #laces that 4ython e8#ects a file obFect9 4ythonistas often
call this feature duck-typing because itCs li/e the sayin$6 I&f it loo/s li/e a duc/ and
Guac/s li/e a duc/6 it must be a duc/9I &n #ro$rammin$ terms) &f this obFect has the
attributes of a file and the read)*6 9rite)*6 and close)* methods of a file6 the #ro$ram
acce#ts it in cases 0here the data ty#e file is called for9
?ow #lass, for Instance @
&n this section6 0e e8#lain ho0 classes fit in 0ith other 4ython obFects and6 in $eneral
terms6 ho0 classes and class instances 0or/ to$ether9 3hese are the most im#ortant thin$s
to remember)
A class is a $eneral descri#tion of somethin$9
A class instance is a s#ecific e8am#le of 0hat the class describes9
&n order to do thin$s 0ith a class6 you usually need to create an instance9
#lasses! odules! and functions
4ython classes are similar to 4ython modules and functions in these 0ays)
:lasses6 modules6 and functions all contain assi$nments and statements9
'oth classes and modules usually include function definitions>code bloc/s that
be$in 0ith a def statement and #erform some action9 &n classes6 these are called
methods rather than functions9%
:lasses6 modules6 and functions all ha7e their o0n names#aces9
Eou call classes and functions by usin$ the name follo0ed by #arentheses9 :allin$
a class does one thin$) &t creates an instance of the class9
A class is like a teplate
A class is a tem#late for data and beha7ior9 Eou use the tem#late to ma/e s#ecific obFects
called instances. 3he instances share the attributes of the class9
Say you ha7e a co#y of the American =ennel :lub breed standard for a .abrador
Detrie7er9 3he A=: document is li/e a class because it describes the Gualities and
abilities a .ab has9 3he data attributes for the .ab breed>its coat Guality6 size6 eye color6
and so on>are described in the class6 and so are the method attributes>its ability to
retrie7e6 to s0im6 and so on9
A 4ython class definin$ a .abrador Detrie7er mi$ht include this code)
class 3a(!
9eig2t = <% + data attri(-te
def retrie5e)self, t2ing*! + met2od attri(-te
ret-rn)t2ing*
200
(ote that the A=: breed standard isnCt a do$6 it is Fust a descri#tion of the do$9 .i/e0ise6
in 4ython6 the class isnCt the actual obFect you mani#ulate9 3o 0or/ 0ith the class6 you
first tell the class to create an instance9 3his is 0here our e8am#le brea/s do0n>you
canCt use the A=: breed standard document to create a do$H you need a cou#le of other
do$s for that5%
Tellin" the difference between a class ob>ect and a function ob>ect
3he 0ay you create a class instance loo/s su#erficially similar to the 0ay you name the
result of a function9 &n fact6 if you donCt /no0 0hether the obFect is a class or a function6
you mi$ht not be able to tell 0hich is bein$ used by loo/in$ at the assi$nment9 :lasses
freGuently do not ta/e ar$uments6 and functions usually do6 but this isnCt uni7ersally true9%
>>> fido = 3a()* + creating a class instance
>>> y = len),mystring,* + calling a f-nction
3o determine 0hat /ind of obFect is associated 0ith a name6 use the type)* function6 li/e
this)
>>> type)fido*
#type ,instance,>
>>> type)y*
#type ,int,>
>>> type )3a(*
#type ,classo(T,>
>>> type)len*
#type ,(-iltin$f-nction$or$met2od,>
(ote that a function can return an instance9
>>> def foo)*!
""" ret-rn 3a()*
"""
>>> type)foo)**
#type ,instance,>
An instance is a copy ade fro the teplate
An instance is a s#ecific obFect6 0ith its o0n name6 that has the same attributes as the
class you use to create it9
3i# &f you $et a .ab from the animal shelter and name her 4ilot6 then your do$ is li/e an
instance of the .abrador Detrie7er class9 She has her o0n name6 but she shares the
attributes of .abrador Detrie7ers in $eneral9
So if you 0ere to describe 4ilot in 4ython code6 you 0ould ty#e this6 0hich creates an
instance pilot% of the 3a()* class)
20-
>>> pilot = 3a()*
All about class and instance attributes
@ach thin$ that you name inside a class6 0hether itCs a method6 data6 or some other /ind
of code6 is an attribute of the class9
D@M@M'@D When you create an instance of the class6 it starts 0ith the same attributes
as the class9 Eou can add or alter instance attributes after that9
3o see the 7alue of a class or instance data attribute6 ty#e the class or instance name
follo0ed by a dot and the attribute name6 li/e this)
>>> 3a("9eig2t
<%
>>> pilot"9eig2t
<%
?se the same code to see ho0 4ython internally identifies a method attribute)
>>> 3a("retrie5e
#-n(o-nd met2od 3a("retrie5e>
>>> pilot"retrie5e
#(o-nd met2od 3a("retrie5e of #$$main$$"3a( instance at %x<23%%>>
3i# MbFect1oriented #ro$rammers say that 3a( has a 0ei$ht and has a retrie5e)*
method9 See the sidebar6 IWhen (ot to ?se &nheritance6I later in this cha#ter9
4akin" and #allin" #lasses
3he follo0in$ sections co7er the synta8 of 0ritin$ a class6 callin$ a class to create an
instance6 and usin$ a method 7ia an instance9 3hese6 alon$ 0ith assi$nin$ and chan$in$
attributes discussed in the #re7ious section%6 are the most common class and instance
tas/s9
&n this section6 0e use the follo0in$ e8am#le class)
class 1ame0ag!
def $$init$$)self, myname*!
self"myname = myname
def say)self*!
print "Hello, my name is", self"myname
202
#reating a class
3o 0rite the first line of a class definition6 ty#e class6 the name of the class6 and a colon6
li/e this)
class 1ame0ag!
3i# 'y con7ention6 class names are ca#italized and ha7e embedded ca#s9 'y contrast6
function and method names are usually all lo0ercase9 3his ma/es it easier to tell at a
$lance 0hich obFect is bein$ used at a #articular #oint in a #ro$ram9
*ritin" an NNinitNN56 method
Most classes ha7e an $$init$$)* method9 3his method runs 0hen you ma/e an instance
of a class9 &t s#ecifies ho0 many ar$uments the instance needs and #uts the instance into
a /no0n initial state9
"ules
A fe0 /ey thin$s to /no0 about $$init$$)* methods)
The $$init$$)* method is a special method called an initiali/er9
&n 4ython6 s#ecial methods be$in and end 0ith t0o underscore characters9
It's conventional for the $$init$$)* method to come first in the class
definition.
The $$init$$)* method, like other methods, needs a self parameter 5which
stands for the instance6, plus any other parameters that the class needs to
create an instance.
0asi syntax
3o 0rite a basic $$init$$)* method that includes only the self #arameter6 follo0 these
ste#s)
-9 (n the line beneath your class definition header, indent four spaces.
29 Type def $$init$$)self*!
,rguments
Many classes reGuire you to #ass ar$uments 0hen you ma/e instances from them9
:reatin$ attributes for these #arameters in the $$init$$)* method lets other methods
access them easily9
3o 0rite an $$init$$)* method that includes #arameter attributes6 follo0 these ste#s)
20"
-9 (n the line beneath your class definition header, indent four spaces and type
this,
2" def $$init$$)self
"9 (n the same line, type a comma and the name of a parameter, like this,
." def $$init$$)self, myn#me
A9 /epeat !tep 7 for each parameter you want to include.
69 Type an end parenthesis and a colon, *!
Eour def statement mi$ht loo/ li/e this)
def $$init$$)self, myname*!
+9 +o to the next line and indent four spaces past the def statement.
,9 #reate an attribute for the first parameter by typin" self6 a dot, the name of
the attribute, an e=uals si"n, and the name of the parameter, like so,
=" def $$init$$)self, myname*!
/%" self.myn#me ! myn#me
--9 /epeat !tep E for each parameter in the def statement.
*ritin" more methods
3he $$init$$)* method usually $i7es the class only some initial information9 Most
classes also include methods that #erform actions9 Eou create methods by usin$ the def
statement6 e8actly the 0ay you 0rite a function9
3o 0rite a method6 follo0 these ste#s)
-9 4akin" sure to indent A spaces, type def6 the name of the method, and )self6
like this,
2" def say)self
3"
!9 5(ptional6 Type any additional parameters the method re=uires. !eparate
parameters with commas.
DonCt use attributes as #arameters>you access them throu$h self9
A9 2nd the line by typin" *!9
69 (n the next line, indent four more spaces and type the code for the function.
&f your code references class or instance attributes6 be sure to use the self"name
synta89
3his e8am#le code includes only the self #arameter9
def say)self*!
print "Hello, my name is", self"myname
ure selfishness
20!
When you 0or/ 0ith 4ython classes6 you encounter the name self a lot9
3he easiest 0ay to understand self is this) self stands for the instance that you create
from a class9 For e8am#le6 if you create an instance named pilot from the class named
3a()*6 self stands for pilot9
When you are 0ritin$ a class and you define a method in that class6 you need to e8#licitly
include the self #arameter in the method definition6 as in the e8am#le belo09 Mther0ise
the method 0ouldnCt ha7e any 0ay of /no0in$ 0hich instance to use9
class 1ame0ag!
def $$init$$)self, myname*!
self"myname = myname
When you $i7e a name to a 7alue in a method definition6 you use self" in front of the
name9 3he line self"myname = myname ma/es the myname #arameter automatically
a7ailable to other instance methods9 3hat means you can call those methods 0ithout
#assin$ myname as an ar$ument9 (ote the follo0in$ code)
def say)self*!
print "Hello, my name is", self"myname
&f this 0ere a function6 you 0ould ha7e to #ass myname as an ar$ument or else 4ython
0ould com#lain that myname isnCt defined9 'ut because itCs a method and youC7e already
defined self"myname in the $$init$$ statement6 the method can fi$ure out the 7alue of
myname by usin$ the self obFect9
3he self #arameter also ma/es life easier 0hen you create an instance9 4ython
automatically #asses the self ar$ument for you9 For e8am#le6 if you create an instance of
1ame0ag)*6 you only ha7e to $i7e it the 7alue of myname9 &t automatically uses the name
of the instance as the 7alue for self9
Static and class methods of ne01style classes 0or/ differently9 See the :ha#ter -! for the
lo01do0n on ne01style classes9
#reatin" other class attributes
Eou can #ut any /ind of code or assi$nment into a class9 Anythin$ inside a class that you
$i7e a name to becomes an attribute of the class9
For e8am#le6 0e could add a fa5orite$color attribute to our (ame3a$ class)
class 1ame0ag!
f#$orite_color ! %&l"e%
20A
3hen if 0e create an instance of the class6 the instance also has this attribute)
>>> grail$seeAer = 1ame0ag),lancelot,*
>>> grail$seeAer"fa5orite$color
,Il-e,
#reating an instance
3o create an instance of a class 0hich is also /no0n as calling a class%6 you $i7e it a
name6 and then ty#e the class name6 #arentheses6 and any #arameters9 Follo0 these ste#s)
-9 Type a name for the instance, followed by an e=uals si"n, like this,
2" 2ello =
"9 Type the class name and ( as shown,
." 2ello = '#me(#g(
A9 If your class re=uires parameters, include values or names for them. !eparate
parameters with commas.
&f you call the 1ame0ag class created in the #re7ious section6 you need to #ass a
7alue for one #arameter6 myname9
2ello = 1ame0ag),)rth"r,
69 Type *9
3he com#leted code loo/s li/e this9 3he instance name is 2ello9
2ello = 1ame0ag),Lrt2-r,*
#alling a ethod $ia an instance
After you ha7e created an instance by usin$ code li/e instance$name =
Hlass1ame)*%6 you can #erform the actions defined by the classCs methods9
D@M@M'@D 3o call a method 7ia an instance6 ty#e this on one line)
3he name of the instance
A dot
3he name of the method
A #air of #arentheses
4ass any needed ar$uments inside the #arentheses9
For e8am#le6 to call the retrie5e)* method of the pilot instance6 ty#e this code)
>>> pilot"retrie5e)"(all"*
,(all,
D@M@M'@D Eou canCt use this code to call the method by usin$ the name of the class
206
because the class is only a tem#late for the instance obFect9 An A=: breed
standard document canCt retrie7e a ball>only the actual do$ can9 <ereCs
0hat ha##ens if you try to call the method by usin$ the name of the class)
>>> 3a("retrie5e)"(all"*
0race(acA )most recent call last*!
>ile "#stdin>", line /, in V
0ype6rror! -n(o-nd met2od retrie5e)* m-st (e called 9it2 3a(
instance as first
arg-ment )got str instance instead*
3@:<(&:A.
S3?FF
3here is actually a 0ay to call a method by usin$ the name of a class9
3his is /no0n as calling an unbound method9 &tCs mostly an ad7anced
#ro$rammin$ techniGue6 but itCs also used to e8tend methods in
subclasses see I@8tendin$ su#erclass methods6I later in this
cha#ter%9 'riefly6 you create an unbound method by usin$ the name
of the class instead of the name of the instance for e8am#le6
3a("retrie5e rather than pilot"retrie5e%9 3o call it6 you #ass it
an instance name alon$ 0ith any other ar$uments the method
reGuires>for e8am#le6 3a("retrie5e)pilot, "(all"*9
*here did self "oC
Does somethin$ seem to be missin$ in the code for callin$ a class2 3he $$init$$)*
method in the class 1ame0ag has t0o #arameters>self and myname9 Why do you need to
#ass only one #arameter 0hen you create a class instance2
3he ans0er is that self is a s#ecial #arameter that essentially #asses itself Ibehind the
scenesI 0hen you use the class instance9 So you donCt ha7e to #ass self in this statement
althou$h there are some cases in 0hich you do%9 &n fact6 if you do #ass it in this
statement6 you $et an error)
>>> 2ello = 1ame0ag)self, ,Lrt2-r,*
0race(acA )most recent call last*!
>ile "#stdin>", line /, in V
1ame6rror! name ,self, is not defined
20+
+ettin" Inside the 'actory, How #lass and Instance
?amespaces Interact
A class and an instance each ha7e a names#ace6 0hich is stora$e for the names of obFects
that 4ython /no0s about9 When you create an instance of a class6 the instance has its o0n
names#ace6 but it also shares the classCs names#ace9
Whene7er 4ython encounters a name thatCs #art of an instance6 it loo/s for the 7alue first
in the instanceCs names#ace9 &f it canCt find the 7alue there6 it loo/s in the classCs
names#ace9
3i# Function names#aces and $lobal names#aces interact in similar 0ays9 See :ha#ter
--9
So anythin$ that you do to the class names#ace such as chan$in$ an attribute of the
class% is also reflected in the instance>e8ce#t 0hen the instance has already o7erridden
that 7alue from the class names#ace9 3he ne8t section sho0s ho0 it 0or/s9
#hanging the $alues of class and instance attributes
Eou can chan$e the 7alues of a classCs attributes9 When you create an instance of your
class6 you can also chan$e or override% the 7alues of any class attributes it inherits9 3he
effect these chan$es ha7e de#ends on 0hat data ty#es the attributes are6 ho0 you chan$e
the 7alues6 and in 0hat order you chan$e the 7alues9
When 0e first define our 3a( instance6 pilot6 it has the same 7alue for 9eig2t that the
3a( class defines)
>>> 3a("9eig2t
<%
>>> pilot"9eig2t
<%
#han"in" the value of the class attribute
3o chan$e the 7alue of the class attribute6 ty#e the class name6 a dot6 the attribute name6
=6 and a ne0 7alue6 li/e this)
>>> 3a("9eig2t = &%
Warnin$ :han$in$ a classCs attributes in code outside the class and es#ecially outside
the classCs module% ma/es your code hard to read and to debu$9
20,
#han"in" the value of the instance attribute
3o chan$e the 7alue of the instance attribute6 ty#e the instance name6 a dot6 the attribute
name6 =6 and a ne0 7alue6 li/e this)
>>> pilot"9eig2t = .&
2ffects of chan"in" attribute values
3he effects of chan$in$ attribute 7alues are as follo0s)
&f you chan$e the class attribute first6 the instance 7alue also chan$es)
>>> 3a("9eig2t = &%
>>> pilot"9eig2t
&%
&f you chan$e the instance attribute first6 the class 7alue does not chan$e)
>>> pilot"9eig2t = .&
>>> 3a("9eig2t
<%
Warnin$ &f the attribute is a mutable data ty#e6 such as a list6 and you use a
method that chan$es the attribute in #lace such as the append)* method
of lists>see :ha#ter ,%6 then chan$in$ the instance attribute does
chan$e the class attribute9 'e sure to o#erate only on co#ies of mutable
instance attributes or a7oid usin$ chan$e1in1#lace methods on them9
;i7in$ a ne0 7alue to the instance attribute overrides the 7alue it ori$inally $ets
from the class9 So if you chan$e the class attribute after you chan$e the instance
attribute6 the instance attribute does not chan$e9
>>> pilot"9eig2t
.&
>>> 3a("9eig2t = /%%
>>> pilot"9eig2t
.&
Adding an attribute to an instance
&n IMa/in$ and :allin$ :lasses6I earlier in this cha#ter6 0e describe ho0 to add an
attribute to a class6 and the #recedin$ section describes ho0 to chan$e the 7alue of a class
or instance attribute9 Eou can also add a data attribute and 7alue% to an instance that
youC7e created9 Just 0rite code li/e this)
>>> pilot"coat$color = "yello9"
D@M@M'@D 3his attribute is stored in the instanceCs names#ace6 so the class 0onCt
/no0 about this attribute6 as illustrated here)
>>> 3a("coat$color
0race(acA )most recent call last*!
>ile "#stdin>", line /, in V
Lttri(-te6rror! class 3a( 2as no attri(-te ,coat$color,
20*
#lass and Instance #onventions
4ython #ro$rammers use some im#ortant con7entions 0hen 0ritin$ and im#lementin$
classes9 4ython 0ill understand your code if you donCt use them6 but humans 0ho ha7e to
read your code and fi$ure out 0hat it does 0ill a##reciate your usin$ them9 Some
con7entions are as follo0s)
Modules that e8ist mostly to e8#ort a sin$le class should be named after the class9
:lass names be$in 0ith an u##ercase letter9 Attribute and method names be$in
0ith lo0ercase letters9
3he name self is used to refer to the name of a class instance9
3@:<(&:A.
S3?FF
A brief privacy note
When youCre 0ritin$ a class attribute6 you s#ecify that it is private by
namin$ it 0ith a sin$le leadin$ underscore9 ?nli/e #ri7ate attributes
in modules and #ac/a$es6 ho0e7er6 4ython doesnCt treat #ri7ate
attributes in classes in any s#ecial 0ay9 3he sin$le leadin$ underscore
is Fust a con7ention that says to #eo#le readin$ your code6 IdonCt
touch this5I 3hat is6 donCt try to re0rite it6 chan$e it6 or use it in any
0ay6 or else you mi$ht brea/ somethin$9%
4ri7ate attributes are most often used in lar$e class hierarchies but
you should use them any time you 0ant to inform users of your class
that this is not #art of the #ublic interface%9
&f you name a class attribute 0ith t$o leadin$ underscores6 that tells
4ython to use name mangling so that base classes and subclasses
canCt see the attribute unless they manually do the name man$lin$
themsel7es%9 3his is an ad7anced #ro$rammin$ tool because itCs hard
to use 0ith inheritance9
Attributes 0ith t0o leadin$ and t0o trailin$ underscores li/e
$$getattr$$% arenCt #ri7ate9 3hey are s#ecial methods discussed
earlier in this cha#ter%9
Some MM4 #urists deni$rate 4ythonCs #ri7acy mechanisms because
the #ri7acy mechanisms donCt enforce #ri7acy9 4ythonistas counter
that anyone 0ho really 0ants to brea/ #ri7acy can do it6 and itCs more
im#ortant to document thin$s>and then $et on 0ith your 0or/9 &n
$eneral6 4ythonistas say6 I4ython is a lan$ua$e for consentin$
adults9I 3hat is6 4ython usually 0onCt #re7ent you from doin$
somethin$ stu#id or com#le8 if you really 0ant to9%
2-0
Inheritin" the 'arm, (verridin" and 2xtendin" #lasses
Eou can chan$e the features of a class or create ne0 features by creatin$ a subclass or
child class% that inherits attributes from its #arent class and then chan$es some of the
attributes inherited from the #arent class9
3@:<(&:A.
S3?FF
:lasses that subclasses inherit from are called parent classes,
superclasses6 or base classes.
#reating a subclass
3o create a class that inherits from another class6 you ty#e class6 the name of the
subclass6 and then6 in #arentheses6 the name of the su#erclass the subclass inherits from9
3o create a subclass of the 1ame0ag class 0e 0or/ 0ith earlier6 you use a class statement
li/e this)
class SeeA1ame0ag)1ame0ag*!
3i# 4ython 29A adds a ne0 feature) classes 0ithout base classes can use em#ty
#arentheses the same 0ay functions can ha7e no ar$uments%9 3hat is6 you donCt ha7e
to s#ecify a su#erclass in the #arentheses9 For e8am#le6 you could Fust ty#e class
H)*!
&n $eneral6 0hen you create a subclass6 you create only 0hat you 0ant to o7erride or
e8tend about the su#erclassCs beha7ior9 So you donCt need to 0rite an $$init$$)*
statement unless you 0ant to ma/e chan$es to the su#erclassCs $$init$$)* statement9
0$erriding superclass ethods
3o create a subclass that o7errides a method of a su#erclass6 you 0rite a method 0ith the
same name as the su#erclass method you 0ant to o7erride6 and you $i7e this method
different beha7ior9
&n the follo0in$ e8am#le6 the subclass defines a say)* method that beha7es differently
from the su#erclassCs say)* method9
class SeeA1ame0ag)1ame0ag*!
def say)self*!
print "02e c-rrent 5al-e of my name is", self"myname
3i#
*hen not to use inheritance
&n some cases6 0ritin$ a subclass that inherits from a su#erclass isnCt the best
solution9 Su##ose you are #lannin$ a conference6 and you created a Begistration
class9 Eou mi$ht thin/ of ma/in$ Begistration inherit from 1ame0ag so you can
2--
use the say)* method9 'ut itCs better to ma/e a nameta$ attribute for the re$istration
class that uses 1ame0ag as a 7alue6 li/e this)
class Begistration!
def $$init$$)self, name*!
self"name = name
self"nametag = 1ame0ag)name*
?sin$ an attribute that refers to an instance of a different class is called ob-ect
composition9 Mne 0ay to describe 0hatCs $oin$ on in the abo7e e8am#le is to say that
an instance of the Begistration class has an attribute that is an instance of the
1ame0ag class9 3o #ut it in material10orld terms6 if you #roduce a bunch of
re$istration #ac/ets for a conference6 each #ac/et is li/e an instance of the
Begistration class6 and each #ac/a$e has a name ta$ in it6 0hich is an instance of
the 1ame0ag class9
<ereCs 0hat ha##ens 0hen you create an instance of the class and the subclass and call
each instanceCs say)* method)
>>> s-perclass$inst = 1ame0ag),3-cy,*
>>> s-(class$inst = SeeA1ame0ag),3in-s,*
>>> s-perclass$inst"say)*
Hello, my name is 3-cy
>>> s-(class$inst"say)*
02e c-rrent 5al-e of my name is 3in-s
,xtending superclass ethods
3here are t0o basic 0ays to e8tend su#erclass methods9 Eou can
@8tend a method that already e8ists in the su#erclass
Write a ne0 method that uses data from a su#erclass method
2xtendin" an existin" superclass method
@8tendin$ an e8istin$ method of a su#erclass is similar to o7erridin$6 e8ce#t that you
also call the su#erclass method in the e8tended code9 Eou e8tend a su#erclass method if
you 0ant the method to #erform as 0ritten and you also 0ant to mani#ulate its result in
some 0ay9
3o create a subclass that e8tends the methods of a su#erclass6 follo0 these ste#s)
-9 :efine a method with the same name as the superclass method you're
extendin".
2" class WeirdSreeting)1ame0ag*!
2-2
3" def say)self*!
!9 In that method's code, call the superclass method by typin" the super1class
name, a dot, the superclass method name, and its ar"ument in parentheses.
&" class WeirdSreeting)1ame0ag*!
<" def say)self*!
E" '#me(#g.s#y(self)
,9 erform some additional manipulations, either on the value returned by the
superclass method or on the subclass's instance data.
3he follo0in$ subclass e8tends the say)* method of 1ame0ag)
class WeirdSreeting)1ame0ag*!
def say)self*!
1ame0ag"say)self*
print self"myname"s9apcase)*
Eou mi$ht call it li/e this)
>>> greet = WeirdSreeting),0otoro,*
>>> greet"say)*
Hello, my name is 0otoro
tJ0JBJ
Addin" a new method
Eou 0rite a ne0 subclass method if you 0ant the subclass to add some com#letely ne0
beha7ior to a #arent class9 3he follo0in$ e8am#le creates a ne0 subclass of 1ame0ag and
also creates a method on the subclass that e8tends the #arent class by sa7in$ the 1ame0ag
data in a database9 Note: 3his code is incom#leteH it 0or/s only if a database file has
been created and o#ened9%
class Cersistent1ame0ag)1ame0ag*!
def sa5e)self*!
d("9rite)picAle"d-mps)self**
)sing ultiple inheritance
A class 0ith more than one su#erclass inherits its attributes from all its su#erclasses9 Such
a class uses multiple inheritance9
D@M@M'@D 3o 0rite a subclass that uses multi#le inheritance6 ty#e the names of more
than one su#erclass in a class statement9 For e8am#le)
class @-(Hlass1ame)@-perHlass/, @-perHlass2*!
And hereCs ho0 you 0ould create a ImuttI ty#e of do$ this do$ is #robably easier to
create as a 4ython class than in real life%)
class HeinQ&EOog)H2i2-a2-a, Srey2o-nd, astiff, Oalmatian*!
2-"
2aespace searching in classes and superclasses
Subclasses ha7e access to the names#aces of all the classes they inherit from9 When a
subclass inherits from #arent classes6 a names#ace hierarchy is created9 When other
classes not direct #arents of the subclass% $et into the act6 the names#ace structure is
called a frame$ork9
When you are 0or/in$ 0ith classes6 4ython searches for names in the follo0in$ order
and sto#s searchin$ as soon as it finds the name)
-9 &nstance
29 :lass
"9 Su#erclasses that the class inherits from
3i# 3his is similar to ho0 function and module names#aces 0or/>4ython searches the
functionCs local names#ace first6 and then the moduleCs $lobal names#ace6 and then
the main or built1in names#ace9
3his $i7es rise to the follo0in$ beha7iors)
Inheritin" from a sin"le superclass
3he names and definitions in a subclass or its instance o7erride the same names and
definitions in the su#erclass9
Inheritin" from multiple superclasses
When a class has more than one su#erclass6 4ython searches first the instance6 and then
the subclass6 as usual9 When 4ython starts searchin$ the su#erclasses6 it uses a method
called depth-first, left-to-right searching6 0hich searches in the follo0in$ order)
-9 .eftmost su#erclass in the class statement
For e8am#le6 in the class statement
0otallyIiQarreSreeeting)WeirdSreeting, 1ame0ag*6 searchin$ 0ould
be$in 0ith WeirdSreeting6 the leftmost su#erclass named9
29 Subclasses of the leftmost class
"9 (e8t class to the ri$ht in the class statement
!9 Subclasses of this class
A9 And so on S
<ere is a sim#le e8am#le)
class L!
def foo)self*!
2-!
print "foo called in L"
class I!
def foo)self*!
print "foo called in I"
def (ar)self*!
print "(ar called in I"
class H)L,I*!
pass
&f you im#ort the #recedin$ e8am#le into interacti7e mode6 hereCs 0hat you $et 0hen you
create an instance of H and use it9
-9 3he instance of H loo/s in class L first and finds the foo)* method there9
&t e8ecutes that and ne7er sees ICs foo)* method9
29 When you call the (ar)* method6 the instance of H doesnCt find it in class L6 so it
loo/s in class I9
3his e8am#le sho0s the result)
>>> x = H)* + Hreate an instance of H
>>> x"foo)* + Hall t2e foo)* met2od
foo called in L
>>> x"(ar)* + Hall t2e (ar)* met2od
(ar called in I
0perator interception and o$erloading
Eou can chan$e the 0ay 4ython o#erators 0or/ in your classes9 3his a##lies both to
e8#ression o#erators such as x ; 3% and o#erations on obFects #rintin$6 callin$ a
function6 and so on%9 &nheritance is one tric/ that ma/es this #ossible6 but 4ython also has
some s#ecial tools to hel#)
Hookin" into the power of special methods
Methods 0ith names that be$in and end 0ith t0o underscores>s#ecial methods>are
also called hooks. 3hey ha7e s#ecial beha7iors9 When you use an o#erator such as :6
4ython calls the s#ecial method $$add$$ behind the scenes9 &f you im#lement the
$$add$$)* method for your class6 4ython 0ill call it each time you use the : o#erator
0ith instances of your class9
3i# 3hese methods are #ro7ided so you can ma/e your o0n class instances 0or/ the
same 0ay 4ythonCs built1in ty#es do9 &tCs $ood #ractice not to chan$e the beha7ior of
the o#erators in 0ays users and readers of your #ro$ram donCt e8#ect such as
chan$in$ $$add$$ so that it subtracts5%9
2-A
3able -"1- lists some of the o#erator o7erloadin$ methods9 3o see them in the
documentation for most of 4ythonCs built1in data ty#es6 ty#e 2elp)data_type*6
substitutin$ the name of the data ty#e you need hel# 0ith>for e8am#le6 2elp)list*9
3able -"1-) Some :ommonly ?sed S#ecial Methods
M#en table as s#readsheet
4ethod &sed 'or !yntax
$$add$$)* : U : P
$$eN$$)*6 $$neN$$)* and
others
:om#arin$ U == P6 U != P6 and so on
$$getattr$$)*
.oo/in$ u#
U"attri(-te
$$getitem$$)*
Detrie7in$ an inde8 or
/ey
U[Aey]6 U[index]6 U in P6 used in
loo#s and tests
$$init$$)*
&nitializin$ obFects
yHlass)*
$$iter$$)*
:reates iterables iter)U*6 for i in U!
$$repr$$)*
4rintin$6 con7ertin$ print U6 U
$$setattr$$)*
Assi$nin$ a 7alue to an
attribute
U"attr$name = 5al-e
$$setitem$$)*
Assi$nin$ an inde8 or
/ey
U[Aey] = 5al-e
U[index] = 5al-e
$$str$$)*
:on7ertin$ obFects to
strin$s
str)U*
For a com#lete list of s#ecial methods6 see IS#ecial method namesI in the 4ython
.an$ua$e Deference) htt#)LL0009docs9#ython9or$LrefLs#ecialnames9html9
!uper strin"s
3he follo0in$ e8am#le class includes a method that o7errides 4ythonCs builtin
$$str$$)* method9 &t chec/s 0hether one or t0o names 0ere #assed and returns the
names in first nameRlast name order)
class 6mployee!
def $$init$$)self, lastname, firstname=1one*!
self"lastname = lastname
self"firstname = firstname
def $$str$$)self*!
if self"firstname!
ret-rn "Ds Ds" D )self"firstname, self"lastname*
else!
ret-rn self"lastname
2-6
When you create instances of this class and #rint them6 the beha7ior of str)* chan$es9
3he print command calls str)object*9%
>>> a = 6mployee),La2Q,*
>>> ( = 6mployee),ar-c2,, ,@tef,*
>>> c = ,ar-c2, @tef,
>>> print a
La2Q
>>> print (
@tef ar-c2
>>> print c
ar-c2, @tef
*hen to +o to #lass
Eou mi$ht benefit from creatin$ classes in your #ro$ram in the follo0in$ situations)
!everal functions use the same parameters.
&f your #ro$ramCs functions #ass a lot of ar$uments bac/ and forth6 consider
creatin$ a class and ma/in$ the functions into methods9 Methods can access their
data throu$h the instance self%6 so you donCt ha7e to #ass the data9
Eou could do this by usin$ $lobals6 but thereCs more of a dan$er that thin$s 0ould
$et chan$ed 0hen you donCt 0ant them to9 Furthermore6 $lobals donCt allo0 you to
create multi#le instances9
%our pro"ram carries out the same operation multiple times.
:lasses are ideal for this #ur#ose because each instance you create is se#arate
from the others6 and you donCt ha7e to reset e7erythin$ to #erform the o#erations
a$ain9
%our pro"ram is event1driven.
An e7ent1dri7en #ro$ram often has a function that collects e7ents user actions%
and sends them to other functions to be #rocessed9 &f this e7ent function is a
method of an Lpplication class6 a##lication information doesnCt ha7e to be
#assed as ar$uments9
%our pro"ram uses a persistent database.
:lass instances can be stored on dis/ by usin$ the picAle or s2el5e modules9
See :ha#ter -*9% 3he picAle feature creates an e8ternal file and sa7es an obFect
in it9 picAle can also create a strin$ suitable for storin$ in a database9 3he s2el5e
feature I#ic/lesI obFects by usin$ a database that you access 0ith /eys9
2-+
%ou want a data type that bundles several items.
An em#ty class definition can store data attributes9 For more information6 see
:ha#ter 2-9
#hapter .A, Introducin" ?ew1!tyle
#lasses
&f youCre ne0 to 4ython and you ha7e read :ha#ter -" on classes6 you mi$ht be $roanin$
at the #ros#ect of yet another cha#ter on classes9 Actually6 almost e7erythin$ in :ha#ter
-" also a##lies to the ne01style classes 0e discuss in this cha#ter9 (e01style classes
sim#lify 4ythonCs obFect hierarchy in 0ays that sa7e you effort if you 0ant to ma/e
chan$es to a built1in data ty#e9 3hey come 0ith some ne0 features that are of interest
mostly in ad7anced #ro$rammin$9 We discuss them here so youCll reco$nize them in
#ro$rams9
3his cha#ter #ro7ides an introduction to ne01style classes and their features9 Eou also
find out about method resolution order and t0o features you shouldn3t use>static
methods and the $$slots$$ class attribute9
An (b>ect's (b>ect, Intro to ?ew1!tyle #lasses
3he #rimary difference bet0een a classic or old-style% class and a ne$-style class is that
a ne01style class al0ays inherits from o(Tect6 either directly class
myclass)o(Tect*!% or indirectly by inheritin$ from one of 4ythonCs built1in ty#es
class myclass)dict*!%6 0hich inherits from o(Tect9
3he ori$inal #ur#ose of ne01style classes 0as to allo0 subclasses based on built1in
4ython data ty#es6 such as dict and list9 3hey also fi8 some #roblems 0ith classic
classes and add a bunch of ne0 features such as #ro#erties%9
(e01style classes 0ere introduced in 4ython 292H ho0e7er6 they 0ere some0hat
e8#erimental in 2926 and subtle but si$nificant chan$es 0ere made in 4ython 29"9 &n case
youCre curious6 most of the chan$es in7ol7ed multi#le inheritance features9% &f youCre
usin$ 4ython 2926 stic/ 0ith classic classes9
#lassic #oke or ?ew #okeC
3here is a contro7ersy in the 4ython community about ne01style classes9 Some #eo#le
say you should use them for all the classes in your code9 Mthers say you should use them
only 0here a re$ular class 0onCt do9 3he contro7ersy is based on the follo0in$ facts)
/e"ular classes will "o away in ython $.K.
2-,
(ot to 0orry>the 7ast maFority of 4ython code 0ritten 0ith re$ular classes 0ill
still 0or/ because classic class code isnCt that different from ne01style class code9
ython 7.. and earlier don't support new1style classes at all, and new1style
classes work differently in 7.7 than in 7.$ and later.
So if you use ne01style classes6 your code mi$ht ha7e #roblems runnin$ in
4ython 292 and earlier9
We focus on classic classes in this boo/ because theyCre still the default and 0ill remain
the default until 4ython "90H in addition6 the 7ast maFority of code in e8istence includin$
the 4ython library% still uses classic classes9
'efore 4ython 2926 data ty#es could be created only by usin$ the : #ro$rammin$
lan$ua$e6 and classes couldnCt inherit from built1in or third1#arty data ty#es9 &f you
0anted a ne0 obFect that 0or/ed /ind of li/e a 4ython dict6 for e8am#le6 you had to 0rite
the 0hole thin$ from scratch9 Eou couldnCt 0rite a subclass based on dict because : ty#es
0ere 7ery different from 4ython classes s#ecifically6 classes 0ere all of the class ty#e6
and class instances 0ere all of the instance ty#e%9 4ython 292 introduced the type;class
unification in the form of ne01style classes9
&n the ne01style class tutorial found at htt#)LL0009#ython9or$6 ;uido Ban Dossum
4ythonCs creator% #ro7ides an e8am#le of a ne01style class that e8tends the dict ty#e by
#ro7idin$ a default 7alue 0hen a /ey is missin$)
class defa-ltdict)dict*!
def $$init$$)self, defa-lt=1one*!
dict"$$init$$)self*
self"defa-lt = defa-lt
def $$getitem$$)self, Aey*!
try!
ret-rn dict"$$getitem$$)self, Aey*
except Xey6rror!
ret-rn self"defa-lt
3he documentation for ne01style classes hasnCt yet been inte$rated 0ith the rest of the
official 4ython documentation at htt#)LL0009#ython9or$9 <ereCs 0here to find
information about ne01style classes)
htt#)LL0009#ython9or$LdocLne0styleL
,$erything coes fro ob'ect
3he basic rule for a ne01style class is that it has to inherit from o(Tect9 We /no0 0hat
youCre thin/in$) IMh no6 another use of the term ob-ect5I% &n this case6 o(Tect is a built1in
2-*
ty#e9 All the 4ython built1in data ty#es are really subclasses of o(Tect9 &f you ty#e
2elp)$$(-iltin$$* into the 4ython inter#reter6 #art of 0hat you see is a hierarchy of
classes6 startin$ 0ith o(Tect)
Help on (-ilt7in mod-le $$(-iltin$$!
1L6
$$(-iltin$$ 7 I-ilt7in f-nctions, exceptions, and ot2er o(Tects"
[""""]
H3L@@6@
o(Tect
(asestring
str
-nicode
(-ffer
["""]
(ethods of inheritance
3here are t0o 0ays to set u# inheritance for a ne01style class9 Eou can inherit directly
from obFect6 or you can inherit from a built1in data ty#e9
Inheritin" from ob>ect
3o 0rite a class that inherits directly from o(Tect6 start 0ith this line)
class yHlass)o(Tect*!
3o ma/e all classes in a sin$le module ne01style classes6 #ut this statement at the to# of
the module)
$$metaclass$$ = type
Inheritin" from a built1in data type
Eour class can inherit from a built1in data ty#e 0hich inherits from o(Tect%9
?se the follo0in$ method if you 0ant somethin$ that 0or/s a lot li/e a builtin data ty#e
but has a fe0 differences li/e ;uidoCs defa-ltdict e8am#le%9
Warnin$ Some functions return a s#ecific data ty#e9 &f you #ass an instance of your
subclass to a function that returns a s#ecific data ty#e6 it may return an instance
of a built1in ty#e rather than an instance of your subclass9
&n this e8am#le6 0e create a subclass of list and an instance of that subclass9 When 0e
use the append)* method on the instance6 the chan$ed instance still belon$s to the
subclass 0e created9 'ut 0hen 0e use the list)* function 0ith the instance6 it returns an
obFect of the list ty#e9
220
>>> class y3ist)list*! pass
"""
>>> ell = y3ist)*
>>> ell"append)/*
>>> ell
[/]
>>> type)ell*
#class ,$$main$$"y3ist,>
>>> ell2 = list)ell*
>>> ell2
[/]
>>> type)ell2*
#type ,list,>
?ew Improved #lass 'eatures
(e01style classes #ro7ide se7eral enhancements o7er old1style classes)
The $$getattri(-te$$)* method
A new return value for type)*
The s-per)* function
The property type
#lass methods, includin" the $$ne9$$)* class method
!tatic methods
The $$slots$$ class attribute
Getcher attributes4
With classic classes6 one of the tools of subclassin$ is the s#ecial method
$$getattr$$)*6 0hich returns an attribute of an obFect9 (e01style classes add the
s#ecial method $$getattri(-te$$)*9 3he difference bet0een $$getattr$$)* and
$$getattri(-te$$)* is that $$getattr$$)* is called only if an attribute isnCt found6 but
$$getattri(-te$$)* is called for all attributes9
.ey! baby! &hat"s your type;
(e01style classes $i7e you more s#ecific information about the instances you create from
a class)
&f you create an instance of an old1style class6 the 7alue returned by
type)myinst* is #type ,instance,>9
&f you create an instance of a ne01style class6 the 7alue returned by
type)myinst* is the same as the instance attribute myinst"$$class$$9
22-
#alling the right superclass ethod
3he s-per)* function #ro7ides a 0ay to $et at a subclassCs su#erclasses 0hen you are
usin$ multi#le inheritance9 Eou usually use it in a method to call a method in the
su#erclass9 3o use it6 ty#e s-per)classname, objectname*9 &t returns a bound su#erclass
obFect9
<ereCs ho0 to use the s-per)* function to re1create the e8am#le 1ame0ag class code in
:ha#ter -"9 (ote that you must con7ert 1ame0ag to a ne01style class first9% 3he only
difference is that you use s-per)* instead of e8#licitly usin$ the 1ame0ag class9 (otice
that 0hen you use s-per)*6 the class name ar$ument must be the current class9
3i# ?sin$ s-per)* ma/es it easier to chan$e the name of a #arent class9 Eou only need
to chan$e the class definition6 not all the su#erclass calls in the methods9
@8tended method usin$ classic% 1ame0ag su#erclass)
class WeirdSreeting)1ame0ag*!
def say)self*!
1ame0ag"say)self*
print self"myname"s9apcase)*
@8tended method usin$ the ne01style 1ame0ag class and s-per)* function)
class WeirdSreeting)1ame0ag*!
def say)self*!
s"per(*eird+reeting, self).s#y()
print self"myname"s9apcase)*
3he s-per)* function has some limitations)
It is a ooperative function, @ach #arent class that defines the method must also
call s-per)*9
It works simply only when all methods have the same signature: 3hat is6 they
must ha7e the same #arameter lists9 &t is #ossible to use s-per)* 0hen methods
ha7e different si$natures6 but difficult9%
3he traditional 0ay of callin$ a su#erclassCs method is to use the name of the su#erclass
you 0ant 0hen callin$ the method)
x = y@-perclass"its$met2od)*
That"s y property4
Properties are attributes that you mana$e by usin$ 7arious get and set methods6 so they
are also called managed attributes. 'efore ne01style classes came alon$6 the only 0ay to
222
customize attribute mana$ement 0as to o7erride $$getattr$$ and $$setattr$$9 3his
0as tric/y and caused #erformance #roblems9
!et up properties
3o set u# #ro#erties in your class6 follo0 these ste#s)
-9 :efine a new1style class and an $$init$$)* method.
?sually6 you set u# a #ri7ate attribute self"$x in this e8am#le% because itCs only
used behind the scenes by the methods9 See :ha#ter -" for more on #ri7ate
attributes9
class yHlass)o(Tect*!
def $$init$$)self*!
self"$x = %
29 :efine class methods that "et, set, or delete an attribute.
3i# &tCs a $ood idea for the names of these methods to include the 0ords get6 set6
and del so itCs clear 0hatCs $oin$ on9 For e8am#le)
def getx)self*!
print "Setting $x"
ret-rn self"$x
def setx)self, x*!
if x # %!
raise Wal-e6rror)"1egati5e 5al-es pro2i(ited! Dr" D
x*
self"$x = x
print "@etting $x"
"9 :efine a property and, in parentheses, pass the names of the methods you
defined, as in the followin" example.
(ote that you do not call the methods donCt include #arentheses after the method
names%9
3o include a doc attribute for a #ro#erty 0hich sho0s u# 0hen you as/ for hel#
on the #ro#erty%6 ty#e doc= and a strin$ inside the #arentheses9
x = property)getx, setx, doc="no negati5e x"*
22"
&se properties
3o use a #ro#erty6 create an instance of the class9 3o assi$n and retrie7e 7alues6 #retend
that the #ro#erty is a re$ular attribute>4ython automatically calls the methods for you9
3hese e8am#les sho0 ho0)
>>> my$inst = yHlass)*
>>> my$inst"x
Setting $x
%
>>> my$inst"x = /%
@etting $x
>>> foo = my$inst"x
Setting $x
>>> foo
/%
>>> print yHlass"x"$$doc$$
no negati5e x
>>> my$inst"x = 7/%
0race(acA )most recent call last*!
>ile "#stdin>", line /, in V
>ile "a"py", line //, in setx
raise Wal-e6rror)"1egati5e 5al-es pro2i(ited! Dr" D x*
Wal-e6rror! 1egati5e 5al-es pro2i(ited! 7/%
*hen only class atters
:lass methods are #assed the class of the obFect but not the obFect itself9 3heyCre useful
0hen
A method needs to /no0 only the class name and doesnCt care about any
underlyin$ data9
Eou call methods directly on the class and you 0ant to return an instance for
e8am#le6 the dict"fromAeys)* method%9
3he follo0in$ sections describe creatin$ and callin$ class methods9 Eou also find out
about the s#ecial $$ne9$$)* method9
#reatin" class methods
Eou #ut class methods in your classes by definin$ a method call it g)*% and then ty#in$
the code g = classmet2od)g*9
&n this e8am#le6 the g)* class method returns the name of the class and a 7alue x that itCs
#assed)
class 6)o(Tect*!
def g)cls, x*!
ret-rn cls"$$name$$, x
g = classmet2od)g*
22!
3i# Another 0ay to create class methods is to use decorator synta!6 li/e this)
Yclassmet2od
def g)cls, x*!
We tell you more about decorators in :ha#ter -69
3@:<(&:A.
S3?FF
4ython #ro$rammers con7entionally use the name cls or
occasionally Alass% to refer to the name of the class that $ets #assed
to a class method9 3hese 0eird names are used because class itself
is a /ey0ord and canCt be used as the name of an obFect9% 3his is
similar to the con7ention of usin$ self to refer to the instance that a
class creates9
#allin" class methods
3o call a class method6 use the class name6 a dot6 and the method name9
3his e8am#le calls the class method g)* from class 6 created by the #recedin$ class
definition9
>>> print 6"g)3*
),6,, 3*
Eou can also call a class method on an instance6 li/e this)
>>> print 6)*"g)3*
),6,, 3*
*hat's new in class methods
3he $$ne9$$)* class method deser7es s#ecial mention9
When you create an instance 0ith an old1style class6 4ython first creates the instance and
then calls the $$init$$)* method to initialize it9 'ut this doesnCt 0or/ 0ell for
immutable instances or 0ith metaclasses9 So ne01style classes ha7e a class method6
$$ne9$$)*6 that returns the instance9 Eou can define both $$ne9$$)* and $$init$$)* in
a class9 &f you define both6 $$init$$)* is called after $$ne9$$)*9
:lasses that use $$ne9$$)* are different in se7eral 0ays from classes that only use
$$init$$)*)
3he $$ne9$$)* method creates a ne0 instance6 so it ta/es a cls #arameter9
An $$init$$)* method ta/es a self #arameter because it is called after the
instance is created9
22A
3he $$ne9$$)* method must call its base classCs $$ne9$$)* method to create the
instance9
With an $$init$$)* method6 you can either call the base classCs $$init$$)* or
o7erride it9
3he $$ne9$$)* method must e8#licitly return the created instance 7ia a ret-rn
statement9
An $$init$$)* method doesnCt return anythin$9
<ereCs a tri7ial e8am#le of a $$ne9$$)* method)
class deri5ed$from)str*!
def $$ne9$$)cls, ;args, ;;A9args*!
instance = str"$$ne9$$)deri5ed$from, ;args, ;;A9args*
ret-rn instance
?nless you need to ha7e a $$ne9$$)* method in your class6 itCs con7entional to use
$$init$$)* to #rocess the #assed1in ar$uments and then raise an e8ce#tion if they are
incorrect9 &tCs a 'ad &dea to use $$ne9$$)* to return an error 7alue rather than a correctly
created instance9 &tCs o/ay for $$ne9$$ to raise an e8ce#tion6 thou$h9%
#utting through the static about ethods
Static methods are basically functions attached to a class rather than to a module9 3he
difference bet0een a static method and a class method is that a static method has no cls
#arameter9 When a static method is called in a #ro$ram6 it loo/s Fust li/e a function call9
A static method be$ins 0ith a def statement6 has no self or cls #arameter6 and ends
0ith name_of_method = staticmet2od)name_of_method*9 3he line Ystaticmet2od
before the def statement is decorator synta8 that also indicates a static method9 See
:ha#ter -6 for more information about decorators9
Warnin$ DonCt use static methodsH they add unnecessary com#le8ity to your #ro$rams9
?se functions if you 0ant to do thin$s 0ith classes that donCt reGuire a class
instance9
1on"t use the slots achine
3he $$slots$$ class attribute #ro7ides a 0ay of restrictin$ the attributes of class
instances9 &tCs intended as an ad7anced memory1sa7in$ techniGue for classes that 0ill
ha7e millions yes6 millions% of instances9 &t doesnCt 0or/ 0ell 0ith inheritance9
Warnin$ Sim#le rule) &f you donCt understand metaclasses6 donCt use $$slots$$9
&f our 0arnin$ isnCt enou$h6 ta/e ;uidoCs 0ord for it)
226
__slots__ is a terrible hack $ith nasty, hard-to-fathom side effects that should only be
used by programmers at grandmaster and $i2ard levels. )nfortunately it has gained an
enormous undeserved popularity amongst the novices and apprentices, $ho should kno$
better than to use this magic incantation casually.
Island of :r. 4/(
&n 4ython6 MDM doesnCt stand for 'eals (eady to Open< it stands for 'ethod (esolution
Order.
3i# 3he im#ortant thin$ to remember about MDM is this) &f you use ne01style classes6
you donCt ha7e to 0orry about method resolution order6 because 4ython handles it
automatically9
MDM matters 0hen you 0rite a class that inherits from more than one #arent class9 For
e8am#le6 assume your class inherits from t0o #arent classes6 and each #arent class has a
9rite)* method9 &f your class calls a 9rite)* method6 4ython loo/s for it first in the
class itself and then in the #arent classes9 'ut ho0 0ill 4ython /no0 0hich 9rite)*
method to use2 And more im#ortant6 ho0 0ill you /no0 0hich one $ets used2 &f you
$uess 0ron$6 you mi$ht $et the dreaded ?ne8#ected Desults9
With classic classes see :ha#ter -"%6 4ython loo/s for the method in this 0ay)
-9 &t loo/s in the #arent class listed first leftmost% in the class definition9
29 &t loo/s at that classCs #arent classes6 and so on until there are no more #arent
classes9
"9 &t $oes to the ne8t class listed in the class definition6 and all of its #arent classes6
and so on9
3@:<(&:A.
S3?FF
3his is called depth first and then left to right order9
?nfortunately6 this order doesnCt 0or/ 0ith ne01style classes6 because they all inherit
from o(Tect9 &f this order 0ere used6 the same #arent class 0ould be e8amined multi#le
times6 and youCd still be in the #osition of not /no0in$ 0hich classCs method 0as
disco7ered first9 @7en 0orse6 sometimes a #arent class is su##osed to be o7erridden by a
subclass6 but the #arent classCs method $ets called instead5
So the 0ay MDM 0or/s in ne01style classes is this)
A ne01style class has an $$mro$$ attribute that #rescribes the order for searchin$ #arent
classes9 &t is created by a com#licated al$orithm that $uarantees that each #arent class
e8ists only once in the $$mro$$9
22+
'est of all6 4ython $enerates a classCs $$mro$$ attribute automatically6 so you donCt ha7e
to 0orry about the Icom#licated al$orithm5I Just e8amine the $$mro$$ attribute to see in
0hat order the su#erclasses are searched9
3i# 3he al$orithm does still 0or/ left1to1ri$ht6 so if you 0ant a #articular su#er1class to
$et its method called first6 ma/e sure that itCs listed first in the classes you inherit
from9
2xplodin" %our Head with 4etaclasses
4ython 292 and later ha7e a functionality called metaclasses9 Just as you use a class to
create instances6 you use a metaclass to create classes9
/oles
D@M@M'@D A metaclass is Fust a class>but it creates classes rather than class
instances9 &n other 0ords6 it really is turtles all the 0ay do0n9
A metaclass doesnCt really create the class9 &nstead6 4ython e8ecutes the class code Fust
li/e initializin$ a module% and then #asses the class to the metaclass9 3he metaclass can
do 0hate7er it li/es6 and the class name is $i7en to 0hat it returns9
3i# 3he 4ython communityCs 0isdom about metaclasses is summed u# by 4ython $uru
3im 4eters) IMetaclasses are dee#er ma$ic than **[ of users should e7er 0orry
about9 &f you 0onder 0hether you need them6 you donCt9I 3herefore6 read this section
to find out 0hat a metaclass is and ho0 to reco$nize one 0hen you see it6 but donCt
0orry about ho0 to #ut one into your o0n #ro$ram9
&n a metaclass6 the first ar$ument for a method is con7entionally called cls rather than
self9 Metaclass methods o#erate on the class that the metaclass creates9 A metaclass
doesnCt create instances6 and if you try to create an instance of a metaclass6 you $et an
error that loo/s li/e this)
0race(acA )most recent call last*!
0ype6rror! -n(o-nd met2od ["""]
3he default metaclass for all ne01style classes is type)*9 Sur#rise5 type is really a
metaclass instead of the function 0eC7e been callin$ it all alon$9 &t Fust does a $ood Fob of
dis$uisin$ itself until you need to use its other ca#abilities9%
Applications
3o use a metaclass6 use the $$metaclass$$ name either
&n the body of a class
22,
At the to# of a module if you 0ant all the classes in that module to use that
metaclass%9
<ereCs an e8am#le that sets u# a class to use a metaclass9 (otice that you only refer to
yetaHlassH you donCt call it there are no #arentheses%9
class yHlass!
$$metaclass$$ = yetaHlass
@7en if you 0ant to 0rite code that creates multi#le classes6 you rarely need to use
metaclasses9 A function can return a class9 A function that returns a class is called a class
factory9 An e8am#le of a class factory called class$9it2$met2od)* can be found in this
article on metaclass #ro$rammin$ in 4ython)
htt#)LL00091-2,9ibm9comLde7elo#er0or/sLlinu8LlibraryLl1#ymeta9html
3he classo(T)* function of the ne9 module also acts as a class factory9
#hapter .B, 'eelin" 2xceptional
4eo#le 0ho use your 4ython #ro$rams donCt al0ays do e8actly 0hat you 0ant them to
do6 and sometimes a #ro$ram $ets in#ut it doesnCt e8#ect9 4ython has built1in tools for
handlin$ these situations9
3his cha#ter describes some of 4ythonCs error1handlin$ features6 includin$ e8ce#tions and
code bloc/s you 0rite to ca#ture e8ce#tions9 We also introduce you to 0ritin$ your o0n
e8ce#tion handlers and discuss t0o 0ays of a##roachin$ error handlin$9
All about !pecial Handlin"
&n 4ython6 as in @n$lish6 an e!ception is a s#ecial case>somethin$ that needs s#ecial
handlin$9 When the 4ython inter#reter encounters somethin$ une8#ected6 it $enerates an
internal messa$e6 or raises an e!ception9 Eou 0rite code to tell 4ython 0hat to do 0hen
an e8ce#tion occurs9 4ythonCs built1in e8ce#tion code usually dis#lays an on1screen error
messa$e containin$ information about 0hat /ind of #roblem occurred and 0here9
4ython also uses e8ce#tions for control flo0 in non1error conditions6 es#ecially in for
loo#s6 0hich 0e discuss in :ha#ter -09
;I didn't think they would do that<;
When you 0rite #ro$rams for other #eo#le to use6 es#ecially #ro$rams that as/ users to
#ro7ide in#ut of some /ind6 users may $i7e your #ro$ram in#ut it doesnCt e8#ect9
22*
For e8am#le6 if your #ro$ram as/s the user to in#ut a number6 she mi$ht accidentally ty#e
a letter instead9 &f your code is set u# to 0or/ only 0ith a number6 this in#ut 0ould cause
your code to fail9 4ro#er e8ce#tion handlin$ catches in#ut of the 0ron$ ty#e6 #rints a
friendly reminder about 0hat in#ut to use6 and lets the user try a$ain9 3hat 0ay6 the user
can correct the #roblem easily instead of ha7in$ to restart the #ro$ram or loo/ at a
confusin$ error messa$e such as this)
0ype6rror! cannot concatenate ,str, and
,int, o(Tects
<ereCs an e8am#le of 4ythonCs error handlin$9 &f you for$et a colon 0hen 0ritin$ a for
statement6 4ython #rints an error messa$e called @yntax6rror)
>>> for x in range)&*
>ile "#stdin>", line /
for x in range)&*
?
@yntax6rror! in5alid syntax
3his e!ception handling functionality ma/es debu$$in$ and usin$ #ro$rams easier9
Without it6 a #ro$ram 0ould Fust mysteriously Guit 0hene7er it encountered a bu$9
EouC7e #robably used #ro$rams that do that and /no0 ho0 frustratin$ it can be5
'ut 4ython ta/es e8ce#tion handlin$ e7en further) Eou can 0rite your o0n e8ce#tion
handlers based on 4ythonCs built1in ones9 For e8am#le6 if you donCt 0ant an error messa$e
dis#layed to the screen6 you can desi$n your #ro$ram to catch s#ecific errors your users
mi$ht ma/e and then 0rite e8ce#tions that $i7e users hints about ho0 to use your
#ro$ram correctly9
Tryin" Thin"s (ut
4ython #ro$rammers handle e8ce#tions in a code bloc/ that be$ins 0ith the 0ord try9
'loc/s that use try are often nested inside each other to #ro7ide com#lete error handlin$9
3here are t0o /inds of try bloc/s)
try8except) &f e8ce#tions occur in the try code6 the except clause ca#tures and
handles the e8ce#tions9
try8finally) 3he try code and the finally code al0ays run9 &f e8ce#tions
occur in the try code6 the finally clause re1raises the e8ce#tions for handlin$
else0here in your #ro$ram9
&n 4ython 29A6 these t0o ty#es can be combined into one bloc/)
try8except8else8finally9 See ItryLe8ce#tLelseLfinally) 3o$ether at last6I later in this
cha#ter9
3he follo0in$ sections describe the inner 0or/in$s of try bloc/s9
2"0
)sing try9except stateents
Eou use a try8except bloc/ if you 0ant the except code to run only if there is an
e8ce#tion9 &t loo/s li/e this)
try!
some code
except SomeException
exception!handling code
Trackin" down tracebacks
4ython /ee#s trac/ of 0hat your #ro$ram does9 @ach time you call a function6 4ython
adds the call to the call stack9 @ach function call adds another layer to the call stac/9
When an e8ce#tion is raised6 4ython stores the call stac/ as a traceback that tells you
e8actly 0here the error occurred and the seGuence of calls that $ot you there9 &t doesnCt6
ho0e7er6 list the function #arameters>you need to do your o0n lo$$in$ for that9%
3he follo0in$ e8am#le #ro$ram contains an error9 When you run it6 4ython raises an
e8ce#tion6 0hich $enerates a tracebac/)
+++ 02ree f-nctions t2at call eac2 ot2er
def a)*!
()*
def ()*!
c)*
def c)*!
/8% + Lttempt at di5ision (y
Qero, 9ill raise exception
+++ B-n f-nction a)*
a)*
When you run the #ro$ram6 the tracebac/ lists the calls in the order they 0ere recei7ed)
>ile "a"py", line =, in #mod-le>
a)*
>ile "a"py", line 3, in a
()*
>ile "a"py", line &, in (
c)*
>ile "a"py", line E, in c
/8% + Lttempt at di5ision (y
Qero, 9ill raise exception
KeroOi5ision6rror! integer di5ision or
mod-lo (y Qero
&t 0or/s as follo0s)
-9 4ython runs the code in the try clause9
2"-
29 &f no e8ce#tion is found6 4ython finishes the try bloc/ and doesnCt run the code in
the except bloc/9
"9 &f an e8ce#tion occurs in the try clause6 4ython s/i#s the rest of the try code and
chec/s the e8ce#tion a$ainst the e8ce#tions named in the except statement9 &f
there is a match6 4ython runs the except clause9
!9 &f an e8ce#tion occurs in the try clause that doesnCt match the except statement6
4ython loo/s for a matchin$ e8ce#tion handler in any code that the try bloc/ is
nested in9 &f 4ython doesnCt find a matchin$ e8ce#tion handler6 then 4ython uses
its built1in e8ce#tion handler that is6 it #rints those $ee/s#ea/ error messa$es you
sa0 earlier%9
Handlin" multiple exceptions
Eou can #rocess se7eral different /inds of e8ce#tions by usin$ try8except code9 &f you
0ant to catch more than one /ind of e8ce#tion in a try8except bloc/6 there are t0o
0ays to do it)
To handle all the exceptions the same way, list multiple exception classes
within a sin"le except clause.
4ass the e8ce#tions as a tu#le in #arentheses6 se#arated by commas%6 li/e this)
except )B-ntime6rror, 0ype6rror, 1ame6rror*!
To handle each exception a different way, use multiple except clauses.
3hese clauses are tested in orderH if thereCs a match in a clause6 the rest of the
clauses are s/i##ed9 <ereCs 0hat t0o except clauses mi$ht loo/ li/e)
except B-ntime6rror!
some code
except "ypeError
some different code
Follo0in$ is a small #ro$ram that chec/s for correct user in#ut9 &t uses a try8except
bloc/ 0ith a sin$le except clause that catches t0o /inds of e8ce#tions9
try!
x = ra9$inp-t)"6nter an integer! "*
y = int)x*
print "Po-r n-m(er 9as", y
except )0ype6rror, Wal-e6rror*!
print "02at didn,t
rocessin" exception ar"uments
Some e8ce#tions use ar$uments associated data6 li/e 0hat functions and methods use%)
2"2
@8ce#tions usually ha7e a strin$ ar$ument describin$ 0hat sort of #roblem
occurred9 <ereCs an e8am#le)
try!
x = int)x*
except 0ype6rror!
raise 0ype6rror)"Dr is not a 5alid integer" D x*
A fe0 e8ce#tions also ha7e a tu#le ar$ument that stores se7eral bits of
information about the #roblem9 3his is an ad7anced feature 0e donCt co7er in this
boo/9
3o #rint or lo$ the details of an e8ce#tion6 s#ecify a name in the except statement to hold
the e8ce#tion instance9 &n the follo0in$ e8am#le6 the name detail is used to store the
e8ce#tion instance)
>>> try!
""" x = /8%
""" except KeroOi5ision6rror, detail!
""" print "Jops,", detail
"""
Jops, integer di5ision or mod-lo (y Qero
Warnin$ &f you use more than one e8ce#tion class in your e8ce#t statement6 #ut them in
#arentheses to differentiate from the e8ce#tion instance name9 Mther0ise youCll
$et an une8#ected result9
:ealin" with exceptional exceptions
When usin$ multi#le except clauses6 set u# the last clause to catch any une8#ected
e8ce#tions9 A Icatch1allI except clause commonly called a bare except% should $o at
the hi$hest le7el of your #ro$ram9 &t should include code that lo$s the errors it catches9 &t
could also #rint the error and send it to a lo$$in$ function and then re1raise the
e8ce#tion9% .o$$in$ is co7ered in :ha#ter -+9
Warnin$ &nclude code in your except clause that lo$s or #rints the errors the except
clause catches9 Mther0ise6 4ython s0allo0s all the une8#ected e8ce#tions and
you 0onCt /no0 0hat /inds of errors your #ro$ram is really $eneratin$6 0hich
ma/es debu$$in$ harder9
*hen it comes to ;or else;
A try8except bloc/ can ha7e an else clause9 3he else clause runs only if the try bloc/
runs successfully and com#letely)
(o e8ce#tion is raised9
(o ret-rn or other bloc/1e8itin$ statement is e8ecuted9
?se an else clause for code that needs to run if the try clause doesnCt raise an e8ce#tion9
4ut it after all the except clauses6 li/e this)
2""
try!
some code
except SomeException
exception!handling code
else!
necessary code
)sing try9finally stateents
&f you need some code that al$ays runs as #art of a try bloc/6 and you 0ant to handle
e8ce#tions else0here in your #ro$ram6 use the try8finally bloc/9
3he finally bloc/ is $ood for cleanin$ u#>closin$ o#en files and releasin$ memory6
for e8am#le9 4ython usually does these thin$s for you automatically6 but in #ro$rams
handlin$ lots of data6 itCs useful to clean u# as you $o alon$9%
3@:<(&:A.
S3?FF
3he try8finally bloc/ follo0s these ste#s)
-9 4ython runs the code in the try bloc/9
29 &f 4ython finds no errors6 it lea7es the try bloc/ and runs the
code in the finally bloc/9
"9 &f a ret-rn6 (reaA6 or contin-e statement is e8ecuted in the
try bloc/6 the finally clause runs on the 0ay out9
!9 &f an e8ce#tion occurs in the try bloc/6 4ython s/i#s the rest
of the bloc/ but saves the e!ception. &t runs the finally
clause and then sends the e8ce#tion u# to hi$her le7els of
your #ro$ram that is6 it re-raises the e!ception%6 0here you
should ha7e e8ce#tion1handlin$ code9
A try8finally bloc/ loo/s li/e this)
try!
some code
finally!
cleanup code
Warnin$ When you use a finally clause6 donCt #ut initializin$ statements for e8am#le6
assi$nment statements% in the try bloc/9 &n the follo0in$ code6 if open)* raises
an e8ce#tion6 the name f doesnCt actually $et created9 3hen 0hen the finally
clause runs6 4ython 0ill #roduce a 1ame6rror com#lainin$ that f doesnCt e8ist9
try!
f = open),c2eese$list,*
process)f* + 02is line is pse-do7code
finally!
f"close)*
3o a7oid the #roblem6 #ut the open)* line before the try8finally bloc/6 li/e this)
f = open),c2eese$list,*
2"!
try!
process)f* + 02is line is pse-do7code
finally!
f"close)*
'ecause itCs usually a $ood idea to do error1chec/in$ 0hene7er you try to o#en a file6 you
mi$ht 0ant to 0ra# the open)* line in a se#arate try8except statement9
try9except9else9finally: Together at last
Startin$ in 4ython 29A6 you can 0rite a sin$le bloc/ that includes all the com#onents
discussed in the #re7ious sections9 3his code 0or/s the same 0ay as the old code did6 and
the $uidelines for ho0 to use the statements are the same>the only difference is that you
donCt ha7e to nest t0o bloc/s if you 0ant to use both except statements and a finally
statement to$ether9
3he follo0in$ e8am#le uses try6 except6 and finally to$ether to create a function that
tries to read a file and return its contents9 'ut if thereCs an error readin$ the file6 the
function returns 1one instead9 Whether or not the file read is successful6 the function
closes the file and returns a 7alue)
def safe$read)filename*!
f = open)filename*
try!
data = f"read)*
except GJ6rror!
data = 1one
finally!
f"close)*
ret-rn data
It's easier to ask for"iveness than permission
@arly in the history of #ro$rammin$6 errors 0ere often handled by tryin$ to $uess e7ery
error that mi$ht occur and then 0ritin$ a lot of if statements to #rocess them9 3his
#hiloso#hy of error handlin$ is called I.oo/ 'efore Eou .ea#I .'E. for short%9 3his is
e8#ensi7e in com#uter #rocessin$ #o0er because the error chec/in$ occurs e7ery time
the user does somethin$ enters data6 clic/s somethin$ on the screen6 chooses from a
menu6 and so on%9
3he try statement lets you assume that users 0ill use your #ro$ram correctly9 &t handles
errors only 0hen they actually occur9 3his #hiloso#hy of error handlin$ is called I@asier
to As/ For$i7eness than 4ermissionI @AF4 for short%9 4ro#s to Ale8 Martelli for the
#hrasin$ and tireless #romotion of the #hiloso#hy6 and to Admiral ;race Murray1<o##er6
architect of :obol6 0ho brou$ht the conce#t into com#uters albeit in a different conte8t
>she 0as commentin$ on a techieCs relations 0ith bureaucrats%9
@AF4 is more efficient than .'E. in se7eral 0ays)
2"A
Eou can handle all the errors in one #lace the except statements%9
Eou can handle une8#ected errors by usin$ an except statement 0ith a Icatch1allI
error handler9
Eou handle errors only 0hen they occur and not chec/ for errors e7ery time the
#ro$ram $ets some in#ut9
/aisin" %our #ode to ?ew -evels
When your #ro$ram determines an error condition such as de#ositin$ a ne$ati7e amount
to a ban/ account%6 the raise statement lets you force an e8ce#tion e7en if 4ython
doesnCt detect an error9 Daisin$ an e8ce#tion I#ushes the error hi$herI in your #ro$ramCs
code hierarchy9
3o 0rite a basic raise statement6 ty#e the 0ord raise and the ty#e of e8ce#tion to raise9
3his e8am#le raises the Wal-e6rror e8ce#tion)
raise Wal-e6rror
3o include a 7alue 0ith an e8ce#tion6 s#ecify the 7alue in #arentheses after the e8ce#tion9
3he 7alue is usually a strin$ that $i7es a messa$e about the error6 as in this e8am#le)
raise 1ame6rror),W2at,s yo-r name againV,*
Eou mi$ht also see this code 0ritten in the old style6 0ith a comma rather than
#arentheses for e8am#le6 raise 1ame6rror, ,W2at,s yo-r name againV,%6 but
#arentheses are #referred6 and the comma form 0onCt be 7alid in 4ython "90 and later9
3@:<(&:A.
S3?FF
A raise statement can also include a tracebac/ obFect6 but 0e donCt
co7er that in this boo/9
Sometimes6 0hen 4ython has already raised an e8ce#tion6 you mi$ht 0ant to do
somethin$ 0ith it no0 and also force hi$her le7els of the #ro$ram to deal 0ith it in
$ee/s#ea/6 this is /no0n as Iallo0in$ the e8ce#tion to #ro#a$ate u# the callin$ stac/I%9
3o sa7e6 or re1raise6 an e8ce#tion6 ty#e raise on a line by itself9 For e8am#le6 if you 0ant
to send an e8ce#tion to a lo$$in$ function and re1raise it6 your code mi$ht loo/
somethin$ li/e this)
try!
some code
except Wal-e6rror!
log$pro(lem)* + replace t2is 9it2 yo-r logging code
raise
D@M@M'@D ?se a bare raise only 0hen there is an e8istin$ e8ce#tion>other0ise you
$et an e8ce#tion5
2"6
4akin" %our ro"ram 2xceptional
4ythonCs e8ce#tions are #retty $eneral9 :reatin$ your o0n e8ce#tions sim#lifies your
error handlin$9 &tCs much easier for users and other #ro$rammers to understand your code
0hen you use an e8ce#tion that describes 0hat the error is6 both at the #oint 0here the
error occurs and 0hen you handle it in an except clause9
3o create your o0n e8ce#tions6 0rite a ne0 e8ce#tion class or class hierarchy thatCs
deri7ed from 4ythonCs 6xception class or one of its subclasses9
*riting a base class for your exceptions
<ere are some ti#s for 0ritin$ an e8ce#tion class)
?se as a base class the 4ython e8ce#tion that most closely resembles the
e8ce#tion youCre 0ritin$9
Most e8ce#tions ha7e names that end in 6rror to maintain consistency 0ith
4ythonCs built1in error handlin$9 Eours should6 too9
=ee# e8ce#tion classes sim#le9 3hey should mostly only include attributes that
can store information about the error9 Se#arate handlers can e8tract this
information and act on it9
For e8am#le6 to define a class based on 4ythonCs 6xception class6 0rite somethin$ li/e
this)
class yod-le6rror)6xception*!
pass
1e$eloping an exception hierarchy
&f youCre creatin$ more than one /ind of e8ce#tion>#erha#s as #art of a module that
handles se7eral related functions>$ood #ractice is to start by creatin$ a base class for the
e8ce#tions9 ?sually6 the base class doesnCt do anythin$9 3he code loo/s somethin$ li/e
this)
class yod-le6rror)6xception*!
"""Iase class for my exceptions""""
pass
3o ma/e a subclass based on the base class6 follo0 these ste#s)
-9 ?ame the subclass after its correspondin" module or class, plus ;2rror;, like
this,
2" class Gnp-t6rror
3@:<(&:A.
S3?FF
3his hel#s you /ee# trac/ of 0hich modules your errors are
comin$ from9
2"+
"9 ut the base class in parentheses in the class definition, and type a colon.
." class Gnp-t6rror (,y,od"le-rror):
A9 (n the next line, indent four spaces, and write code for what you want the
exception to do.
<" class Gnp-t6rror)yod-le6rror*!
E" p#ss
#hapter .E, Tacklin" !ome Advanced
'eatures
3his cha#ter describes some of the ad7anced features of 4ython6 as 0ell as some of the
ne0 features of 4ython 29A9
&f you donCt understand #arts of this cha#ter6 donCt 0orry9 WeCre describin$ these thin$s
mainly so you 0ill reco$nize them if you see them in someone elseCs code9 As you 0or/
0ith 4ython6 your understandin$ 0ill im#ro7e until youCre ready to use these features
yourself5
*hat's That IdiomC
3able -61- sho0s you ho0 some of the ad7anced and ne0 features loo/ in 4ython code9
All these features are described later in this cha#ter9
3able -61-) Deco$nizin$ Ad7anced 4ython :odin$ &dioms
M#en table as s#readsheet
8eyword or
2xample
'eature :escription
[U for U in
mylist]
.ist com#rehension
listcom#%
:reates a ne0 listH allo0s
mani#ulation of list items%
))x;2* for _ in
)2, ., <**
;enerator e8#ression
$ene8#%
:reates a ne0 iterator obFectH more
efficient than a listcom#
yield in a function
or method
;enerator Ma/es a function that remembers
0here it left off
9it2 exp as name!
9it2 statement Adds conte8t mana$ement to
try8finally bloc/s%
U if H else P
:onditional e8#ression @asier truth testin$
Y
Decorator :reates function 0ra##er
lam(da a, (! a;;(
.ambda e8#ression or
anonymous function
An e8#ression that returns a function
2",
*hat to :o ?ext, Iterators and +enerators
.ists are a useful 4ython feature that can ta/e u# a lot of memory and #rocessin$ time9
/terators are tools that hel# ma/e lists more efficient6 and generators ma/e creatin$
iterators easy9
The itertools library
3he itertools library6 0hich 0as introduced in 4ython 29"6 includes functions for
ma/in$ lists more efficient both to 0rite and to use9 @ach of the itertools functions
creates a different ty#e of iterator obFect9 3he obFects are desi$ned to 0or/ to$ether9 3hey
also 0or/ 0ith the tools in the operator module to #roduce hi$h1s#eed results9
<ere are some sim#le e8am#les of itertools code9
3his itertools"imap)* code ta/es t0o lists and #asses their elements one element
from each list at a time% to a lam(da function see the IMary had a little lambdaI section6
later in this cha#ter%6 0hich multi#lies the elements)
>>> n = [/, 3, <, ., 3, <, 3, 23.]
>>> m = [/, 2, 3, &, <, E, ', =]
>>> for i in itertools"imap))lam(da x, y! x;y*, m, n*!
""" print i,
"""
/ < /' 2% /' .2 2. 2/%<
The inner lives of iterators
&terators are used throu$hout 4ython6 and if you understand them6 you 0ill ha7e a $ood
$ras# on 0hat 4ython is all about9
An iterator is a 4ython obFect that #roduces elements one at a time9 An iterable is an
obFect that can create an iterator9 For e8am#le6 the iterator created from a list returns the
list elements one at a time6 in order9 3he iterator for a dict returns the /eys one at a time6
unordered9 .ists and dicts are e8am#les of iterables9
As if thin$s 0erenCt confusin$ enou$h6 some iterables such as files% are also iterators9
For e8am#le6 a file sim#ly returns itself 0hen as/ed for an iterator technically6 it returns
self%9 3his means that all iterators are also iterables9
Finally6 you can create functions and classes that either create iterators or are themsel7es
iterators9
&terators are useful because they sim#lify code and reduce memory usa$e9 3hey can also
ma/e a##lications more res#onsi7e because they do only the calculations needed to
#roduce one element at a time instead of doin$ the 0or/ of #roducin$ all the elements
u#front9
2"*
3he official 4ython tutorial a7ailable on the 4ython Web site at htt#)LL0009#ython9or$
contains further e8#lanation of the inner 0or/in$s of iterators)
0ehind the scenes, the for statement calls iter%4 on the container ob-ect. &he function
returns an iterator ob-ect that defines the method ne!t%4 $hich accesses elements in the
container one at a time. "hen there are no more elements, ne!t%4 raises a ,top/teration
e!ception $hich tells the for loop to terminate. &his e!ample sho$s ho$ it all $orks9
>>> s = ,a(c,
>>> it = iter)s*
>>> it
#iterator o(Tect at %x%%L/OI&%>
>>> it"next)*
a,
>>> it"next)*
(,
>>> it"next)*
c,
>>> it"next)*
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
@topGteration
3his itertools"co-nt)* code creates an iterator that returns consecuti7e inte$ers
be$innin$ 0ith the ar$ument you s#ecify 0 by default%9 Eou can use
itertools"co-nt)* 0ith itertools"imap)* in the #recedin$ e8am#le to $enerate one
of the lists6 li/e this)
>>> n = [/, 3, <, ., 3, <, 3, 23.]
>>> for i in itertools"imap))lam(da x, y! x;y*, n, itertools"co-nt)**!
""" print i,
"""
% 3 /2 /2 /2 3% /' /<3'
3he itertools"islice)* function 0or/s on a slice of a list of numbers9 3his code
creates a list of consecuti7e numbers bet0een 0 and 6- xrange)<2*%9 &t then ta/es a
slice of that list the ar$ument < s#ecifies the be$innin$ of the slice and the ar$ument <2
s#ecifies the end% and #rints e7ery third number from the slice the ar$ument 3 s#ecifies
e7ery third number%)
>>> for i in itertools"islice)xrange)<2*, <, <2, 3*!
""" print i,
"""
< = /2 /& /' 2/ 2. 2E 3% 33 3< 3= .2 .& .' &/ &. &E <%
Generators: yield for faster processing
=enerators loo/ li/e functions>in fact6 they are a s#ecial /ind of function9 3hey use the
yield statement to return data 0hereas re$ular functions use the ret-rn statement%9
2!0
;enerators are a con7enient 0ay to create iterators because they sim#lify the record1
/ee#in$ needed for returnin$ each element9 3hat is6 you donCt ha7e to /ee# chec/in$ and
reassi$nin$ 7alues because the $enerator remembers the 7alues it 0as assi$ned last9%
;enerators are different from functions in t0o other 0ays)
:allin$ a $enerator al0ays returns the same thin$) an iterator usually called a
generator iterator or geniter%9
:allin$ a function can return any data ty#e6 de#endin$ on 0hat the function does9
When 4ython encounters a yield statement6 it doesnCt e8it the $enerator iterator9
&nstead6 it remembers 0hat 0as ha##enin$ inside the function includin$ any
7alues that 0ere assi$ned%9
When 4ython encounters a ret-rn statement6 it e8its the function6 and 7alues
assi$ned in the function are for$otten9
'ecause they ma/e iterators6 $enerators are usually used in loo#s9 <ereCs ho0 a $enerator
0or/s)
-9 When you call a $enerator6 you $et a ne0 iterator9
29 When you call the next)* method of the $enerator iterator6 the body of the
$enerator function e8ecutes until it hits a yield statement9
3he for statement calls an iteratorCs next)* method automatically9
"9 3he yield statement #asses a ne0 7alue to the next)* method9 3he $enerator
iterator doesnCt e8it9 &nstead6 it #reser7es or remembers the state of the function
body9
!9 3he next)* method $ets called a$ain9 'ecause the iterator remembers the state of
the function6 the 7alues that 0ere in effect before6 remain in effect9
A9 3he cycle re#eats until 4ython runs off the end of the $enerator6 a ret-rn
statement is e8ecuted6 or an e8ce#tion is raised9
69 &f the $enerator ends normally6 4ython raises @topGteration9
3@:<(&:A.
S3?FF
;enerators are sometimes called resumable functions or generator
functions. 4eo#le 0ho call them generator functions usually call the
thin$ that they return a generator rather than a generator iterator.
4ython can add to your stoc/ of ton$ue t0isters as 0ell as hel# you
become a better #ro$rammer5%
3he follo0in$ code creates a $enerator function that filters out re#eated items in a
seGuence>for e8am#le6 re#eated lines in a file9 Eou #re#are the file by readin$ it usin$
the readlines)* method and then sortin$ the resultin$ list of strin$s)
2!-
def -niN)inp-t*!
pre5 = o(Tect)*
for line in inp-t!
if line != pre5!
yield line
pre5 = line
3i# &n 4ython 29! and earlier6 you canCt use yield in the try clause of a try8finally
statement9
3@:<(&:A.
S3?FF
4ython 29A adds some esoteric features to $enerators9 We list them
here so you 0onCt be sur#rised if you see them in other #eo#leCs
#ro$rams9% All three features are ne0 methods on $eniters)
send)* allo0s you to #ass 7alues bac/ into the $enerator9
A conseGuence of this chan$e is that yield becomes an
e8#ression in 4ython 29A6 so code li/e this is allo0ed in
earlier 7ersions6 it raises an error%)
foo = )yield foo*
Startin$ in 4ython 29A6 $enerators are also called coroutines.
t2ro9)* raises an e8ce#tion inside the $enerator9
close)* forces the $enerator to e8it9
2xpression and #omprehension, -istcomps and
+enexps
.ist com#rehensions listcom#s% and $enerator e8#ressions $ene8#s% let you focus on
data rather than control structures9 See also the IFocusin$ on FunctionsI section6 later in
this cha#ter9% 3hey re#lace a for loo# 0ith an e8#ression9
.ist com#rehension and $enerator e8#ression code can loo/ intimidatin$ if you donCt
/no0 0hatCs $oin$ on9 'ut after you $et used to them6 youCll #robably find them a lot
easier and Guic/er to use than the multi1line statements they re#lace9 Demember that you
ne7er have to use a listcom# or a $ene8#6 but a lot of #ro$rammers use them6 and itCs best
to ha7e a basic understandin$ of ho0 they 0or/9
List coprehensions
A listcom# is a nifty shorthand 0ay of creatin$ a ne0 list9 Eou can create a ne0 list in
other 0ays6 such as by usin$ the map)* function6 but the listcom# synta8 is more fle8ible6
sim#ler to create6 and often easier to read9
2!2
A list com#rehension is enclosed in sGuare brac/ets and al0ays includes the /ey0ords
for and in9
As an e8am#le6 if you ha7e a list of strin$s and you 0ant to ma/e sure they are all
lo0ercase6 you could do somethin$ li/e this)
mylist = [,LIH,, ,fJJ,, ,(ar,]
tmp = []
for x in mylist!
tmp"append)x"lo9er)**
mylist = tmp
3hatCs a lot of code for a sim#le tas/5 Well6 Ja7a #ro$rammers mi$ht not thin/ itCs a lot
of code6 but 4ythonistas are s#oiled9% 4lus6 anyone readin$ the code 0ould ha7e to read
the 0hole for loo# carefully to understand that it 0as creatin$ a ne0 list9
Fortunately6 you can use a listcom# instead9 &t does the e8act same thin$ as the for loo#6
but it uses only one line of code9
#reatin" a simple listcomp
3o create a sim#le listcom#6 follo0 these ste#s)
-9 Type a name, =6 and [
2" mylist = [
"9 Type the action you want done to create each list item.
For e8am#le6 if you ha7e a list of strin$s and you 0ant to ma/e sure they are all
lo0ercase6 you mi$ht use the lo9er)* method of lists9 Eour line of code 0ould
no0 loo/ li/e this)
mylist = [x.lower()
!9 Type for and the same name you used in the action.
&" mylist = [x"lo9er)* for x
<"
+9 Type in6 the name you typed at the be"innin" of the line, and ]
'" mylist = [x"lo9er)* for x in mylist]
D@M@M'@D Eou should use a listcom# rather than a for loo# 0hen you 0ant to focus
on creatin$ a list9 3hat 0ay6 someone readin$ the code doesnCt ha7e to
e8amine the for loo# to find the #ur#ose of the code9
#reatin" a listcomp that applies a filter
EouC7e seen that you can use a listcom# to do somethin$ to each item in a list9 Another
thin$ you can do is a##ly filters to the items in a list to build a ne0 list9 3he follo0in$
listcom# #roduces a list of numbers di7isible by A by usin$ the filter if x D & == %9
(ote that it uses the e8#ression range)&%* rather than a list name9
2!"
>>> filtered$list = [x for x in range)&%* if x D & == %]
>>> filtered$list
[%, &, /%, /&, 2%, 2&, 3%, 3&, .%, .&]
3i# .istcom#s can $et com#le8 rather Guic/ly9 &f your code is $ettin$ hard to read6 use a
for loo# instead)
filtered$list = []
for x in range)&%*!
if x D & == %!
filtered$list"append)x*
Generator expressions
&n the earlier section6 I;enerators) yield for faster #rocessin$6I 0e discuss $enerators6
0hich are a s#ecial /ind of function that ma/es #rocessin$ in loo#s more efficient9
4ython 29! introduces generator e!pressions9 ;enerator e8#ressions gene!ps for short%
are a shorthand 0ay of creatin$ $enerator iterators9
;ene8#s loo/ li/e listcom#s6 but they use #arentheses rather than brac/ets9 <o0e7er6 if
the $enerator e8#ression is the only ar$ument of a function6 you can s/i# the
#arentheses9%
3he difference bet0een a $ene8# and a listcom# is)
A $ene8# creates a $enerator iterator also called a geniter%9
A listcom# creates a list9
3i# Mne 0ay to use a listcom# or a $ene8# is to $i7e it as the ar$ument to a function that
ta/es an iterable9 For e8am#le6 a $ene8# is a handy 0ay of buildin$ a dictionary by
usin$ the dict)* constructor9
3o 0rite a sim#le $ene8# that creates a dict in 0hich each number is associated 0ith its
sGuare6 follo0 these ste#s)
-9 Type the name of a function and )9
&n this e8am#le 0e use the dict)* function6 0hich creates a dictionary out of
t0o1item tu#les9
dict)
29 Type )6 a name for one item in the tuple, and a comma.
3" dict)(x,
!9 Type an expression for the other item in the tuple, and then type *
&" dict ))x, x ** 2)
69 Type for and the name of the first item in the tuple.
E" dict ))x, x ;; 2* for x
2!!
,9 Type in and a tuple representin" the values you want to assi"n to the first
item in the tuple. Then type *
=" dict))x, x ;; 2* for x in (2, ., /))
&f you ty#ed the abo7e code into interacti7e mode6 youCd $et this result)
>>> dict))x, x ;; 2* for x in )2, ., <**
{2! ., .! /<, <! 3<}
3i# &f the e8#ression 0ould e7aluate to a tu#le6 it must be in #arentheses9 3his also
a##lies to listcom#s9
*ith *hat, %our Bare HandsC 5The ower of OwithP
!tatements6
&n 4ython 29A6 the ne0 9it2 statement ma/es try8finally statements more #o0erful
and easier to use9 Maybe e7en #o0erful enou$h to slay a fierce $reen dra$on5% 3he
synta8 is as follo0s)
9it2 6UCB6@@GJ1 as 1L6!
I3JHX
3he 9it2 statement 0or/s li/e this)
6UCB6@@GJ1 returns a 7alue that the 9it2 statement uses to create a conte!t a
s#ecial /ind of 0ra##er obFect%9 3his is similar to the 0ay a for loo#
automatically creates an iterator9 3he conte8t is used to e8ecute the I3JHX9 3he
bloc/ mi$ht end normally6 $et terminated by a (reaA or ret-rn6 or raise an
e8ce#tion9 (o matter 0hich of those thin$s ha##ens6 the conte8t contains code to
clean u# after the bloc/9
3he as 1L6 #art is o#tional9 &f you include it6 you can use 1L6 in your I3JHX9
1L6 is similar to the tar$et of a for loo# that is6 the i in for i in mylist%9
3o use the 9it2 statement in 4ython 29A6 #ut this code in your module)
from $$f-t-re$$ import 9it2$statement
3@:<(&:A.
S3?FF
&n 4ython 296 and later6 the 9it2 /ey0ord 0ill automatically be
reco$nized9
3he #rotocol used by the 9it2 statement is called the conte!t management protocol, and
obFects im#lementin$ it are conte!t managers.
Eou can create a conte8t mana$er 0ith a decorated $enerator see the later section6
IDecoratin$ Eour :odeI%6 li/e this)
from contextli( import contextmanager
2!A
Ycontextmanager
def opened)filename, mode="r"*!
f = open)filename, mode*
try!
yield f
finally!
f"close)*
Eou mi$ht use the #recedin$ code as follo0s)
9it2 opened)"8etc8pass9d"* as f!
for line in f!
print line"rstrip)*
3@:<(&:A.
S3?FF
3his canonical standard% e8am#le is from the 4ython docs at
htt#)LL0009#ython9or$9 3he code creates a tem#late for o#enin$ a file
that ensures the file is closed 0hen 4ython lea7es the 9it2 bloc/9
4akin" 2xceptions for %ourself
3he 0ay you use standard e8ce#tions and 0rite custom e8ce#tions chan$es sli$htly in
4ython 29A9 <ereCs the scoo#)
4ython 29A turns all standard e8ce#tions into ne01style classes see :ha#ter -! for
more about ne01style classes% and introduces a ne0 su#erclass called
Iase6xception9 All the standard e8ce#tions youCll use in your #ro$rams still
inherit from the 6xception class6 but the 6xception class in turn is a subclass of
Iase6xception9
&n 4ython -9A throu$h 29!6 all standard e8ce#tions are subclasses of the
6xception class6 but any classic% class can be raised as an e8ce#tion9
3@:<(&:A.
S3?FF
30o e8ce#tions inherit from Iase6xception) Xey(oardGnterr-pt
and @ystem6xit9 'ut you ha7e no business catchin$ those
e8ce#tions9 Eou should let them beha7e the 0ay theyCre su##osed to
so that the user can interru#t your #ro$ram9
D@M@M'@D Any custom e8ce#tions you 0rite should be subclasses of 6xception9
See :ha#ter -A to find out ho0 to 0rite custom e8ce#tions9% Althou$h
this rule isnCt enforced no06 it 0ill be enforced in 4ython "909
Warnin$ @arly 7ersions of 4ython #rior to -9A% used strin$ e8ce#tions9 Althou$h 4ython
still lets you create strin$ e8ce#tions6 they 0onCt be su##orted in the future9 &n
4ython 29A and later6 strin$ e8ce#tions raise a CendingOeprecationWarning9
?se them only in the e8tremely unusual% case of code that needs to be
com#atible 0ith 7ersions earlier than -9A9
&nder (ne #ondition
2!6
:onditional e8#ressions 0ere added to 4ython 29A to sim#lify choosin$ one of t0o
o#tions in an e8#ression9 See :ha#ter -09%
A conditional e8#ression ta/es the follo0in$ form)
U if H else P
&t 0or/s li/e this)
-9 H is e7aluated9
29 Action de#ends on 0hether : is true)
o &f H is true6 then U is e7aluated to $i7e the result9
o &f : isnCt true6 P is e7aluated to $i7e the result9
Eou can use #arentheses in conditional e8#ressions9 'ecause #arentheses identify the
conditional e8#ression as a sin$le unit6 they ma/e it easier to read in conte8t of other
code6 as in this e8am#le)
x = )"tiger" if fr-it=="redc-rrant" else "crocodile"*
Althou$h you can 0rite nested conditional e8#ressions6 you shouldnCt because they are
hard to read9 3he follo0in$ e8am#le is too hard to read as a sin$le statement9 &t should be
0ritten as an if bloc/ instead)
+ too7complex conditional expression
cleese = )"H-ngarian to-rist" if sAetc2 == "C2rase(ooA @Aetc2" else
)"H-stomer in searc2 of parrot" if sAetc2 == "Cet @2op @Aetc2" else
">res2 fr-it sergeant"*
*
+ easier7to7read if (locA
if sAetc2 == "C2rase(ooA @Aetc2"!
cleese = "H-ngarian to-rist"
elif sAetc2 == "Cet @2op @Aetc2"!
cleese = "H-stomer in searc2 of parrot"
else!
cleese = ">res2 fr-it sergeant"
:ecoratin" %our #ode
Decorator synta! #ro7ides a 0ay of modifyin$ functions and methods9 A decorator also
called a function decorator or function $rapper% is a function that ta/es a function as an
ar$ument and returns another function9
2!+
3@:<(&:A.
S3?FF
'efore decorator synta8 made its 0ay into 4ython6 #ro$rammers
modified functions and methods by callin$ the decorator function and
assi$nin$ the result bac/ to the ori$inal name of the function9
A standard use for decorators is to im#lement a cache that stores the results of function
calls9 3his is called memoi2ing9 &t 0or/s li/e this)
-9 3he first time you call the memoized function6 the 0ra##er calls the ori$inal
function to $et the result9 &t returns the result but also stores it in the cache9
29 When the #ro$ram calls the memoized function a$ain 0ith the same ar$uments6
the stored 7alue is returned9
3his s#eeds u# the #ro$ram because the ori$inal function doesnCt run a$ain9
&f you 0rote a decorator function called memoiQe)*6 you 0ould set it u# to 0or/ 0ith a
function by usin$ the follo0in$ synta89 3he Y character indicates a decorator9 3he
decorator comes on the line before the function or method definition)
YmemoiQe
def myf-nc)myarg*!
some code
Without decorator synta86 you 0rite the code this 0ay)
def myf-nc)myarg*!
some code
myf-nc = memoiQe)myf-nc*
D@M@M'@D When you #ass myf-nc as an ar$ument to memoiQe)* in the #recedin$
code6 myf-nc doesnCt ha7e #arentheses after it9 3hat is because you arenCt
callin$ myf-nc)* as a functionH you are #assin$ the function itself as an
ar$ument9
Some memoizin$ decorator functions can be found in the 4ython :oo/boo/)
htt#)LL0009as#n9acti7estate9comLAS4(L:oo/boo/
2!,
'ocusin" on 'unctions
Se7eral 4ython tools are desi$ned s#ecifically to 0or/ 0ith functional #ro$rammin$6
0hich is a /ind of #ro$rammin$ that 0or/s 7ia functions9
;ene8#s6 listcom#s6 and the itertools module are functional #ro$rammin$ tools
co7ered earlier in this cha#ter9 3his section introduces some more esoteric tools6 mostly
so you can reco$nize them in other #eo#leCs #ro$rams9
3i# &f you made an easy A in calculus6 you mi$ht enFoy functional #ro$rammin$9 &f you
ne7er made it to the calculus le7el6 donCt 0orry9 3he more com#le8 ty#es of
functional #ro$rammin$ arenCt necessary for most ty#es of #ro$rammin$ tas/s9
4ythonCs functional #ro$rammin$ tools include these features)
lam(da expressions create functions you can define in other function calls this is
useful if you donCt 0ant to create a 0hole se#arate function%9
Hi"her1order functions ta/e functions as in#ut and out#ut a function9
3i# Decorators are an e8am#le of hi$her1order functions9
'irst1class functions include functions that can be either
o Stored in a data structure for e8am#le6 usin$ the picAle module%
o 4assed as an ar$ument to another function
-ist comprehensions, 0hich 0e discuss earlier in this cha#ter
The map)*6 red-ce)*6 Qip)*6 and filter)* functions
(ary had a little labda
3he lam(da /ey0ord creates anonymous functions>functions that donCt ha7e names9
3he name lambda comes from .&S4 #ro$rammin$9% &t creates a function obFect the same
0ay the def /ey0ord does6 but the lam(da function obFect has #lam(da> in #lace of the
name of a function6 as sho0n9
>>> lam(da x! xD& is %
#f-nction #lam(da> at %x'2//'..>
3his code uses the abo7e lambda e8#ression to ma/e a list of the numbers from 0 to +A
that are di7isible by A)
>>> filter)lam(da x! xD& is %, xrange)E<**
[%, &, /%, /&, 2%, 2&, 3%, 3&, .%, .&, &%, &&, <%, <&, E%, E&]
A cou#le of other differences bet0een lambda functions and functions created 0ith the
def /ey0ord are as follo0s)
2!*
A lam(da is an e8#ression6 not a statement6 and it can a##ear any0here that an
e8#ression is allo0ed9
A lam(da e8#ression canCt ha7e statements in it such as x = 26 or if or try
statements%9
(apping it out
Another functional #ro$rammin$ tool is the map)* function9 &n its sim#lest form6 usin$
1one as the first ar$ument6 it turns a seGuence into a list6 or multi#le lists into a sin$le list
of tu#les9
&n the follo0in$ e8am#le6 the map)* function turns a strin$ into a list of sin$le1character
strin$s)
>>> mystring = "2ello Aitty"
>>> map)1one, mystring*
[,2,, ,e,, ,l,, ,l,, ,o,, , ,, ,A,, ,i,, ,t,, ,t,, ,y,]
&f you #ass a function as the first ar$ument6 map)* #erforms the functionCs action
on each element of the list or seGuence and stores the result in another list9
&f you #ass more than one seGuence6 the function needs a #arameter for each
seGuence9
&f the seGuences ha7e different len$ths6 map)* substitutes 1one 0hen there is no
corres#ondin$ 7alue in the shorter seGuence9
3i# &f you donCt need this seGuence1e8tendin$ beha7ior6 you should use Qip)*6 listcom#s6
or $ene8#s rather than map)*9 3heyCre sim#ler9
Applying filters
3he filter)* function ta/es a function 0hich can be a lambda% and a seGuence9 &t
#rocesses each element usin$ the function and returns a seGuence of the items for 0hich
the result of the function is 3rue9 For e8am#le)
>>> data = [/%, 2, E, &]
>>> filter)lam(da x! x>&, data*
[/%, E]
3i# Eou can also filter elements 0ith listcom#s9 See I:reatin$ a listcom# that a##lies a
filter6I earlier in this cha#ter9
/eductionis
3he red-ce)* function ta/es a function 0hich can be a lambda% and a seGuence9 &t
returns a sin$le 7alue constructed as follo0s)
-9 &t calls the function by usin$ the first t0o items of the seGuence as ar$uments and
returns the result9
2A0
29 &t calls the function by usin$ the result Fust returned and the ne8t item of the
seGuence9
"9 And so on until it runs out of items9
3his e8am#le #erforms x ; y on a list of ! items)
>>> mylist = [2, ., <, ']
>>> red-ce)lam(da x, y! x;y, mylist*
3'.
3i# For most #ur#oses6 red-ce)* has been re#laced by the built1in function s-m)*9 3he
s-m)* function ta/es a seGuence of numbers and adds them6 as sho0n)
>>> s-m)range)2%**
/=%
2A-
#hapter .H, &sin" ython's rimary
!ervices
&n this cha#ter6 you find out about many of the tools built into e7ery installation of
4ython9
We call this the I#rimary ser7icesI cha#ter because almost e7ery non1tri7ial #ro$ram uses
some but not all% of the features listed in this cha#ter9
ython, Batteries Included
3he tools that come 0ith 4ython are collecti7ely called the standard library. 3he standard
library contains commands6 modules6 and #ac/a$es9
3@:<(&:A.
S3?FF
Sometimes youCll see modules or #ac/a$es that come 0ith 4ython
referred to as libraries6 0hich is short for standard library module9
3his boo/ uses module and package6 thou$h9 :ha#ter -2 e8#lains the
difference bet0een modules and #ac/a$es9
3he standard library is li/e a basic education for 4ython6 allo0in$ it to 0or/ 0ith
different o#eratin$ systems ?(&O6 Windo0s6 and Mac MS6 for e8am#le%6 to handle
many /inds of data6 to na7i$ate the &nternet6 to 0or/ 0ith different human lan$ua$e
systems6 and so on9
3here are so many features that #eo#le often say that 4ython comes 0ith Ibatteries
included9I
D@M@M'@D
/emember to import modules
4ythonCs abilities come #ac/a$ed in modules so you donCt ha7e to thin/
about tools you arenCt usin$ ri$ht no09 3o use a tool6 you usually ha7e to
im#ort the module itCs stored in9
3he recommended 0ay to im#ort modules is to im#ort the 0hole module
by ty#in$
import modulename
We describe other 0ays to im#ort tools in :ha#ter -29
D@M@M'@D 3his /ey #oint 0ill sa7e you many many many hours of codin$)
2A2
'efore you start 0ritin$ a 4ython #ro$ram to #erform a function6 chec/
0hether the function already e8ists in 4ythonCs libraries9 <undreds of
#ro$rammers ha7e de7elo#ed these tools so you donCt ha7e to9
@ach ne0 7ersion includes lots of feature u#$rades and additions9 So 0hen you u#$rade
to a ne0 7ersion of 4ython6 be sure to read the IWhatCs (e0I Web #a$e for the 7ersion at
htt#)LL0009#ython9or$L9 3he ne0 features of 4ython 29A are a7ailable here)
htt#)LL0009docs9#ython9or$L
%ou +et All This<9The NNbuiltinNN 4odule
3he tools in the $$(-iltin$$ module are a7ailable 0hene7er you use 4ython9 Eou donCt
ha7e to im#ort them9 3o see 0hatCs in the module6 ty#e dir)$$(-iltins$$*9 DonCt
for$et the JsK>althou$h the module is called $$(-iltin$$6 the alias for the module is
$$(-iltins$$9 &f that bothers you6 you can ty#e import $$(-iltin$$ to use the actual
module name9%
&f you donCt reco$nize most of the names6 thatCs o/ay9 A lot of 0hatCs in $$(-iltin$$
0or/s behind the scenes6 at least 0hen youCre Fust startin$ out9 :urious2 ;et a descri#tion
of a #articular item in the library by ty#in$ 2elp)name of item*9
Most of the $$(-iltin$$ tools that you need to /no0 about are described else0here in
this boo/9 3his section describes a fe0 additional tools you mi$ht find useful9
Seeing &hat"s inside Python ob'ects
3he dir)* function returns an al#habetized list of an obFectCs attributes6 such as functions
or methods6 constants6 and the name of the obFect9
<ereCs ho0 to use the dir)* function)
3o see the names in the current names#ace6 ty#e dir)*9
&f you ty#e dir)* immediately after startin$ 4ythonCs interacti7e mode6 you 0ill
see somethin$ li/e this)
>>> dir)*
[,$$(-iltins$$,, ,$$doc$$,, ,$$name$$,]
2A"
3o see all the attributes named items% belon$in$ to an obFect6 ty#e dir)name of
object*9 For e8am#le)
>>> dir)Lrit2metic6rror*
[,$$class$$,, ,$$delattr$$,, ,$$dict$$,, ,$$doc$$,,
,$$getattri(-te$$,,
,$$getitem$$,, ,$$2as2$$,, ,$$init$$,, ,$$ne9$$,,
,$$red-ce$$,,
,$$red-ce$ex$$,, ,$$repr$$,, ,$$setattr$$,,
,$$setstate$$,,
,$$str$$,, ,$$-nicode$$,, ,args,, ,message,]
3o see the attributes of a s#ecific attribute6 se#arate the obFect name and the
attribute name 0ith a dot6 li/e this)
dir)Lrit2metic6rror"$$doc$$*
3i# Eou can also see some attributes by ty#in$ 2elp 0ith the name in
#arentheses6 for e8am#le)
>>> 2elp)Lrit2metic6rror*
3he dir)* function sho0s you these ty#es of attributes)
For a module6 it returns the moduleCs attributes9
For a ty#e or class obFect6 it returns the obFectCs attributes and those of its base
classes9
For any other obFect6 it returns the obFectCs attributes and the attributes of its class
and base classes9
/eading and &riting files
3he open)* function sets u# a file obFect in 4ython9 &t returns a file data ty#e9
Warnin$ 3he built1in documentation for open)* for 4ython 292 throu$h 29! has an error9
&t states or im#lies% that because open)* is an alias for file)*6 you should use
file)*9 3his is incorrect9 ?se open)* rather than file)* so that your code 0ill
0or/ 0ith all 7ersions of 4ython9
3he follo0in$ sections describe most of the ar$ument o#tions and the methods of the
open)* function9
(ptions for the open56 function
<ere are the rules and o#tions for open)*)
Eou should $i7e a name to the file youCre o#enin$6 or else it 0ill be difficult to do
anythin$ 0ith it9
3he first item in the #arentheses is a strin$ containin$ the filename9 &f the file
belon$s in a #articular directory6 ty#e the #ath to the directory9 For e8am#le)
,my$dir8my$file,
2A!
3he second item in #arentheses is a strin$ re#resentin$ the mode9 &f you lea7e this
out6 the mode defaults to ,r, for Iread1only9I 3he modes are described in 3able
-+1-9
3able -+1-) Modes of the o#en% Function
M#en table as s#readsheet
4ode 4eanin"
,r,
M#en the file as read1only allo0in$ no chan$es%9 3his is the default9
,9,
M#en the file for 0ritin$9 :reate the file if it doesnCt already e8ist9
Warnin$ ?sin$ ,9, erases anythin$ currently in the file9
,a,
M#en the file for a##endin$9 :reate the file if it doesnCt already e8ist9
,(,
3reat the fileCs contents as binary9
3his code is used mostly 0ith Windo0s9 Most other MSes these days donCt
differentiate bet0een te8t and binary files9
,:,
Allo0 both readin$ and 0ritin$9 Add it to the ,r, or ,9, mode li/e this)
,r:,
,4,
?se uni7ersal ne0line su##ortH for readin$ te8t files created on Mac6 ?(&O6
or Windo0s9 Wor/s only 0ith ,r,H doesnCt 0or/ 0ith J :,9 3y#e it on its
o0n or add it to ,r, mode li/e this) ,r4,
So to o#en a file for readin$6 ty#e code li/e this)
myfile = open)filename, ,r,*
!avin" chan"es to disk
3o sa7e file chan$es to dis/6 you need to use one or both of these methods)
3he fl-s2)* method forces 4ython to ta/e data in the internal buffer and sa7e it
to the file9 ?se it 0hen you 0ant to 0rite chan$es to dis/ 0ithout closin$ the file9
3he close)* method closes the file obFect that is created 0ith the open)*
method9 Eou canCt read from or 0rite to the file after you close it9 ?se it 0hen
youCre finished 0ith the file9
"eading %ile ontents
Eou can read the contents of a file in se7eral 0ays9 Which one you use de#ends on the
format you 0ant for the fileCs contents)
For a strin$6 use the read)* method9 &t returns the 0hole file or u# to a s#ecified
number of bytes as a strin$9 3his e8am#le returns 2+ bytes)
>>> myN-ote = open),N-otes"txt,*
2AA
>>> myN-ote"read)2E*
,Gf yo- liAe la9s and sa-sag,
For a list of strin$s each strin$ is one line of the file%6 use the read7lines)*
method9 3he follo0in$ e8am#le reads the 0hole file9
>>> myN-ote"readlines)*
[,Gf yo- liAe la9s and sa-sages, yo- s2o-ld Zn,, ,ne5er 9atc2
eit2er one (eing made" Zn,, ,77 Crince Jtto 5on IismarcA
)attri("*Zn,,
,Zn,, ,1ot to mention 9e( sites" Zn,, ,77 @FZn,]
For a strin$ re#resentin$ each line6 use a for loo#>0hich is also best if you 0ant
to read a file #iecemeal rather than in a bi$ $ul#9
>>> for line in myN-ote!
""" print line"rstrip)*
"""
Gf yo- liAe la9s and sa-sages, yo- s2o-ld
ne5er 9atc2 eit2er one (eing made"
77 Crince Jtto 5on IismarcA )attri("*

1ot to mention 9e( sites"

77 @F
3i# &n the #recedin$ e8am#le6 the strin$ method rstrip)* remo7es 0hite s#ace
and the end1of1line character Zn% from the strin$s9 'ecause print also
a##ends Zn6 if you donCt use rstrip)*6 the out#ut 0ill be double1s#aced9
-riting in%ormation to a %ile
3he 9rite)* method 0rites a s#ecified strin$ to the file9 3he file must ha7e been o#ened
for 0ritin$ or a##endin$9%
3i# &nformation 0ritten to a file may not a##ear in the dis/ co#y of the file until you
ha7e flushed the buffer and closed the file9
3his e8am#le creates a file obFect pit2y$sayings* and 0rites a strin$ to it)
>>> pit2y$sayings = open),myN-ote,, ,9,*
>>> mystring = "6ntropy isn,t 92at it -sed to (e""
>>> pithy_s#yings.write(mystring)
>>> pit2y$sayings"close)*
3@:<(&:A.
S3?FF
File obFects donCt su##ort ?nicode strin$s see :ha#ter 6%9 3o 0rite a
?nicode strin$ to a file6 you need to encode it as ?3F1, first6 li/e
this)
myfile"9rite)mystring"encode),-tf7',**
3i# &f you ha7e a file or file1li/e obFect% o#en for 0ritin$6 you can use the >> o#erator
0ith the print statement to redirect out#ut to the file9 3he print >> statement is
useful for lo$$in$ or to ma/e sure that a command1line #ro$ram #rints out#ut to the
screen 0hen stdo-t is redirected else0here6 li/e this)
2A6
print >> sys"stderr, "Oanger! Oanger!"
*orking &ith attributes
3o e8amine6 s#ecify6 and chan$e an obFectCs attributes indirectly6 you use the 2asattr)*6
getattr)*6 and setattr)* functions9 Mne use for these functions is con7ertin$ user
in#ut into an attribute of a class9
3o find out 0hether an obFect has a #articular attribute6 ty#e 2asattr and then6 in
#arentheses6 s#ecify the name of the obFect and the attribute name as a strin$
se#arated by commas%9
>>> 2asattr)mat2, ,cos2,*
0r-e
3he result is 0r-e if the strin$ matches the name of one of the obFectCs attributes
and >alse if not9
3o find out the 7alue of an obFectCs attribute6 use getattr)* 0ith the obFect name
and attribute name a$ain6 as a strin$%9 &f the attribute e8ists6 4ython returns its
7alue9
>>> getattr)mat2, ,pi,*
3"/./&=2<&3&'=E=3/
&f the attribute doesnCt e8ist6 4ython raises an Lttri(-te6rror by default9 'ut
you can s#ecify a third ar$ument to the function) a 7alue you 0ant returned if the
attribute isnCt found9 3his 7alue is often 1one9
>>> x = getattr)mat2, ,mary poppins,, 1one*
>>> print x
1one
3i# An easier 0ay to $et the 7alue of an attribute is by ty#in$ the obFect name6 a
dot6 and the attribute name) mat2"pi9 3his returns an Lttri(-te6rror if the
attribute doesnCt e8ist6 so if you 0ant to return a 7alue instead6 use
getattr)*9
3o assi$n a 7alue to an obFectCs attribute or to create a ne0 attribute and assi$n a
7alue at the same time6 use the setattr)* function9
&n the #arentheses6 ty#e the obFect name6 the attribute name as a strin$6 and the
attributeCs 7alue6 li/e this)
setattr)myo(Tect, ,my attri(-te,, ,my 5al-e,*
&f the attribute e8ists6 the ne0 7alue is assi$ned to it9 &f the attribute doesnCt e8ist6
4ython creates it and assi$ns the ne0 7alue9
2A+
%inding largest and sallest ites
3o find the lar$est item6 use the max)* function9 &n the #arentheses6 s#ecify a seGuence6
li/e this)
>>> a = [/, &, 3, E]
>>> max)a*
E
3o find the lar$est of se7eral items6 s#ecify them all as ar$uments to the max)* function9
Se#arate ar$uments 0ith commas9 <ereCs an e8am#le)
>>> a = [/, &, 3, E]
>>> ( = [/%%, 2%%, &%%]
>>> max)a, (*
[/%%, 2%%, &%%]
3he min)* function 0or/s the same 0ay but returns the smallest item or ar$ument9
Getting input fro users
3he ra9$inp-t)* and inp-t)* functions read information from 4ythonCs standard in#ut
file sys"stdin%9 Eou usually use them to collect in#ut that a user ty#es in res#onse to a
#rom#t or Guestion9
rawNinput56
3he ra9$inp-t)* function #rints a #rom#t strin$ to 4ythonCs standard out#ut file6
sys"stdo-t9 'y default it 0rites out#ut to the screen9% 3he function returns the userCs
in#ut as a strin$9 3he #rom#t strin$ is o#tional6 but youCll usually 0ant to include one9%
Eou s#ecify the #rom#t strin$ as the ar$ument6 li/e this)
ra9$inp-t)"Ho9 old are yo-V "*
input56
3he inp-t)* function e8#ects the user to enter a 7alid 4ython e8#ression and then it
e7aluates that e8#ression9
?nli/e ra9$inp-t)*6 the inp-t)* function can return any 7alid 4ython obFect6 not Fust a
strin$9
Warnin$ &tCs safer to use ra9$inp-t)* and ha7e your #ro$ram con7ert the strin$ into a
4ython e8#ression9 'ecause the inp-t)* function calls e5al)*6 it could be used
to run malicious code9 See I@7aluatin$ a strin$6I later in this cha#ter9%
2A,
&f inp-t)* doesnCt recei7e a 7alid 4ython e8#ression6 it raises an e8ce#tion6 as in this
e8am#le6 in 0hich the user in#ut is pi)
>>> inp-t)"W2at is 3"/./&V "*
W2at is 3"/./&V pi
0race(acA )most recent call last*!
>ile "#stdin>", line /, in #mod-le>
>ile "#string>", line /, in #mod-le>
1ame6rror! name ,pi, is not defined
%inding an ob'ect"s type
3o find an obFectCs data ty#e6 use the type)* function9 &n #arentheses6 $i7e it the name of
the obFect9 &t returns the obFectCs data ty#e>for e8am#le6 strin$ or function9 3his e8am#le
returns the ty#e of the function ro-nd)*9
>>> type)ro-nd*
#type ,(-iltin$f-nction$or$met2od,>
/eloading a odule
3he reload)* function allo0s you to re1im#ort a module 0ithout Guittin$ and restartin$
4ython9 Deloadin$ is useful 0hen debu$$in$ a #ro$ram that ta/es a lon$ time to start u#6
0hen #ro$rammin$ a ;?&6 or 0hen 4ython is embedded in another a##lication9
Warnin$ 3he reload)* function should ne7er be used in a li7e a##lication because it
does not modify e8istin$ references to the contents of a module9
,$aluating a string
3he e5al)* function ta/es a 4ython e8#ression in the form of a strin$6 con7erts it into a
code obFect6 runs the code6 and returns the result9 Eou use it 0hen you 0ant to $i7e your
users direct access to 4ython9
Warnin$ 3he e5al)* function is a security ris/6 so if your code needs to be secure6 itCs
better to use some other a##roach for e8am#le6 setattr)* or a dictionary%9
3@:<(&:A.
S3?FF
3he e5al)* function also 0or/s 0ith a code obFect6 but thatCs an
ad7anced feature 0e 0onCt be documentin$ in this boo/9
3his e8am#le uses e5al)* to sol7e an e8#ression9 Eou 0ouldnCt use this code in a real
#ro$ram6 thou$h>youCd sim#ly ty#e print x:/5%
>>> x = /
>>> print e5al),x:/,*
2
Eou can use either of these o#tional ar$uments 0ith the e5al)* function9 3hey $o after
the strin$9 Eou must #ass them in this order)
2A*
A dictionary of "lobal names, used as the $lobal names#ace for e7aluatin$ the
e8#ression9 3his defaults to the current $lobal names#aceCs dictionary9
A dictionary of local names, used as the local names#ace for e7aluatin$ the
e8#ression9
But *ait, There's 4ore9The sys 4odule
3he sys module is for interactin$ 0ith and controllin$ the 4ython inter#reter9 &t includes
information about the o#eratin$ system and the 7ersion of 4ython youCre usin$9 Most of
the time6 you donCt interact directly 0ith 0hatCs in the sys module6 but you should /no0
about a fe0 tools it offers9
D@M@M'@D Eou must im#ort the sys module before you use it9
import sys
3o 0or/ 0ith a feature in the sys module6 ty#e sys6 a dot6 and the name)
sys"exit)*
3hese are the items in the sys module youCll #robably use most often)
sys"exit)* function, 3ells the 4ython inter#reter to Guit9 &tCs the most direct 0ay
to end a 4ython scri#t 0hile itCs runnin$9
sys"arg5 list, Stores any command1line ar$uments #assed 0hen you started
4ython9 Also includes the name of the #ro$ram youCre runnin$9
?se sys"arg5 0hen 0ritin$ utility scri#ts that acce#t #arameters on the command
line9 3his e8am#le sho0s the contents of sys"arg5 after you run a #ro$ram called
add"py and #ass it the #arameter 39
D pyt2on 7i add"py 3
>>> import sys
>>> sys"arg5
[,add"py,, ,3,]
3he sys module also contains the follo0in$ ty#es of obFects)
Input, output, and error files
o stdin) ?sed by the inp-t)* and ra9$inp-t)* functionsH acce#ts in#ut
from user
o stdo-t) ?sed by the print statementH in interacti7e mode6 #rints to the
screen
o stderr) Stores error messa$es
260
(b>ects that store information specific to your version of ython. @8am#les
include #athnames6 the list of a7ailable modules6 and character encodin$s9
Functions be$innin$ 0ith get and set let you access and chan$e this information9
:ebu""in" and exception1handlin" tools.
!olvin" (! Incompatibility9The os and subprocess
4odules
3he os and s-(process modules include code that lets 4ython 0or/ 0ith your o#eratin$
system>they e7en run o#eratin$ system commands9
3hese modules $i7e 4ython 0ays of accessin$ the o#eratin$ system that donCt reGuire you
to 0rite code s#ecific to a #articular o#eratin$ system9 3herefore6 you should im#ort and
use them if youCre 0ritin$ a #ro$ram that needs to 0or/ on more than one o#eratin$
system9
3he os module is best for the follo0in$ tas/s)
Wor/in$ 0ith #aths and #ermissions test for access to a #ath6 chan$in$
directories6 chan$in$ access #ermissions and userL$rou# &Ds%
Wor/in$ 0ith files o#en6 close6 0rite6 truncate6 create lin/s%
3i# Another module thatCs useful for co#yin$ and mo7in$ files is s2-til 0hich
stands for Ishell utilityI%9 See :ha#ter -*9
3he s-(process module6 ne0 in 4ython 29!6 lets you safely interact 0ith the o#eratin$
system to run commands and $et information out of them9
3hin/ of the os and s-(process modules as the 0ay that 4ython does the same thin$s
you do 0ith your o#eratin$ system directly such as startin$ #ro$rams and mani#ulatin$
files%9 &f you 0or/ on more than one o#eratin$ system6 you must remember different
commands and synta8 for filenames6 for e8am#le9 4ythonCs os module hel#s 4ython
remember these thin$s9 For e8am#le6 the os"pat2 module handles #athnames6 so you
donCt ha7e to 0rite s#ecial code to handle both ?(&O #athnames 0hich ha7e for0ard
slashes% and Windo0s #athnames 0hich ha7e bac/slashes%9
*orking &ith the os odule
3i# 3his section lists some useful os functions and data9 3o find out more about the
abilities of the os module6 ty#e 2elp)os*9
D@M@M'@D @8ce#t 0here indicated in the follo0in$ sections6 all the tools of the os
module 0or/ 0ith ?(&O6 Mac6 and Windo0s o#eratin$ systems9
26-
4anipulatin" directories and their files
?se these functions to 0or/ 0ith directories and files on a com#uter system9
os"c2dir)* chan$es the current 0or/in$ directory to the s#ecified #ath9 S#ecify
the #ath as a strin$6 li/e this)
os"c2dir),8-sers8stef8`-ote,*
os"getc9d)* returns the current 0or/in$ directory as a strin$6 li/e so)
>>> os"getc9d)*
,8-sers8stef8`-ote,

os"mAdir)* creates a directory 0ith the #ath you s#ecify9 S#ecify the #ath as a
strin$6 as follo0s)
os"mAdir),y1e9Oictory,*
3o set a directoryCs #ermissions6 s#ecify a four1di$it octal #ermissions mode as the
second ar$ument9 3he default mode is usually %EEE6 0hich $i7es e7eryone full
access to the directory6 but your o#eratin$ system mi$ht o7erride this default9
<ereCs ho0 to s#ecify the default)
os"mAdir),y1e9Oictory,, mode=%EEE*
os"maAedirs)* 0or/s li/e os"mAdir)*6 but it creates directories recursi7ely9 For
e8am#le6 if youCre in directory A and you 0ant to create directory ' that holds
directory : that holds directory D6 ty#e this)
os"maAedirs),I8H8O,*
Warnin$ os"maAedirs)* doesnCt 0or/ 0ith Windo0s ?ni7ersal (amin$
:on7ention ?(:% #aths6 0hich use the ZZ2ostZpat2 format9
os"remo5e)* deletes the item on the #ath s#ecified9 S#ecify the #ath as a strin$9 &t
doesnCt remo7e directories9 &n Windo0s it raises an error if the file is in use9 3he
code loo/s li/e this)
os"remo5e),B8test,*
os"rmdir)* remo7es a sin$le directory on the #ath s#ecified6 and
os"remo5edirs)* remo7es multi#le directories9 We recommend usin$
s2-til"rmtree)* rather than these functions9 See :ha#ter -*9
os"9alA)* creates a $enerator obFect that lists the files in a directory tree9 &t
$enerates a three1item tu#le directory #ath6 directory names6 filenames% and
e8amines the directory in to#1do0n default% or bottom1u# order9 3o ma/e and use
the $enerator obFect6 0rite code li/e this)
>>> for root, dirs, files in os"9alA),N-otes,*!
""" print root, dirs, files
Eou use three ames in the loo# because the $enerator ma/es a three1item tu#le9
os"tmpfile)* creates a ne0 tem#orary file9 3he file is o#ened for 0ritin$ and is
binary "9:("%9 &tCs automatically deleted 0hen you close it9
262
3i# 3he tempfile module #ro7ides more tools for creatin$ tem#orary filesH use
that instead of os"tmpfile)* if you 0ant more than the basics9
*anderin" down the os.path
3he os"pat2 module is a submodule of os9 &t contains tools that handle filenames so that
your #ro$ram can 0or/ on multi#le #latforms9
3i# We recommend that you im#ort the 0hole os module 0hen you need to use os"pat29
&f you donCt6 Mur#hyCs .a0 dictates that youCll need somethin$ else in the os module
and for$et you didnCt im#ort it and $et an annoyin$ error9
3@:<(&:A.
S3?FF
Many of the os"pat2 functions donCt 0or/ 0ith Windo0s ?ni7ersal
(amin$ :on7ention ?(:% #aths6 0hich use the ZZ2ostZpat2
format9
Descri#tions of some im#ortant os"pat2 tools follo09 All these tools ta/e #athnames as
ar$uments9 ?se strin$s to s#ecify #athnames9
os"pat2"Toin)* is one of the most im#ortant os"pat2 tools9 &t ta/es one or more
#aths and Foins them by usin$ the current o#eratin$ systemCs #ath se#arator9 &f any
com#onent is an absolute #ath6 all #re7ious com#onents are thro0n a0ay9 <ereCs
an e8am#le)
>>> os"pat2"Toin),-sers,, ,stef,, ,`-ote,*
Mn ?(&O this #roduces)
,-sers8stef8`-ote,
Mn Windo0s it #roduces)
,-sersZZstefZZ`-ote,
3i# Mn Windo0s6 os"pat2"Toin)"c!", "foo"* creates a #ath relati7e to the
current directory on dri7e H! instead of creatin$ c!ZZfoo9 3o $et an absolute
#ath on Windo0s6 use this synta8)
os"pat2"Toin),c!ZZ,, ,foo,*
os"pat2"a(spat2)* ta/es a relati7e #athname and returns the corres#ondin$
absolute #athname6 li/e so)
>>> os"pat2"a(spat2),`-ote,*
,8-sers8stef8`-ote8,
os"pat2"normpat2)* con7erts #ath names in nonstandard formats to standard
format9 For e8am#le)
>>> os"pat2"normpat2),stef88"8`-ote,*
,stef8`-ote,
os"pat2"split)* ta/es a #athname and returns it in t0o #arts) the directory #art
and the filename9
26"
>>> os"pat2"split),8-sers8stef8`-ote8N-ote2"ne9,*
),8-sers8stef8`-ote,, ,N-ote2"ne9,*
&f you s#ecify a directory6 it returns the #ath and an em#ty strin$6 li/e this)
>>> os"pat2"split),8-sers8stef8`-ote8,*
),8-sers8stef8`-ote,, ,,*
3i# Mn Windo0s systems usin$ ?(:6 use os"pat2"split-nc)* instead9
os"pat2"split)* has t0o related functions)
o os"pat2"dirname)* returns the directory name of the #ath the first half
of the #air that os"split)* returns%9
o os"pat2"(asename)* returns the filename the second half of the
os"split)* #air%9 &f no file 0as s#ecified6 the os"pat2"(asename)*
function returns an em#ty strin$9
os"pat2"splitext)* 0hich stands for Is#lit e8tensionI% s#lits the #athname
into a #air of #athnames)
o 3he first #art is the #athname6 includin$ the #art of the filename before the
e8tension9
o 3he second #art includes a #eriod and the fileCs e8tension9
o >>> os"pat2"splitext),8-sers8stef8`-ote8N-ote2"txt,*
o ),8-sers8stef8`-ote8N-ote2,, ,"txt,*
3@:<(&:A.
S3?FF
&f there is no e8tension or no file6 the second #art is an
em#ty strin$9
o 3his e8am#le #uts os"pat2"split)* and os"pat2"splitext)* to$ether)
o >>> dirname, filename =
os"pat2"split),-sers8stef8`-ote8N-ote2"txt,*
o >>> (asename, extension = os"pat2"splitext)filename*
o >>> dirname, filename
o ),-sers8stef8`-ote,, ,N-ote2"txt,*
o >>> (asename, extension
o ),N-ote2,, ,"txt,*
os"pat2"exists)* returns 0r-e if the s#ecified #ath e8istsH other0ise6 it returns
>alse9 &t also returns >alse for bro/en symbolic lin/s9
os"pat2"isdir)* returns 0r-e if the s#ecified #ath is an e8istin$ directory9 &t
follo0s symbolic lin/s9
!eein" environment variables
3he os module includes a dictionary6 os"en5iron6 that stores your o#eratin$ systemCs
en7ironment 7ariables 0hich contain user and system #references%9 3he 7ariables and
their 7alues are stored as strin$s9 3he dictionary is set u# 0hen you start 4ython9 &f you
chan$e your en7ironment 7ariables outside 4ython6 the dictionary doesnCt reflect the
chan$es until you restart 4ython9
3o see the 7alue of an en7ironment 7ariable6 ty#e os"en5iron and then6 in sGuare
brac/ets6 ty#e the name of the 7ariable in Guotation mar/s6 li/e this)
26!
>>> os"en5iron[,HJ6,]
,8-sers8stef,
Warnin$ Althou$h itCs #ossible to chan$e en7ironment 7ariables by chan$in$ the
os"en5iron dictionary6 itCs not safe to do so9 ?se the Copen)* function of the
s-(process module to chan$e en7ironment 7ariables instead9 3he chan$es
affect only the sub#rocesses9%
Subprocessing
3he s-(process module6 ne0 in 4ython 29!6 lets you interact 0ith the o#eratin$ system
to create ne0 #rocesses6 #ass information into and out of them6 and $et their return codes9
&t re#laces a number of functions and modules a7ailable else0here in 4ython6 includin$
the follo0in$)
os"system
os"spa9n
os"popen
popen2
commands
3he s-(process module is safer than the #recedin$ methods of startin$ ne0 #rocesses
because its default is to create a ne0 #rocess directly rather than creatin$ them throu$h
the shell9 3hat means that6 0ith s-(process6 you can safely #ass shell s#ecial characters9
3here are t0o 0ays to use the s-(process module) by creatin$ a Copen instance and by
usin$ the call)* function9 3he Copen method is more com#licated6 so 0e only document
the call)* function here9
Introducin" the call56 function
3he function s-(process"call)* is a shortcut for one of the more common uses of the
s-(process module9 &t runs a command6 0aits for the command to finish6 and then
returns its return code9 3his sim#le e8am#le lists the contents of a directory9 3he % after
the directory listin$ is a return code>a status messa$e that the sub#rocess sends9 Mn
?(&O6 % indicates that the sub#rocess com#leted successfully9
>>> s-(process"call)[,ls,, ,yOir,]*
copyy"py 2ello9orld"pyc myst-ff"Qip st-ff"Qip
copyy"pyc myspider"py pageco-nt"py st-ff2"Qip
2ello9orld"py myspider"pyc pageco-nt"pyc x
%
&seful callin" parameters
<ere are some of the more useful #arameters of the call)* function)
26A
args6 a strin$ or seGuence of #ro$ram ar$uments9 3he #ro$ram is the first item in
the seGuence6 and the other items are any command1line ar$uments the #ro$ram
ta/es9
&n the abo7e e8am#le6 args is a list9 3he #ro$ram is ,ls, and the command1line
ar$ument is ,yOir,9
3@:<(&:A.
S3?FF
Mn Windo0s6 args is con7erted to a strin$H the con7erted
7alue may not 0or/ 0ith all Windo0s a##lications9 &t 0or/s
0ith a##lications that su##ort the rules of MS : runtime9%
s2ell=0r-e s#ecifies to run the command throu$h the shell9 3he default shell is
s2 ?(&O% or 0hate7er is s#ecified by :MMS4@: Windo0s%9 3o s#ecify a
different shell6 use the exec-ta(le #arameter9
en5 defines en7ironment 7ariables for the sub#rocess9 3hese only a##ly to the
sub#rocessH they donCt chan$e any en7ironment 7ariables defined in your main
shell9
stdin6 stdo-t6 and stderr define ho0 data and error messa$es are transmitted to
and from the child #rocess9 Balues for these #arameters include CGC66 an e8istin$
file descri#tor a #ositi7e inte$er%6 an e8istin$ file obFect6 or 1one9 CGC6 creates a
ne0 #i#e to the child9 1one s#ecifies not to redirect messa$es the childCs file
handles are inherited from the #arent%9 3o send error messa$es to the same #lace
as other out#ut6 set stderr=@0OJ409
c9d s#ecifies a directory to chan$e to before the child #rocess runs9
Tryin" an (! command with call56
3his e8am#le code tries to run a command usin$ call)* and #rints information about the
success or failure of the attem#t9 3he name retcode stands for the return code that the
command sends9 3o use this try bloc/ in your o0n code6 Fust fill in your command and
ar$ument in #lace of "mycmd" : "myarg")
try!
retcode = s-(process"call)"mycmd" : " myarg", s2ell=0r-e*
if retcode # %!
print >>sys"stderr, "H2ild 9as terminated (y signal", 7retcode
else!
print >>sys"stderr, "H2ild ret-rned", retcode
except J@6rror, e!
print >>sys"stderr, "6xec-tion failed!", e
266
!tayin" on Time with the datetime and time 4odules
:om#uters usually store time as the number of seconds that ha7e #assed since some
s#ecific date called the epoch%9 3he e8act date 7aries de#endin$ on the o#eratin$ system9
3he ?(&O o#eratin$ system usually uses January -6 -*+09
<umans donCt thin/ of dates in terms of lar$e numbers of seconds6 so one of the functions
of the datetime and time libraries is to con7ert this machine time into date and time
information you can use9
4ython has t0o #rimary modules 0ith date and time tools)
3he datetime module includes tools for 0or/in$ 0ith dates6 times6 and
combinations thereof9 &t su##orts se7eral different calendar systems and 0ays of
#resentin$ time zone information but 0e donCt co7er time zones in this boo/%9
3he time module includes tools for 0or/in$ 0ith times and dates in the recent
#ast to near future9 &t focuses mostly on mani#ulatin$ time based on the
com#uterCs internal re#resentations of time9 For e8am#le6 the time module
includes a sleep)* method6 0hich lets you #ause e8ecution of your #ro$ram
0hile the com#uter counts do0n for you9
)sing the datetie odule
When you im#ort the datetime module6 you ha7e a7ailable a datetime)* obFect that
stores both date and time information9 Eou can also 0or/ 0ith dates and times se#arately
by usin$ date)* obFects and time)* obFects9 3hey 0or/ much the same 0ay as the
datetime)* obFect6 so 0e donCt co7er them here9
#omponents of a datetime56 ob>ect
An obFect that stores date and time information loo/s li/e this)
datetime"datetime)/=<=, E, 2%, 22, &<*
<ereCs more information about the com#onents)
datetime"datetime is the ty#e of obFect9
3he ar$uments are inte$ers6 se#arated by commas6 in this order)
o DeGuired ar$uments) year6 month6 and day of month
o M#tional ar$uments 0hich default to %%) hours6 minutes6 seconds6
microseconds9 Another o#tional ar$ument is time zone information6 0hich
defaults to 1one9 ?sin$ time zones in 4ython is an ad7anced feature
beyond the sco#e of this boo/9%
26+
3he #recedin$ obFect lea7es out seconds, microseconds, and time 2one
information9
When you s#ecify o#tional ar$uments6 you must s#ecify all ar$uments do0n to
the le7el of #recision you need by ty#in$ a number for any ar$uments to the left
of the ones you 0ant to s#ecify9 &tCs o/ay to lea7e out ar$uments to the ri$ht9 For
e8am#le6 to s#ecify no hours and A* minutes6 you ty#e % for the hours and &= for
the minutes9 Eou can lea7e out the seconds9 3he code loo/s li/e this)
datetime"datetime)/=</, /2, 3/, %, &=*
'ormattin" date and time information
4ython stores a datetime)* obFect in e8actly the same 0ay you entered it)
>>> moon9alA = datetime"datetime)/=<=, E, 2%, 22, &<, %*
>>> moon9alA
datetime"datetime)/=<=, E, 2%, 22, &<*
&f you 0ant the date and time in another format6 you ha7e a fe0 built1in o#tions6
includin$ the str)* function6 the ctime)* method6 and the isoformat)* method 0e
donCt document the latter t0o%9
3i# 3he most fle8ible 0ay to dis#lay a datetime)* obFect6 ho0e7er6 is to use the
strftime)* method IstrftimeI stands for Istrin$1format timeI%9 3his method ta/es a
strin$ as an ar$ument and uses D codes inside the strin$ to s#ecify ho0 to format
each element of the datetime)* obFect9 3he strftime codes 0or/ li/e the strin$
inter#olation codes described in :ha#ter 66 but the meanin$s of the codes themsel7es
are different9% 3he datetime)* formattin$ codes 7ary sli$htly by o#eratin$ system9
<ereCs one 0ay to format the moon9alA obFect)
-9 Type moon9alA"strftime9
29 (n the same line, in parentheses, type the followin" strin",
3" )"DL, DI Dd, DP DG!D!D@"*
3his strin$ tells 4ython to dis#lay the time usin$ a lon$ day of the 0ee/ DL%6 lon$
month DI%6 date of month Dd%6 four1di$it yearDP%6 and time9 &t uses commas and
colons as #unctuation9
<ereCs the line of code and the result)
>>> moon9alA"strftime)"DL, DI Dd, DP DG!D!D@"*
,@-nday, F-ly 2%, /=<= /%!&<!%%,
26,
Addin" time
When you #erform arithmetic on datetime)* obFects6 you $et the result in a
timedelta)* obFect9 &ts attributes are days, seconds6 and microseconds.
3@:<(&:A.
S3?FF
<ere is the timedelta)* obFect you $et 0hen you subtract the date
of the moon 0al/ from todayCs date in this e8am#le6 ItodayI is May
2-6 20066 a##ro8imately A)2A #9m9%9 3he e8am#le sho0s that -"6!A"
days ela#sed bet0een the first moon 0al/ on July 206 -*6*6 and May
2-6 2006)
>>> no9 = datetime"datetime"today)*
>>> moon9alA = datetime"datetime)/=<=, E, 2%, 22, &<*
>>> no9 7 moon9alA
datetime"timedelta)/3.&3, <<&=<, .%E=<'*
>>> print no9 7 moon9alA
/3.&3 days, /'!2=!&<".%E=<'
3he timedelta)* obFect 0or/s 0ith the follo0in$ o#erations) addition, subtraction,
multiplication, floor division, and absolute value. 3he timedelta)* obFect is immutable6
so it 0or/s as a dictionary /ey9
D@M@M'@D When you create a timedelta)* obFect6 you donCt ha7e to use days6
seconds6 and microseconds9 3hat 0ould be tedious for lar$e time
differences5%
Follo0 these ste#s to s#ecify a timedelta)
-9 Type datetime"timedelta9
29 (n the same line, in parentheses, specify any of the followin" keyword
ar"uments, separated by commas,
3" 9eeAs, days, 2o-rs, min-tes, seconds, microseconds, milliseconds
All the ar$uments are o#tional and if left out default to %9 For e8am#le6 to s#ecify
one day6 fi7e minutes6 and three seconds6 ty#e this)
datetime"timedelta)d#ys!0, min"tes!1, seconds!2*
3his is the timedelta obFect created and 4ythonCs result9 3he result doesnCt loo/ e8actly
li/e 0hat you entered because 4ython internally con7erts your data to days6 seconds6 and
microseconds9
>>> datetime"timedelta)/,3,%,%,&*
datetime"timedelta)/, 3%3*
When #rinted as a strin$6 the #recedin$ timedelta)* obFect loo/s li/e this)
>>> str)datetime"timedelta)/, 3%3**
26*
/ day, %!%&!%3
Taking your tie
3he time)* module includes tools for 0or/in$ 0ith the com#uterCs internal
re#resentation of time9 3ools de#end on your o#eratin$ system9
3he time)* module doesnCt handle times or dates in either
3he far #ast before -*00 A9D9%
3he far future
3@:<(&:A.
S3?FF
3he future time and date of the cutoff de#ends on your
o#eratin$ systemH for ?(&O systems6 itCs 20", A9D9
3o 0or/ 0ith far #ast or far future dates6 use the datetime)* module instead9
&sin" the time56 ob>ect
A time)* obFect is stored as a seGuence of nine inte$ers) year, month, day of month, hour,
minute, second, $eekday, day of year, and $hether daylight savings time is on % / 4 or off
% % 4.
3he time)* obFect is a tu#le in 4ython 29- and earlier9 &n later 7ersions6 it is another data
ty#e called str-ct$time)*9 WeCre tellin$ you this because you mi$ht see an error
messa$e referencin$ str-ct$time)* obFects9% 3ime is also e8#ressed as a floatin$ #oint
number6 for e8am#le6 by the time"time)* method9
3o create a time)* obFect that stores the current time and date6 ty#e this youCll $et a
different result6 of course%)
>>> time"localtime)*
)2%%<, 2, /, /', =, ., 2, 32, %*
3o see the local time as a strin$6 ty#e this)
>>> time"asctime)*
,Wed >e( / /E!3&!2= 2%%<,
3o format a time obFect as a strin$6 use the strftime)* method9 See IFormattin$ date
and time information6I earlier in this cha#ter9
2+0
-et's pause for a moment
3he time moduleCs sleep)* method is useful for #ro$rams that need built1in #auses9
Yuiz sho0s6 anyone2% 3he sleep)* method #auses the e8ecution of a #ro$ram for a
s#ecified number of seconds9
3he follo0in$ e8am#le uses the sleep)* method)
import time
for x in range)3*!
print "02e time is no9", time"asctime)*
print "1o9 sleeping for 2 seconds""""
time"sleep)2*
3his is the result of runnin$ the e8am#le code)
02e time is no9 @at >e( . /E!2'!%' 2%%<
1o9 sleeping for 2 seconds"""
02e time is no9 @at >e( . /E!2'!/% 2%%<
1o9 sleeping for 2 seconds"""
02e time is no9 @at >e( . /E!2'!/2 2%%<
1o9 sleeping for 2 seconds"""
8eepin" Track with the lo""in" 4odule
3he logging module is ne0 in 4ython 29"9 ?se it to set u# lo$ files or dis#lays for the
errors and debu$$in$ information for your #ro$rams9 4ython has 7ery fle8ible lo$$in$
featuresH 0e $et you started 0ith a fe0 basic 0ays to use lo$$in$9
Getting started &ith basic logging
3he tool that #rocesses messa$es is called a logger9 3he default lo$$er is called Iroot9I
.o$ messa$es are ta$$ed 0ith #riority codes6 and each #riority code has a method that
#roduces a lo$ messa$e of that #riority9 3he code methods are
de(-g)*, info)*, 9arning)*, error)*, critical)*
3o lo$ a messa$e6 follo0 these ste#s)
-9 Type logging6 a dot, and the method correspondin" to the messa"e priority,
for example,
2" logging"9arning
3i# 'y default6 the root lo$$er doesnCt do anythin$ 0ith debu$ or info messa$es9
&f you 0ant to see your messa$e 0ithout reconfi$urin$ the lo$$er6 use one of
these methods that indicate a hi$her #riority messa$e) 9arning)*6 error)*6
2+-
or critical)*9
"9 (n the same line, in parentheses, type a messa"e as a strin".
." logging"9arning(%*#tch o"t3%)
3he follo0in$ e8am#le tells the root lo$$er to lo$ a 0arnin$ messa$e and sho0s
the result you $et if you ty#e this in interacti7e mode)
>>> logging"9arning)"Watc2 o-t!"*
WLB1G1S!root!Watc2 o-t!
3@:<(&:A.
S3?FF
3he default beha7ior of the root lo$$er is as follo0s)
4rocess 0arnin$ messa$es and hi$her6 i$nore debu$ and info
messa$es
&f you try to use the info)* method 0ith the default root
lo$$er6 you $et no res#onse)
>>> logging"info)"0ry and see me"*
>>>
4rint messa$es as strin$s
.o$ messa$es to sys"stderr
&n interacti7e mode6 sys"stderr #rints to the screen9
#hanging the configuration of a logger
3o chan$e the default confi$uration of the root lo$$er6 or to set u# the confi$uration of a
lo$$er you 0rite yourself6 use the (asicHonfig)* function9 Fi$ure -+1- illustrates some
e8am#le (asicHonfig)* code9
Fi$ure -+1-) @8am#le of lo$$in$9 basic :onfi$% code9
3he /ey0ord ar$uments for (asicHonfig)* reGuire 4ython 29! and later9
1esigning your o&n logging syste
&f different #arts of your #ro$ram ha7e different lo$$in$ reGuirements6 hereCs some
$uidance to $et you started creatin$ your o0n lo$$ers9
2+2
3i# (ame your lo$$ers accordin$ to the #art of the #ro$ram youCre lo$$in$ errors from
and then confi$ure your lo$$er in these basic 0ays)
-evels of messa"es to process
3he le7els are associated 0ith inte$ers6 as follo0s)
o :D&3&:A.) A0
o @DDMD) !0
o WAD(&(;) "0
o &(FM) 20
o D@'?;) -0
'ormat of the messa"es
Handlers that determine where the messa"es should be lo""ed.
Most handlers are of the ty#e @treamHandler or >ileHandler9 3hereCs also
@0CHandler sends error messa$es 7ia e1mail%6 H00CHandler sends
messa$es to an <334 ser7er%6 and more9
Seeing a fe& logging functions
3hese are the most useful basic functions a7ailable in the lo$$in$ module)
log)*
.o$s a messa$e9 S#ecify o#tions in this order6 se#arated by commas) #riority le7el
as an inte$er%6 messa$e a formattin$ strin$ 0ith D codes%6 and the ar$uments to
include in the strin$9 Add exc$info at the end to include e8ce#tion information in
the messa$e9 3his e8am#le lo$s a 0arnin$ messa$e by usin$ D formattin$)
>>> logging"log)3%, "2ello, is t2at DsV", "yo-"*
WLB1G1S!root!2ello, is t2at yo-V
disa(le)*
Disables messa$es at the s#ecified #riority le7el and belo09 M7errides the le7els
s#ecified in lo$$ers9 S#ecify the #riority le7el as an inte$er9
s2-tdo9n)*
Shuts do0n the lo$$in$ system9 Flushes and closes all handlers9
#hapter .G, rocessin" Text
(verview
2+"
3here are 0hole boo/s on 4ythonCs te8t1#rocessin$ ca#abilities6 so this cha#ter co7ers
only the basics>three of the most im#ortant te8t1#rocessin$ modules that come 0ith
4ython9 &n this cha#ter6 you find out about
3he re module6 0hich brin$s the #o0er of re$ular e8#ression te8t searches to
4ython
3he @tringGJ library6 0hich lets you 0or/ 0ith strin$s as if they 0ere files
3he text9rap library6 0hich includes 7arious tools for tidyin$ u# #ara$ra#hs
3i# More te8t1#rocessin$ information can be found in :ha#ter 69
A 4illion *ays to re, %ou 8now That There Are
3he re module su##orts searchin$ te8t files by usin$ regular e!pressions rege!es for
short%>strin$s that s#ecify a set of match rules9
3he follo0in$ sections describe
3he character codes that you use to build re$e8es
3he search abilities of 4ythonCs re library
3i#
*hen not to use a re"ex
4ythonCs data ty#es include a number of easy1to1use te8t1search methods9 We
recommend that you $et familiar 0ith these methods and use them rather than the re
module if they 0ill fit your needs9
De$ular e8#ressions are com#le8 and hard to use6 and itCs easy to ma/e mista/es
0hen usin$ them9
For e8am#le6 if you ha7e a file of Guotations6 each se#arated by ,DDZn,6 you could
use a re$e8 to s#lit the file into se#arate Guotes9 'ut it 0ould be better to use the
split)* method of strin$s9
*riting a basic regex
3o create a re$e86 Fust 0rite it as a strin$>that is6 enclose some te8t in Guotation mar/s9
Eou can use sin$le or double Guotation mar/s6 or e7en tri#le Guotes9 Eour strin$ can be
Fust a set of characters to loo/ for6 or it can include s#ecial instructions9
2+!
3he follo0in$ strin$6 if used 0ith one of the re methods or functions6 uses the []
characters to $i7e s#ecial instructions to search for either monty or minty but not
mointy6 a city in =aza/hstan%)
,m[oi]nty,
3i# 'oth re$e8es and 4ython strin$s often use the bac/slash Z% to indicate s#ecial
treatment for a character9 3he re module reco$nizes 4ythonCs Z codes6 li/e Zn for
ne0line9 We discuss these codes in :ha#ter 69% 'ut to a7oid conflicts6 you should
usually 0rite re$e8es as ra0 strin$s by #re#endin$ r to the strin$9 3he r tells
4ythonCs strin$ data ty#e to i$nore any bac/slashes inside the strin$ and sa7e them
for the re method or function to #rocess9
Setting up a basic regex search
3he follo0in$ code $i7es the name Qipcode to a re$e8 s#ecified as a ra0 strin$% that
loo/s for the te8t Kip! follo0ed by any number of 0hite s#ace characters Zs;% and fi7e
di$its Zd%)
>>> Qipcode = r,Kip!Zs;ZdZdZdZdZd,
3@:<(&:A.
S3?FF
3o use the Qipcode re$e8 to search for a zi# code in a strin$6 ty#e
code li/e this)
>>> addr = "@treet address! 3.2 Lny92ere Bd Zn Kip!
32.33"
>>> re"searc2)Qipcode, addr*
&f the search is successful6 it returns an obFect of the ty#e
$sre"@B6$atc26 li/e this)
#$sre"@B6$atc2 o(Tect at %x'2%2<.%>
&f there is no match6 it returns 1one9
>>> mystring = "foo"
>>> print re"searc2)Qipcode, mystring*
1one
/egular expression characters and codes
3he search rules in a re$ular e8#ression can be sim#le the sim#lest useful re$e8 is a
sin$le character% or com#le89 :om#le8 rules are im#lemented by usin$ characters that
ha7e s#ecial meanin$s in re$ular e8#ressions9 We describe these characters and codes in
the follo0in$ sections9
!pecial characters
3able -,1- sho0s the most commonly used of the characters that ha7e s#ecial meanin$s
in re$e8es9
2+A
3able -,1-) De$ular @8#ression S#ecial :haracters
M#en table as s#readsheet
#haracter Action 2xample and ?otes
" dot% Matches any sin$le character e8ce#t a
ne0line9
,p"t2on, matches pyt2on6
p!t2on6 p2t2on6 but not
pyyt2on9
[ ]
@ncloses a set of characters to match a
character class%9 A match occurs if any one
of the characters is found9 Eou canenclose
s#ecific characters or a ran$e of characters6
such as all the u##ercase letters) [L7K]
,0[iy]ger, matches 0iger or
0yger but not 0iyger%9
&f you 0ant to match a hy#hen
inside a character class6 it must
be the first or last character9
[Zs"7] matches s#ace6 #eriod6
or hy#hen9
caret% At the be$innin$ of a character class6 stands
for Inot9I Mutside of a character class6
matches the be$innin$ of a line9
,[a], matches any character
that isnCt JaK9
,L, matches ,Lmerica, but
not ,Hanada,9
a
Matches the end of a line or strin$6 de#endin$
on the 430GJO6 fla$9 See 3able -,1"9%
,ta, matches ,(rig2t, but
not ,tender,9
regex# [
regex$
Matches either of t0o re$e8es6 startin$ 0ith
the leftmost and sto##in$ 0hen it finds a
match9 Eou can use multi#le [ characters to
Foin se7eral re$e8es9
,pyt2on, [ ,asp, first loo/s
in a strin$ for ,pyt2on,9 &f
,pyt2on, is not found6 it then
loo/s for ,asp,9
{ number }
Matches the #recedin$ re$e8 only if the re$e8
occurs a certain number of times
consecuti7ely9
,y{3}, matches ,pyyyt2on,
but not ,pyt2on,
)*
@ncloses a re$e8 $rou#9 Eou can refer to
$rou#s by number9 3he first $rou# is referred
to by Z/6 the second by Z26 and so on9
r ,C2one! )Zd{3}*7)Zd{3}7
Zd{.}*, loo/s for a #hone
number6 0ith the area code in
$rou# - and the number in
$rou# 29
Z/ refers to the area code $rou#
in the abo7e re$e89
Z
@sca#e code>treats the character that
follo0s as s#ecial6 or treats a s#ecial
character as te8t9 See the follo0in$ section9
,Za, searches for the a
character in te8t instead of
treatin$ a as an Iend of line or
strin$I code9
2+6
3able -,12) De$e8 :odes 0ith S#ecial Meanin$s
M#en table as s#readsheet
#ode Action
Z number
Matches the contents of the $rou# 0ith that number
ZL
Matches only at the start of a strin$
Z(
Matches an em#ty strin$ at the be$innin$ or end of a 0ord
ZI
Matches an em#ty strin$ in the middle of a 0ord
Zd
Matches any di$it %7=%
ZO
Matches any character that is not a di$it
Zs
Matches any 0hite s#ace character
Z@
Matches any character that is not 0hite s#ace
Z9
Matches any al#hanumeric character
ZW
Matches any character that is not al#hanumeric
ZK
Matches only at the end of a strin$
3able -,1") M#tional Fla$s for De$e8es
M#en table as s#readsheet
-on" ?ame !hort
?ame
4eanin"
&;(MD@:AS@ & Matches are case1insensiti7e9
.M:A.@ . Matches de#end on the current locale9
M?.3&.&(@ M Allo0s and a to match linefeeds Zn% inside a strin$9 Without
it6 they match only the be$innin$ % and end a% of a strin$9
DM3A.. S Dot "% matches any character includin$ ne0line9
?(&:MD@ ? Matches de#end on the ?nicode locale9
B@D'MS@ O Allo0 s#aces and comments in re$e8es9 3his ma/es them
easier for humans to read9
2scape codes with special meanin"s
When you use Z in front of some characters in a re$e86 it creates a code 0ith a s#ecial
meanin$9 3able -,12 lists these s#ecial re$e8 codes9 3he re module also reco$nizes the
4ython esca#e codes>for e8am#le6 Zn for ne0line9
'indin" repeats
Mne common re$e8 tas/ is to find re#eats of a character or other match9 Eou 0rite a re$e8
to find re#eats by usin$ the characters :6 ;6 V6 or {}9
4ython lets you search for re#eated characters in a number of 0ays)
2++
; matches the #re7ious character any number of times6 including none.
py;t2on matches pt2on6 pyt2on6 pyyt2on6 and so on9
: matches the #re7ious character one or more times9
py:t2on matches pyt2on and pyyt2on6 but not pt2on9
V matches the #re7ious character zero or one times9
pyVt2on matches pt2on and pyt2on6 but not pyyt2on9
(umbers enclosed in curly braces {}% create a ran$e of re#eated characters6 li/e this)
py{&}t2on matches an e8act number of re#eats) pyyyyyt2on
py{/,3}t2on matches a ran$e of re#eats) pyt2on6 pyyt2on6 and pyyyt2on9 &t
doesnCt match pt2on or pyyyyt2on9
3i# &f you lea7e out the first number of the ran$e for e8am#le6 py{,3}t2on%6 the
first ran$e defaults to 09 3his e8am#le 0ould match pt2on6 pyt2on6 pyyt2on6
or pyyyt2on9 &f you lea7e out the last number of the ran$e for e8am#le6
py{/,}t2on%6 any number of re#eats eGual to or lar$er than the first number
0ill match9
De$e8es su##ort t0o /inds of re#eatin$ searches) =reedy and non-greedy.
1reedy searhes
A $reedy search tries to match as many of the search characters as #ossible9
3he follo0in$ re$e8 $reedily searches for one or more y characters in a ro09 &t finds all
three y characters in the strin$ ,pyyyt2on,)
>>> p = ,pyyyt2on,
>>> greedy$re = 'y4'
>>> mymatc2 = re"searc2)greedy$re, p*
>>> mymatc2"gro-p)*
,yyy,
Non-greedy searhes
A non1$reedy search sto#s after it finds one match9
3o s#ecify a non1$reedy search6 add V after either
3he re#eat character
3he end brace of a ran$e
2+,
3he follo0in$ re$e8 searches for one or more y characters in a ro06 but the V character
s#ecifies a non1$reedy search9 As soon as this search finds one y6 itCs finished)
>>> p = ,pyyyt2on,
>>> non$greedy$re = 'y45'
>>> mymatc2 = re"searc2)non$greedy$re, p*
>>> mymatc2"gro-p)*
,y,
/e"ex "roups
De$e8es can be com#licated to read and to ty#e9 Mne 0ay of ma/in$ re$e8es easier to
read is to enclose a #ortion of a re$e8 inside #arentheses to ma/e a rege! group. 3his also
ma/es the re$e8 easier to use later because you can refer to the $rou# by ty#in$ a number
or name instead of rety#in$ the 0hole re$e89
4ython deals 0ith t0o ty#es of re$e8 $rou#s)
?umbered "roups, Whene7er you $rou# #art of a re$e8 inside #arentheses6 it
automatically $ets a number>/ for the first $rou#6 2 for the second6 and so on9
?amed "roups, 3o name a $rou#6 be$in the statement inside #arentheses 0ith
this code substitutin$ your name%)
VC#groupname>
Follo0 it 0ith the re$e8 and then ty#e a closin$ #arenthesis9
3he follo0in$ e8am#le creates a $rou# named Qip that searches for the te8t Kip!
follo0ed by any number of s#aces and e8actly fi7e di$its9
)VC#Qip>Kip!Zs;ZdZdZdZdZd*
Eou can refer to a numbered or named re$e8 $rou# in se7eral 0ays)
Eou can refer to a $rou# in any atc2J(Tect method that ta/es a re$e8 as an
ar$ument9 &n the e8am#les belo06 the gro-pdict)* method returns a dictionary
containin$ the $rou# name ,Qip, and its matches9 3he gro-p)* method returns
the matches of the second $rou#)
>>> my$regex = r,)VC#Qip>Kip!Zs;ZdZdZdZdZd*Zs;)@tate!Zs;Z9Z9*,
>>> addrs = "Kip! /%%/% @tate! 1P"
>>> y = re"searc2)my$regex, addrs*
>>> y"gro-pdict),Qip,*
{,Qip,! ,Kip! /%%/%,}
>>> y"gro-p)2*
,@tate! 1P,
When 0ritin$ a re$e86 you can refer to the ,Qip, $rou# by usin$ the follo0in$
synta8) )VC=,Qip,*
Eou can use a $rou# 0hen s#ecifyin$ re#lacement te8t) Zg#Qip>9
2+*
3i# For an e8am#le of a re$e8 0ith multi#le $rou#s6 see IMa/in$ re$e8es more
readable6I later in this cha#ter9
)sing the regular expression odule
3here are t0o 0ays to use the re module)
?se functions to #erform re$e8 o#erations on a strin$9
With the compile)* function6 turn the re$e8 into an obFect called a regular
e!pression ob-ectH in some 4ython messa$es6 itCs called an ,(1>Pattern ob-ect%
and use the obFectCs methods to 0or/ 0ith the re$e89
'unctional versus methodical
3i# &f you 0ant to use a sim#le re$e8 only once6 itCs o/ay to use the functions9 'ut for
code that uses re$e8es hea7ily6 0e recommend usin$ the com#iled form of re$e8es
for t0o reasons)
3he com#iled obFect 0or/s faster9
Dememberin$ the order of ar$uments is easier if you al0ays use the com#iled
form9
2sing a regex %untion
3o use a re$e8 function6 ty#e these elements)
3he function name
4arentheses
4ass any ar$uments inside the #arentheses6 se#arated by commas9 &he rege! is
al$ays the first argument.
3his e8am#le uses the findall)* function to return a list of all the 7o0els in a strin$9
>>> mystring = ,Po-r fat2er smelt of elder(erries!,
>>> print re"findall),[aeio-],, mystring*
[,o,, ,-,, ,a,, ,e,, ,e,, ,o,, ,e,, ,e,, ,e,, ,i,, ,e,]
Some re$e8 functions return a match obFect9 See IYueryin$ the match obFect6I later in
this cha#ter9
2sing a regex method
3o use a re$e8 method6 ty#e these elements)
3he name of the re$e8 obFect that you created by usin$ the compile)* function
2,0
See the ne8t section6 I:om#ilin$ re$ular e8#ressions9I
A dot
3he method name
4arentheses
4ass any ar$uments inside the #arentheses6 se#arated by commas9
3his e8am#le creates a re$e8 obFect that finds 7o0els and uses the findall)* method to
return a list of all the 7o0els in a strin$9
>>> mystring = ,Po-r fat2er smelt of elder(erries!,
>>> 5o9els = re"compile),[aeio-],*
>>> 5o9els"findall)mystring*
[,o,, ,-,, ,a,, ,e,, ,e,, ,o,, ,e,, ,e,, ,e,, ,i,, ,e,]
#ompilin" re"ular expressions
3o turn a re$e8 strin$ into a regular e!pression ob-ect6 you use the compile)* function9
compile)* ta/es a re$e8 strin$ and o#tional fla$s see 3able -,1"% as ar$uments9 <ereCs
an e8am#le)
>>> my$regex = re"compile),py:t2on,, re"GS1JB6HL@6*
>>> my$regex
#$sre"@B6$Cattern o(Tect at %x'22%%e%>
3he obFect contains the follo0in$ data attributes)
flags) A number corres#ondin$ to the fla$ used 0hen the re obFect 0as
com#iled9 See 3able -,1"9 3his is % if no fla$s 0ere used9
>>> my$regex"flags
2
gro-pindex) A dictionary ma##in$ any $rou# names to $rou# numbers9 3he
dictionary is em#ty if no $rou# names 0ere s#ecified9
pattern) 3he re$e8 from 0hich the obFect 0as com#iled9
>>> my$regex"pattern
,py:t2on,
Tools of the re module
3he follo0in$ re$e8 functions and methods are the most useful9
%indall&'
findall)* returns a list of all the occurrences of a re$e8 in a strin$9 &t also ta/es an
o#tional fla$ ar$ument 3able -,1" lists the fla$s%9
2,-
3i# finditer)* does the same thin$ as findall)* but returns an iterator obFect rather
than a list9
math&'
3o find a sin$le occurrence of a re$e8 at the start of a strin$6 use matc2)*)
matc2)* ta/es a strin$ and an o#tional fla$ as ar$uments 3able -,1" lists the
fla$s%9
matc2)* returns either
o A atc2J(Tect instance if there is a match%
See IYueryin$ the match obFect6I later in this cha#ter9
o 1one if there is no match%
D@M@M'@D &tCs easy to confuse matc2)*6 0hich matches only at the be$innin$ of a
strin$6 and searc2)*6 0hich matches any0here in a strin$9 See the
follo0in$ section9% Mne 0ay around this #roblem is to al0ays use
searc2)*6 s#ecifyin$ in your re$e8 to match only at the be$innin$ of a
strin$9
searh&'
3o find a sin$le occurrence of a re$e8 any$here in a strin$6 use searc2)*9
searc2)* ta/es a strin$ and an o#tional fla$ as ar$uments 3able -,1" lists the
fla$s%9
searc2)* returns either
o A atc2J(Tect instance if there is a match%
See IYueryin$ the match obFect6I later in this cha#ter9
o 1one if there is no match%
split&'
3o s#lit a strin$ 0here7er a re$e8 is found6 use split)*9
split)* ta/es these ar$uments)
o A strin$
o An o#tional inte$er s#ecifyin$ the ma8imum number of times to s#lit the
strin$
split)* returns a list of the substrin$s9
3his e8am#le sho0s the 0or/in$s of the split)* function)
2,2
>>> co9/ = "G ne5er sa9 a p-rple co9, YY G ne5er 2ope to see oneR"
>>> re"split),,, co9/* + f-nction
[,G ne5er sa9 a p-rple co9, ,, , G ne5er 2ope to see oneR,]
3his e8am#le uses the split)* method 0ith the same re$e8)
>>> co92 = "I-t G can tell yo- any2o9, YY G,d rat2er see t2an (e one""
>>> sep = re"compile),,*
>>> sep"split)co92*
[,I-t G can tell yo- any2o9, ,, " G,d rat2er see t2an (e one""]
su!&'
3o find all occurrences of some te8t in a strin$ and substitute other te8t6 use s-()*)
When s-()* finds a match6 it substitutes the re#lacement strin$9
s-()* returns either
o 3he chan$ed strin$ if any chan$es 0ere made%
o 3he ori$inal strin$ if no chan$es 0ere made%
s-()* ta/es these ar$uments)
A re#lacement strin$
3he ori$inal strin$
An o#tional inte$er
3he inte$er s#ecifies the ma8imum number of re#lacements9 &f you lea7e the
inte$er out6 all matches are re#laced9
3he follo0in$ code sho0s the result of re#lacin$ #art of a strin$)
>>> mystring = "6-ropean s9allo9"
>>> myregex = re"compile)"6-ropean"*
>>> myregex"s-()"Lfrican", mystring* + met2od
,Lfrican s9allo9,
>>> re"s-(),6-ropean,, ,Lfrican,, mystring* + f-nction
,Lfrican s9allo9,
Iueryin" the match ob>ect
A successful re$e8 search returns a 4ython obFect called a atc2J(Tect6 as illustrated in
the follo0in$ e8am#le)
>>> my$regex = re"compile),py:t2on,*
>>> mystring = "pyyyt2on is a s---per programming lang-age"
>>> mymatc2 = my$regex"matc2)mystring*
>>> mymatc2
#$sre"@B6$atc2 o(Tect at %x'2c<c2'>
2,"
3he atc2J(Tect stores information about 0here in the strin$ the match starts and ends6
the substrin$s% that 0ere matched6 and so on9 3o $et access to this information6 you use
the follo0in$ methods)
gro-p)*) 3a/es the $rou# inde8 number as an ar$umentH this defaults to 06 or the
first $rou#6 0hich returns the matched strin$9
>>> mymatc2"gro-p)%*
,pyyyt2on,
gro-ps)*) Deturns a tu#le containin$ the match found for each re$e8 $rou#9
3a/es an o#tional ar$ument to return for the re$e8 $rou#s that didnCt match
anythin$H this defaults to 1one9
3i# 3he re$e8 for the follo0in$ atc2J(Tect has t0o $rou#s6 one named $rou#
for zi# code and one numbered $rou# for the strin$ ,4@L,9
>>> y"gro-ps)*
),Kip! =./%/,, ,4@L,*
gro-pdict)*) Deturns a dictionary containin$ all the named sub$rou#s of the
match9 3he /eys are the sub$rou# names9 3a/es an o#tional ar$ument to return for
non#artici#atin$ $rou#sH this defaults to 1one9
>>> y"gro-pdict)*
{,Qip,! ,Kip! =./%/,}
span)*) Deturns a tu#le containin$ the startin$ and endin$ inde8 numbers that
0ere matched9 3a/es the $rou# inde8 number as an ar$umentH this defaults to 06 or
the first $rou#9
>>> mymatc2"span)%*
)%, '*
Eou can $et Fust the startin$ #osition 0ith start)* and Fust the endin$ #osition
0ith end)*9 'oth of these also ta/e the $rou# inde8 number ar$ument9
3i#
Additional re"ex resources
3he IDe$ular @8#ression <MW3MI Web #a$e at
htt#)LL0009am/9caL#ythonLho0toLre$e8L includes a basic tutorial on re$ular
e8#ressions9
De$e8 debuggers can hel# clarify re$e8 #roblems9 =odos6 the 4ython De$ular
@8#ression Debu$$er a7ailable at htt#)LL0009/odos9sourcefor$e9netL%6 is one such
tool9
A tool for #racticin$ and testin$ re$e8es comes 0ith 4ython 29!9 &tCs #art of the ;?&
tool /it 3/inter6 and itCs usually installed at 0ools8scripts8redemo"py9
=i/i6 0hich comes 0ith the W84ython installer6 has nice colorin$ for $rou#in$ in
re$e8es9 More info about W84ython can be found at htt#)LL000908#ython9or$L9
2,!
When youCre 0ritin$ a #ro$ram that uses a re$e8 to search a strin$6 you usually 0ant to
chec/ 0hether there 0as a match9 3o do this6 you chec/ 0hether the match obFect is
1one9 For e8am#le6 you mi$ht use this code remember that if mymatc2 is short for if
mymatc2 is not 1one%)
if mymatc2!
print ,atc2 fo-nd,
else!
print ,1o matc2,
4akin" re"exes more readable
Eou can use the W6BIJ@6 fla$ 0hen you 0rite a re$e8 to ma/e it more readable9 With this
fla$6 you can use comments and 0hite s#ace in your re$e89 <ereCs ho0 it 0or/s)
3he re$e8 inter#reter i$nores any 0hite s#ace that is outside sGuare brac/ets9
Anythin$ follo0in$ the + character on a line>as lon$ as + isnCt inside sGuare
brac/ets>is considered a comment rather than #art of the re$e89
?sin$ a ra0 strin$ 0ith tri#le1Guotes is the sim#lest 0ay to 0rite a multi1line
re$e8 0ith comments9
3his e8am#le searches te8t for a #hone number9 &t finds numbers 0ith or 0ithout
#arentheses around the area code6 and 0ith or 0ithout a s#ace6 #eriod6 or hy#hen as a
se#arator9
>>> p2one$re = re"compile)r,,,
""" Z)V + optionally matc2 (egin parent2esis
""" )VC#area>Zd{3}* + matc28name gro-p for area code
""" Z*V + optionally matc2 end parent2esis
""" [Zs"7]V + optionally matc2 space, period, or 2yp2en
""" )VC#prefix>Zd{3}* + matc28name gro-p for prefix
""" [Zs"7]V + optionally matc2 space, period, or 2yp2en
""" )VC#s-ffix>Zd{.}* + matc28name gro-p for s-ffix
""" ,,,, re"W6BIJ@6*
>>> p2one$re"s-()r,Zg#area>7Zg#prefix>7Zg#s-ffix>,, ,)2/3*&&&7/2/2,*
2/37&&&7/2/2
>>> p2one$re"s-()r,Zg#area>7Zg#prefix>7Zg#s-ffix>,, ,2/3"&&&"/2/2,*
2/37&&&7/2/2
!trin"s :is"uised as 'iles
3he c@tringGJ and @tringGJ modules su##ort Istrin$ buffersI also called memory
files% that let you #retend that a strin$ is a file9 3his is useful because some 4ython library
modules6 such as the tarfile module6 0or/ 0ith files but not 0ith strin$s9 4ython holds
the IfileI in memory instead of 0ritin$ the file to dis/9
2,A
!trin"I( versus c!trin"I(
3he c@tringGJ module im#lements the same functionality as @tringGJ9 c@tringGJ is
faster6 but it has a cou#le of limitations)
c@tringGJ doesnCt su##ort subclassin$9 ?se @tringGJ if you need to 0rite a
subclass of @tringGJ9
&f you $i7e ?nicode strin$s to c@tringGJ6 you must encode them as ?3F1, see
:ha#ter 6%9
#reating a StringI0 ob'ect
3here are t0o 0ays to create a @tringGJ obFect)
ass it a strin" as an ar"ument. 3his is called initiali2ing the buffer.
Do this if you 0ant to read or other0ise #rocess an e8istin$ strin$9
-eave out the ar"ument, 0hich creates the obFect 0ith an em#ty buffer9
Do this if you 0ant to 0rite to the obFect9
3o create a @tringGJ obFect6 follo0 these ste#s)
-9 Type from c@tringGJ import @tringGJ9
29 (n the next line, type code like one of the followin" lines.
Substitute the name of your file and your strin$ or its name%9
3o create an em#ty buffer6 ty#e this)
pretend$file = @tringGJ)*
3o initialize the buffer 0ith an e8istin$ strin$6 ty#e this)
pretend$file = @tringGJ)"mystring"*
StringI0 special ethods
3he methods for 0or/in$ 0ith @tringGJ files are the same as the methods for 0or/in$
0ith re$ular files described in :ha#ter -+%9
<ere are t0o differences)
2,6
3he @tringGJ obFect includes the get5al-e)* method6 0hich returns the entire
contents of the memory file as a strin$)
>>> pretend$file"get5al-e)*
,mystring,
3he @tringGJ close)* method frees u# the memory buffer9
A re$ular file obFectCs close)* method 0rites the contents to dis/9
ara"raph :umplin"s, 'illin" and *rappin" Text
3he text9rap module6 ne0 in 4ython 29"6 is for formattin$ #ara$ra#hs of te8t9 Eou can
#erform three basic formattin$ tas/s 0ith it) unindentin$ Idedentin$I%6 0ra##in$6 and
fillin$9 Eou can also create a customized 0extWrapper obFect9
/eo$ing indentation fro strings
3o remo7e 0hite s#ace that a##ears in front of e7ery line of the strin$6 use the dedent)*
function9 &t ta/es a strin$ as an ar$ument9
3@:<(&:A.
S3?FF
Dedent is meant to be the o##osite of
indent.
Mne use for this function is to ma/e tri#le1Guoted strin$s in a 4ython #ro$ram>
docstrin$s for e8am#le>line u# 0ith the left mar$in6 e7en thou$h they are indented in
the source code9 <ereCs an e8am#le)
>>> mystring = ,,, 0yger, 0yger, (-rning (rig2t
""" Gn t2e forests of t2e nig2t,,,
>>> print mystring
0yger, 0yger, (-rning (rig2t
Gn t2e forests of t2e nig2t
>>> print text9rap"dedent)mystring*
0yger, 0yger, (-rning (rig2t
Gn t2e forests of t2e nig2t
*rapping text by splitting it up
3o turn a lon$ strin$ into a list of strin$s6 one for each line of te8t6 use the 9rap)*
function9 &t ta/es a strin$ as an ar$ument6 and it also ta/es an o#tional 9idt2 ar$ument6
s#ecifyin$ the ma8imum len$th of any line it defaults to +0 characters%9 3he strin$s
returned donCt ha7e ne0line characters9
3he follo0in$ e8am#le sho0s the use of the 9rap)* function on a lon$ strin$)
>>> metap2or = """Z
""" Worse, many a(andon t2e pearl 92ic2 exists in t2e present in fa5or
""" of a cara5an of dreams 92ic2 al9ays recedes across t2e desert" 77
ixed
2,+
""" etap2or Hall of >ame"""
>>> m = text9rap"9rap)metap2or, 9idt2=.%*
>>> m
[,Worse, many a(andon t2e pearl 92ic2,, ,exists in t2e present in fa5or
of
a,,,cara5an of dreams 92ic2 al9ays recedes,, ,across t2e desert" 77
ixed
etap2or,, ,Hall of >ame,]
3i# Eou could use a for loo# to #rint the result of the 9rap)* function)
>>> for i in m!
""" print i
"""
Worse, many a(andon t2e pearl 92ic2
exists in t2e present in fa5or of a
cara5an of dreams 92ic2 al9ays recedes
across t2e desert" 77 ixed etap2or
Hall of >ame
<ereCs a shorter idiom for accom#lishin$ the same thin$)
print ,Zn,"Toin)m*
*rapping text by adding ne&line characters
3o add ne0line characters to a lon$ strin$6 use the fill)* function9 &t ta/es a strin$ as an
ar$ument and returns a strin$9 &t also ta/es an o#tional 9idt2 ar$ument6 s#ecifyin$ the
ma8imum len$th of any line it defaults to +0 characters%9
<ereCs an e8am#le of 0ra##in$ te8t 0ith the fill)* function)
>>> longstring = ,,,
""" I-t once yo- (-ild some islands of peace into yo-r daily ro-tine,
t2ey
""" 2elp ser5e as (eac22eads against t2e f-ll7co-rt press of life"
""" 77ixed etap2or Hall of >ame,,,
>>> 9rappedstring = text9rap"fill)longstring, 9idt2=.%*
>>> 9rappedstring
, I-t once yo- (-ild some islands ofZnpeace into yo-r daily ro-tine,
t2ey 2elpZnser5e as (eac22eads against t2e f-ll7Znco-rt press of
life" 77ixed etap2orZnHall of >ame,
>>> print 9rappedstring
I-t once yo- (-ild some islands of
peace into yo-r daily ro-tine, t2ey 2elp
ser5e as (eac22eads against t2e f-ll7
co-rt press of life" 77ixed etap2or
Hall of >ame
2,,
#reating a Text*rapper ob'ect
3he 9rap)* and fill)* functions 0or/ by creatin$ a 0extWrapper instance and callin$
a sin$le method on it9
3@:<(&:A.
S3?FF
3his instance $oes a0ay after you use it6 so for a##lications that
format many te8t strin$s6 itCs more efficient to create your o0n
0extWrapper obFect9
Text*rapper attributes
When you create a 0extWrapper obFect6 you can s#ecify any of the follo0in$ ar$uments9
Eou can also use them as /ey0ord ar$uments for the 9rap)* and fill)* functions9
9idt2) 3he ma8imum len$th of a 0ra##ed line9 3he default is +0 characters9
expand$ta(s) :han$es tabs to an eGui7alent number of s#aces bet0een - and ,%9
Default 0r-e9 &f set to >alse6 tabs are treated as sin$le characters9
replace$92itespace) :han$es all 0hite s#ace characters to s#aces9 Default
0r-e9
What counts as a 0hite s#ace character is defined by the 92itespace data
attribute of the string module9 3his de#ends on your locale and o#eratin$
system9 <ereCs our result)
>>> import string
>>> string"92itespace
,ZtZnZx%(Zx%cZr ,
3he meanin$s of the codes are) Zt tab%6 Zn ne0line%6 Zx%( 7ertical tab%6 Zx%c
form feed%6 Zr carria$e return%6 , , s#ace%9
Warnin$ &f you set expand$ta(s to >alse and replace$92itespace to 0r-e6
tabs are con7erted to sin$le s#ace characters9
initial$indent) Set this to a strin$ of fi7e s#aces or so to $et an indented line at
the be$innin$ of a #ara$ra#h9 3he default is an em#ty strin$9
s-(seN-ent$indent) 3his strin$ is added at the be$innin$ of all 0ra##ed lines
after the first9 Default is an em#ty strin$9
fix$sentence$endings) 4uts t0o s#aces bet0een sentences9
Warnin$ What text9rap thin/s a sentence is mi$ht not match 0hat you thin/ a
sentence is9 For e8am#le6 fix$sentence$endings #uts t0o s#aces after
IDr9I Default is >alse9
(reaA$long$9ords) 'rea/s 0ords lon$er than the 9idt2 attribute9 &f set to
>alse6 lines 0ith lon$ 0ords may e8ceed the s#ecified 0idth9 Default is 0r-e9
2,*
2xample of a custom Text*rapper ob>ect
<ereCs an e8am#le of a custom 0extWrapper obFect9 3his obFect s#ecifies a !01character
line and indents each line after the first one ! s#aces9
>>> my9rapper = text9rap"0extWrapper)9idt2=.%, s-(seN-ent$indent=" "*
>>> indented$string = my9rapper"fill)longstring*
>>> print indented$string
I-t once yo- (-ild some islands of
peace into yo-r daily ro-tine, t2ey
2elp ser5e as (eac22eads against t2e
f-ll7co-rt press of life" 77ixed
etap2or Hall of >ame
2*0
#hapter .J, :i""in" into :isk :ata
4ython includes a 7ariety of modules and #ac/a$es for 0or/in$ 0ith data files on dis/9 &n
this cha#ter6 you find out ho0 to
?se 4ython to 0or/ 0ith files on your hard dri7e6 includin$ com#ressed Qi# files9
?se 4ython to communicate 0ith databases9
3urn 4ython obFects such as dictionaries% into formats that can be stored or sent
o7er the &nternet9
!hell +ame, #opyin" and 4ovin" 'iles
3he s2-til module lets you use 4ython to mani#ulate6 co#y6 and remo7e files on your
hard dri7e IshutilI stands for Ishell utilityI%9
3i# Eou can use the os module to 0or/ 0ith hard dri7e files6 but s2-til is usually
sim#ler because it does a lot of the #ath mani#ulation behind the scenes9
Warnin$ &f youCre 0or/in$ on a Mac or your #ro$ram 0ill run on a Mac6 use the
macostools module6 not s2-til6 to co#y files and directories9 Mn Mac MS6 the
s2-til module does not reco$nize resource for/s and other metadata9 &f you
use s2-til to co#y files on a Mac6 the filesC resources6 file ty#es6 and creator
codes may not be correct9
Some of the useful s2-til functions are described in the follo0in$ list9 All the functions
ta/e #athname ar$uments as strin$s%>source #athname first6 follo0ed by destination
#athname if any%)
copy)*) :o#ies the source file and its #ermissions to the destination9
3@:<(&:A.
S3?FF
3he copy)* function has these rules)
o 3he destination can be a file or a directory9
o &f the destination is a directory6 the co#y has the same
name as the source file9
3his e8am#le co#ies the file ,myspider"py, to ,copyy"py, 0ithin the same
directory)
>>> import s2-til
>>> s2-til"copy),myspider"py,, ,copyy"py,*
copy2)*) .i/e copy)*6 but also co#ies the last access time and last modification
time9
2*-
copymode)*) :o#ies the #ermissions of the source file to the destination file9
Does not chan$e the file contents6 o0ner6 or $rou#9
copytree)*) :o#ies the entire contents of the source directory to the destination9
3he destination cannot already e8ist9 ?ses copy2)* to co#y files9 3his e8am#le
co#ies the contents of ,yOir, to ,y1e9Oir,)
>>> s2-til"copytree),yOir,, ,y1e9Oir,*
3his function also ta/es an o#tional third ar$ument6 symlinAs6 s#ecifyin$ 0hat to
do 0ith symbolic lin/s)
o 0r-e creates symbolic lin/s in the ne0 directory tree9
o >alse the default% co#ies the contents of symlin/ed files9
3@:<(&:A.
S3?FF
Startin$ in 7ersion 29"6 4ython raises an J@6rror if any #roblems occur
0hile im#lementin$ copytree)*9 &n earlier 7ersions6 4ython #rinted a
messa$e9% 3he J@6rror loo/s somethin$ li/e this)
>>> s2-til"copytree),yOir,, ,y1e9Oir,*
0race(acA )most recent call last*!
>ile "#stdin>", line /, in V
>ile
"8@ystem83i(rary8>rame9orAs8Cyt2on"frame9orA8Wersions82"38li(8
pyt2on2"38s2-til"py", line /%2, in copytree
J@6rror! [6rrno /E] >ile exists! ,y1e9Oir,
mo5e)*) (e0 in 4ython 29"9 Mo7es the source to the destination9
3@:<(&:A.
S3?FF
3he mo5e)* function has these rules)
o 3he destination cannot already e8ist9
o &f the source and the destination are on different file
systems6 mo5e)* first does a co#y to the destination
and then deletes the source9
o 3he #aths can be files or directories9
3his e8am#le mo7es a directory)
s2-til"mo5e),y1e9Oir,, ,""8y1e9Oir,*
rmtree)*) Deletes the s#ecified directory and its contents9
@rror messa$es de#end on the o#tional ar$ument ignore$errors)
o When set to 0r-e6 ignore$errors su##resses any error messa$es9
o 3he default is >alse6 0hich causes 4ython to raise an e8ce#tion if it
disco7ers an error 0hile e8ecutin$ rmtree)*9
2*2
An ad7anced feature also lets you customize the e8ce#tion handlin$9
3his e8am#le remo7es the directory that 0e mo7ed in the #re7ious e8am#le)
s2-til"rmtree),""8y1e9Oir,*
Dippin" and &n)ippin"
3he Qipfile and gQip modules su##ort data com#ression and e8#ansion9
6ipfile
3he Qipfile module #ro7ides access to Qi# files6 0hich are created 0ith WinQi# the
most common Windo0s file com#ression utility%6 the Mac MS I:reate Archi7eI
command6 or the ?(&O Qip utility9
3@:<(&:A.
S3?FF
&n Windo0s O46 Mac MS6 and ?(&O6 Qi# files are similar to folders
because they can hold files and folders%9 &f you select a folder in
Windo0s O4 and ma/e it a com#ressed folder6 itCs com#ressed as a
Qi# file9
3he Qipfile module lets you use 4ython to create6 read6 0rite6 a##end6 and list a
com#ressed Qi# file9
Warnin$ 3he Qipfile module doesnCt 0or/ 0ith either
Qi# files 0ith a##ended comments
Qi# files that s#an multi#le dis/s
'indin" out whether a file is a Dip file
3o identify a file as a Qi# file6 im#ort Qipfile and use the is$Qipfile)* function)
&ts ar$ument is a #athname strin$9
&t returns 0r-e if the file is a 7alid Qi# file9
3his e8am#le chec/s a file called ,st-ff"Qip,)
>>> import Qipfile
>>> Qipfile"is$Qipfile),yOir8st-ff"Qip,*
0r-e
Warnin$ DonCt ma/e incorrect assum#tions if is$Qipfile)* returns >alse9 &t also
returns >alse if the file doesnCt e8ist9
2*"
#reatin" a Dip'ile ob>ect for readin" or writin"
3o read or 0rite to a com#ressed Qi# file6 you create a Kip>ile)* instance9
3o create a Kip>ile obFect6 follo0 these ste#s)
-9 Type a name for the ob>ect and = Qipfile"Kip>ile)9
29 Type the path to your Dip file 5as a strin"6.
"9 If you want to write to the Dip file, type a comma and ,9,9
Warnin$ ?sin$ ,9, erases 0hate7er is currently in the file6 so ma/e doubly sure
that you donCt need to /ee# 0hat is already in the Qi# file before you $o
a##endin$ ,9,9
!9 3here is another mode6 ,a, for a##end9 3his is an ad7anced feature 0e donCt
e8#ound on in this boo/9
3i# &f you donCt 0ant to com#ress the stored data6 s/i# to Ste# A9
A9 If you want to compress the data, specify a compression type by typin" a
comma and compression= KGC$O6>3L06O9
KGC$@0JB6O the default% stores data 0ithout com#ression9
3@:<(&:A.
S3?FF
3he Qli( module must be a7ailable if you 0ant to com#ress
the data9
69 2nd by typin" *9
&f you fill in both o#tional #arameters6 your instance mi$ht loo/ li/e this)
>>> myQ = Qipfile"Kip>ile),yOir8x"Qip,, ,9,,
compression=Qipfile"KGC$O6>3L06O*
>>> myQ
#Qipfile"Kip>ile instance at %xE'%a'>
*orkin" with a Dip'ile ob>ect
Kip>ile instances are similar to file obFects9 3hey ha7e these methods)
close)* and read)*) Wor/ li/e the file)* obFect methods of the same names
see :ha#ter -+%9
getinfo)*) 3a/es a strin$ s#ecifyin$ the name of an item in the archi7e and
returns a KipGnfo)* obFect containin$ information about the item9
>>> myQ"getinfo),pageco-nt"py,*
#Qipfile"KipGnfo instance at %xE=fa'>
Mne 0ay to see the attributes of the KipGnfo)* obFect is to use the dir)*
function9 3he follo0in$ e8am#le loo/s at the contents of a KipGnfo)* obFect
called myinfo and then loo/s at its file size)
2*!
>>> dir)myinfo*
[,HBH,, ,>ileHeader,, ,$$doc$$,, ,$$init$$,, ,$$mod-le$$,,
,comment,,
,compress$siQe,, ,compress$type,, ,create$system,,
,create$5ersion,,
,date$time,, ,external$attr,, ,extra,, ,extract$5ersion,,
,file$offset,,
,file$siQe,, ,filename,, ,flag$(its,, ,2eader$offset,,
,internal$attr,,
,orig$filename,, ,reser5ed,, ,5ol-me,]
>>> myinfo"file$siQe
.22%3
infolist)*) Deturns a list of KipGnfo)* obFects for all items in the order theyCre
stored in the archi7e9
namelist)*) Deturns a list of strin$s>the names of the items in the archi7e>li/e
so)
>>> myQ"namelist)*
[,copyy"py,, ,2ello9orld"py,, ,myspider"py,, ,pageco-nt"py,, ,x,]
printdir)*) .ists the items in the archi7e to sys"stdo-t9
>>> myQ"printdir)*
>ile 1ame odified
@iQe
copyy"py 2%%<7%37%E /<!&<!&.
.22%
2ello9orld"py 2%%&7%E7%& /&!%/!2'
22
myspider"py 2%%&7//7%< 2/!2=!%2
.22%
pageco-nt"py 2%%&7/%7/% /&!%/!/%
3<E
x 2%%<7%272. /3!.=!.<
%
testQip)*) @8amines the chec/sums :D:s% of all the items in the archi7e9
Deturns as a strin$ the name of the first bad file detectedH if all files are $ood6
returns 1one9
9rite)*) 3a/es as an ar$ument a strin$ s#ecifyin$ a #athname and 0rites the
s#ecified file to the archi7e9
3he archi7e must be o#en for 0ritin$ or a##endin$9 9rite)* ta/es t0o o#tional
ar$uments)
o arcname6 a strin$ s#ecifyin$ the name for the file in the archi7e it defaults
to the filename%
o A com#ression ty#e6 either KGC$@0JB6O or KGC$O6>3L06O
3his e8am#le 0rites the file ,2ello9orld"py, to the archi7e and stores it 0ith
the name ,foo,)
myQ"9rite),yOir82ello9orld"py,, arcname=,foo,*
2*A
9ritestr)*) Writes a data strin$ to the archi7e9 3he archi7e must be o#ened 0ith
mode ,9, or ,a,9 3a/es t0o ar$uments)
o A strin$ s#ecifyin$ the name that the 0ritten data strin$ 0ill ha7e in the
archi7e or a KipGnfo)* instance 0ith at least a filename6 a date6 and a
time%
o A strin$ containin$ the data to store
myQipf"9ritestr)info, "my$data"*
3he Kip>ile)* instance has a data attribute6 de(-g6 0hich s#ecifies the le7el of debu$
out#ut to #rint to sys"stdo-t9 3he o#tions ran$e from % no out#ut% to 3 the most
out#ut%9 3he default is %9
Dippin" up a ython library
CyKip>ile)* instances create zi# archi7es containin$ 4ython libraries9 4ython can
im#ort modules from Qi# files9 4uttin$ the modules your #ro$ram uses into Qi# files is
one 0ay of deli7erin$ a smaller #ro$ram9
3o create a zi# archi7e 0ith 4ython files6 follo0 these ste#s)
-9 #reate a CyKip>ile)* instance.
?se the instructions in I:reatin$ a Qi#File obFect for readin$ or 0ritin$6I earlier
in this cha#ter9 M#en the archi7e for 0ritin$ or a##endin$9
Eour code 0ill loo/ somethin$ li/e this)
mypQ = Qipfile"CyKip>ile),foo"Qip,, ,9,*
29 (n the next line, type the name of your instance, a dot, and 9ritepy)9
"9 (n the same line, type a file or directory pathname and *9
&f you ty#e a filename6 the suffi8 must be "py9 3his e8am#le uses a directory
#athname)
mypQ"9ritepy),yOir,*
<o0 9ritepy)* 0or/s de#ends on the #athname you ty#e)
&f you ty#e a filename6 the file is added to the archi7e9
&f you ty#e a directory name6 all the 4ython files in the directory 0ith the suffi8es
"py6 "pyo6 or "pyc are added to the archi7e9 3he file locations de#end on the
#athCs location)
2*6
o &f the #ath is a re$ular directory6 the files are added to an archi7e at the to#
le7el of the directory9
o &f the #ath is a #ac/a$e directory6 the files are added under the #ac/a$e
name and subdirectory names if any%9
D@M@M'@D CyKip>ile)* obFects use the same methods as Kip>ile)* obFects9
g6ip
3he gQip module reads and 0rites com#ressed files that are com#atible 0ith the ;(?
#ro$ram gQip9 3o your #ro$ramCs users6 the contents of these files loo/ li/e ordinary files
that is6 not zi##ed%9
3@:<(&:A.
S3?FF
3he gQip module doesnCt su##ort all the formats that the ;(? gQip
utility su##orts9 For e8am#le6 compress and pacA arenCt su##orted9
3o use 4ythonCs gQip module6 use its open)* function to create a SQip>ile)* instance9
3he instance 0or/s li/e a file obFect6 but 0ith these differences)
3he SQip>ile)* instance doesnCt su##ort the readinto)* or tr-ncate)*
methods9
3he close)* method does not close the file obFect the instance is usin$9 &t closes
the instance only9
3his feature allo0s you to do somethin$ to the file obFect after 0or/in$ 0ith it as
a SQip>ile)* instance9 For e8am#le6 if the file obFect is a @tringGJ obFect6 you
can use the @tringGJ"get5al-e)* function to retrie7e the contents after closin$
the SQip>ile)* instance9
3o create a SQip>ile)* instance from a file on dis/6 follo0 these ste#s)
-9 Type gQip"open)
29 (n the same line, type the path to your ")ipped file as a strin". 'or example,
3" gQip"open)'filen#me.g6'
3i# &f you donCt 0ant to 0rite to the file6 s/i# to Ste# !9
!9 If you want to write to the file, type a comma and ,9,9
Warnin$ ?sin$ the ,9, mode erases 0hate7er is currently in the file6 so ma/e
sure that you donCt need to /ee# 0hat is already in the file before you $o
a##endin$ ,9,9
A9 3here is another mode6 ,a, for a##end9 3his is an ad7anced feature 0e donCt
document in this boo/9
3i# &f you 0ant the file to o#en and close faster6 you can tell $zi# to create a
faster, larger file)
a9 &ype a comma.
2*+
b9 &ype compressle5el=9
c9 &ype an integer from / %fastest, largest file4 to = %slo$est, smallest
file4.
'y default6 the compressle5el 7alue is = slo0est6 smallest file%9
69 2nd the line of code by typin" *9
&f you fill in both o#tional #arameters6 your code and the result mi$ht loo/ li/e
this)
>>> import gQip
>>> myfile = gQip"open),N-ote2"ne9"gQ,, mode=,9,, compressle5el='*
>>> myfile
#gQip open file ,N-ote2"ne9"gQ,, mode ,9(, at %x.(&c% %x&d.=%>
3@:<(&:A.
S3?FF
&tCs also #ossible to create a SQip>ile)* instance from a file or file1
li/e obFect such as a @tringGJ obFect% already o#ened in 4ython9
3his 0or/s much li/e usin$ the open)* function6 but the order of the
ar$uments is different)
-9 Mode o#tional6 defaults to the mode of the 4ython file
obFect%
29 :om#ression le7el o#tional6 defaults to * or
slo0estLsmallest%
"9 3he name of the 4ython file obFect reGuired%
3he creation of a SQip>ile)* instance mi$ht loo/ somethin$
li/e this)
>>> gfile = gQip"SQip>ile)mode=,9,,
compressle5el=', fileo(T=myfile*
2*,
!ussin" (ut !I- :atabases
3he sNlite3 module $i7es you an easy 0ay to store your data by usin$ the SY.ite
library6 an im#lementation of the uni7ersal database lan$ua$e SY.9 SY. is #ronounced
IseGuelI and stands for Structured Yuery .an$ua$e9 SY.ite is #ronounced IseGuel1iteI%9
sNlite3 is a ne0 standard module in 4ython 29A9 &f you ha7e 4ython 7ersion 292 throu$h
29!6 you can do0nload the essentially similar pysNlite module from
htt#)LL0009#ysGlite9or$L9
We donCt ha7e the s#ace for detailed information on usin$ SY.>SY. is a 0hole
#ro$rammin$ lan$ua$e all by itself9 'ut in the sections that follo06 0e sho0 you the
basics of usin$ sNlite3 as 0ell as some Guic/ tric/s for usin$ SY.9 ,? For Dummies,
Ath @dition6 by Allen 3aylor has more information9% 3he Web site htt#)LL0009sGlite9or$L
also has lots of documentation9
Installing S-Lite and s3lite<
3he sNlite3 module is automatically installed 0hen you install 4ython 29A9 Mn
Windo0s6 the 4ython 29A installation also includes SY.ite itself9 Mn other #latforms6
ma/e sure that SY.ite is installed before you build 4ython 29A9 See the B6LO6 file in
your 4ython do0nload for details9
Setting up a S-Lite database
3o create or use a SY.ite database6 you o#en a connection to the database itCs li/e
o#enin$ a file% and create a cursor to access the database9
Eou can o#en a connection in t0o 0ays)
:isk1based connection, Allo0s you to 0rite chan$es to the database file on dis/9
In1memory database, 3he connection 0or/s faster6 but you canCt 0rite chan$es
to dis/9 &tCs most useful for loadin$ some data into memory and then runnin$ a
bunch of Gueries9
3o o#en a connection to a database on dis/6 follo0 these ste#s)
-9 Type import sNlite39
29 (n the next line, type the code to open the connection,
o For a dis/1based connection6 ty#e the name of the database in the
#arentheses)
o conn = sNlite3"connect),my$data(ase,*
o For an in1memory database6 ty#e the s#ecial strin$ ,!memory!, in the
#arentheses9
2**
Eou can ty#e a #athname to an e8istin$ database or ty#e a ne0 filename to
create a ne0 database9
conn = sNlite3"connect),!memory!,*
"9 (n the next line, create a cursor by typin" code like this,
." c-rsor = conn"c-rsor)*
3he cursor is li/e a boo/mar/ tellin$ you 0here you are in the database9
*orking &ith a S-Lite database
3his section describes some basic tas/s you can do 0ith the database) creatin$ a table6
addin$ data to a table6 and $ettin$ data out of a table9
#reatin" a table
A table is an area in a database 0here you store related information9 A table consists of
records sets of information%6 0hich in turn contain fields each field is one bit of
information of a #articular type%9 3o create a table6 you 0rite a 7uery instructions to the
database%6 and then use the cursorCs exec-te)* method to run the Guery9 3o create a table
to store addresses6 you mi$ht use code li/e this)
N-ery = """ 77 sNlite N-eries are stringsR comments -se
"77"
create ta(le address 77 create a ta(le named "address"
) 77 (egin creating a record
name 5arc2ar, 77 create a field called "name", 9it2 type
"5arc2ar"
street 5arc2ar,
city 5arc2ar
* 77 end of t2is record
""" + end of N-ery
3he abo7e code is formatted so that itCs easier for humans to read9 SY. doesnCt care about
indentation in Guery strin$s9 3he te8t after 77 on each line re#resents comments9 4ython
i$nores these9
D@M@M'@D 3he code 5arc2ar in the #recedin$ e8am#le is a type a declaration of the
/ind of information to be stored in that field%9 5arc2ar s#ecifies that the
field contains te8t of 7aryin$ len$th9 SY.ite reGuires you to define a ty#e
for each field9 SY.ite doesnCt care much about ty#es6 but most other SY.
databases do9%
3i# 3hin/ of SY. tables as bein$ li/e 4ython classes e8ce#t that they only contain data6
not methods9 A SY. database can ha7e multi#le tables9 A record or ro$ the section
0ithin #arentheses in the abo7e e8am#le% is li/e a class instance9 3he fields or
columns of a record each line inside the #arentheses is one field% are li/e instance
data attributes6 e8ce#t that all records ha7e e8actly the same attributes the data
"00
associated 0ith the fields can be different%9 &n contrast6 class instances can ha7e
different attributes6 althou$h most of the time they donCt9
3@:<(&:A.
S3?FF
Actually6 most modern SY. databases do allo0 for creatin$ methods6
but theyCre an ad7anced and com#licated feature9 So #retend 0e
didnCt mention them9
opulatin" a table with data
After you ha7e a table6 you can populate the table add data to it%6 li/e this)
-9 #reate a list of tuples.
@ach element in a tu#le should corres#ond to a field in one of the databaseCs
records9 For e8am#le)
addresses = [
),Cet @2ops 3td,, ,/23 ain @t,, ,1otlo(,*,
),@imilar Cet @2ops 3td,, ,32/ >irst @t,, ,Iolton,*,
]
3i# For hel# arran$in$ data into the #ro#er format6 see :ha#ter ,9
29 &se the exec-te)* method in a for loop to write the addresses into the
database.
3" for addr in addresses!
." c-rsor"exec-te)"insert into address 5al-es )V, V, V*", addr*
3he exec-te)* methodCs first ar$ument is a strin$ 0ith the SY. command
insert into6 the name of the table6 and 5al-es follo0ed by a set of Guery
#arameters in #arentheses9 Yuestion mar/s V% stand for Guery #arametersH
sNlite3 #asses in an ar$ument for each #arameter9 3he number of Guestion mar/s
must match the number of elements in the second ar$ument9 .uc/y us>in the
e8am#le abo7e6 there are three Guestion mar/s and three elements in each addr
tu#le9 3he second ar$ument is the tar$et of the for loo#9
3i# ?se double Guotation mar/s or tri#le Guotes for all 4ython strin$s that contain SY.
Gueries9 SY. reGuires strin$ 7alues to be surrounded by sin$le Guotation mar/s see
the e8am#le in the I;ettin$ a subset of the 7aluesI section%6 so youCll ma/e life easier
for yourself if you a7oid usin$ sin$le Guotation mar/s for 4ython strin$s 0hen
0or/in$ 0ith SY.9
+ettin" field values from a table
3o $et field 7alues from a table6 you e8ecute a Guery s#ecifyin$ the data you 0ant and
then use the fetc2all)* method to retrie7e the data9 Eou may ha7e noticed by no0 that
most SY.ite tas/s in7ol7e e8ecutin$ a Guery9%
"0-
1etting all the values
3his e8am#le retrie7es a list of all the 7alues stored in our tableCs name field)
>>> c-rsor"exec-te)"select name from address"*
#sNlite3"H-rsor o(Tect at %x<<'3%>
>>> print c-rsor"fetc2all)*
[)-,Cet @2ops 3td,,*, )-,@imilar Cet @2ops 3td,,*]
3he fetc2all)* method returns a list of tu#les9 'ecause each tu#le in the result has only
one element6 the tu#les end 0ith a comma9 See :ha#ter , for a re7ie0 of tu#les9
D@M@M'@D SY.ite stores te8t data as ?nicode strin$s9 See :ha#ter 6 for more info
about ?nicode9
1etting a su!set o% the values
3he real #o0er of a database lies in its ability to $i7e you the subset of information that
matches your needs9 &n this e8am#le6 0e $et the records that ha7e I'oltonI in the city
field9 &f you /no0 that the ; character stands for Iall fields6I itCs #retty easy to understand
0hat this Guery does)
>>> c-rsor"exec-te)"select ; from address 92ere city=,Iolton,"*
#sNlite3"H-rsor o(Tect at %x<<'3%>
>>> print c-rsor"fetc2all)*
[)-,@imilar Cet @2ops 3td,, -,/23 ain @t,, -,Iolton,*]
3@:<(&:A.
S3?FF
When youCre startin$ out 0ith sNlite36 you should #robably stic/
0ith storin$ and retrie7in$ sim#le strin$s6 numbers6 and dates9 'ut
0hen you $et more comfortable6 you can store 4ython obFects in the
database by usin$ the picAle moduleCs d-mps)* function9 See the
ne8t section6 I4ic/lin$ Eour Data And Delishin$ the Mutcome%9I
(ote that you 0onCt be able to share your database 0ith non14ython
#ro$rams if you store #ic/led data9
3@:<(&:A.
S3?FF
sNlite3 follo0s the 4ython Database A4& S#ecification 7290 for
more details6 see 4ython @nhancement 4ro#osal 4@42!* at
htt#)LL0009#ython9or$Lde7L#e#sL#e#102!*L%9 'ecause 4ython
database modules are all desi$ned to 0or/ consistently6 0hen you
need a more #o0erful database such as 4ost$reSY. or Firebird%6 it
should be easy to u#$rade your code) Eou need only chan$e the
connect)* function call9
"02
icklin" %our :ata 5And /elishin" the (utcome6
3he picAle and cCicAle modules let you store data bet0een runs of a #ro$ram6 the 0ay
a 0ord #rocessor allo0s you to sa7e formatted documents and edit them later e7en if you
Guit the #ro$ram9 3his is called pickling because itCs a 0ay of preserving your data9
3@:<(&:A.
S3?FF
Storin$ a 4ython obFect in a file ma/es it a persistent ob-ect. Eou
could 0rite your o0n code to store and read 4ython obFects6 but if
your data includes com#le8 obFects6 itCs easier to use #ic/lin$ because
it automatically con7erts data bac/ and forth bet0een strin$s and
4ython obFects9
4ython includes the follo0in$ su##ort for #ersistent obFects)
3he cCicAle and picAle modules con7ert 4ython obFects to and from strin$
re#resentations9
3@:<(&:A.
S3?FF
4ic/lin$ is commonly used 0hen 0or/in$ 0ith #ersistent
databases6 0hich store 4ython obFects so that they can be
accessed by /eys9
3he s2el5e module see the ne8t section% su##orts #ersistent dictionaries 0hose
7alues can be arbitrary 4ython obFects9 &t 0or/s 0ith the picAle and anyd(m
modules9
Warnin$ 4ic/led data is a security ris/ because it mi$ht include malicious code9 Ma/e
sure you un#ic/le data only from a trusted source9
3he module of choice for the maFority of #ic/lin$ tas/s is cCicAle6 0hich is sim#ler and
faster than the picAle module9 3he only reason to use picAle is if you need access to its
ad7anced features 0hich 0e donCt co7er in this boo/%9
Pickling an ob'ect
3o #ic/le a 4ython obFect6 follo0 these ste#s)
-9 Type import cCicAle9
29 (pen a file for writin". 'or example,
3" mypicAlefile = open)myfile, ,9,*
!9 Type cCicAle"d-mp and in parentheses specify the name of the ob>ect you
want to pickle and the name of the file you opened 5which is where the
pickled ob>ect will be stored6.
&" cCicAle"d-mp)myo(T, mypicAlefile*
69 #lose the file.
E" mypicAlefile"close)*
icklin" restrictions
"0"
Most 4ython data ty#es can be #ic/led6 0ith the follo0in$ e8ce#tions)
Functions6 built1in functions6 and classes defined at a le7el other than the to# le7el
of a module canCt be #ic/led9
A class 0ith a $$dict$$ attribute or a $$setstate$$)* method that isnCt
com#atible 0ith #ic/lin$ canCt be #ic/led9
3u#les6 lists6 sets6 and dictionaries that contain non1#ic/lable obFects canCt be
#ic/led9
4ic/lin$ stores only the names of functions and classes6 not any code or attributes
from them9 So 0hen you un#ic/le a module6 its functions must be a7ailable for
im#ortin$ on the system youCre un#ic/lin$ from9
When instances are #ic/led6 class attributes arenCt #ic/led alon$ 0ith them9
3he follo0in$ functions #ic/le a 4ython obFect9 3he function you use de#ends on 0hat
ty#e of data you 0ant returned9
dumps56
3he d-mps)* function #ic/les a 4ython obFect and returns a strin$9 &tCs useful for storin$
4ython obFects in databases6 such as SY.ite see the #re7ious section6 ISussin$ Mut SY.
Databases9I%
3his function ta/es a 4ython obFect as an ar$ument9
dump56
3he d-mp)* function #ic/les the obFect and 0rites the #ic/led obFect to an o#en file or a
file1li/e obFect li/e @tringGJ%9
3his function ta/es t0o ar$uments)
A 4ython obFect
A file obFect o#ened for 0ritin$
3i# 3he d-mp)* and d-mps)* functions ta/e one o#tional #arameter that s#ecifies the
#ic/lin$ 7ersion to use9 3he follo0in$ subsections sho0 the ri$ht #arameter for your
7ersion of 4ython9
ython 7.$ or later
&f youCre usin$ 4ython 29" or later6 the #ic/lin$ 7ersion #arameter for the d-mp)* and
d-mps)* functions is called protocol9
3i# Eou can s#ecify the #ic/lin$ #rotocol 7ersion by enterin$ one of the 7alues from the
"0!
sidebar6 IAll about #ic/lin$ #rotocols9I
All about picklin" protocols
3here are three #ic/lin$ #rotocols)
% is an .,C// #rotocol9 &tCs com#atible 0ith earlier 7ersions of 4ython9
% is the default 7alue9
/ is a binary #rotocol also com#atible 0ith earlier 7ersions of 4ython%9
2 0or/s more efficiently 0ith 4ythonCs ne01style classes discussed in :ha#ter
-!%9
Eou can also s#ecify this 7ersion by enterin$ HGSH6@0$CBJ0JHJ3 or any negative
inte$er9
4rotocol 7ersion 2 is ne0 in 4ython 29"9
(lder ython versions
&f youCre usin$ a 7ersion of 4ython older than 29"6 the o#tional #ic/lin$ 7ersion #arameter
is called (in9 &t s#ecifies to #ic/le the data in a binary format9 3he default 7ersion is te8t6
0hich is less efficient9%
Warnin$ DonCt use (in in your code unless your #ro$ram must be com#atible 0ith earlier
7ersions of 4ython9
)npickling an ob'ect
3he loadin$ function for a #ic/led 4ython obFect de#ends on 0hether itCs a file or a strin$9
&npicklin" files
3he load)* function ta/es a file obFect or a file1li/e obFect such as @tringGJ% as an
ar$ument9 3he file should be o#ened in read mode9 load)* reads the contents of the file
obFect and un#ic/les it9 3he result is the ori$inal obFect that you #ic/led9
3@:<(&:A.
S3?FF
3o un#ic/le a 4ython obFect from a file6 follo0 these ste#s)
-9 Import cCicAle9
29 (pen for readin" the file containin" the pickled ob>ect.
3" mypicAlefile = open)myfile, ,r(,*
!9 Type a name for the ob>ect, = cCicAle"load6 and in
"0A
parentheses the name of the file you opened.
&" myo(T = cCicAle"load)mypicAlefile*
&npicklin" strin"s
3he loads)* function ta/es the name of a strin$ as an ar$ument9 &t reads the contents of
the strin$ and un#ic/les it9 3he result is the ori$inal obFect that you #ic/led9
&sin" shelve with :B41style databases
3his section is for #eo#le 0ho need to store 4ython data on dis/ usin$ 4ython 29! or
earlier6 or 0ho need to use the 'er/eley D' database library9 'er/eley D' and its
relati7es are called D0'-style databases9% &f you ha7e 4ython 29A6 read ISussin$ Mut
SY. Databases6I earlier in this cha#ter6 instead9 &tCs easier to use9 Eou can also do0nload
pysNlite for 4ython 292 throu$h 29!9%
Storing pickles on a shelf
3he s2el5e module is a I0ra##erI around se7eral D'M1style database modules
a7ailable in 4ython9 3he shel7e module 0or/s li/e this)
-9 Eou create a s2el5e obFect and tell it to o#en a database file9
29 3he s2el5e obFect loo/s at your database file on dis/ and decides 0hich 4ython
database module to use9
"9 3he 4ython database module accesses your database file9
3he s2el5e module and its tools ha7e the follo0in$ features)
3he open)* function automatically chooses an a7ailable database module 0hen
you o#en a file9
Shel7e obFects beha7e li/e dictionaries see :ha#ter *%6 0ith a fe0 minor
differences see I4ro#erties of a shel7e obFectI later in this cha#ter%9
Shel7e obFects allo0 you to store #ic/led 4ython obFects as 7alues9 See I4ic/lin$
Eour Data And Delishin$ the Mutcome%I earlier in this cha#ter9%
A shel7e obFect is called a persistent dictionary because it can store and reconstitute
4ython obFects from a dis/ file9
#reating a shel$e ob'ect
3o create a s2el5e)* obFect6 follo0 these ste#s)
-9 Type import s2el5e9
"06
29 (n the next line, type a name for the shelf, =6 and s2el5e"
open),mydata(ase,9
Substitute the name of your D'M1style database file9
"9 To open the file as read1only, to open an existin" file as read1write, or to
create a new, empty database, type a comma and a fla",
3he fla$s are)
,r,
read only
,9,
read and 0rite
,c,
create database if it doesnCt e8ist default%
,n,
create ne0 em#ty database
Warnin$ &f the file e8ists6 ty#in$ ,n, erases its contents9
mys2elf = s2el5e"open),mydata(ase,, 'w'
!9 If you have ython 7.$ or later and you want to use one of the advanced
picklin" protocols, type a comma6 protocol= and one of the followin",
For more about the #rotocols6 see I4ic/lin$ Eour Data And Delishin$ the
Mutcome%I earlier in this cha#ter9
o / binary #rotocol
o 2 or <&;<@S3P4DM3M:M. ad7anced #rotocolH 0or/s more efficiently
0ith 4ythonCs ne01style classes
mys2elf = s2el5e"open),mydata(ase,, ,9,, protocol=2
A9 To allow chan"es to mutable ob>ects in the database, type a comma and
9rite(acA=0r-e9
<" mys2elf = s2el5e"open),mydata(ase,, ,9,, protocol=2,
write7#c!(r"e
Warnin$ 3his feature ma/es the database slo0 to close9
3i# &f you donCt turn on the 9rite(acA feature6 you can still ma/e chan$es to
mutable obFects by usin$ a three1ste# #rocess described in the sidebar6
I:han$in$ mutable obFects in a shel7e database9I
,9 Type the end parenthesis.
=" mys2elf = s2el5e"open),mydata(ase,, ,9,, protocol=2,
9rite(acA=0r-e*
#han"in" mutable ob>ects in a shelve database
When you create a s2el5e obFect6 by default chan$es to mutable obFects are not stored in
the database file6 because allo0in$ this ma/es the database slo09 3o allo0 such chan$es6
you can set 9rite(acA=0r-e 0hen o#enin$ a s2el5e obFect see I:reatin$ a shel7e
obFectI%9 'ut if you lea7e it turned off6 you can use this three1ste# #rocess for ma/in$
"0+
chan$es to mutable obFects9 3hese ste#s assume youC7e already o#ened a s2el5e database
obFect9
-9 Access the mutable 7alue by usin$ its /ey6 and $i7e it a tem#orary name9 &n this
e8am#le6 the mutable 7alue is a list and its /ey is ,mylist,)
2" temp = mys2elf[,mylist,]
"9 Ma/e chan$es to the co#y9 &n this e8am#le6 0e a##end a strin$ to the list9
." temp"append),foo,*
A9 Assi$n the chan$ed co#y bac/ to the same database /ey9
<" mys2elf[,mylist,] = temp
Properties of a shel$e ob'ect
3he obFects created by the s2el5e module are li/e a cross bet0een a dictionary and a file
obFect9 As 0ith a dictionary6 you can retrie7e6 store6 search for6 and delete /eys and
7alues9 As 0ith a file obFect6 you can o#en and close a s2el5e obFect and direct it to 0rite
chan$es to a file on dis/9 s2el5e obFects ha7e these uniGue features)
=eys must be strin$s9
Balues can be strin$s or #ic/lable 4ython obFects9
:han$es to mutable obFects are not 0ritten to dis/ unless you set
9rite(acA=0r-e 0hen you create the shel7e obFect9
See the sidebar6 I:han$in$ mutable obFects in a shel7e database6I for some
0or/around 0ays of chan$in$ mutable obFects9
3he sync)* method 0rites chan$es to dis/9 Writin$ ha##ens automatically 0hen
you use the close)* method9%

3@:<(&:A.
S3?FF
When you 0rite chan$es to dis/ by usin$ the sync)* or
close)* method6 an e8tension mi$ht be added to the
filename and more than one file mi$ht be created9
Whether these ha##en de#ends on the underlyin$ database s2el5e is usin$9
"0,
#hapter 7K, Accessin" the Internet
4ython has an array of tools for 0or/in$ 0ith information o7er the &nternet9 3his cha#ter
introduces tools for handlin$ Web #a$e addresses6 do0nloadin$ and #arsin$ data from
Web #a$es6 buildin$ OM. data structures6 creatin$ and sendin$ e1mail messa$es6 and
0ritin$ and installin$ :;& scri#ts for #rocessin$ Web forms%9
3@:<(&:A.
S3?FF
3his cha#ter introduces conce#ts for 0or/in$ 0ith &nternet modules6
but 0e assume that you ha7e basic /no0led$e of Web6 OM.6 and e1
mail #rotocols9
:ownloadin" *eb :ata
3he follo0in$ sections co7er o#enin$ ?D.s6 readin$ their contents6 and submittin$ form
data to a Web ser7er9
4ython has t0o modules for #erformin$ these tas/s) -rlli( and -rlli(29 @ach has
s#ecific stren$ths9 We focus on the sim#ler -rlli( module in this section6 but 0e
recommend the -rlli(2 module for o#enin$ and fetchin$ data from Web #a$es because
it has better error handlin$9
0pening a )/L
3he function -rlopen)* creates obFects that beha7e a lot li/e files6 but it has t0o
im#ortant differences from the open)* function6 0hich creates files)
-rlopen)* ta/es a Web #a$e address ?niform Desource .ocator6 or ?D.% as an
ar$ument rather than as a filename%9
-rlopen)* o#ens the ?D. only for readin$6 not for 0ritin$9
3i# 'oth the -rlli( and the -rlli(2 modules su##ort the -rlopen)* function9 3he
function 0or/s the same 0ay in both6 but the -rlopen)* function in -rlli(2 has
better error re#ortin$ on #roblems that occur 0hen o#enin$ Web #a$es9
&sin" urllib7.urlopen56 to open a &/-
3o o#en a ?D.6 follo0 these ste#s)
-9 Type import -rlli(29
29 (n the next line, type a name for the ob>ect and = -rlli("-rlopen)9
"9 Type the &/- 5as a strin"6 and close the parentheses by typin" *9
Eour code should loo/ somethin$ li/e this)
"0*
page =
-rlli(2"-rlopen),2ttp!88999"pyt2on"org8doc8c-rrent8modindex"2tml,*
&f all $oes 0ell6 the Web #a$e o#ens9 &f you e8amine the obFect you Fust created6 youCll
see somethin$ li/e this)
>>> page
#addinfo-rl at /3E'.'E'% 92ose fp = #socAet"$fileo(Tect o(Tect at
%x'3Ec/(.>>
/eadin" text from a &/-
3o read te8t from an o#ened ?D.6 use a for loo#9 3his e8am#le #rints the te8t to
#sys"stdo-t> one line at a time)
for line in page!
sys"stdo-t"9rite)line*
&nderstandin" *eb pa"e errors
&f thereCs a #roblem o#enin$ the #a$e6 4ython raises an e8ce#tion s#ecifyin$ the /ind of
error9 Sometimes the messa$e is lon$6 so 0e 0onCt re#roduce the 0hole thin$ here9 3he
critical #art of the messa$e is the last line9 <ereCs #art of the messa$e you $et if the site
e8ists but the #a$e doesnCt e8ist)
>>> page=-rlli(2"-rlopen),2ttp!88999"pyt2on"org8idontexist"2tml,*
["""]
-rlli(2"H00C6rror! H00C 6rror .%.! 1ot >o-nd
Detailed error re#ortin$ is useful 0hen you 0ant to 0rite code that handles different Web
errors in different 0ays9 For e8am#le6 you mi$ht 0rite code that chec/s a Web #a$eCs
lin/s and lo$s 0hether the lin/ is still 7alid6 0hether it redirects to another #a$e6 or
0hether the lin/ed #a$e no lon$er e8ists9 3he spider"py #ro$ram in :ha#ter ! uses this
functionality9%
%inding inforation about a )/L
4ython has t0o useful tools for $ettin$ the scoo# on a ?D.9
info56
3o $et meta1information ser7er ty#e6 last1modified date6 content ty#e6 and so on% about a
?D. youC7e o#ened6 use the info)* method6 li/e this)
>>> print page"info)*
Oate! @-n, 2/ ay 2%%< %E!&2!/& S0
@er5er! Lpac2e82"%"&. )Oe(ian S1483in-x* OLW82 @W18/"/".
mod$pyt2on83"/"3
Cyt2on82"3"& mod$ssl82"%"&. Jpen@@38%"="Ee
"-0
3ast7odified! on, /E Lpr 2%%< /2!%.!%& S0
60ag! "2.%//%7'ac&73'//(E.%"
Lccept7Banges! (ytes
Hontent73engt2! 3&&2&
Honnection! close
Hontent70ype! text82tml
"eturl56
3o $et the actual ?D. that 0as o#ened 0hen you made your reGuest6 use the get-rl)*
method6 li/e this)
>>> redirect =
-rlli(2"-rlopen),2ttp!88999"li5eTo-rnal"com8-sers8firecat,*
>>> redirect"get-rl)*
,2ttp!88firecat"li5eTo-rnal"com8,
3i# ?se get-rl)* to find out 0hether the ?D. you o#ened redirected you some0here
else9
Processing special characters in a )/L
3o #rocess s#ecial characters such as a s#ace or tilde% in a ?D.6 use the -rlli(
moduleCs N-ote$pl-s)* function9
Warnin$ Althou$h the functions N-ote)* and -nN-ote)* are similar to N-ote$pl-s)*6
0e recommend usin$ N-ote$pl-s)* to a7oid #roblems 0ith ?D.s that contain
: and s#ace characters9
3he N-ote$pl-s)* function has a reGuired ar$ument and an o#tional ar$ument9
/e=uired ar"ument
3he N-ote$pl-s)* function reGuires a ?D. strin$ or #art of a ?D.% as an ar$ument and
does the follo0in$)
De#laces s#ecial characters anythin$ but letters6 di$its6 underscores6 dots6 and
hy#hens% by usin$ the "Dxx" esca#e format
De#laces s#aces 0ith : reGuired for Guotin$ <3M. form contents%
@sca#es : characters in the ori$inal strin$
3his e8am#le #rocesses a ?D. 0ith slash characters and a tilde \%)
>>> import -rlli(
>>> -rlli("N-ote$pl-s),2ttp!88cat7and7dragon"com8\stef,*
,2ttpD3LD2>D2>cat7and7dragon"comD2>DE6stef,
3i# 3o re7erse this #rocess6 use -nN-ote$pl-s)*9 3his function doesnCt use any o#tional
#arameters9%
"--
(ptional ar"ument
3he N-ote$pl-s)* function ta/es an o#tional safe ar$ument6 0hich s#ecifies characters
to lea7e alone9
3he follo0in$ e8am#le #rocesses the same ?D. as the #recedin$ e8am#le6 but the slash
character has been desi$nated as safe9
>>> -rlli("N-ote$pl-s),2ttp!88cat7and7dragon"com8\stef,, safe=,8,*
,2ttpD3L88cat7and7dragon"com8DE6stef,
Subitting for data
When communicatin$ 7ia <3346 the -rlopen)* function usually ma/es a S60 reGuest to
the <334 ser7er9 A S60 reGuest limits your ?D. address and data% to -602! bytes9 3o
send more data>for e8am#le6 to submit the results of a form>you need to ma/e a CJ@0
reGuest9
Sendin$ data 7ia a CJ@0 reGuest reGuires the follo0in$ ste#s9 (ote that these ste#s reGuire
you to im#ort both -rlli( for the -rlencode)* function% and -rlli(2 for the
-rlopen)* function%)
-9 Type the followin",
2" import -rlli(, -rlli(2
3"
!9 &se the -rlli("-rlencode)* function to encode the data.
3he function ta/es one of the follo0in$ ar$uments)
o A ma##in$ obFect such as a dictionary of form fields%
o A seGuence of t0o1element tu#les
3he function con7erts its ar$ument to the format application8x79997form7
-rlencoded9 <ereCs an e8am#le)
>>> mylist = [),/,, ,one,*, ),2,, ,t9o,*, ),3,, ,t2ree,*]
>>> mydata = -rlli("-rlencode)mylist*
>>> mydata
,/=one^2=t9o^3=t2ree,
A9 #all -rlli(2"-rlopen)* and pass the data from -rlencode)* as the second
ar"ument, like this,
<" x = -rlli(2"-rlopen),2ttp!88999"company"com,, mydata*
"-2
Tamin" the *ild &/-
3he -rlparse module s#lits ?D.s into com#onents6 combines com#onents into a ?D.6
and con7erts a relati7e ?D. to an absolute ?D.9
3o s#lit a ?D. strin$ into com#onents6 #ass it to the -rlparse)* function9 3here are t0o
o#tional #arameters for -rlparse)*)
defa-lt$sc2eme) ?sed if the ?D. doesnCt include an addressin$ scheme6 for
instance6 ,2ttp,9 3he default is an em#ty strin$ 0hich means itCs off%9
allo9$fragments) Allo0s ?D.s 0ith elements follo0in$ a + character
desi$natin$ a location some0here inside a #a$e%9 Defaults to /6 0hich means to
allo0 them9
3he -rlparse)* function returns a si81item tu#le of strin$s containin$
-9 Addressin$ scheme 2ttp or ftp%
29 (et0or/ location htt#)LL0009#ython9or$%
"9 4ath 8doc82"."28li(8mod-le7-rlparse"2tml%
!9 4arameters Rtype="a"%
A9 Yuery Vfilter=/<.%%%
69 Fra$ment identifier +top%
3he tu#le items donCt include delimiters colons and slashes%6 e8ce#t for a leadin$ slash in
the #ath com#onent9 &f any of the items isnCt #art of the ?D. bein$ #arsed6 the tu#le
contains an em#ty strin$ for that item9
3he follo0in$ e8am#le contains an addressin$ scheme6 net0or/ location6 and #ath6 but
doesnCt contain #arameters6 a Guery6 or a fra$ment identifier)
>>> -rlparse"-rlparse)"2ttp!88pyt2on"org8doc82"."28li(8mod-le7
-rlparse"2tml"*
),2ttp,, ,pyt2on"org,, ,8doc82"."28li(8mod-le7-rlparse"2tml,, ,,, ,,,
,,*
3he -rlparse module has a cou#le of other ca#abilities)
3o turn a tu#le created by -rlparse)* bac/ into an ?D. strin$6 #ass the tu#le to
-rl-nparse)*9
3o stic/ to$ether a base ?D. and a relati7e ?D. to create a com#lete ?D.6 use
-rlToin)*9 &t ta/es the base ?D. and relati7e ?D. as strin$s9 &t also ta/es the
o#tional allo9$fragments ar$ument9 3his e8am#le Foins a sin$le Web #a$e to its
location)
>>> -rlparse"-rlToin),2ttp!88pyt2on"org8doc82"."28mac8,,
,mac"2tml,*
"-"
,2ttp!88pyt2on"org8doc82"."28mac8mac"2tml,
+ettin" Hip with Hypertext
3o read and out#ut <3M.1formatted te8t files and to find lin/s in <3M. documents6 use
the 2tmlli( module9 &t su##orts all of O<3M. -906 all of <3M. u# to 2906 and much of
<3M. "90 and "929
0f parsers! foratters! and &riters
Deadin$ and out#uttin$ an <3M. file is a three1ste# #rocess9 <ereCs 0hatCs $oin$ on
inside 4ython 0hile itCs ha##enin$)
-9 A #arser recei7es information from an <3M.1formatted file9 3his file mi$ht be an
<3M. document you ha7e on dis/6 or it mi$ht be a Web #a$e youC7e o#ened 0ith
-rlli(2"-rlopen)* see IDo0nloadin$ Web Data6I earlier in this cha#ter%9
When the #arser encounters an o#enin$ ta$6 it stores 0hate7er is inside that ta$ in
a buffer until it encounters the matchin$ closin$ ta$9
29 3he #arser #asses the information to a formatter6 0hich reformats it into a human1
readable form by readin$ the <3M. ta$s and a##lyin$ instructions to them9
"9 3he formatter #asses the reformatted information to a 0riter6 0hich out#uts the
information9
Setting up a read+and+output process
3he #arser6 formatter6 and 0riter are all instance obFects6 so you need to create the
instances before they can act9 3he #arser 0or/s on the contents of the file or Web #a$e6
so you ha7e to o#en and read a file or Web #a$e before the #arser6 formatter6 and 0riter
can act9
3o set u# a read1and1out#ut #rocess6 follo0 these ste#s)
-9 Import the 2tmlli(6 formatter6 and @tringGJ modules, like so,
2" import 2tmlli(, formatter
3" from c@tringGJ import @tringGJ
!9 (pen an HT4-1formatted file,
&" myfile = open)"memo"2tml", ,r(,*
69 /ead the file,
E" 2tml = myfile"read)*
,9 #reate a writer instance.
3he sim#lest 0riter is O-m(Writer)*6 0hich out#uts #lain te8t9
"-!
d-md-m = formatter"O-m(Writer)@tringGJ)**
*9 #reate a formatter instance and pass it the writer instance.
L(stract>ormatter)* is the most commonly used formatter class9
fermat = formatter"L(stract>ormatter)d-md-m*
-09 #reate an H03Carser instance and pass it the formatter instance.
//"parsley = 2tmlli("H03Carser)fermat*
-29 'eed the file contents to the parser.
/3"parsley"feed)2tml*
-!9 #lose the parser and the file.
/&"parsley"close)*
/<"myfile"close)*
0utputting the links of a *eb page
After the #arser has read the document6 the documentCs lin/s are a7ailable in the data
attribute anc2orlist9
>>> parsley"anc2orlist
[,2ttp!88999"portmeirion75illage"com8,]
Getting help for essy .T(L
&f you ha7e to deal 0ith badly formatted <3M. and thereCs a lot of it out there%6 donCt
des#airH a third1#arty tool can hel#9 &tCs called 'eautiful Sou# after the #oem in .lice3s
.dventures in "onderland%6 and full details are a7ailable at
htt#)LL0009crummy9comLsoft0areL'eautifulSou#9
The +reat Q4-
4ython comes 0ith modules that su##ort @8tensible Mar/u# .an$ua$e OM.%6 a
mechanism for creatin$ structured documents in #lain te8t9
3@:<(&:A.
S3?FF
Althou$h 0e 0rote plain te!t abo7e6 OM. is actually often encoded
in ?3F1,9 See :ha#ter 6 for details about character encodin$9
3@:<(&:A.
S3?FF
'oth <3M. and OM. data include tags>te8t surrounded by
brac/ets #>%9 'ut they use ta$s differently9
&n <3M.6 ta$s are specific formatting instructions. For
e8am#le6 #p> starts a ne0 #ara$ra#h and #(> mar/s boldface
ty#e9
"-A
&n OM.6 ta$s label kinds of data.
An OM. ta$ can also ha7e subta$s for /inds of data that are
part of a lar$er $rou#>#address> data can include #name>
and #street>H #item> data can include #price>6 and so on9
3hese ta$s clarify the data structure6 so itCs easy for a
com#uter to se#arate the data into #arts9
3i# &f OM. ta$s and subta$s remind you of 4ythonCs classes and their data attributes6 you
mi$ht be on to somethin$S9
The ,leentTree =(L ipleentation
3he best 0ay to use OM. in 4ython is 0ith @lement3ree9
@lement3ree is included as xml"etree in 4ython 29A9
@lement3ree is a7ailable for do0nload from htt#)LL0009effbot9or$9zoneLelement1
inde89htm if youCre usin$ an earlier 7ersion of 4ython9
@lement3ree is based on an 6lement data ty#e6 0hich stores hierarchical data structures
such as OM.% in memory9
3@:<(&:A.
S3?FF
(rderin" up some Q4-
<ereCs an a##lication for 0hich OM. is useful9 Su##ose you need to
send an order9 &f you 0ere 0ritin$ it on a #iece of #a#er6 it 0ould
loo/ somethin$ li/e this)
Jrder!
6ric Half7a7Iee
/23 ain @t
Lnyto9n, HL, =&.32
Gtems!
>oo / a/2 a/2
Iar 2 a/& a3%
@-(total! a.2
@2ipping! a&
0otal! a.E
&n OM.6 it 0ould loo/ somethin$ li/e this)
#Vxml 5ersion="/"%" encoding="G@J7''&=7/"V>
#order>
#recipient>
#name>6ric Half7a7Iee#8name>
#street>/23 ain @t#8street>
#city>Lnyto9n#8city> #state>HL#8state>
#Qipcode>=&.32#8Qipcode>
#8recipient>
#items>
#item>
"-6
#prodcode>>oo#8prodcode>
#Nty>/#8Nty> #price>/2#8price>
#total>/2#8total>
#8item>
#item>
#prodcode>Iar#8prodcode>
#Nty>2#8Nty> #price>/&#8price>
#total>3%#8total>
#8item>
#8items>
#s-(total>.2#8s-(total>
#s2ipping>&#8s2ipping>
#total>.E#8total>
#8order>
Importin" 2lementTree
<o0 you im#ort @lement3ree de#ends on your 7ersion of 4ython9
&n 4ython 29A6 ty#e this)
from xml"etree import 6lement0ree as 60

&n earlier 7ersions6 after you do0nload @lement3ree6 ty#e the follo0in$)
import elementtree"6lement0ree as 60
3i# Eou donCt ha7e to use the as 60 #art6 but it 0ill hel# if you are follo0in$
alon$ 0ith our e8am#les9%
#reatin" an element
An @lement3ree structure consists of 6lement instances9
An 6lement instance must ha7e a tag>a strin$ identifyin$ the element ty#e9
An 6lement instance can ha7e these o#tions) attributes, a te!t string, and
subelements child elements%9
3o create an element6 ty#e 60"6lement and #ass the ta$ strin$ as an ar$ument6 li/e this)
tree = 60"6lement)"tree"*
2lement attributes
@lement attributes are dictionary /ey)7alue #airs9 3he /eys must be uniGue9%
,ssigning attri!utes
3o assi$n attributes to an e8istin$ element6 use the attri()* method6 li/e this)
(ranc2 = 60"6lement)"(ranc2"*
"-+
(ranc2"attri(["one"] = "/"
(ranc2"attri(["t9o"] = "2"
3anipulating attri!utes
3o mani#ulate attributes6 use the follo0in$ methods6 0hich 0or/ a lot li/e dictionary
methods see :ha#ter *%)
3o assi$n attributes 0hen creatin$ an element6 use /ey0ord ar$uments6 li/e this)
(ranc2 = 60"6lement)"(ranc2", one="/", t9o="2"*
3o return attribute 7alues6 use the get)* method 0ith the /ey)
(ranc2"get)"one"*
3o $et a list of attribute /eys6 use the Aeys)* method6 li/e so)
(ranc2"Aeys)*
3o $et a list of attributes /ey)7alue tu#les%6 use the items)* method)
(ranc2"items)*

3o set attribute 7alues6 use the set)* method6 li/e this)

(ranc2"set)"t2ird", "3"*
3o set an elementCs text attribute6 assi$n it a strin$6 li/e so)
(ranc2"text = "t2is element also contains text"
!ubelements
@lement instances can ha7e subelements6 also called child elements9
4reating su!elements
3here are a cou#le of different 0ays to build a tree)
The @-(6lement)* function, Eou can create subelements and attach them to the
#arent element by usin$ the @-(6lement)* function9 3he resultin$ code loo/s li/e
this)
60"@-(6lement)tree, "(ranc2"*
The append)* method, Eou can attach subelements to a #arent element 0ith the
append)* method6 li/e this)
tree"append)60"6lement)"(ranc2"**
3i# Subelements child elements% are stored as a list6 so you can access6 add6 and delete
them by usin$ list methods6 li/e this)
>>> tree"insert)%, 60"6lement)"fr-it flies"**
5earhing %or su!elements
3o search for or 0ithin subelements6 use these methods)
find)pattern* returns the first matchin$ subelement9
"-,
findtext)pattern* returns the 7alue of the te8t attribute for the first matchin$
subelement9
findall)pattern* returns a list of all subelements9
3i# 3he pattern ar$ument in find)* can be either
A ta", &f you use a ta$6 only subelements of that ta$ are chec/ed9
A path, Eou can use a #ath to search the entire subtree9
3i# 3o search the 0hole tree6 use the getiterator)* method9 getiterator)tag*
returns a list of all subelements 0ith the ta$H getiterator)* 0ithout an ar$ument%
returns a list of all subelements in the subtree9
3@:<(&:A.
S3?FF
getiterator)* searches the tree in de#th1first orderH that is6 it
searches do0n one branch to the end6 and then do0n the ne8t branch6
and so on9
&sin" Q4- files
@lement3ree is desi$ned to automatically read OM. files6 re#resent their structures6 and
0rite them to dis/ or to a 4ython file obFect9
6oading douments
3o load an OM. document and turn it into an 6lement0ree instance6 use the file
/ey0ord ar$ument to create a tree from a file in a sin$le o#eration6 li/e this)
order = 60"6lement0ree)file=,order"xml,*
-riting an Element tree to disk as an 736 %ile
3o sa7e an 6lement0ree instance bac/ to dis/6 use the 9rite)* method9 &t ta/es either a
filename or a file obFect9 3he out#ut mi$ht not be human1readable9
order"9rite)o-tp-t$file*
3o sa7e an 6lement structure to dis/6 use the follo0in$ code)
60"6lement0ree)tree*"9rite)o-tp-t$file*
0ther useful =(L odules
4ython includes a fe0 other OM. modules)
xml"dom) (e0 in 4ython 2909 Su##orts Document MbFect Model DMM%6 a
method for readin$ and modifyin$ OM. documents that 0or/s in a 7ariety of
#ro$rammin$ lan$ua$es9
"-*
3i# DMM creates OM. documents in a tree structure and is useful for random1
access readin$9
xml"dom"minidom) Su##orts Document MbFect Model DMM% but is sim#ler and
smaller than the full xml"dom module9
xml"sax) 3his #ac/a$e im#lements Sim#le A4& for OM. SAO%9 &tCs $ood for
hu$e OM. documents because it doesnCt read the 0hole thin$ in one chun/9
<o0e7er6 SAO is more difficult to use than the other modules6 so 0e recommend
you use it only 0hen you really need it9
4I421in" !uccess, 4ana"in" 214ail 4essa"es
3he email #ac/a$e is a library that includes tools for readin$ the te8t of e1mail messa$es6
transformin$ messa$es from te8t to 4ython obFects and bac/ a$ain6 and $eneratin$ e1mail
obFects6 includin$ M&M@ documents9
D@M@M'@D 3he email #ac/a$e doesnCt send messa$esH the smtpli( module sends
them9
/epresenting an e+ail essage in Python
&n 4ython6 e1mail obFects are re#resented as instances of the essage class9 A essage
instance has t0o #arts)
4essa"e headers, Addressin$ information6 subFect6 date6 and so on are stored in a
dictionary1li/e format a ma##in$%6 but there are a fe0 differences from
dictionaries)
o Du#licate messa$e headers are #ossible9
o Messa$e headers are stored in the order they a##eared in the ori$inal
messa$e9
ayload, 3he body of the messa$e can be either a string a te8t1only messa$e% or
a list of essage ob-ects a multi#art messa$eH for instance6 a messa$e that has
te8t6 <3M.6 a ;&F file6 and so on%9
#reating e+ail and (I(, ob'ects
3o build a messa$e structure6 you create a essage instance and add attachments and
headers9
#reatin" a 4essa"e ob>ect
3he sim#lest 0ay to create a essage obFect is to use the message$from$ string)* or
message$from$file)* function9
3o create a essage obFect from a strin$6 use message$from$string)*9 4ass the
function a strin$ or @tringGJ instance6 li/e this)
"20
>>> import email
>>> msg = email"message$from$string)mystring*
3o create a essage obFect from a file6 use message$from$file)*9 4ass the function an
o#en file obFect9
#reatin" 4I42 ob>ects via subclasses
3he email moduleCs M&M@ submodules are for attachin$ #articular /inds of data6 such as
formatted te8t documents6 to an e1mail messa$e9 3he subclasses automatically set u#
some of the M&M@ headers for you9
3he name of the class is al0ays the same as the name of its corres#ondin$ submodule9 3o
im#ort a class from a M&M@ submodule6 ty#e the follo0in$ line of code substitute the
name of the classLsubmodule you 0ant to im#ort%)
from email"G6Iase import G6Iase
3o create an instance of the class after usin$ the #recedin$ im#ort statement6 ty#e code
li/e this)
mime$msg = G6Iase)parameters*
3he follo0in$ M&M@ subclasses create messa$es that include M&M@ obFects9
3I3E3ultipart&'
3he G6-ltipart)* subclass is an outer layer for M&M@ messa$es that ha7e multi#le
#arts9
3o use essage obFects or other M&M@ subclass instances%6 you can either
S#ecify the obFects as #ayload sub#arts 0hen you create an instance of the
G6-ltipart subclass9
Add the obFects later by usin$ the essage"attac2)* method9
3@:<(&:A.
S3?FF
3he G6-ltiCart subclass is ne0 in 4ython 292929
3I3E0ase&'
3he G6Iase)* subclass is for creatin$ M&M@ messa$es 0ith messa$e #arts that arenCt
of s#ecific other M&M@ ty#es te8t6 audio6 or ima$e%9
G6Iase)* reGuires t0o Hontent70ype ar$uments)
"2-
MaFor ty#e for e8am#le6 application%
Minor ty#e for e8am#le6 ms9ord%
3@:<(&:A.
S3?FF
&f you arenCt sure 0hat ty#es to use6 im#ort the mimetypes module
and use the g-ess$type)* function6 li/e this)
>>> mimetypes"g-ess$type),foo"doc,*
),application8ms9ord,, 1one*
>>> x = email"G6Iase"G6Iase),application,,
,ms9ord,*
3i# 3o attach a Word document to an e1mail messa$e6 use the imeIase)* subclass)
-9 Import the modules you need, like so,
2" >>> from email"G6Iase import G6Iase
"9 (pen the *ord file for readin",
." >>> 9ord$file = file),foo"doc,, ,r(,*
A9 /ead the file, and then close it,
<" >>> file$contents = 9ord$file"read)*
E" >>> 9ord$file"close)*
,9 4ake a G6Iase)* ob>ect by typin" this,
=" >>> mime$msg = mime$msg = G6Iase),application,, ,ms9ord,*
-09 !et the payload of the G6Iase)* ob>ect,
//">>> mime$msg"set$payload)file$contents*
!pecifyin" a character set
3o s#ecify the character set of a #ayload6 use the set$c2arset)* method9
3@:<(&:A.
S3?FF
3he set$c2arset)* method ar$ument can be either
A H2arset)* instance
A strin$ 0ith the name of a character set
1one 0hich remo7es the c2arset #arameter from the
Hontent70ype! header%
3he follo0in$ line s#ecifies the character set usin$ a strin$)
>>> msg"set$c2arset),G@J7''&=7/,*
Addin" and chan"in" messa"e headers
essage obFect headers are stored in a dictionary1li/e obFect)
3he header field is the /ey9
3he content of the header is the 7alue9
"22
3o create or chan$e a header6 or to add a 7alue6 use the /ey6 li/e this)
>>> msg[,@-(Tect,] = ,Cict-res of y Hat,
3he add$2eader)* method creates a ne0 header6 a 7alue6 and o#tional #arameters for the
7alue)
>>> msg"add$2eader),yHat,, ,Lng-s,, coat=,0-xedo,*
3he set$param)* method sets or chan$es a #arameter in the Hontent70ype! header6
creatin$ the header if it doesnCt e8ist9
Addin" content to an existin" messa"e
3o add a #ayload to a multi#art e1mail messa$e that already has an e8istin$ #ayload6 use
attac2)* and #ass it a list of essage obFects9
&f the messa$e doesnCt ha7e any #ayload yet6 use set$payload)* to add a #ayload stored
as a strin$9
Warnin$ &f the messa$e already has a #ayload6 the set$payload)* method re#laces it9
Generating (I(, docuents fro essage structures
After you ha7e set u# an e1mail messa$e as a structure of 4ython obFects6 you need to
con7ert it to #lain te8t if you 0ant to send it or #rint it9 3his is called flattening the
messa$e9 3here are se7eral 0ays to flatten a messa$e obFect9 We discuss t0o of them9
rintin" a messa"e ob>ect as a strin"
3he easiest 0ay to #rint the te8t of a messa$e is to use the as$string)* method of
essage)* obFects6 li/e so)
>>> print littlemsg"as$string)*
Oate! Wed, & F-l 2%%< %/!%.!.2 7%E%%
>rom! Crofessor Sr-e
0o! Seograp2y /%/ st-dents
@-(Tect! Gslands of t2e 9orld
>arallons!
@eal BocA
aintop Gsland
2ncodin" binary data into strin" data
3he 6ncoders module includes functions for turnin$ binary data into data that can be
sent as e1mail9 30o of its functions are
"2"
encode$N-opri)*) ?se for a messa$e that has mostly te8t but some un#rintable
characters9
encode$(ase<.)*) ?se for a messa$e that has mostly binary un#rintable% data9
3he format is more com#act than Guoted1#rintable6 but humans canCt read it9
3he encodin$ functions add a Hontent70ransfer76ncoding! header9 3hey chan$e a
messa$e in #lace and return 1one9 3o encode the essage)* obFect littlemsg as base
6!6 ty#e this code)
>>> import email"6ncoders
>>> email"6ncoders"encode$(ase<.)littlemsg*
>>> print littlemsg
>rom no(ody Wed F-l & %/!%.!.2 2%%<
>rom! Crofessor Sr-e
0o! Seograp2y /%/ st-dents
@-(Tect! Gslands of t2e 9orld
Hontent70ransfer76ncoding! (ase<.
Bm>yPWxs(2&QJgp0KW>sG>F5P2sX0W>p(nB5cHIFc2x2(m`XHgoX
/eading e+ail essages
3his section sho0s ho0 4ython can read and mani#ulate e8istin$ e1mail messa$es9
+ettin" information and payloads
3he sim#lest 0ay to return an e1mail messa$e as a te8t strin$ is to use the as$string)*
method of a essage)* instance9 3o include an en7elo#e header in the strin$6 s#ecify
-nixfrom=0r-e as the ar$ument9
mymessage"as$string)-nixfrom=0r-e*
3o find 0hether the e1mail messa$e has multi#le #arts6 use the is$m-ltipart)* method9
&t returns 0r-e or >alse9 >alse means the messa$e is a strin$9
3o see a messa$eCs #ayload6 use the get$payload)* method9 &f the messa$e is multi#art6
it returns a list of essage)* obFects9 &f not6 it returns a strin$9
>>> msg"get$payload)*
[#email"essage"essage instance at %x'2e2<ec>,
>email"essage"essage instance at %x'2e2<%c>]
>>> littlemsg"get$payload)*
,>arallons!Zn@eal BocAZnaintop GslandZn
arsin" e1mail messa"es
3he classes of the Carser module #rocess more com#le8 messa$es9 When you already
ha7e the 0hole messa$e as a strin$ or file6 use its IclassicI Carser class9 Follo0 these
ste#s)
"2!
-9 Import the Carser module, like so,
2" >>> import email"Carser
3"
!9 #reate an instance of the Carser)* class,
&" >>> p = email"Carser"Carser)*
?se the parse)* method for a file #ass it a file obFect% or the parsestr)*
method for a strin$ #ass it a strin$%9
3he te8t must be a bloc/ of headers follo0ed by the body of the messa$e 0hich
can ha7e M&M@1encoded sub#arts%9 3o read only the headers6 #ass the o#tional
#arameter 2eadersonly=0r-e9
>>> x = p"parse)fp*
>>> print x
>rom no(ody Wed F-l & %/!%.!.2 2%%<
>rom! Crofessor Sr-e
0o! Seograp2y /%/ st-dents
@-(Tect! Gslands of t2e 9orld
>arallons!
@eal BocA
aintop Gsland
)sing e+ail utilities
3he email"4tils module includes the follo0in$ messa$e tools)
'unctions for mana"in" =uotation marks and other delimiters
o N-ote)* ta/es a strin$ and esca#es bac/slashes and double Guotes by
#recedin$ them 0ith Z9
o -nN-ote)* remo7es double Guotes and an$le brac/ets from the be$innin$
and end of a strin$9
'unctions for readin" address headers
o parseaddr)* s#lits the header into t0o #arts>real name and e1mail
address9 &t returns a tu#le9
o formataddr)* ta/es the parseaddr)* tu#le and turns it bac/ into a strin$
suitable for an address header9
o getaddresses)* ta/es a list of headers and returns a #arsed list of
addresses found in the headers9
3his code $ets all the addresses in a messa$eCs 0o! header)
from email"4tils import getaddresses
to$addrs = msg"get$all),to,, []*
to$recips = getaddresses)to$addrs*
Tools for workin" with dates
"2A
o parsedate)* reads a date in a messa$e header and returns a nine1item
tu#le that 0or/s 0ith time"mAtime)* see :ha#ter -+%9 &f the date doesnCt
follo0 the standard format6 parsedate)* tries to $uess ho0 the date is
formatted9
o formatdate)* ta/es a floatin$ #oint time 7alue or uses the current time%
and returns a date strin$ of the follo0in$ format)
o >ri, %= 1o5 2%%/ %/!%'!.E 7%%%%
'unctions for decodin" and encodin" character sets
o decode$rfc223/)* decodes a strin$ accordin$ to DF: 22"-9
o encode$rfc223/)* encodes a strin$ and acce#ts o#tional character set
and lan$ua$e ar$uments9
o collapse$rfc223/$5al-e)* turns a get$param)* three1item tu#le
character set6 lan$ua$e6 and 7alue% into a ?nicode strin$9
o decode$params)* decodes a list of t0o1item tu#les in the format content1
ty#e6 strin$17alue%9
!imply !4T
3he email #ac/a$e only $enerates and #rocesses e1mail messa$es9 3o send e1mail
messa$es6 you need the smtpli( module9 SM34 stands for ,imple 'ail &ransfer
Protocol.
3he #rimary 0ay to use the smtpli( module is to create an instance of the @0C class its
#arameter is a hostname%H then use the sendmail)* and N-it)* methods in that order9
3he sendmail)* method reGuires the follo0in$ ar$uments)
From1address strin$
.ist of to1address strin$s6 or a strin$ containin$ a sin$le to1address
Messa$e a te8t strin$>usually a flattened email"essage obFect%
3@:<(&:A.
S3?FF
3he o#tional ar$uments for sendmail)* are ad7anced6 and
0e donCt co7er them in this boo/9
3he res#onse from sendmail)* de#ends on the follo0in$ factors)
&f the ser7er acce#ts the mail for at least one of the to1addresses6 sendmail)*
re#orts success9
&f any of the to1addresses didnCt recei7e the messa$e6 sendmail)* returns a
dictionary containin$ one entry for each reci#ient 0ho didnCt $et the mail6 alon$
0ith error codes9
3o end the SM34 session and close the connection 0ith the ser7er6 use the N-it)*
method9
3i# 3he sim#lest code for sendin$ a messa$e is the follo0in$)
"26
import smtpli(
ser5er = smtpli("@0C),local2ost,*
ser5er"sendmail)fromaddr, toaddrs, msg*
ser5er"N-it)*
#+I, +ateway to the *eb
Common =ate$ay /nterface, or :;&6 is a standard scri#tin$ lan$ua$e for Web sites9 :;&
scri#ts 0or/ li/e this)
-9 A bro0ser ma/es a reGuest to a Web ser7er9
29 3he Web ser7er e8ecutes a :;& scri#t9
"9 3he :;& scri#t out#ut is returned to the bro0ser as a Web #a$e9
Eou can 0rite :;& scri#ts in 4ython9 3he cgi module includes tools that let your scri#ts
0or/ 0ith Web #a$es and recei7e data from form fields9 Debu$$in$ tools are also
#ro7ided9
Setting up #GI output in Python
A :;& scri#t usually out#uts t0o sections of te8t se#arated by a blan/ line9
3i# 3o $enerate this te8t from your 4ython #ro$ram6 use the print command)
-9 3he first section contains headers describin$ the ty#e of data in the second
section9 :ode for this section mi$ht loo/ li/e this)
2" print "Hontent70ype! text82tml"
"9 ?se an em#ty print command to $enerate the blan/ line se#arator)
." print
A9 3he second section usually includes <3M.1formatted te8t that $enerates the
Web #a$e6 li/e this)
<" print "#0G036>essage in a (ro9ser#80G036>"
E" print "#H/> Hello, 9orld!#8H/>"
'" print "#C> Help! G,m trapped in t2is We( (ro9ser"
=" print "and G can,t get o-t! #8C>"
/eading data fro *eb input
:;& scri#ts usually #rocess in#ut from a Web form created 0ith the <3M. ta$ #form>9
Form fields can contain data of 7arious ty#es6 but you usually 0ant to treat the data as a
strin$ or a file9
"2+
/eadin" data from form fields
3o $et form data6 you create an instance of the >ield@torage)* class 0ithout
ar$uments%)
3he instance reads form contents from standard in#ut or from the a##ro#riate
en7ironment9
3he instance stores data in a dictionary1li/e structure in 0hich a field name is
associated 0ith its 7alue9
?nli/e 4ython dictionaries6 instances of the >ield@torage)* class allo0 for multi#le
/eys 0ith the same name9 3hey su##ort such methods as 2as$Aey)*6 Aeys)*6 and len)*9
After youC7e stored the data6 the easiest 0ay to $et the 7alues out of indi7idual fields is to
use the getfirst)* and getlist)* methods9
3i# 3hese methods #rotect a$ainst the #ossibility that a user entered too many 7alues in a
field9
get%irst&'
&f a field is su##osed to ha7e only one 7alue6 use the getfirst)* method of the
>ield@torage instance to return a sin$le 7alue9 4ass the name of the form field as an
ar$ument6 li/e this)
addr = form"getfirst)"addr"*
3he getfirst)* method ta/es an o#tional #arameter s#ecifyin$ 0hat to return if the
form field doesnCt e8ist or has no 7alue9 &t defaults to 1one9
getlist&'
3o return a list of all the 7alues associated 0ith a form field6 use the getlist)* method
and #ass the name of the form field9 &f there is only one 7alue in the field6 the method
returns a one-item list9 &f there are no 7alues or the form field doesnCt e8ist6 it returns an
empty list9
3o #rocess the list of 7alues6 use a for loo#6 li/e this)
for item in form"getlist)"field$2eader"*!
do$somet2ing)item*
Warnin$
4aintainin" security when usin" HT4- forms
Forms on <3M. #a$es are 7ulnerable to security #roblems>malicious code
can be entered9 &f you are #lannin$ to use form data in a shell command on your
com#uter 7ia the os"system)* function6 for e8am#le%6 include tests in your
scri#t to ma/e sure the data contains only al#hanumeric characters6 dashes6
"2,
underscores6 and #eriods9 ,pecifically do not allo$ spaces. Whene7er #ossible6
use 4ython functions for instance6 s2-til"mo5e)*% instead of callin$
os"system)* 0ith data entered by end users9
Similarly6 0hen sendin$ user1entered data bac/ to the bro0ser6 ma/e sure to
stri# <3M. ta$s6 es#ecially if you ha7e a Web site 0here users can see data
entered by other users such as a blo$%9
/eadin" files from form fields
3o find 0hether a field stores a file6 test the file data attribute of the >ield@torage
instance 0ith an if statement6 li/e this)
fileitem = form["-serfile"]
if fileitem"file!
+ do somet2ing
Setting up and installing a #GI script
Eour scri#t must follo0 certain $uidelines to 0or/ in the Web en7ironment9 3he
follo0in$ instructions sho0 ho0 to 0rite and install your scri#t9
*ritin" a script to work in the *eb environment
3y#e the follo0in$ code as the first line of the scri#t re#lace the #athname 0ith the
#athname of the 4ython installation on your Web ser7er%)
+!8-sr8local8(in8pyt2on
3i# ?se absolute #aths in your scri#t to access #ro$rams or files9
3o load modules from a location not on the default 4ython search #ath6 use
sys"pat2"insert)* to add their #athnames to sys"pat29 ?se % as the first ar$ument to
ha7e this #ath searched first9 For e8am#le6 you mi$ht ty#e
import sys
sys"pat2"insert)%, "8-sr82ome8stef8pyt2on$mod-les"*
#heckin" for syntax errors
Dun your scri#t from the command line to see 0hether it contains synta8 errors9 3his ste#
ma/es sure your scri#t contains 7alid 4ython code)
D pyt2on script"py
"2*
Installin" a script and settin" permissions
Eour :;& scri#t usually $oes in the cgi7(in directory of your Web ser7er9 :hec/ the
documentation for your Web host #ro7ider to find out any reGuirements for the scri#t>
for e8am#le6 some &S4s reGuire that all :;& scri#ts end 0ith "cgi9
After youC7e installed the scri#t in the a##ro#riate directory6 you need to set #ermissions
so that users of your Web site can access it9 <ereCs ho0)
-9 #han"e the permissions for the script to let the ;others; "roup read and
execute the script.
3i# Mn ?(&O6 the command for $i7in$ the IothersI $rou# read and e8ecute
access is c2mod %E&& scriptname9
29 If the script uses any files, chan"e those file permissions so that the ;others;
"roup can read or write the files 5dependin" on how the script uses the files6.
o (eading the files9 3he ?(&O command for ma/in$ files readable by the
IothersI $rou# is) c2mod %<.. filename9
o "riting the files9 3he ?(&O command for allo0in$ the IothersI $rou# to
0rite to files is c2mod %<<< filename9
1ebugging #GI scripts
:;& scri#ts donCt handle 4ythonCs error tracebac/s the same 0ay that 4ython itself does6
so you need to follo0 s#ecial #rocedures for debu$$in$ your :;& scri#ts9 3he rest of this
cha#ter sho0s you ho09
#heck for syntax errors
'efore doin$ any other debu$$in$ ste#s6 double1chec/ your scri#t for synta8 errors yes6
e7en if you already did it once%9 Follo0 the instructions in I:hec/in$ for synta8 errors6I
earlier in this cha#ter9
4ake sure your script is installed correctly
?se these t0o ste#s to install and chec/ the scri#t)
-9 Install a copy of the cgi"py module in the location of your script.
29 /un the cgi"py module by typin" code like this into your browser 5replacin"
2ostname8cgi7(in8 with the path to your cgi7(in directory6,
htt#)LL0009hostnameLc$i1binLc$i9#y2nameVMyN(ame&addrV:yber
3he results sho0 0hether the scri#t is installed in the correct directory)
""0
&f the directory is correct6 some dia$nostic te8t6 includin$ the te8t after the V in the
abo7e line of code6 a##ears in the Web bro0ser9
&f you see a !0! error or a messa$e that the #a$e canCt be found6 then the scri#ts
are installed in the 0ron$ directory9
Eou mi$ht $et a different error if the scri#t is in the ri$ht directory but installed
incorrectly9
Test your code
&f your scri#t doesnCt 0or/6 and youC7e 7erified that itCs installed in the correct directory6
these ste#s test your code by usin$ the cgi"test)* function)
-9 In a text editor, omment out the main body of your code 5put a R character at
the be"innin" of every line6 and add this line of code,
2" cgi"test)*
"9 /un the altered script by typin" code like this into your browser 5replace
2ostname8cgi7(in8 with the path to your cgi7(in directory and replace
scriptname with the name of your script6,
htt#)LL0009hostnameLc$i1binLscri#tname9#y2nameVMyN(ame&addrV:yber
&f the dia$nostic te8t and the te8t after the V in the abo7e line of code a##ears in
the Web bro0ser6 then the scri#t is installed correctly6 and any #roblems youCre
ha7in$ are #robably 0ith your scri#tCs code9
3i# &f the cgi"test)* code doesnCt 0or/6 then the scri#t #robably isnCt installed
correctly9 ;o bac/ to I&nstallin$ a scri#t and settin$ #ermissions6I earlier in
this cha#ter9 Eou mi$ht need to as/ your Web hostin$ com#any for the #ath of
your cgi7(in directory9
Include debu""in" code in your script
&f your scri#t is e8ecutin$ some code but 0or/s incorrectly6 set u# your scri#t to dis#lay
hel#ful debu$$in$ messa$es9 ?se one or both of the follo0in$ methods9
5eeing 41I sript errors
3he cgit( module dis#lays error information for :;& scri#ts9 &m#ort and enable the
cgit( module by includin$ one of the follo0in$ code lines near the to# of your scri#t6
after the +!8-sr8local8(in8pyt2on line)
3his line dis#lays errors in the Web bro0ser)
import cgit(R cgit("ena(le)*
3his line sa7es errors to a tem#orary file)
import cgit(R cgit("ena(le)display=%, logdir="8tmp"*
""-
5eeing trae!ak in%ormation
&f your scri#t isnCt 0or/in$ correctly6 it mi$ht be #roducin$ tracebac/ information the
error messa$es that 4ython normally #rints 0hen you run a #ro$ram from the command
line or from interacti7e mode%9 De#endin$ on the confi$uration of your Web host6 the
tracebac/ messa$es sometimes a##ear in the <334 ser7erCs lo$ files9 <o0 you access
these files de#ends on the ser7er setu#9 :ontact the su##ort team for your Web host to
find out more9
&f you donCt 0ant to di$ throu$h the lo$ files6 you can set u# your scri#t so that tracebac/
information is dis#layed in your Web bro0ser9 &nclude this code near the to# of your
scri#t)
import sys
sys"stderr = sys"stdo-t
print "Hontent70ype! text8plain"
print
""2
art 3, The art of Tens
#hapter -ist
:ha#ter 2-) 3en :ritical 4ython &dioms
:ha#ter 22) 3en ;reat Desources
3he A
th
Wa7e 'y Dich 3ennant
IWell6 hereCs your #roblem9 Eou only ha7e half the ram you need9I
In this part
.ists6 lists6 and more lists5 For Dummies readers /no0 that they can count on the 4art of
3ens to #ro7ide yummy tidbits of information6 and this 4art of 3ens is no different9
&n this #art6 you $et ten chun/s of code that sol7e annoyin$ little #ro$rammin$ #roblems
in ele$ant 0aysH Fust dro# them into your #ro$rams9 We also sho0 you ten free resources
you can use to find out more about 4ython and hoo/ u# 0ith the rest of the 4ython
community9
"""
#hapter 7., Ten #ritical ython Idioms
<ere are ten little code sni##ets that illustrate ho0 to handle some common #roblems in
4ython9 3hey are arran$ed rou$hly in order of difficulty9
3@:<(&:A.
S3?FF
Some of these idioms are from the 4ython :oo/boo/6 and youCll find
more)
htt#)LL0009#ythoncoo/boo/9acti7estate9com
#ollectin" +lobs and +lobs of 'iles
3he glo( module #ro7ides a sin$le function6 also called glo(6 0hich lets you $et a list of
files from a directory you can also find directory names%9 3he glo( function reco$nizes
the same 0ildcard search characters that the ?(&O shell reco$nizes6 e8ce#t for tilde \%9
3@:<(&:A.
S3?FF
Mn Mac and ?ni8 systems6 glo( searches are case1sensiti7e9
<ereCs ho0 to find all the Word documents 0hich end 0ith the suffi8 "doc% in a
directory called yOocs)
>>> import glo(
>>> docs = glo("glo(),yOocs8;"doc,*
[,yOocs82ello9orld"doc,, ,yOocs8myspider"doc,,
,yOocs8pageco-nt"doc,]
3he follo0in$ e8am#le finds files be$innin$ 0ith " a dot%9 3hese files arenCt found in
0ildcard searches9
>>> glo("glo(),";,*
[,"2idden$file,]
/ollin" :ice and !hufflin" #ards
4ythonCs random module is $ood for $eneratin$ sim#le random numbers and for
so#histicated random number #roblems6 but 0e 0onCt $et into that>0eCre Fust as ea$er to
a7oid statistics as e7erybody else%9
""!
(aking a sa$ing thro&
<ereCs a sim#le dice1roller function9 3o use it6 Fust call it 0ith an o#tional inte$er
ar$ument)
import random
def roll)d=<*!
ret-rn random"randint)/, d*
>>> roll)* + rolls a <7sided die
.
>>> roll)2%* + rolls a 2%7sided die
/E
Playing the dealer
(o0 su##ose you ha7e a list re#resentin$ a dec/ of cards9 <ere is some code that 0ould
create such a list)
def maAe$decA)*!
s-its = [,spades,, ,2earts,, ,diamonds,, ,cl-(s,]
5al-es = [,ace,, ,2,, ,3,, ,.,, ,&,, ,<,, ,E,, ,',, ,=,, ,/%,,
,TacA,,
,N-een,, ,Aing,]
decA = []
for s in s-its!
for 5 in 5al-es!
decA"append)5 : , of , : s*
ret-rn decA
3o $et a sin$le card6 run the function to ma/e a dec/ and #ic/ a card 0ith
random"c2oice)* li/e this)
>>> decA = maAe$decA)*
>>> random"c2oice)decA*
,3 of diamonds,
&f you 0ant to #ic/ a fe0 cards6 use random"s2-ffle)* and then use the pop)* method
of lists to retrie7e cards one at a time9
>>> ne9decA = maAe$decA)*
>>> random"s2-ffle)ne9decA*
>>> 2and = []
>>> for c in range)&*!
""" 2and"append)ne9decA"pop)**
"""
>>> 2and
[,& of diamonds,, ,< of diamonds,, ,ace of spades,, ,ace of
cl-(s,, ,Aing of 2earts,]
3i# 'ecause s2-ffle)* and pop)* chan$e the list in #lace6 you should ma/e a ne0 dec/
each time you deal9
3i# &n 4ython 292 and earlier6 s2-ffle)* 0or/s 0ell only 0ith small lists9 4ython 29"
""A
uses a ne0 random number al$orithm so that s2-ffle)* to 0or/ correctly 0ith lists
containin$ as many as 26000 elements9 'ut someone for$ot to u#date the docs for
4ython 29" and 29!H they donCt reflect this chan$e9
""6
&ni=uely (rdered -ists
4ythonCs set data ty#e ma/es it easy to find all the uniGue items in a list9 See :ha#ter * to
find out about sets9% 'ut sets donCt 0or/ 0ell if you 0ant to /ee# the order of items9 3his
function ta/es a list and returns a ne0 list containin$ only its uniGue items6 in the same
order as the ori$inal list)
def -niN-e)items*!
tmp = []
cac2e = set)*
for item in items!
if item not in cac2e!
tmp"append)item*
cac2e"add)item*
ret-rn tmp
&f youCre concerned about memory usa$e6 you can use a $enerator 7ersion of the
#recedin$ function see :ha#ter -6%)
def -niN-e)items*!
cac2e = set)*
for item in items!
if item not in cac2e!
cac2e"add)item*
yield item
<ereCs ho0 they 0or/)
>>> men- = [,egg,, ,(acon,, ,egg,, ,sa-sage,, ,(acon,, ,egg,,
,spam,, ,egg,, ,(acon,, ,spam,, ,egg,, ,(acon,, ,sa-sage,,
,spam,, ,spam,, ,(acon,, ,tomato,, ,spam,,
,lo(ster t2ermidor 9it2 tr-ffle pate, (randy, and a fried egg on top,,
,spam,, ,(aAed (eans,]
>>> -niN-e)men-* + preser5es item order
[,egg,, ,(acon,, ,sa-sage,, ,spam,, ,tomato,, ,lo(ster t2ermidor 9it2
tr-ffle
pate, (randy, and a fried egg on top,, ,(aAed (eans,]
/eversin" %our *ay to !uccess
3he -niN-e function in the #re7ious section /ee#s the first item it finds and thro0s a0ay
subseGuent du#licates9 What if you 0ant the last matchin$ item2 Most of the time6 addin$
the double1re7erse techniGue does 0hat you 0ant)
my$data"re5erse)*
my$data = -niN-e)my$data*
my$data"re5erse)*
""+
(ote that the sort)* method of lists and the sorted)* built1in function6 0hich #uts list
items in al#hanumeric order6 both ha7e a re5erse #arameter ne0 in 4ython 29!%9 See
:ha#ter , for the lo0do0n on sort)* and sorted)*9
2xceptional Type1Testin"
Sometimes itCs a $ood idea to chec/ the ty#e of data that is bein$ #ut into your function to
ma/e sure itCs the ty#e of data you 0ant9 Eou can use isinstance)* or iss-(class)* to
do this9 'ut thatCs not the ideal test for code thatCs intended to 0or/ 0ith user1defined
classes based on built1in data ty#es9 4ythonCs duc/1ty#in$ see :ha#ter -"% ma/es it
#ossible to create an obFect that has an append method6 for e8am#le6 that isnCt an instance
or subclass of the list data ty#e9 3his obFect mi$ht 0or/ in your function but 0ould not
#ass the isinstance)* or iss-(class)* test9
&f you 0ant your function to #rocess such obFects6 itCs better to use a try8except bloc/ to
7erify that the obFect behaves the 0ay you need it to9 For e8am#le6 you mi$ht test
0hether an obFect su##orts the append)* and pop)* methods and 0hether it allo0s
inde8in$9 &f so6 thereCs a $ood chance it 0ill su##ort other list o#erations9% <ereCs a code
bloc/ that #erforms such a test)
def foo)l*!
try!
l"append),foo,*
l[%]
l"pop)*
except @tandard6rror!
raise 0ype6rror)"1ot a 5alid list o(Tect! Dr" D l*
3@:<(&:A.
S3?FF
3his code catches @tandard6rror in the except statement9
@tandard6rror is the class from 0hich almost all e8ce#tions deri7e
e8ce#t for @ystem6xit and Xey(oardGnterr-pt%9 :atchin$ it also
catches any e8ce#tion that deri7es from it9 We then translate the
e8ce#tion into a 0ype6rror for the #ur#ose of lo$$in$ the result or
#rintin$ a messa$e9
3i# ?se this chec/in$ only 0ith critical code9 ?sually6 this le7el of chec/in$ is o7er/ill6
and you can assume that your users 0ill follo0 the documentation you #ro7ided 0ith
your function you did #ro7ide documentation6 ri$ht2%9
"",
#lasses 0ust for :ata
4ython class instances are a lot li/e dicts>both can store /eys and associated 7alues9 &n
fact6 in many 0ays6 instances are sim#ly a thin 0ra##er around dicts6 and attribute synta8
is easier to read than dict synta89
foo"(ar + a class attri(-te
foo[,(ar,] + a dictionary Aey
4ython #ro$rammers commonly create classes 0ith no methods a data-only class% for
mani#ulatin$ /eyL7alue data9 <ereCs a class that ma/es it easy to initialize the class
instance 0ith some 7alues courtesy of Ale8 Martelli%)
class I-nc2!
def $$init$$)self, ;;A9args*!
self"$$dict$$"-pdate)A9args*
When creatin$ the instance6 you Fust #ass it one or more /ey0ord ar$uments9 &n this
e8am#le6 0e create an instance of I-nc2 and store the current 0or/in$ directory by usin$
the /ey0ord start$dir)
>>> import os
>>> config = I-nc2)start$dir=os"getc9d)**
>>> config"start$dir
,84sers8firecat,
For more info about I-nc26 see this Web #a$e6 #art of the 4ython :oo/boo/)
htt#)LL0009as#n9Acti7eState9comLAS4(L:oo/boo/L4ythonLDeci#eLA2"0,
+ettin" #lose 2nou"h with difflib
4eo#le often ma/e mista/es 0hen enterin$ te8t9 3he diffli( module $i7es you a 0ay to
find strin$s that are close but not e8act matches to a $i7en strin$)
>>> import diffli(
>>> rig2t = ,02e N-icA (ro9n fox,
>>> 9rong = ,0He N-acA (ro9n fix,
>>> matc2er = diffli("@eN-enceatc2er)1one, rig2t, 9rong*
>>> print matc2er"ratio)*
%"'.2/%&2<3/&'
3he ratio)* method returns a floatin$ #oint number bet0een 0 and - that indicates ho0
close the match is9 <i$her numbers indicate a closer match9 A match hi$her than 096 is
usually considered I$oodI maybe not by medie7al manuscri#t1illuminatin$ mon/s6 but
$ood enou$h for the modern 0orld%9
""*
3o com#are a sin$le 0ord a$ainst a list of 0ords6 use the diffli( moduleCs
get$close$matc2es)* method9 &t finds the 0ords 0ith the hi$hest match ratio)
>>> import diffli(
>>> mylist = [,N-icA,, ,N-acA,, ,N-arA,, ,N-art,]
>>> diffli("get$close$matc2es),N-ote,, mylist*
[,N-art,]
:!&< :!&< /ah rah :!&<
DS? stands for Idecorate6 sort6 undecorate6I and itCs a cle7er tric/ for sortin$ seGuence
obFects by one of their elements9
3@:<(&:A.
S3?FF
3his use of the 0ord decorate doesnCt ha7e anythin$ to do 0ith the
decorator feature discussed in :ha#ter -69 4ython has Fust $otten so
bi$ that itCs ha7in$ to recycle the 0ords it uses to describe tools5
Su##ose you ha7e a list of address tu#les6 li/e this)
addresses = [
),/23 ain @t,, ,Lnyto9n,, ,/23.&,*,
),/23 @econd @t,, ,Jt2erto9n,, ,&.32/,*,
),.&< @econd @t,, ,1o92ere5ille,, ,/////,*,
),EEE orris @t,, ,>ilenes Iasement,, ,=====,*
]
(o0 su##ose you 0ant to sort them by zi# code9 3he sort)* method of lists lets you
#ass a com#arison function6 but 0e donCt recommend that because itCs clumsy and slo09 A
better 0ay is to create a ne0 list that is decorated 0ith the zi# field6 so that each tu#le
becomes a 21tu#le 0here the first element is the zi# code and the second element is the
old tu#le)
),/23.&,, ),/23 ain @t,, ,Lnyto9n,, ,/23.&,* *
After you ha7e the list of 21tu#les6 you can sort the list and then undecorate it remo7e
the e8tra zi# field%9
3hese t0o functions do DS? on such a list9 3he first one uses a list com#rehension to
create the tmp list and the return 7alue9 See :ha#ter -6 for more on list
com#rehensions9%
def ds-$Qip)addresses*!
tmp = [)x[2], x* for x in addresses]
tmp"sort)*
ret-rn [x[/] for x in tmp]
<ereCs 0hat ha##ens 0hen you run the function)
"!0
>>> ds-$Qip)addresses*
[),.&< @econd @t,, ,1o92ere5ille,, ,/////,*, ),/23 ain @t,,
,Lnyto9n,, ,/23.&,*, ),/23 @econd @t,, ,Jt2erto9n,, ,&.32/,*,
),EEE orris @t,, ,>ilenes Iasement,, ,=====,*]
3i# 3hereCs another 0ay to #erform a DS? sort9 4ython 29! adds a ne0 Aey #arameter to
the sort)* method and the sorted)* built1in function9 ?se this 0ith the
itemgetter)* class from the operator module for a sim#ler DS?1ty#e solution)
>>> import operator
>>> t2ird$item = operator"itemgetter)2* + get 3rd item from t-ple
>>> addresses"sort)Aey=t2ird$item*
>>> addresses
[),.&< @econd @t,, ,1o92ere5ille,, ,/////,*, ),/23 ain @t,,
,Lnyto9n,, ,/23.&,*, ),/23 @econd @t,, ,Jt2erto9n,, ,&.32/,*,
),EEE orris @t,, ,>ilenes Iasement,, ,=====,*]
3@:<(&:A.
S3?FF
3he Aey #arameter reGuires a function6 0hich itemgetter)*
su##lies9 A similar attrgetter)* function 0or/s 0ith class
instances to retrie7e attribute 7alues based on their names9
!implifyin" #hoices &sin" :icts
3y#in$ lots of if8elif8else statements can $et rather tedious6 as the follo0in$ e8am#le
sho0s9 &n the e8am#le code6 acco-nt$type is a strin$ and H2ecAingLcco-nt6
@a5ingsLcco-nt6 and SenericLcco-nt are classes or functions for this #ur#ose it
doesnCt matter 0hich%)
if acco-nt$type == ,c2ecAing,!
ne9$acco-nt = H2ecAingLcco-nt)*
elif acco-nt$type == ,sa5ings,!
ne9$acco-nt = @a5ingsLcco-nt)*
else!
ne9$acco-nt = SenericLcco-nt)*
&f youCre chec/in$ a sin$le e8#ression a$ainst a bunch of constants6 as in the #recedin$
code6 usin$ a dict to store the constants ma/es more sense)
acco-nts = {
,c2ecAing,! H2ecAingLcco-nt,
,sa5ings,! @a5ingsLcco-nt,
}
ne9$acco-nt = acco-nts"get)acco-nt$type, SenericLcco-nt*)*
3he #recedin$ line of code contains a fe0 useful techniGues)
3he get)* method of dicts lets you s#ecify a 7alue to return if the /ey isnCt found9
<ere6 if the account ty#e isnCt in the acco-nts dict6 the get)* method returns
SenericLcco-nt9
"!-
H2ecAingLcco-nt and @a5ingsLcco-nt donCt ha7e #arentheses after them inside
the dict because theyCre bein$ stored rather than called9
3he set of #arentheses at the end of the line after the get)* call s#ecify that the
function or class that get)* returns should be called9
!in"les +oin" !teady
Sometimes you 0ant to ma/e sure that there is only one of an obFect called a singleton%
0ithin your #ro$ram9 A common e8am#le mi$ht be an obFect that holds confi$uration
info9 3here are t0o standard 0ays to do this in 4ython) creatin$ a sin$leton obFect and
creatin$ a 'or$ 4attern9
)sing a singleton ob'ect
Mne 0ay to ma/e sure you ha7e a uniGue obFect is to create a ty#e of obFect thatCs a
al0ays a sin$leton9 4ython has t0o) modules and classes9 Classes are sin$letons6 but
instances arenCt9% 3he follo0in$ e8am#le creates a class called Honfig and stores an
attribute in it9 Eou canCt create another Honfig class in your module6 so you can be sure
that Honfig"start$dir is uniGue9
class Honfig!
pass
config"start$dir = os"getc9d)*
#alling in the Borg Pattern
Eou can ma/e a s#ecial /ind of class so that all of its instances share the same state
0hich ma/es them functionally identical%9 3hat means 0hate7er you do to one instance
is also done to all the other instances9
3i# 3o create this class6 use the follo0in$ brilliant code from Ale8 Martelli called the
0org Pattern9
class Honfig!
$$s2ared$state = {}
def $$init$$)self*!
self"$$dict$$ = self"$$s2ared$state
<ereCs 0hat ha##ens 0hen you test it9 3his code sho0s that the t0o Iorg instances are
different obFects they are stored in different locations%)
>>> (org/ = Honfig)*
>>> (org2 = Honfig)*
>>> (org/
#$$main$$"config instance at %x&'.e%>
>>> (org2
#$$main$$"config instance at %x&'.('>
"!2
3his code sho0s that both instances share state>0hen an attribute is assi$ned to (org26
the same attribute no0 e8ists in (org/9
>>> (org2"start$dir = os"getc9d)*
>>> print (org2"start$dir
84sers8firecat8@tefCyt2onCrogs
>>> print (org/"start$dir
84sers8firecat8@tefCyt2onCrogs
For more about the 'or$ 4attern6 see
htt#)LL0009as#n9Acti7eState9comLAS4(L:oo/boo/L4ythonLDeci#eL66A"-
#hapter 77, Ten +reat /esources
3his cha#ter lists ten resources to chec/ out to find out more about 4ython6 to $et more
hel# 0ith your #ro$rams6 and to $et in7ol7ed 0ith the 4ython community9
The 4othership, http,SSwww.python.or"
3he 4ython mothershi# on the Web is doc/ed at htt#)LL0009#ython9or$9 &f you ha7e
Guestions about 4ython6 you should $o here first9 &t includes the latest 7ersions of 4ython
for do0nload6 alon$ 0ith documentation6 FAYs6 introductions6 tutorials6 a Wi/i an
encyclo#edia1ty#e structure that anyone can edit%6 mailin$ list archi7es6 announcements6
lin/s to third1#arty modules6 and more9
A search bo8 is a7ailable on most of the main #a$es of htt#)LL0009#ython9or$9 &f you
0ant to search s#ecific #arts of the site or s#ecify lots of search criteria6 use the search
#a$e6 a7ailable here)
htt#)LL0009#ython9or$LsearchL
3he follo0in$ sections hi$hli$ht im#ortant #arts of the htt#)LL0009#ython9or$ Web site9
*e"re glad you asked that: Python %A-s
4ython FAYs FreGuently As/ed Yuestions% and a S#anish translation can be found at
htt#)LL0009#ython9or$LdocLfaGL9 3he FAYs co7er such to#ics as
What 4ython is6 ho0 to $et a co#y6 0ho uses it and for 0hat6 and 4ythonCs desi$n
#hiloso#hy
<o01tos for common #ro$rammin$ tas/s
&nstallin$ and usin$ third1#arty libraries
"!"
Writin$ e8tensions to 4ython in other lan$ua$es
4ythonCs beha7ior in Windo0s
;ra#hical ?ser &nterface ;?&% #ro$rammin$
0fficial docuentation
Eou can al0ays find the documentation for the latest 7ersion of 4ython at
htt#)LL0009#ython9or$LdocLcurrentL9 Documentation for earlier 7ersions of 4ython is also
a7ailable9 Eou can 7ie0 the docs on the Web site or do0nload them in a 7ariety of
formats9
&n addition to the docs for s#ecific 7ersions6 you can find $eneral $uides co7erin$ a
7ariety of subFects)
'e$innerCs $uides for #eo#le 0ho ha7enCt #ro$rammed before%
&ntroductions to 4ython some for #eo#le 0ho ha7e used other lan$ua$es and
some for be$innersH tutorials are also included%
A 4ython&nfo Wi/i>a collection of #a$es that anyone can edit
3o#ic $uides>articles about databases6 #arsers6 scientific uses of 4ython6 Web
#ro$rammin$6 OM.6 and more
A list of boo/s and re7ie0s of boo/s 0ritten about 4ython6 or$anized by to#ic
3@:<(&:A.
S3?FF
4ython @nhancement 4ro#osals 4@4s% are documents of the #rocess
of addin$ ne0 features to 4ython9 An archi7e of 4@4s for features
added to #re7ious 7ersions of 4ython is a7ailable9 4@4s arenCt
documentation #er se6 but they usually include an e8#lanation of a
featureCs benefits6 0hich can be 7ery hel#ful for understandin$ its
uses9 Summaries of ar$uments for and a$ainst the feature shed li$ht
on the #hiloso#hy behind the 4ython lan$ua$e9 An inde8 of 4@4s is
here)
htt#)LL0009#ython9or$Lde7L#e#sL
&f youCre a history buff6 youCll li/e 4@4s because they include bac/$round information
about ho0 #ro#osals de7elo#ed9
tutor>python?org and help>python?org
3he 3utor mailin$ list is for be$innin$ and intermediate 4ython #ro$rammers to as/ and
ans0er each otherCs Guestions9 &ts Web #a$e is here)
htt#)LL0009mail9#ython9or$LmailmanLlistinfoLtutorL
Eou can #ost a messa$e to it by sendin$ e1mail to tutor\#ython9or$9 We recommend that
if you #ost a messa$e6 you also subscribe to the list5 Eou can do so 7ia a form on the
abo7e Web #a$e9
"!!
3utor mailin$ list archi7es are at htt#)LL0009mail9#ython9or$L#i#ermailLtutorL9 When you
use the search bo8 on the 4ython home #a$e6 you $et results from the 3utor Archi7es as
0ell as from other #a$es on the site9
&f you ha7e a Guestion that you 0ant ans0ered #ri7ately6 and you canCt find information
about it by searchin$ the 4ython Web site6 you can send e1mail to hel#\#ython9or$6
0hich is staffed by 7olunteer 4ython e8#erts9
The comp.lan".python ?ews"roup
3he comp"lang"pyt2on ?senet ne0s$rou# is the main source for a 7ariety of discussions
about 4ython9 'oth be$inners and ad7anced #ro$rammers #ost to the $rou#6 and contents
include e8amination of #ro$rammin$ #roblems6 discussions of 4ython com#ared 0ith
other lan$ua$es6 discussions often 7ociferous5% of #ro#osed ne0 4ython features6 and
more9
Eou can read comp"lang"pyt2on either 0ith netne0s soft0are or as a mailin$ list9
'ecause it recei7es hundreds of #osts a day6 0e recommend readin$ it 7ia ?senetH ne0s1
readin$ soft0are $enerally handles com#le8 messa$e threadin$ better than e1mail
soft0are9
#heese !hop, (nline #ollection of ython 4odules
:heese Sho#6 formerly called 4y4&6 maintains a collection of third1#arty 4ython modules9
&t li7es on the htt#)LL0009#ython9or$ Web site9 &ts home #a$e is here)
htt#)LL0009cheesesho#9#ython9or$L
As of this 0ritin$6 it contains -6!2* #ac/a$es9 Most of them are a7ailable for free but
chec/ the licensin$ scheme before you distribute them or use them in commercial
a##lications%9 Eou can search #ac/a$es by name or by /ey0ord6 and you can bro0se a list
of #ac/a$es or$anized by to#ic and by ty#e for e8am#le6 you can bro0se for #ac/a$es
that 0or/ on a #articular o#eratin$ system%9 Eou can also submit your o0n #ac/a$es9
3@:<(&:A.
S3?FF
:heese Sho# is named after the Monty 4ython s/etch of the same
name6 in 0hich a customer disco7ers that the cheese sho# doesnCt6 in
fact6 ha7e any cheese for sale at all9
"!A
/andom Access /eference at
http,SSwww.wiki.python.or"
3he Web #a$e htt#)LL00090i/i9#ython9or$L contains lin/s to t0o Wi/is) the 4ython Wi/i
for 4ython% and the Jython Wi/i9 Jython is 4ython for Ja7a9%
A Wi/i is a collection of Web #a$es that anyone can edit9 Wi/is usually ma/e hea7y use
of hy#erlin/s6 and you $ather information by Fum#in$ from one #a$e to another as you
find lin/ed to#ics that interest you9
3he front #a$e for the 4ython Wi/i contains a list of startin$ #oints for Fum#in$ in9 3his
includes a :ode #a$e that lists bits of useful code that are too small to count as modules9
Mne of the items on the :ode #a$e e8tracts a useful bit of information about strin$
formattin$ thatCs buried in the official documentation for seGuence ty#es)
htt#)LL00090i/i9#ython9or$LmoinLStrin$Formattin$L
3i# 3he 4ython Wi/i is a 0or/ in #ro$ress and doesnCt include all the information
a7ailable on other #a$es of the htt#)LL0009#ython9or$ Web site9 'ut it does contain
some information that isnCt a7ailable on other #arts of the site9 &t can be a $ood #lace
to e8#lore if you li/e to learn by in$estin$ small chun/s of information9 As you
become more comfortable 0ith 4ython6 you mi$ht 0ant to contribute your o0n
#a$es9
3he 4ython :oo/boo/6 #art of the Acti7eState 4ro$rammer (et0or/ Web site6 collects a
7ariety of reci#es6 or short bits of code or #ro$rams that #erform #articular tas/s and can
be freely used in your o0n #ro$rams9 3he home #a$e is here)
htt#)LL0009as#n9acti7estate9comLAS4(L:oo/boo/L4ythonL
@ditors re7ie0 submissions to the :oo/boo/6 and you ha7e the o#tion of searchin$ the
editorsC fa7orites6 a##ro7ed6 and not1a##ro7ed reci#es9 3he reci#es are #eriodically
collected into a dead1trees boo/9
@ach reci#e is dis#layed on its o0n #a$e 0ith a descri#tion6 source code6 and discussion9
Members of AS4( can add comments to the #a$e
"!6
The -atest ?ews
3he 4ython ne0s$rou# comp"lang"pyt2on is an e8cellent resource for findin$ out about
4ython and Foinin$ in the community9 'ut if you donCt ha7e time to read 200N #osts e7ery
day6 you can find out 0hatCs $oin$ on in the 4ython community in the follo0in$ 0ays9
1r? 1obbs" Python+)/L
Dr9 DobbsC 4ython1?D. is a 0ee/ly summary of hot to#ics in comp"lang" pyt2on and
other doin$s9 &tCs #osted 0ee/ly to comp"lang"pyt2on and
comp"lang"pyt2on"anno-nce9
Eou can $et #ast issues from ;oo$le ;rou#s6 an archi7e of ?senet ne0s$rou# #ostin$s9
;o to htt#)LL0009$rou#s9$oo$le9comL$rou#sL and ty#e dr do((s pyt2on7-rl! in the
Search bo89
1aily Python )/L
Daily 4ython ?D. is a blo$ "eb log% from htt#)LL0009#ython0are9com that includes
lin/s to ne0s about 4ython6 additions to the :heese Sho# module library6 and more9 Dead
it here)
htt#)LL0009#ython0are9comLdailyL
cop?lang?python?announce
3he comp"lang"pyt2on"anno-nce ne0s$rou# is a moderated forum for 4ython1related
announcements9 A7ailability of ne0 modules and #ro$rams and reGuests for comments on
4ython @nhancement 4ro#osals 4@4s% are #osted here9 3his ne0s$rou# recei7es only a
fe0 messa$es a day6 so itCs easier to /ee# u# 0ith than comp"lang"pyt2on9
Bein" a &+1nosed I+"ie, -ocal &ser +roups
4ython user $rou#s $ather in 0hat com#uter nerds call Imeats#aceI in cities throu$hout
the 0orld9 Such $rou#s 0elcome be$inners and #ro7ide demonstrations6 lectures6 and
time for Guestions and socializin$9 Sometimes you $et free food6 too5% 3he $rou#s often
ha7e the acronym P/= I4ython &nterest ;rou#I% or P)= I4ython ?ser ;rou#I% in their
names9
A list of local user $rou#s can be found on the 4ython Wi/i here)
htt#)LL00090i/i9#ython9or$LmoinL.ocal?ser;rou#sL
"!+
3he 4ython Wi/i mi$ht not be u#1to1date6 so if you donCt see a $rou# in your area6 be sure
to search the Web andLor #ost to comp"lang"pyt2on to see if others /no0 of a $rou#
there9
Many local user $rou#s maintain mailin$ lists in 0hich you can read announcements
about local meetin$s and #artici#ate in discussions about 4ython9 Some of the $rou#s
ha7e archi7es of #ast messa$es that are a7ailable to non1subscribers so you can chec/ out
0hether the $rou# meets your needs9
"!,
art 3I, Appendixes
#hapter -ist
A##endi8 A) ;ettin$ and &nstallin$ 4ython
A##endi8 ') 4ython Bersion Differences
3he A
th
Wa7e 'y Dich 3ennant
In this part
&f you 0erenCt luc/y enou$h to ha7e 4ython already installed on your com#uter6
A##endi8 A sho0s you ho0 to do0nload and set u# 4ython for your o#eratin$ system9
A##endi8 ' describes the ne0 features in each ne0 7ersion of 4ython startin$ 0ith
4ython 2909
Appendix A, +ettin" and Installin"
ython
"!*
3his A##endi8 contains instructions for installin$ 4ython and its modules6 the 4ython
de7elo#ment en7ironment &D.@%6 and 4ython documentation on the three maFor
o#eratin$ systems) Windo0s6 Mac MS6 and ?(&O9 3his cha#ter also #ro7ides ti#s for
usin$ 4ython 0hen it is embedded in your a##lication9
3i# All 7ersions of 4ython are a7ailable for do0nload here)
htt#)LL0009#ython9or$Ldo0nload
(peratin" !ystems
3o install 4ython on your Windo0s6 Mac MS6 or ?(&O com#uter6 follo0 the instructions
in the a##ro#riate subsection belo09
*indo&s
Eou can find out 0hether 4ython is already installed on your Windo0s system9 &f you
ha7enCt already installed 4ython6 or if you ha7e an older 7ersion of it6 0e sho0 you ho0
to install the latest 7ersion9
#heckin" for ython
3here are three 0ays to find out 0hether 4ython is installed on your Windo0s system)
.oo/ for 4ython in the Start menu9
?se the Search command to search for pyt2on"exe9
3y#e pyt2on in the :ommand 4rom#t 0indo09
&sin" 2mbedded ython
&f you ha7e an a##lication that uses 4ython as its scri#tin$ lan$ua$e6 youCre in luc/5
4ython ma/es it easy to customize your a##lication9
EouCll be able to use the full #o0er of the 4ython lan$ua$e as described in this boo/6 but
there are some issues to be a0are of)
The embedded ython mi"ht not include all the standard ython modules.
Eou 0onCt be able to use the modules that arenCt included in scri#ts for your
a##lication9
%ou won't be able to up"rade the embedded version of ython. EouCll ha7e to
0ait for an u#$rade to the a##lication itself9
Warnin$ Eou can still install a ne0er 7ersion of 4ython else0here on your
system9 'ut be sure not to o7er0rite the 7ersion that the a##lication
uses9
"A0
%ou may want to test your scripts outside the application. De#endin$ on ho0
the a##lication is set u#6 a mista/e in your scri#t could cause the a##lication to
crash or han$9
&sin" 2mbedded ython
&f you ha7e an a##lication that uses 4ython as its scri#tin$ lan$ua$e6 youCre in luc/5
4ython ma/es it easy to customize your a##lication9
EouCll be able to use the full #o0er of the 4ython lan$ua$e as described in this boo/6 but
there are some issues to be a0are of)
The embedded ython mi"ht not include all the standard ython modules.
Eou 0onCt be able to use the modules that arenCt included in scri#ts for your
a##lication9
%ou won't be able to up"rade the embedded version of ython. EouCll ha7e to
0ait for an u#$rade to the a##lication itself9
Warnin$ Eou can still install a ne0er 7ersion of 4ython else0here on your
system9 'ut be sure not to o7er0rite the 7ersion that the a##lication
uses9
%ou may want to test your scripts outside the application. De#endin$ on ho0
the a##lication is set u#6 a mista/e in your scri#t could cause the a##lication to
crash or han$9
"A-