Working with Excel files in Python

Chris Withers with help from John Machin

EuroPython 2009, irmingham

!he !utorial Materials

These can be obtained by CD, USB drive or downloaded from here: http://www.simplistix.co. !/presentations/e ropython"##$excel.%ip

!he We"site
The best place to start when wor!in& with 'xcel files in (ython is the website: http://www.python)excel.or&

* Simplistix +td "##$

(a&e "

#icense
THE WORK (AS DEFINED BELOW) IS PROVIDED UNDER THE TERMS OF THIS CREATIVE COMMONS PUBLIC LICENCE ("CCPL" OR "LICENCE"). THE WORK IS PROTECTED BY COPYRIGHT AND/OR OTHER APPLICABLE LAW. ANY USE OF THE WORK OTHER THAN AS AUTHORIZED UNDER THIS LICENCE OR COPYRIGHT LAW IS PROHIBITED. BY EXERCISING ANY RIGHTS TO THE WORK PROVIDED HERE, YOU ACCEPT AND AGREE TO BE BOUND BY THE TERMS OF THIS LICENCE. THE LICENSOR GRANTS YOU THE RIGHTS CONTAINED HERE IN CONSIDERATION OF YOUR ACCEPTANCE OF SUCH TERMS AND CONDITIONS. T !" C#$%&!'$ C())(*" E*+,%*- %*- W%,$" P./,!0 L!0$*0$ $*%/,$" Y(. (%,, 0%1!&%,!"$- &$#)" -$2!*$- /$,(3) &( '!$3, $-!&, )(-!24, &#%*",%&$ %*- -!"&#!/.&$ W(#5" 3(#,-3!-$ 2(# N(*6C())$#0!%, 1.#1("$" .*-$# & $ &$#)" (2 & !" L!0$*0$, 1#('!-$- & %& Y(. 0#$-!& & $ O#!+!*%, A.& (#. 7T $ L!0$*"(#7 8(*$ (# )(#$ ,$+%,,4 #$0(+*!"$- 1$#"(*" (# $*&!&!$" (22$#!*+ & $ W(#5 .*-$# & $ &$#)" %*- 0(*-!&!(*" (2 & !" L!0$*0$9 %*7Y(.7 %+#$$ %" 2(,,(3": ;. D$2!*!&!(*" a) b) "A&&#!/.&!(*" )$%*" %05*(3,$-+!*+ %,, & $ 1%#&!$" 3 ( %'$ 0(*&#!/.&$- &( %*- %'$ #!+ &" !* & $ W(#5 (# C(,,$0&!'$ W(#5 .*-$# & !" L!0$*0$. "C(,,$0&!'$ W(#5" )$%*" & $ W(#5 !* !&" $*&!#$&4 !* .*)(-!2!$- 2(#) %,(*+ 3!& % *.)/$# (2 (& $# "$1%#%&$ %*- !*-$1$*-$*& 3(#5", %""$)/,$!*&( % 0(,,$0&!'$ 3 (,$. c) "D$#!'%&!'$ W(#5" )$%*" %*4 3(#5 0#$%&$- /4 & $ $-!&!*+, )(-!2!0%&!(*, %-%1&%&!(* (# &#%*",%&!(* (2 & $ W(#5 !* %*4 )$-!% ( (3$'$# % 3(#5 & %& 0(*"&!&.&$" % C(,,$0&!'$ W(#5 3!,, *(& /$ 0(*"!-$#$- % D$#!'%&!'$ W(#5 2(# & $ 1.#1("$ (2 & !" L!0$*0$). F(# & $ %'(!-%*0$ (2 -(./&, 3 $#$ & $ W(#5 !" % )."!0%, 0()1("!&!(* (# "(.*- #$0(#-!*+, & $ "4*0 #(*!<%&!(* (2 & $ W(#5 !* &!)$-6#$,%&!(* 3!& % )('!*+ !)%+$ (""4*0 !*+") 3!,, /$ 0(*"!-$#$- % D$#!'%&!'$ W(#5 2(# & $ 1.#1("$ (2 & !" L!0$*0$. d) e) "L!0$*0$" )$%*" & !" C#$%&!'$ C())(*" E*+,%*- %*- W%,$" P./,!0 L!0$*0$ %+#$$)$*&. "N(*6C())$#0!%," )$%*" "*(& 1#!)%#!,4 !*&$*-$- 2(# (# -!#$0&$- &(3%#-" 0())$#0!%, %-'%*&%+$ (# 1#!'%&$ )(*$&%#4 0()1$*"%&!(*". T $ $=0 %*+$ (2 & $ W(#5 2(# (& $# 0(14#!+ &$- 3(#5" /4 )$%*" (2 -!+!&%, 2!,$6" %#!*+ (# (& $#3!"$ " %,, *(& /$ 0(*"!-$#$- &( /$ !*&$*-$- 2(# (# -!#$0&$- &(3%#-" 0())$#0!%, %-'%*&%+$ (# 1#!'%&$ )(*$&%#4 0()1$*"%&!(*, 1#('!-$- & $#$ !" *( 1%4)$*& (2 %*4 )(*$&%#4 0()1$*"%&!(* !* 0(**$0&!(* 3!& & $ $=0 %*+$ (2 0(14#!+ &$- 3(#5". f) g) h) "O#!+!*%, A.& (#" )$%*" & $ !*-!'!-.%, ((# $*&!&4) 3 ( 0#$%&$- & $ W(#5. "W(#5" )$%*" & $ 3(#5 1#(&$0&$- /4 0(14#!+ & 3 !0 !" (22$#$- .*-$# & $ &$#)" (2 & !" L!0$*0$. F(# & $ 1.#1("$ (2 & !" L!0$*0$, 3 $* *(& !*0(*"!"&$*& 3!& & $ 0(*&$=&, 3(#-" !* & $ "!*+.,%# *.)/$# !*0,.-$ & $ 1,.#%, *.)/$#.

>. L!0$*0$ T$#)" >.; T $ L!0$*"(# $#$/4 +#%*&" &( Y(. % 3(#,-3!-$, #(4%,&462#$$, *(*6$=0,."!'$, L!0$*0$ 2(# N(*6C())$#0!%, ."$ %*- 2(# & $ -.#%&!(* (2 0(14#!+ & !* & $ W(#5. Y(. )%4: 0(14 & $ W(#5? !*0(#1(#%&$ & $ W(#5 !*&( (*$ (# )(#$ C(,,$0&!'$ W(#5"? 0(14 & $ W(#5 %" !*0(#1(#%&$- !* %*4 C(,,$0&!'$ W(#5? %*1./,!" , -!"&#!/.&$, %#0 !'$, 1$#2(#) (# (& $#3!"$ -!""$)!*%&$ & $ W(#5 (# & $ W(#5 %" !*0(#1(#%&$- !* %*4 C(,,$0&!'$ W(#5, &( & $ 1./,!0 !* %*4 )%&$#!%, 2(#) !* %*4 )$-!% 3 $& $# *(3 5*(3* (# $#$%2&$# 0#$%&$-. HOWEVER, Y(. )."& *(&: !)1("$ %*4 &$#)" (* & $ ."$ &( /$ )%-$ (2 & $ W(#5, & $ W(#5 %" !*0(#1(#%&$- !* % C(,,$0&!'$ W(#5 & %& %,&$# (# #$"&#!0& & $ &$#)" (2 & !" L!0$*0$ (# %*4 #!+ &" +#%*&$- .*-$# !& (# %" & $ $22$0& (# !*&$*& (2 #$"&#!0&!*+ & $ %/!,!&4 &( $=$#0!"$ & ("$ #!+ &"? !)1("$ %*4 -!+!&%, #!+ &" )%*%+$)$*& &$0 *(,(+4 (* & $ W(#5, & $ W(#5 %" !*0(#1(#%&$- !* % C(,,$0&!'$ W(#5 & %& %,&$#" (# #$"&#!0&" & $ &$#)" (2 & !" L!0$*0$ (# %*4 #!+ &" +#%*&$- .*-$# !& (# %" & $ $22$0& (# !*&$*& (2 #$"&#!0&!*+ & $ %/!,!&4 &( $=$#0!"$ & ("$ #!+ &"? FINALLY, Y(. )."&: )%5$ #$2$#$*0$ &( & !" L!0$*0$ (/4 U*!2(#) R$"(.#0$ I-$*&!2!$# (URI), "1(5$* 3(#- (# %" %11#(1#!%&$ &( & $ )$-!% ."$-) (* %,, 0(1!$" (2 & $ W(#5 %*- C(,,$0&!'$ W(#5" 1./,!" $-, -!"&#!/.&$-, 1$#2(#)$- (# (& $#3!"$ -!""$)!*%&$- (# )%-$ %'%!,%/,$ &( & $ 1./,!0 /4 Y(.? #$0(+*!"$ & $ L!0$*"(#7" / O#!+!*%, A.& (#7" #!+ & (2 %&&#!/.&!(* !* %*4 W(#5 %*- C(,,$0&!'$ W(#5 & %& Y(. 1./,!" , -!"&#!/.&$, 1$#2(#) (# (& $#3!"$ -!""$)!*%&$ &( & $ 1./,!0 %*- $*".#$ & %& Y(. 0#$-!& & $ L!0$*"(# / O#!+!*%, A.& (# %" %11#(1#!%&$ &( & $ )$-!% ."$-? %* &( & $ $=&$*& #$%"(*%/,4 1#%0&!0%/,$, 5$$1 !*&%0& %,, *(&!0$" & %& #$2$# &( & !" L!0$*0$, !* 1%#&!0.,%# & $ URI, !2 %*4, & %& & $ L!0$*"(# "1$0!2!$" &( /$ %""(0!%&$- 3!& & $ W(#5, .*,$"" ".0 URI -($" *(& #$2$# &( & $ 0(14#!+ & *(&!0$ (# ,!0$*"!*+ !*2(#)%&!(* 2(# & $ W(#5. A--!&!(*%, P#('!"!(*" 2(# & !#- 1%#&!$" )%5!*+ ."$ (2 & $ W(#5 >.>. F.#& $# ,!0$*0$ 2#() & $ L!0$*"(# E%0 &!)$ Y(. 1./,!" , -!"&#!/.&$, 1$#2(#) (# (& $#3!"$ -!""$)!*%&$ & $ W(#5? (# & $ W(#5 %" !*0(#1(#%&$- !* % C(,,$0&!'$ W(#5 )%5$ %*4 D$#!'%&!'$ W(#5"? "./,!0$*"$ & $ W(#5? "./@$0& & $ W(#5 &( %*4 -$#(+%&(#4 &#$%&)$*& %" -$2!*$- !* & $ C(14#!+ &, D$"!+*" %*- P%&$*&" A0& ;ABB.

& $ L!0$*"(# %+#$$" &( (22$# &( & $ #$,$'%*& & !#- 1%#&4 )%5!*+ ."$ (2 & $ W(#5 (!* %*4 (2 & $ %,&$#*%&!'$" "$& (.& %/('$) % ,!0$*0$ &( ."$ & $ W(#5 (* & $ "%)$ &$#)" %*- 0(*-!&!(*" %" +#%*&$- &( Y(. $#$.*-$#. >.C. T !" L!0$*0$ -($" *(& %22$0& %*4 #!+ &" & %& & $ U"$# )%4 %'$ .*-$# %*4 %11,!0%/,$ ,%3, !*0,.-!*+ 2%!# ."$, 2%!# -$%,!*+ (# %*4 (& $# ,$+%,,4 #$0(+*!"$,!)!&%&!(* (# $=0$1&!(* &( 0(14#!+ & !*2#!*+$)$*&.

Simplistix Ltd 2009

(a&e ,
>.D. A,, #!+ &" *(& $=1#$"",4 +#%*&$- /4 & $ L!0$*"(# %#$ $#$/4 #$"$#'$-, !*0,.-!*+ /.& *(& ,!)!&$- &(, & $ $=0,."!'$ #!+ & &( 0(,,$0&, 3 $& $# !*-!'!-.%,,4 (# '!% % ,!0$*"!*+ /(-4, ".0 %" % 0(,,$0&!*+ "(0!$&4, #(4%,&!$" 2(# %*4 ."$ (2 & $ W(#5 2(# %*4 #$%"(* 3 !0 #$".,&" !* 0())$#0!%, %-'%*&%+$ (# 1#!'%&$ )(*$&%#4 0()1$*"%&!(*. C. W%##%*&!$" %*- D!"0,%!)$# E=0$1& %" #$E.!#$- /4 ,%3, & $ W(#5 !" ,!0$*"$- /4 & $ L!0$*"(# (* %* "%" !"" %*- "%" %'%!,%/,$" /%"!" %*- 3!& (.& %*4 3%##%*&4 (2 %*4 5!*-, $!& $# $=1#$"" (# !)1,!$-. D. L!)!& (2 L!%/!,!&4 S./@$0& &( %*4 ,!%/!,!&4 3 !0 )%4 *(& /$ $=0,.-$- (# ,!)!&$- /4 ,%3 & $ L!0$*"(# " %,, *(& /$ ,!%/,$ %*- $#$/4 $=1#$"",4 $=0,.-$" %,, ,!%/!,!&4 2(# ,("" (# -%)%+$ (3"($'$# %*- 3 $*$'$# 0%."$- &( Y(.. F. T$#)!*%&!(* T $ #!+ &" +#%*&$- &( Y(. .*-$# & !" L!0$*0$ " %,, &$#)!*%&$ %.&()%&!0%,,4 .1(* %*4 /#$%0 /4 Y(. (2 & $ &$#)" (2 & !" L!0$*0$. I*-!'!-.%," (# $*&!&!$" 3 ( %'$ #$0$!'$- C(,,$0&!'$ W(#5" 2#() Y(. .*-$# & !" L!0$*0$, (3$'$#, 3!,, *(& %'$ & $!# L!0$*0$" &$#)!*%&$- 1#('!-$- ".0 !*-!'!-.%," (# $*&!&!$" #$)%!* !* 2.,, 0()1,!%*0$ 3!& & ("$ L!0$*0$". G. G$*$#%, G.;. T $ '%,!-!&4 (# $*2(#0$%/!,!&4 (2 & $ #$)%!*!*+ &$#)" (2 & !" %+#$$)$*& !" *(& %22$0&$- /4 & $ (,-!*+ (2 %*4 1#('!"!(* (2 !& &( /$ !*'%,!- (# .*$*2(#0$%/,$. G.>. T !" L!0$*0$ 0(*"&!&.&$" & $ $*&!#$ L!0$*0$ A+#$$)$*& /$&3$$* & $ 1%#&!$" 3!& #$"1$0& &( & $ W(#5 ,!0$*"$- $#$. T $#$ %#$ *( .*-$#"&%*-!*+", %+#$$)$*&" (# #$1#$"$*&%&!(*" 3!& #$"1$0& &( & $ W(#5 *(& "1$0!2!$- $#$. T $ L!0$*"(# " %,, *(& /$ /(.*- /4 %*4 %--!&!(*%, 1#('!"!(*" & %& )%4 %11$%# !* %*4 0()).*!0%&!(* !* %*4 2(#). G.C. A 1$#"(* 3 ( !" *(& % 1%#&4 &( & !" L!0$*0$ " %,, %'$ *( #!+ &" .*-$# & $ C(*&#%0&" (R!+ &" (2 T !#- P%#&!$") A0& ;AAA &( $*2(#0$ %*4 (2 !&" &$#)". G.D. T !" L!0$*0$ " %,, /$ +('$#*$- /4 & $ ,%3 (2 E*+,%*- %*- W%,$" %*- & $ 1%#&!$" !##$'(0%/,4 "./)!& &( & $ $=0,."!'$ @.#!"-!0&!(* (2 & $ C(.#&" (2 E*+,%*%*- W%,$". H. O* & $ #(,$ (2 C#$%&!'$ C())(*" H.;. N$!& $# & $ L!0$*"(# *(# & $ U"$# )%4 ."$ & $ C#$%&!'$ C())(*" ,(+( $=0$1& &( !*-!0%&$ & %& & $ W(#5 !" ,!0$*"$- .*-$# % C#$%&!'$ C())(*" L!0$*0$. A*4 1$#)!&&$- ."$ %" &( /$ !* 0()1,!%*0$ 3!& & $ C#$%&!'$ C())(*" &#%-$ )%#5 ."%+$ +.!-$,!*$" %& & $ &!)$ (2 ."$ (2 & $ C#$%&!'$ C())(*" &#%-$ )%#5. T $"$ +.!-$,!*$" )%4 /$ 2(.*- (* & $ C#$%&!'$ C())(*" 3$/"!&$ (# /$ (& $#3!"$ %'%!,%/,$ .1(* #$E.$"& 2#() &!)$ &( &!)$. H.>. C#$%&!'$ C())(*" C(#1(#%&!(* -($" *(& 1#(2!& 2!*%*0!%,,4 2#() !&" #(,$ !* 1#('!-!*+ & !" L!0$*0$ %*- 3!,, *(& !*'$"&!+%&$ & $ 0,%!)" (2 %*4 L!0$*"(# (# ."$# (2 & $ L!0$*0$. H.C. O*$ (2 & $ 0(*-!&!(*" & %& C#$%&!'$ C())(*" C(#1(#%&!(* #$E.!#$" (2 & $ L!0$*"(# %*- Y(. !" %* %05*(3,$-+$)$*& (2 !&" ,!)!&$- #(,$ %*- %+#$$)$*& /4 %,, 3 ( ."$ & $ L!0$*0$ & %& & $ C(#1(#%&!(* !" *(& #$"1(*"!/,$ &( %*4(*$ 2(# & $ "&%&$)$*&" %*- %0&!(*" (2 Y(. (# & $ L!0$*"(# (# %*4(*$ $,"$ %&&$)1&!*+ &( ."$ (# ."!*+ & !" L!0$*0$. H.D. C#$%&!'$ C())(*" C(#1(#%&!(* !" *(& % 1%#&4 &( & !" L!0$*0$, %*- )%5$" *( 3%##%*&4 3 %&"($'$# !* 0(**$0&!(* &( & $ W(#5 (# !* 0(**$0&!(* &( & $ L!0$*0$, %*- !* %,, $'$*&" !" *(& ,!%/,$ 2(# %*4 ,("" (# -%)%+$ #$".,&!*+ 2#() & $ L!0$*"(#7" (# Y(.# #$,!%*0$ (* & !" L!0$*0$ (# (* !&" $*2(#0$%/!,!&4. H.F. USE OF THIS LICENCE MEANS THAT YOU AND THE LICENSOR EACH ACCEPTS THESE CONDITIONS IN SECTION H.;, H.>, H.C, H.D AND EACH ACKNOWLEDGES CREATIVE COMMONS CORPORATION7S VERY LIMITED ROLE AS A FACILITATOR OF THE LICENCE FROM THE LICENSOR TO YOU.

Simplistix Ltd 2009

(a&e -

$ntro%uction
This t torial covers the followin& libraries: xlr% xlwt http://pypi.python.or&/pypi/xlwt writin& data and formattin& to .xls files this t torial covers version #..." incomplete 0(1 doc mentation can be fo nd at: https://sec re.simplistix.co. !/svn/xlwt/tr n!/xlwt/doc/xlwt.html fairly complete examples can be fo nd at https://sec re.simplistix.co. !/svn/xlwt/tr n!/xlwt/examples/ xlutils http://pypi.python.or&/pypi/xl tils a collection of tilities sin& both xlrd and xlwt: copyin& data from a so rce to a tar&et spreadsheet filterin& data from a so rce to a tar&et spreadsheet this t torial covers version /.,.# and above. doc mentation and examples can be fo nd at: https://sec re.simplistix.co. !/svn/xl tils/tr n!/xl tils/docs/ There are still reasons why a tomatin& an 'xcel instance via C23 is necessary: manip lation of &raphs rich text cells readin& form lae in cells wor!in& with macros and names the more esoteric thin&s fo nd in .xls files http://pypi.python.or&/pypi/xlrd readin& data and formattin& from .xls files this t torial covers version #.../ 0(1 doc mentation can be fo nd at: https://sec re.simplistix.co. !/svn/xlrd/tr n!/xlrd/doc/xlrd.html

Simplistix Ltd 2009

(a&e 4

$nstallation
There are several methods of installation available. 5hile the followin& examples are for xlrd, the exact same steps can be sed for any of the three libraries.

$nstall from &ource

2n +in x: $ tar xzf xlrd.tgz $ cd xlrd-0.7.1 $ python setup.py install NB: 3a!e s re yo se the python yo intend to se for yo r pro6ect.

2n 5indows, havin& sed 5in7ip or similar to npac! xlrd)#.../.%ip: C:\> cd xlrd-0.7.1 C:\xlrd-0.7.1> \Python !\python setup.py install NB: 3a!e s re yo se the python yo intend to se for yo r pro6ect.

$nstall using Win%ows $nstaller

2n 5indows, yo can download and r n the xlrd)#.../.win,".exe installer. Beware that this will only install to (ython installations that are in the 5indows re&istry.

$nstall using Easy$nstall

This cross)platform method re8 ires that yo already have 'asy1nstall installed. 9or more information on this, please see: http://pea!.telecomm nity.com/DevCenter/'asy1nstall

easy"install xlrd

Simplistix Ltd 2009

(a&e :

$nstallation using

uil%out

B ildo t provides a cross)platform method of meetin& the python pac!a&e dependencies of a pro6ect witho t interferin& with the system (ython. ;avin& created a directory called #y$uildout, download the followin& file into it: http://svn.%ope.or&/<chec!o t</%c.b ildo t/tr n!/bootstrap/bootstrap.py =ow, create a file in #y$uildout called $uildout.cfg containin& the followin&: %$uildout& parts ' py (ersions ' (ersions %(ersions& xlrd'0.7.1 xl)t'0.7. xlutils'1.*. %py& recipe ' zc.recipe.egg eggs ' xlrd xl)t xlutils interpreter ' py buildout.cfg =B: The versions section is optional 9inally, r n the followin&: $ python $ootstrap.py $ $in+$uildout These lines: initialise the b ildo t environment r n the b ildo t. This sho ld be done each time dependencies chan&e.

=ow yo can do the followin&: $ $in+py your"xlrd"xl)t"xltuils"script.py B ildo t lives at http://pypi.python.or&/pypi/%c.b ildo t

Simplistix Ltd 2009

(a&e .

'ea%ing Excel (iles

0ll the examples shown below can be fo nd in the xlrd directory of the co rse material.

)pening Work"ooks
5or!boo!s can be loaded either from a file, an ##ap.##ap ob6ect or from a strin&: fro# ##ap i#port ##ap,-CC.//"0.-1 fro# xlrd i#port open")or2$oo2 print open")or2$oo234si#ple.xls45 )ith open34si#ple.xls4,4r$45 as f: print open")or2$oo23 file"contents'##ap3f.fileno35,0,access'-CC.//"0.-15 5 a/tring ' open34si#ple.xls4,4r$45.read35 print open")or2$oo23file"contents'a/tring5 open.py

*a+igating a Work"ook
;ere is a simple example of wor!boo! navi&ation: fro# xlrd i#port open")or2$oo2 )$ ' open")or2$oo234si#ple.xls45 for s in )$.sheets35: print 4/heet:4,s.na#e for ro) in range3s.nro)s5: (alues ' %& for col in range3s.ncols5: (alues.append3s.cell3ro),col5.(alue5 print 4,4.6oin3(alues5 print simple.py The next few sections will cover the navi&ation of wor!boo!s in more detail.

Simplistix Ltd 2009

(a&e >

$ntrospecting a

ook

The xlrd.7oo2 ob6ect ret rned by open")or2$oo2 contains all information to do with the wor!boo! and can be sed to retrieve individ al sheets within the wor!boo!. The nsheets attrib te is an inte&er containin& the n mber of sheets in the wor!boo!. This attrib te, in combination with the sheet"$y"index method, is the most common way of retrievin& individ al sheets. The sheet"na#es method ret rns a list of nicodes containin& the names of all sheets in the wor!boo!. 1ndivid al sheets can be retrieved sin& these names by way of the sheet"$y"na#e f nction. The res lts of the sheets method can be iterated over to retrieve each of the sheets in the wor!boo!. The followin& example demonstrates these methods and attrib tes: fro# xlrd i#port open")or2$oo2 $oo2 ' open")or2$oo234si#ple.xls45 print $oo2.nsheets for sheet"index in range3$oo2.nsheets5: print $oo2.sheet"$y"index3sheet"index5 print $oo2.sheet"na#es35 for sheet"na#e in $oo2.sheet"na#es35: print $oo2.sheet"$y"na#e3sheet"na#e5 for sheet in $oo2.sheets35: print sheet introspect_book.py xlrd.7oo2 ob6ects have other attrib tes relatin& to the content of the wor!boo! that are only rarely sef l: codepage countries user"na#e

1f yo thin! yo may need to se these attrib tes, please see the xlrd doc mentation.

Simplistix Ltd 2009

(a&e $

$ntrospecting a &heet The xlrd.sheet./heet ob6ects ret rned by any of the methods described above contain all the information to do with a wor!sheet and its contents. The na#e attrib te is a nicode representin& the name of the wor!sheet. The nro)s and ncols attrib tes contain the n mber of rows and the n mber of col mns, respectively, in the wor!sheet. The followin& example shows how these can be sed to iterate over and display the contents of one wor!sheet: fro# xlrd i#port open")or2$oo2,cellna#e $oo2 ' open")or2$oo234odd.xls45 sheet ' $oo2.sheet"$y"index305 print sheet.na#e print sheet.nro)s print sheet.ncols for ro)"index in range3sheet.nro)s5: for col"index in range3sheet.ncols5: print cellna#e3ro)"index,col"index5,4-4, print sheet.cell3ro)"index,col"index5.(alue introspect_sheet.py xlrd.sheet./heet ob6ects have other attrib tes relatin& to the content of the wor!sheet that are only rarely sef l: col?label?ran&es row?label?ran&es visibility

1f yo thin! yo may need to se these attrib tes, please see the xlrd doc mentation.

Simplistix Ltd 2009

(a&e /#

,etting a particular Cell 0s already seen in previo s examples, the cell method of a /heet ob6ect can be sed to ret rn the contents of a partic lar cell. The cell method ret rns an xlrd.sheet.Cell ob6ect. These ob6ects have very few attrib tes, of which (alue contains the act al val e of the cell and ctype contains the type of the cell. 1n addition, /heet ob6ects have two methods for ret rnin& these two types of data. The cell"(alue method ret rns the val e for a partic lar cell, while the cell"type method ret rns the type of a partic lar cell. These methods can be 8 ic!er to exec te than retrievin& the Cell ob6ect. Cell types are covered in more detail later. The followin& example shows the methods, attrib tes and classes in action: fro# xlrd i#port open")or2$oo2,89"C.99":.8: $oo2 ' open")or2$oo234odd.xls45 sheet ' $oo2.sheet"$y"index315 cell ' sheet.cell30,05 print cell print cell.(alue print cell.ctype''89"C.99":.8: for i in range3sheet.ncols5: print sheet.cell"type31,i5,sheet.cell"(alue31,i5 cell_access.py

Simplistix Ltd 2009

(a&e //

$terating o+er the contents of a &heet 5e@ve already seen how to iterate over the contents of a wor!sheet and retrieve the res ltin& individ al cells. ;owever, there are methods to retrieve &ro ps of cells more easily. There are a symmetrical set of methods that retrieve &ro ps of cell information either by row or by col mn. The ro) and col methods ret rn all the Cell ob6ects for a whole row or col mn, respectively. The ro)"slice and col"slice methods ret rn a list of Cell ob6ects in a row or col mn, respectively, bo nded by and start index and an optional end index. The ro)"types and col"types methods ret rn a list of inte&ers representin& the cell types in a row or col mn, respectively, bo nded by and start index and an optional end index. The ro)"(alues and col"(alues methods ret rn a list of ob6ects representin& the cell val es in a row or col mn, respectively, bo nded by a start index and an optional end index. The followin& examples demonstrates all of the sheet iteration methods: fro# xlrd i#port open")or2$oo2 $oo2 ' open")or2$oo234odd.xls45 sheet0 ' $oo2.sheet"$y"index305 sheet1 ' $oo2.sheet"$y"index315 print print print print print print print print print print print print print print print print sheet0.ro)305 sheet0.col305 sheet0.ro)"slice30,15 sheet0.ro)"slice30,1, 5 sheet0.ro)"(alues30,15 sheet0.ro)"(alues30,1, 5 sheet0.ro)"types30,15 sheet0.ro)"types30,1, 5 sheet1.col"slice30,15 sheet0.col"slice30,1, 5 sheet1.col"(alues30,15 sheet0.col"(alues30,1, 5 sheet1.col"types30,15 sheet0.col"types30,1, 5

sheet_iteration.py

Simplistix Ltd 2009

(a&e /"

-tility (unctions 5hen navi&atin& aro nd a wor!boo!, it@s often sef l to be able to convert between row and col mn indexes and the 'xcel cell references that sers may be sed to seein&. The followin& f nctions are provided to help with this: The cellna#e f nction t rns a row and col mn index into a relative 'xcel cell reference. The cellna#ea$s f nction t rns a row and col mn index into an absol te 'xcel cell reference. The colna#e f nction t rns a col mn index into an 'xcel col mn name. These three f nctions are demonstrated in the followin& example: fro# xlrd i#port cellna#e, cellna#ea$s, colna#e print cellna#e30,05,cellna#e310,105,cellna#e3100,1005 print cellna#ea$s3*,15,cellna#ea$s3;1,<=5,cellna#ea$s3 !<,*<>5 print colna#e305,colna#e3105,colna#e31005 utility.py

-nico%e
0ll text attrib tes and val es prod ced by xlrd will be either nicode ob6ects or, in rare cases, ascii strin&s. 'ach piece of text in an 'xcel file written by 3icrosoft 'xcel is encoded into one of the followin&: +atin/, if it fits UT9?/:?+', if it doesn@t fit into +atin/ 1n older files, by an encodin& specified by an 3S codepa&e. These are mapped to (ython encodin&s by xlrd and still res lt in nicode ob6ects.

1n rare cases, other software has been !nown to write no codepa&e or the wron& codepa&e into 'xcel files. 1n this case, the correct encodin& may need to be specified to open")or2$oo2: fro# xlrd i#port open")or2$oo2 $oo2 ' open")or2$oo234dodgy.xls4,encoding'4cp1 < 45

!ypes of Cell
5e have already seen the cell type expressed as an inte&er. This inte&er corresponds to a set of constants in xlrd that identify the type of the cell. The f ll set of possible cell types is listed in the followin& sections.

Simplistix Ltd 2009

(a&e /,

!ext These are represented by the xlrd.89"C.99":.8: constant. Cells of this type will have val es that are unicode ob6ects. *um"er These are represented by the xlrd.89"C.99"?@A7.0 constant. Cells of this type will have val es that are float ob6ects. .ate These are represented by the xlrd.89"C.99"1-:. constant. NB: Dates don@t really exist in 'xcel files, they are merely = mbers with a partic lar n mber formattin&. xlrd will ret rn xlrd.89"C.99"1-:. as the cell type if the n mber format strin& loo!s li!e a date. The xldate"as"tuple method is provided for t rnin& the float in a Date cell into a t ple s itable for instantiatin& vario s date/time ob6ects. This example shows how to se it: fro# dateti#e i#port date,dateti#e,ti#e fro# xlrd i#port open")or2$oo2,xldate"as"tuple $oo2 ' open")or2$oo234types.xls45 sheet ' $oo2.sheet"$y"index305 date"(alue ' xldate"as"tuple3sheet.cell3*, 5.(alue,$oo2.date#ode5 print dateti#e3Bdate"(alue5,date3Bdate"(alue%:*&5 dateti#e"(alue ' xldate"as"tuple3sheet.cell3*,*5.(alue,$oo2.date#ode5 print dateti#e3Bdateti#e"(alue5 ti#e"(alue ' xldate"as"tuple3sheet.cell3*,;5.(alue,$oo2.date#ode5 print ti#e3Bti#e"(alue%*:&5 print dateti#e3Bti#e"(alue5 dates.py Caveats: 'xcel files have two possible date modes, one for files ori&inally created on 5indows and one for files ori&inally created on an 0pple machine. This is expressed as the date#ode attrib te of xlrd.7oo2 ob6ects and must be passed to xldate?as?t ple. The 'xcel file format has vario s problems with dates before , Aan /$#- that can ca se date ambi& ities that can res lt in xldate"as"tuple raisin& an B+Date'rror. The 'xcel form la f nction 1-:.35can ret rn nexpected dates in certain circ mstances.
Simplistix Ltd 2009

(a&e /-

oolean These are represented by the xlrd.89"C.99"7CC9.-? constant. Cells of this type will have val es that are $ool ob6ects. Error These are represented by the xlrd.89"C.99".00C0 constant. Cells of this type will have val es that are inte&ers representin& specific error codes. The error"text"fro#"code dictionary can be sed to t rn error codes into error messa&es: fro# xlrd i#port open")or2$oo2,error"text"fro#"code $oo2 ' open")or2$oo234types.xls45 sheet ' $oo2.sheet"$y"index305 print error"text"fro#"code%sheet.cell3<, 5.(alue& print error"text"fro#"code%sheet.cell3<,*5.(alue& errors.py 9or a simpler way of sensibly displayin& all cell types, see xlutils.display.

Simplistix Ltd 2009

(a&e /4

Empty /

lank

'xcel files only store cells that either have information in them or have formattin& applied to them. ;owever, xlrd presents sheets as rectan& lar &rids of cells. Cells where no information is present in the 'xcel file are represented by the xlrd.89"C.99".AP:D constant. 1n addition, there is only one Cempty cellD, whose val e is an empty strin&, sed by xlrd, so empty cells may be chec!ed sin& a (ython identity chec!. Cells where only formattin& information is present in the 'xcel file are represented by the xlrd.89"C.99"79-?E constant and their val e will always be an empty strin&. fro# xlrd i#port open")or2$oo2,e#pty"cell print e#pty"cell.(alue $oo2 ' open")or2$oo234types.xls45 sheet ' $oo2.sheet"$y"index305 e#pty ' sheet.cell3!, 5 $lan2 ' sheet.cell37, 5 print e#pty is $lan2, e#pty is e#pty"cell, $lan2 is e#pty"cell $oo2 ' open")or2$oo234types.xls4,for#atting"info':rue5 sheet ' $oo2.sheet"$y"index305 e#pty ' sheet.cell3!, 5 $lan2 ' sheet.cell37, 5 print e#pty.ctype,repr3e#pty.(alue5 print $lan2.ctype,repr3$lan2.(alue5 emptyblank.py

Simplistix Ltd 2009

(a&e /:

The followin& example brin&s all of the above cell types to&ether and shows examples of their se: fro# xlrd i#port open")or2$oo2 def cell"contents3sheet,ro)"x5: result ' %& for col"x in range3 ,sheet.ncols5: cell ' sheet.cell3ro)"x,col"x5 result.append33cell.ctype,cell,cell.(alue55 return result sheet ' open")or2$oo234types.xls45.sheet"$y"index305 print print print print print print print 489"C.99":.8:4,cell"contents3sheet,15 489"C.99"?@A7.04,cell"contents3sheet, 5 489"C.99"1-:.4,cell"contents3sheet,*5 489"C.99"7CC9.-?4,cell"contents3sheet,;5 489"C.99".00C04,cell"contents3sheet,<5 489"C.99"79-?E4,cell"contents3sheet,!5 489"C.99".AP:D4,cell"contents3sheet,75

print sheet ' open")or2$oo23 4types.xls4,for#atting"info':rue 5.sheet"$y"index305 print print print print print print print 489"C.99":.8:4,cell"contents3sheet,15 489"C.99"?@A7.04,cell"contents3sheet, 5 489"C.99"1-:.4,cell"contents3sheet,*5 489"C.99"7CC9.-?4,cell"contents3sheet,;5 489"C.99".00C04,cell"contents3sheet,<5 489"C.99"79-?E4,cell"contents3sheet,!5 489"C.99".AP:D4,cell"contents3sheet,75

cell_types.py

*ames
These are an infre8 ently sed b t powerf l way of abstractin& commonly sed information fo nd within 'xcel files. They have many ses, and xlrd can extract information from many of them. 0 notable exception are names that refer to sheet and EB0 macros, which are extracted b t sho ld be i&nored. =ames are created in 'xcel by navi&atin& to Fnsert > ?a#e > 1efine. 1f yo plan to se xlrd to extract information from =ames, familiarity with the definition and se of names in yo r chosen spreadsheet application is a &ood idea.

Simplistix Ltd 2009

(a&e /.

!ypes 0 =ame can refer to: 0 constant CurrentFnterest0ate ' 0.01< ?a#eCfPG7 ' H-ttila :. GunI 0n absol te Fi.e. not relativeG cell reference CurrentFnterest0ate ' /heet1J$7$; 0bsol te reference to a /D, "D, or ,D bloc! of cells Aonthly/ales7y0egion ' /heet :/heet<J$-$ :$A$100 0 list of absol te references Print":itles ' %ro)"header"ref, col"header"ref&5 Constants can be extracted. The coordinates of an absol te reference can be extracted so that yo can then extract the correspondin& data from the relevant sheetFsG. 0 relative reference is sef l only if yo have external !nowled&e of what cells can be sed as the ori&in. 3any form las fo nd in 'xcel files incl de f nction calls and m ltiple references and are not sef l, and can be too hard to eval ate. 0 f ll calc lation en&ine is not incl ded in xlrd. &cope The scope of a =ame can be &lobal, or it may be specific to a partic lar sheet. 0 =ame@s identifier may be re) sed in different scopes. 5hen there are m ltiple =ames with the same identifier, the most appropriate one is sed based on scope. 0 &ood example of this is the b ilt)in name (rint?0reaH each wor!sheet may have one of these. 'xamples: na#e'rate, scope'/heet1, for#ula'0.01< na#e'rate, scope'/heet , for#ula'0.0 * na#e'rate, scope'global, for#ula'0.0;0 0 cell form la 31Krate5L 0 is e8 ivalent to 1.01<L 0 if it appears in /heet1 b t e8 ivalent to 1.0 *L 0 if it appears in /heet , and 1.0;0L 0 if it appears in any other sheet. -sage Common reasons for sin& names incl de: 0ssi&nin& text al names to val es that may occ r in many places within a wor!boo! e&: 0-:. ' 0.01< 0ssi&nin& text al names to complex form lae that may be easily mis)copied e&: /-9./"0./@9:/ ' $-$10:$A$=== ;ere@s an example real)world se case: reportin& to head office. 0 company@s head office ma!es p a template wor!boo!. 'ach department &ets a copy to fill in. The vario s ran&es of data to be provided all have defined names. 5hen the files come bac!, a script is sed to
Simplistix Ltd 2009

(a&e />

validate that the department hasn@t trashed the wor!boo! and the names are sed to extract the data for f rther processin&. Usin& names deco ples any artistic repositionin& of the ran&es, by either head office template)desi&nin& ser or by departmental sers who are fillin& in the template, from the script which only has to !now what the names of the ran&es are. 1n the examples directory of the xlrd distrib tion yo will find na#esde#o.xls which has examples of most of the non)macro varieties of defined names. There is also xlrdna#es-PFde#o.py which shows how to se the name loo! p dictionaries, and how to extract constants and references and the data that references point to.

(ormatting
5e@ve already seen that open")or2$oo2 has a parameter to load formattin& information from 'xcel files. 5hen this is done, all the formattin& information is available, b t the details of how it is presented are beyond the scope of this t torial. 1f yo wish to copy existin& formatted data to a new 'xcel file, see xlutils.copy and xlutils.filter. 1f yo do wish to inspect formattin& information, yo @ll need to cons lt the followin& attrib tes of the followin& classes: xlr%0 ook colour"#ap font"list for#at"list for#at"#ap xlr%0sheet0&heet cell"xf"index ro)info"#ap colinfo"#ap co#puted"colu#n")idth default"additional"space"a$o(e default"additional"space"$elo) default"ro)"height xlr%0sheet0Cell xf"index )ther Classes 1n addition, the followin& classes are solely sed to represent formattin& information: xlrd.sheet.0o)info xlrd.sheet.Colinfo xlrd.for#atting.Mont xlrd.for#atting.Mor#at xlrd.for#atting.8M
Simplistix Ltd 2009

palette"record style"na#e"#ap xf"list

default"ro)"height"#is#atch default"ro)"hidden defcol)idth gc) #erged"cells standard")idth

xlrd.for#atting.8M-lign#ent xlrd.for#atting.8M7ac2ground xlrd.for#atting.8M7order xlrd.for#atting.8MProtection

(a&e /$

Working with large Excel files

1f yo @re wor!in& with partic larly lar&e 'xcel files then there are two feat res of xlrd that yo sho ld be aware of: The on?demand parameter can be passed as Tr e to open?wor!boo! res ltin& in wor!sheets only bein& loaded into memory when they are re8 ested. xlrd.Boo! ob6ects have an nload?sheet method that will nload wor!sheet, specified by either sheet index or sheet name, from memory.

The followin& example shows how a lar&e wor!boo! co ld be iterated over when only sheets matchin& a certain pattern need to be inspected, and where only one of those sheets ends p in memory at any one time: fro# xlrd i#port open")or2$oo2 $oo2 ' open")or2$oo234si#ple.xls4,on"de#and':rue5 for na#e in $oo2.sheet"na#es35: if na#e.ends)ith34 45: sheet ' $oo2.sheet"$y"na#e3na#e5 print sheet.cell"(alue30,05 $oo2.unload"sheet3na#e5 large_files.py

Simplistix Ltd 2009

(a&e "#

$ntrospecting Excel files with runxlr%0py

The xlrd so rce distrib tion incl des a runxlrd.py script that is extremely sef l for introspectin& 'xcel files witho t writin& a sin&le line of (ython. Io are enco ra&ed to r n a variety of the commands it provides over the 'xcel files provided in the co rse materials. The followin& &ives an overview of what@s available from runxlrd, and can be obtained sin& python runxlrd.py N-help:
runxlrd.py %options& co##and %input-file-patterns& Co##ands: ro)s *ro)s $ench $iff"count%1& $iff"du#p%1& fonts hdr hotshot la$els na#e"du#p na#es o( profile sho) (ersion%0& xfc Print the contents of first and last ro) in each sheet Print the contents of first, second and last ro) in each sheet /a#e as Osho)O, $ut doesn4t print -- for profiling Print a count of each type of 7FMM record in the file Print a du#p 3char and hex5 of the 7FMM records in the file hdr K print a du#p of all font o$6ects Aini-o(er(ie) of file 3no per-sheet infor#ation5 1o a hotshot profile run e.g. ... -f1 hotshot $ench $igfileB.xls 1u#p of sheet.col"la$el"ranges and ...ro)... for each sheet 1u#p of each o$6ect in $oo2.na#e"o$6"list Print $rief infor#ation for each ?-A. record C(er(ie) of file 9i2e OhotshotO, $ut uses cProfile Print the contents of all ro)s in each sheet Print (ersions of xlrd and Python and exit Print O8M countsO and cell-type counts -- see code for details

%0& #eans no file arg %1& #eans only one file arg i.e. no glo$.glo$ pattern Cptions: -h, --help sho) this help #essage and exit -l 9CPMF9.?-A., --logfilena#e'9CPMF9.?-A. contains error #essages -( Q.07C/F:D, --(er$osity'Q.07C/F:D le(el of infor#ation and diagnostics pro(ided -p PFCE9.-79., --pic2lea$le'PFCE9.-79. 1: ensure 7oo2 o$6ect is pic2lea$le 3default5R 0: don4t $other -# AA-P, --##ap'AA-P 1: use ##apR 0: don4t use ##apR -1: accept heuristic -e .?CC1F?P, --encoding'.?CC1F?P encoding o(erride -f MC0A-::F?P, --for#atting'MC0A-::F?P 0 3default5: no f#t info 1: f#t info 3all cells5 -g PC, --gc'PC 0: auto gc ena$ledR 1: auto gc disa$led, #anual collect after each fileR : no gc -s C?./G..:, --onesheet'C?./G..: restrict output to this sheet 3na#e or index5 -u, --unnu#$ered o#it line nu#$ers or offsets in $iff"du#p

Simplistix Ltd 2009

(a&e "/

Writing Excel (iles

0ll the examples shown below can be fo nd in the xl)t directory of the co rse material.

Creating elements within a Work"ook

5or!boo!s are created with xl)t by instantiatin& an xl)t.Sor2$oo2 ob6ect, manip latin& it and then callin& its sa(e method. The sa(e method may be passed either a strin& containin& the path to write to or a file) li!e ob6ect, opened for writin& in binary mode, to which the binary 'xcel file data will be written. The followin& ob6ects can be created within a wor!boo!: Worksheets 5or!sheets are created with the add"sheet method of the Sor2$oo2 class. To retrieve an existin& sheet from a Sor2$oo2, se its get"sheet method. This method is partic larly sef l when the Sor2$oo2 has been instantiated by xlutils.copy. 'ows Jows are created sin& the ro) method of the Sor2sheet class and contain all of the cells for a &iven row. The ro) method is also sed to retrieve existin& rows from a Sor2sheet. 1f a lar&e n mber of rows have been written to a Sor2sheet and memory sa&e is becomin& a problem, the flush"ro)"data method may be called on the Sor2sheet. 2nce called, any rows fl shed cannot be accessed or modified. 1t is recommended that flush"ro)"data is called for every /### or so rows of a normal si%e that are written to an xl)t.Sor2$oo2. 1f the rows are h &e, that n mber sho ld be red ced. Columns Col mns are created sin& the col method of the Sor2sheet class and contain display formattin& information for a &iven col mn. The col method is also sed to retrieve existin& col mns from a Sor2sheet. Cells Cells can be written sin& either the )rite method of either the Sor2sheet or 0o) class. 0 more detailed disc ssion of different ways of writin& cells and the different types of cell that may be written is covered later.

Simplistix Ltd 2009

(a&e ""

1 &imple Example The followin& example shows how all of the above methods can be sed to b ild and save a simple wor!boo!:

fro# te#pfile i#port :e#poraryMile fro# xl)t i#port Sor2$oo2 $oo2 ' Sor2$oo235 sheet1 ' $oo2.add"sheet34/heet 145 $oo2.add"sheet34/heet 45 sheet1.)rite30,0,4-145 sheet1.)rite30,1,47145 ro)1 ' sheet1.ro)315 ro)1.)rite30,4- 45 ro)1.)rite31,47 45 sheet1.col305.)idth ' 10000 sheet sheet sheet sheet sheet sheet sheet ' $oo2.get"sheet315 .ro)305.)rite30,4/heet -145 .ro)305.)rite31,4/heet 7145 .flush"ro)"data35 .)rite31,0,4/heet -*45 .col305.)idth ' <000 .col305.hidden ' :rue

$oo2.sa(e34si#ple.xls45 $oo2.sa(e3:e#poraryMile355 simple.py

-nico%e
The best policy is to pass nicode ob6ects to all xl)t)related method calls. 1f yo absol tely have to se encoded strin&s then ma!e s re that the encodin& sed is consistent across all calls to any xl)t)related methods. 1f encoded strin&s are sed and the encodin& is not 4ascii4, then any Sor2$oo2 ob6ects m st be created with the appropriate encodin& specified:

fro# xl)t i#port Sor2$oo2 $oo2 ' Sor2$oo23encoding'4utf->45

Simplistix Ltd 2009

(a&e ",

Writing to Cells
0 n mber of different ways of writin& a cell are provided by xlwt alon& with different strate&ies for handlin& m ltiple writes to the same cell. .ifferent ways of writing cells There are &enerally three ways to write to a partic lar cell: 5or!sheet.writeFrow?index,col mn?index,val eG This is 6 st syntactic s &ar for sheet.rowFrow?indexG.writeFcol mn?index,val eG 1t can be sef l when yo only want to write one cell to a row Jow.writeFcol mn?index,val eG This will write the correct type of cell based on the val e passed Beca se it fi& res o t what type of cell to write, this method may be slower for writin& lar&e wor!boo!s Specialist write methods on the Jow class 'ach type of cell has a specialist setter method as covered in the CTypes of CellD section below. These re8 ire yo to pass the correct type of (ython ob6ect b t can be faster. 1n &eneral, se 5or!sheet.write for convenience and the specialist write methods if yo re8 ire speed for a lar&e vol me of data. )+erwriting Cells The 'xcel file format does nothin& to prevent m ltiple records for a partic lar cell occ rrin& b t, if this happens, the res lts will vary dependin& on what application is sed to open the file. 'xcel will display a HMile error: data #ay ha(e $een lostI while 2pen2ffice.or& will show the last record for the cell that occ rs in the file. To help prevent this, xl)t provides two modes of operation: 5ritin& to the same cell more than once will res lt in an exception This is the defa lt mode. 5ritin& to the same cell more than once will replace the record for that cell, and only one record will be written when the 5or!boo! is saved.

Simplistix Ltd 2009

(a&e "-

The followin& example demonstrates these two options: fro# xl)t i#port Sor2$oo2 $oo2 ' Sor2$oo235 sheet1 ' $oo2.add"sheet34/heet 14,cell"o(er)rite"o2':rue5 sheet1.)rite30,0,4original45 sheet ' $oo2.get"sheet305 sheet.)rite30,0,4ne)45 sheet ' $oo2.add"sheet34/heet sheet .)rite30,0,4original45 sheet .)rite30,0,4ne)45 overwriting.py The most common case for needin& to overwrite cells is when an existin& 'xcel file has been loaded into a 5or!boo! instance sin& xlutils.copy. 45

!ypes of Cell
0ll types of cell s pported by the 'xcel file format can be written: !ext 5hen passed a unicode or strin&, the )rite methods will write a Text cell. The set"cell"text method of the 0o) class can also be sed to write Text cells. 5hen passed a strin&, these methods will first decode the strin& sin& the 5or!boo!@s encodin&. *um"er 5hen passed a float, int, long, or deci#al.1eci#al, the )rite methods will write a = mber cell. The set"cell"nu#$er method of the 0o) class can also be sed to write = mber cells. .ate 5hen passed a dateti#e.dateti#e, dateti#e.date or dateti#e.ti#e, the )rite methods will write a Date cell. The set"cell"date method of the 0o) class can also be sed to write Date cells. =ote: 0s mentioned earlier, a date is not really a separate type in 'xcelH if yo don@t apply a date format, it will be treated as a n mber. oolean 5hen passed a $ool, the )rite methods will write a Boolean cell. The set"cell"$oolean method of the 0o) class can also be sed to write Text cells.

Simplistix Ltd 2009

(a&e "4

Error Io sho ldn@t ever want to write 'rror cellsK ;owever, if yo absol tely m st, the set"cell"error method of the Jow class can be sed to do so. 9or convenience, it can be called with either hexadecimal error codes, expressed as inte&ers, or the error text that 'xcel wo ld display. lank 1t is not normally necessary to write blan! cells. The one exception to this is if yo wish to apply formattin& to a cell that contains nothin&. To do this, either call the )rite methods with an empty strin& or =one, or se the set"cell"$lan2 method of the 0o) class. 1f yo need to do this for more than one cell in a row, sin& the set"cell"#ul$lan2s method will res lt in a smaller 'xcel file when the Sor2$oo2 is saved.

Simplistix Ltd 2009

(a&e ":

The followin& example brin&s all of the above cell types to&ether and shows examples se both the &eneric )rite method and the specialist methods: fro# dateti#e i#port date,ti#e,dateti#e fro# deci#al i#port 1eci#al fro# xl)t i#port Sor2$oo2,/tyle )$ ' Sor2$oo235 )s ' )$.add"sheet34:ype exa#ples45 )s.ro)305.)rite30,u4\xa*45 )s.ro)305.)rite31,4:ext45 )s.ro)315.)rite30,*.1;1<5 )s.ro)315.)rite31,1<5 )s.ro)315.)rite3 , !<95 )s.ro)315.)rite3*,1eci#al34*.!<455 )s.ro)3 5.set"cell"nu#$er30,*.1;1<5 )s.ro)3 5.set"cell"nu#$er31,1<5 )s.ro)3 5.set"cell"nu#$er3 , !<95 )s.ro)3 5.set"cell"nu#$er3*,1eci#al34*.!<455 )s.ro)3*5.)rite30,date3 00=,*,1>55 )s.ro)3*5.)rite31,dateti#e3 00=,*,1>,17,0,155 )s.ro)3*5.)rite3 ,ti#e317,155 )s.ro)3;5.set"cell"date30,date3 00=,*,1>55 )s.ro)3;5.set"cell"date31,dateti#e3 00=,*,1>,17,0,155 )s.ro)3;5.set"cell"date3 ,ti#e317,155 )s.ro)3<5.)rite30,Malse5 )s.ro)3<5.)rite31,:rue5 )s.ro)3!5.set"cell"$oolean30,Malse5 )s.ro)3!5.set"cell"$oolean31,:rue5 )s.ro)375.set"cell"error30,0x175 )s.ro)375.set"cell"error31,4T?@99J45 )s.ro)3>5.)rite3 0,44,/tyle.easyxf34pattern: pattern solid, fore"colour greenR455 )s.ro)3>5.)rite3 1,?one,/tyle.easyxf34pattern: pattern solid, fore"colour $lueR455 )s.ro)3=5.set"cell"$lan23 0,/tyle.easyxf34pattern: pattern solid, fore"colour yello)R455 )s.ro)3105.set"cell"#ul$lan2s3 <,10,/tyle.easyxf34pattern: pattern solid, fore"colour redR45 5 )$.sa(e34types.xls45 cell_types.py

Simplistix Ltd 2009

(a&e ".

&tyles
3ost elements of an 'xcel file can be formatted. 9or many elements incl din& cells, rows and col mns, this is done by assi&nin& a style, !nown as an B9 record, to that element. This is done by passin& an xlwt.B9Style instance to the optional last ar& ment to the vario s write methods and specialist set?cell? methods. xlwt.Jow and xlwt.Col mn instances have set?style methods to which an xlwt.B9Style instance can be passed. 2(&tyle 1n xlwt, the B9 record is represented by the B9Style class and its related attrib te classes. The followin& example shows how to create a red Date cell with 0rial text and a blac! border: fro# dateti#e i#port date fro# xl)t i#port Sor2$oo2, 8M/tyle, 7orders, Pattern, Mont fnt ' Mont35 fnt.na#e ' 4-rial4 $orders ' 7orders35 $orders.left ' 7orders.:GFCE $orders.right ' 7orders.:GFCE $orders.top ' 7orders.:GFCE $orders.$otto# ' 7orders.:GFCE pattern ' Pattern35 pattern.pattern ' Pattern./C9F1"P-::.0? pattern.pattern"fore"colour ' 0x0style ' 8M/tyle35 style.nu#"for#at"str'4DDDD-AA-114 style.font ' fnt style.$orders ' $orders style.pattern ' pattern $oo2 ' Sor2$oo235 sheet ' $oo2.add"sheet34- 1ate45 sheet.)rite31,1,date3 00=,*,1>5,style5 $oo2.sa(e34date.xls45 xfstyle_format.py This can be 8 ite c mbersomeK

Simplistix Ltd 2009

(a&e ">

easyxf Than!f lly, xl)t provides the easyxf helper to create 8M/tyle instances from h man readable text and an optional strin& containin& a n mber format. ;ere is the above example, this time created with easyxf: fro# dateti#e i#port date fro# xl)t i#port Sor2$oo2, easyxf $oo2 ' Sor2$oo235 sheet ' $oo2.add"sheet34- 1ate45 sheet.)rite31,1,date3 00=,*,1>5,easyxf3 4font: na#e -rialR4 4$orders: left thic2, right thic2, top thic2, $otto# thic2R4 4pattern: pattern solid, fore"colour redR4, nu#"for#at"str'4DDDD-AA-114 55 $oo2.sa(e34date.xls45 easyxf_format.py The h man readable text brea!s ro &hly as follows, in pse do)re& lar expression syntax: 3Uele#ent>:3Uattri$ute> U(alue>,5KR5K This means: The text contains a semi)colon delimited list of element definitions. 'ach element contains a comma)delimited list of attrib te and val e pairs.

The followin& sections describe each of the types of element by providin& a table of their attrib tes and possible val es for those attrib tes. 9or explanations of how to express boolean val es and colo rs, please see the CTypes of attrib teD section.

Simplistix Ltd 2009

(a&e "$

font bold charset 0 boolean val e. The defa lt is Malse. The character set to se for this font, which can be one of the followin&: ansi"latin, sys"default, sy#$ol, apple"ro#an, ansi"6ap"shift"6is, ansi"2or"hangul, ansi"2or"6oha$, ansi"chinese"g$2, ansi"chinese"$ig<, ansi"gree2, ansi"tur2ish, ansi"(ietna#ese, ansi"he$re), ansi"ara$ic, ansi"$altic, ansi"cyrillic, ansi"thai, ansi"latin"ii, oe#"latin"i The defa lt is sys"default. 0 colour specifyin& the colo r for the text. The defa lt is the auto#atic colo r. This can be one of none, superscript or su$script. The defa lt is none. This sho ld be a strin& containin& the name of the font family to se. Io probably want to se na#e instead of this attrib te and leave this to its defa lt val e. The defa lt is ?one. The hei&ht of the font as expressed by m ltiplyin& the point si%e by "#. The defa lt is "##, which e8 ates to /#pt. 0 boolean val e. The defa lt is Malse. This sho ld be a strin& containin& the name of the font family to se. The defa lt is -rial. 0 boolean val e. The defa lt is Malse. 0 boolean val e. The defa lt is Malse. 0 boolean val e. The defa lt is Malse. 0 boolean val e or one of none, single, single"acc, dou$le or dou$le"acc. The defa lt is none. 0 synonym for colour 0 synonym for colour 0 synonym for colour

colo r escapement family

hei&ht italic name o tline shadow str c!?o t nderline

color?index colo r?index color

Simplistix Ltd 2009

(a&e ,#

alignment direction hori%ontal 2ne of general, lr, or rl. The defa lt is general. 2ne of the followin&: general, left, centerVcentre, right, filled, 6ustified, centerVcentre"across"selection, distri$uted The defa lt is general. 0 indentation amo nt between # and /4. The defa lt is #. 0n inte&er rotation in de&rees between )$# and L$# or one of stac2ed or none. The defa lt is none. 0 boolean val e. The defa lt is Malse. 2ne of the followin&: top, centerVcentre, $otto#, 6ustified, distri$uted The defa lt is $otto#. 0 boolean val e. The defa lt is Malse. This is a synonym for direction. This is a synonym for horizontal. This is a synonym for horizontal. This is a synonym for indent. This is a synonym for rotation. This is a synonym for shrin2"to"fit. This is a synonym for shrin2"to"fit. This is a synonym for (ertical.

indent rotation

shrin!?to?fit vertical

wrap dire hori% hor% inde rota shri shrin! vert

Simplistix Ltd 2009

(a&e ,/

"or%ers left ri&ht top bottom dia& left?colo r ri&ht?colo r top?colo r 0 type of border line< 0 type of border line< 0 type of border line< 0 type of border line< 0 type of border line< 0 colour. The defa lt is the auto#atic colo r. 0 colour. The defa lt is the auto#atic colo r. 0 colour. The defa lt is the auto#atic colo r.

bottom?colo r 0 colour. The defa lt is the auto#atic colo r. dia&?colo r need?dia&?/ need?dia&?" left?color ri&ht?color top?color bottom?color 0 colour. The defa lt is the auto#atic colo r. 0 boolean val e. The defa lt is Malse. 0 boolean val e. The defa lt is Malse. 0 synonym for left"colour 0 synonym for right"colour 0 synonym for top"colour 0 synonym for $otto#"colour

dia&?color 0 synonym for diag"colour <This can be either an inte&er width between # and /, or one of the followin&: no"line, thin, #ediu#, dashed, dotted, thic2, dou$le, hair, #ediu#"dashed, thin"dash"dotted, #ediu#"dash"dotted, thin"dash"dot"dotted, #ediu#"dash"dot"dotted, slanted"#ediu#"dash"dotted

Simplistix Ltd 2009

(a&e ,"

pattern bac!?colo r fore?colo r pattern 0 colour. The defa lt is the auto#atic colo r. 0 colour. The defa lt is the auto#atic colo r. 2ne of the followin&: no"fill, none, solid, solid"fill, solid"pattern, fine"dots, alt"$ars, sparse"dots, thic2"horz"$ands, thic2"(ert"$ands, thic2"$ac2)ard"diag, thic2"for)ard"diag, $ig"spots, $ric2s, thin"horz"$ands, thin"(ert"$ands, thin"$ac2)ard"diag, thin"for)ard"diag, sWuares, dia#onds The defa lt is none. fore?color bac!?color pattern?fore?colo r pattern?fore?color pattern?bac!?color protection The protection feat res of the 'xcel file format are only partially implemented in xl)t. 0void them nless yo plan on finishin& their implementation. cell?loc!ed 0 boolean val e. The defa lt is :rue. 0 synonym for fore"colour 0 synonym for $ac2"colour 0 synonym for fore"colour 0 synonym for fore"colour 0 synonym for $ac2"colour

pattern?bac!?colo r 0 synonym for $ac2"colour

form la?hidden 0 boolean val e. The defa lt is Malse. align 0 synonym for align#ent "or%er 0 synonym for $orders !ypes of attri"ute Boolean val es are either Tr e or 9alse, b t easyxf allows &reat flexibility in how yo choose to express those two val es: :rue can be expressed by 1, yes, true or on Malse can be expressed by 0, no, false, or off

Simplistix Ltd 2009

(a&e ,,

Colours in 'xcel files are a conf sin& mess. The safest bet to do is 6 st pic! from the followin& list of colo r names that easyxf nderstands. The names sed are those reported by the 'xcel "##, MU1 when yo are inspectin& the default colo r palette. 5arnin&: There are many differences between this implicit mappin& from colo r)names to JMB val es and the mappin& sed in standards s ch as ;T3+ andCSS. a8 a blac! bl e bl e?&ray bri&ht?&reen brown coral cyan?e&a dar!?bl e dar!?bl e?e&a dar!?&reen dar!?&reen?e&a dar!?p rple dar!?red dar!?red?e&a dar!?teal dar!?yellow &old &ray?e&a &ray"4 &ray-# &ray4# &ray># &reen ice?bl e indi&o ivory lavender li&ht?bl e li&ht?&reen li&ht?oran&e li&ht?t r8 oise li&ht?yellow lime ma&enta?e&a ocean?bl e olive?e&a olive?&reen oran&e pale?bl e periwin!le pin! pl m p rple?e&a red rose sea?&reen silver?e&a s!y?bl e tan teal teal?e&a t r8 oise violet white yellow

=B: grey can be sed instead of gray wherever it occ rs above.

(ormatting 'ows an% Columns

1t is possible to specify defa lt formattin& for rows and col mns within a wor!sheet. This is done sin& the set"style method of the 0o) and Colu#n instances, respectively. The precedence of styles is as follows: the style applied to a cell the style applied to a row the style applied to a col mn

1t is also possible to hide whole rows and col mns by sin& the hidden attrib te of Jow and Col mn instances. The width of a Colu#n can be controlled by settin& its )idth attrib te to an inte&er where / is //"4: of the width of the %ero character, sin& the first font that occ rs in the 'xcel file. By defa lt, the hei&ht of a row is determined by the tallest font for that row and the height attrib te of the row is i&nored. 1f yo want the height attrib te to be sed, the row@s height"#is#atch attrib te needs to be set to 1.

Simplistix Ltd 2009

(a&e ,-

The followin& example shows these methods and properties in se alon& with the style precedence:

fro# xl)t i#port Sor2$oo2, easyxf fro# xl)t.@tils i#port ro)col"to"cell ro) ' easyxf34pattern: pattern solid, fore"colour $lue45 col ' easyxf34pattern: pattern solid, fore"colour green45 cell ' easyxf34pattern: pattern solid, fore"colour red45 $oo2 ' Sor2$oo235 sheet ' $oo2.add"sheet34Precedence45 for i in range30,10, 5: sheet.ro)3i5.set"style3ro)5 for i in range30,10, 5: sheet.col3i5.set"style3col5 for i in range3105: sheet.)rite3i,i,?one,cell5 sheet ' $oo2.add"sheet34Giding45 for ro)x in range3105: for colx in range3105: sheet.)rite3ro)x,colx,ro)col"to"cell3ro)x,colx55 for i in range30,10, 5: sheet.ro)3i5.hidden ' :rue sheet.col3i5.hidden ' :rue sheet ' $oo2.add"sheet340o) height and Colu#n )idth45 for i in range3105: sheet.)rite30,i,05 for i in range3105: sheet.ro)3i5.set"style3easyxf34font:height 4Kstr3 00Bi555 sheet.col3i5.)idth ' <!Bi $oo2.sa(e34for#at"ro)scols.xls45 format_rowscols.py

(ormatting &heets an% Work"ooks

There are many possible settin&s that can be made on Sheets and 5or!boo!s. 3ost of them yo will never need or want to to ch. 1f yo thin! yo do, see the C2ther (ropertiesD section below.

Simplistix Ltd 2009

(a&e ,4

&tyle compression
5hile its fine to create as many B9Style and their associated 9ont instances as yo li!e, each one written to 5or!boo! will res lt in an B9 record and a 9ont record. 'xcel has fixed limits of aro nd -## 9onts and -### B9 records so care needs to be ta!en when &eneratin& lar&e 'xcel files. To help with this, xl)t.Sor2$oo2 has an optional style"co#pression parameter with the followin& meanin&: # N no compression. This is the defa lt. / N compress 9onts only. =ot very sef l. " N compress 9onts and B9 records.

The followin& example demonstrates these three options: fro# xl)t i#port Sor2$oo2, easyxf style1 ' easyxf34font: na#e :i#es ?e) 0o#an45 style ' easyxf34font: na#e :i#es ?e) 0o#an45 style* ' easyxf34font: na#e :i#es ?e) 0o#an45 def )rite"cells3$oo25: sheet ' $oo2.add"sheet34Content45 sheet.)rite30,0,4-14,style15 sheet.)rite30,1,4714,style 5 sheet.)rite30, ,4C14,style*5 $oo2 ' Sor2$oo235 )rite"cells3$oo25 $oo2.sa(e34*xf*fonts.xls45 $oo2 ' Sor2$oo23style"co#pression'15 )rite"cells3$oo25 $oo2.sa(e34*xf1font.xls45 $oo2 ' Sor2$oo23style"co#pression' 5 )rite"cells3$oo25 $oo2.sa(e341xf1font.xls45 stylecompression.py Be aware that doin& this compression involves deeply nested comparison of the B9Style ob6ects, so may slow down writin& of lar&e files where many styles are sed. The recommended best practice is to create all the styles yo will need in advance and leave style"co#pression at its defa lt val e.

Simplistix Ltd 2009

(a&e ,:

(ormulae
9orm lae can be written by xl)t by passin& an xl)t.Mor#ula instance to either of the write methods or by sin& the set"cell"for#ula method of 0o) instances, b &s allowin&. The followin& are s pported: all the b ilt)in 'xcel form la f nctions references to other sheets in the same wor!boo! access to all the add)in f nctions in the 0nalysis Toolpa! F0T(G comma or semicolon as the ar& ment separator in f nction calls case)insensitive matchin& of form la names references to external wor!boo!s array a!a Ctrl)Shift)'nter a!a CS' form las references to defined =ames sin& form las for data validation or conditional formattin& eval ation of form lae

The followin& are not s ppoted:

The followin& example shows some of these thin&s in action:

fro# xl)t i#port Sor2$oo2, Mor#ula $oo2 ' Sor2$oo235 sheet1 ' $oo2.add"sheet34/heet 145 sheet1.)rite30,0,105 sheet1.)rite30,1, 05 sheet1.)rite31,0,Mor#ula34-1+71455 sheet ' $oo2.add"sheet34/heet 45 ro) ' sheet .ro)305 ro).)rite30,Mor#ula34su#31, ,*5455 ro).)rite31,Mor#ula34/uA31R R*5455 ro).)rite3 ,Mor#ula3O$-$1K$7$1B/@A34/h..t 14J$-$1:$$$ 5O55 $oo2.sa(e34for#ula.xls45 formulae.py

*ames
=ames cannot c rrently be written by xl)t.

Simplistix Ltd 2009

(a&e ,.

-tility metho%s
The Utils mod le of xlwt contains several sef l tility f nctions: col3"y3name This will convert a strin& containin& a col mn identifier into an inte&er col mn index. cell3to3rowcol This will convert a strin& containin& an excel cell reference into a fo r)element t ple containin&: 3ro),col,ro)"a$s,col"a$s5 ro) N inte&er row index of the referenced cell col N inte&er col mn index of the referenced cell ro)"a$s N boolean indicatin& whether the row index is absol te FTr eG or relative F9alseG col"a$s N boolean indicatin& whether the col mn index is absol te FTr eG or relative F9alseG cell3to3rowcol2 This will convert a strin& containin& an excel cell reference into a two)element t ple containin&: 3ro),col5 ro) N inte&er row index of the referenced cell col N inte&er col mn index of the referenced cell rowcol3to3cell This will covert an inte&er row and col mn index into a strin& excel cell reference, with either index optionally bein& absol te. cellrange3to3rowcol3pair This will convert a strin& containin& an excel ran&e into a fo r)element t ple containin&: 3ro)1,col1,ro) ,col 5 ro)1 N inte&er row index of the start of the ran&e col1 N inte&er col mn index of the start of the ran&e ro) N inte&er row index of the end of the ran&e col N inte&er col mn index of the end of the ran&e rowcol3pair3to3cellrange This will covert a pair of inte&er row and col mn indexes into a strin& containin& an excel cell ran&e. 0ny of the indexes specified can optionally be made to be absol te. +ali%3sheet3name This f nction ta!es a sin&le strin& ar& ment and ret rns a boolean val e indication whether the sheet name will wor! witho t problems FTr eG or will ca se complaints from 'xcel F9alseG.

Simplistix Ltd 2009

(a&e ,>

The followin& example shows all of these f nctions in se:

fro# xl)t i#port @tils print 4-- ->4,@tils.col"$y"na#e34--45 print 4- ->4,@tils.col"$y"na#e34-45 print 4-1 ->4,@tils.cell"to"ro)col34-145 print 4$-$1 ->4,@tils.cell"to"ro)col34$-$145 print 4-1 ->4,@tils.cell"to"ro)col 34-145 print print print print print 30,05,4->4,@tils.ro)col"to"cell30,05 30,0,Malse,:rue5,4->4, @tils.ro)col"to"cell30,0,Malse,:rue5 30,0,:rue,:rue5,4->4, @tils.ro)col"to"cell3 ro)'0,col'0,ro)"a$s':rue,col"a$s':rue 5 41:* ->4,@tils.cellrange"to"ro)col"pair341:*45 47:P ->4,@tils.cellrange"to"ro)col"pair347:P45 4- :77 ->4,@tils.cellrange"to"ro)col"pair34- :7745 4-1 ->4,@tils.cellrange"to"ro)col"pair34-145 30,0,100,1005,4->4, @tils.ro)col"pair"to"cellrange30,0,100,1005 30,0,100,100,:rue,Malse,Malse,Malse5,4->4, @tils.ro)col"pair"to"cellrange3 ro)1'0,col1'0,ro) '100,col '100, ro)1"a$s':rue,col1"a$s'Malse, ro) "a$s'Malse,col "a$s':rue 5

print print print print print print print print

for na#e in 3 44,O4Wuoted4O,OC4hareO,O8OB* ,O%&:\\X+B\x00O 5: print 4Fs Yr a (alid sheet na#eX4 Y na#e, if @tils.(alid"sheet"na#e3na#e5: print ODesO else: print O?oO utilities.py

Simplistix Ltd 2009

(a&e ,$

)ther properties
There are many other properties that yo can set on xlwt)related ob6ects. They are all listed below, for each of the types of ob6ect. The names are mostly int itive b t yo are warned to experiment thoro &hly before attemptin& to se any of these in an important sit ation as some properties exist that aren@t saved to the res ltin& 'xcel files and some others are only partially implemented. xlwt0Work"ook o)ner country"code )nd"protect o$6"protect protect $ac2up"on"sa(e hpos xlwt0'ow set"style height has"default"height xlwt0Column set"style )idth"in"pixels )idth hidden le(el collapse height"#is#atch le(el collapse hidden space"a$o(e space"$elo) (pos )idth height acti(e"sheet ta$")idth )nd"(isi$le )nd"#ini hscroll"(isi$le (scroll"(isi$le ta$s"(isi$le dates"1=0; use"cell"(alues

Simplistix Ltd 2009

(a&e -#

xlwt0Worksheet na#e (isi$ility ro)"default"height"#is#atch ro)"default"hidden ro)"default"space"a$o(e ro)"default"space"$elo) sho)"for#ulas sho)"grid sho)"headers sho)"zero"(alues auto"colour"grid cols"right"to"left sho)"outline re#o(e"splits selected sheet"(isi$le page"pre(ie) first"(isi$le"ro) first"(isi$le"col grid"colour dialog"sheet auto"style"outline outline"$elo) outline"right fit"nu#"pages sho)"ro)"outline sho)"col"outline alt"expr"e(al alt"for#ula"entries ro)"default"height col"default"height calc"#ode calc"count 0C"ref"#ode iterations"on delta
Simplistix Ltd 2009

sa(e"recalc print"headers print"grid header"str footer"str print"centered"(ert print"centered"horz left"#argin right"#argin top"#argin $otto#"#argin paper"size"code print"scaling start"page"nu#$er fit")idth"to"pages fit"height"to"pages print"in"ro)s portrait print"colour print"draft print"notes print"notes"at"end print"o#it"errors print"hres header"#argin footer"#argin copies"nu# )nd"protect o$6"protect protect scen"protect pass)ord

(a&e -/

&ome examples of )ther Properties

The followin& sections contain examples of how to se some of the properties listed above. 4yperlinks ;yperlin!s are a type of form la as shown in the followin& example: fro# xl)t i#port Sor2$oo2,easyxf,Mor#ula style ' easyxf34font: underline single45 $oo2 ' Sor2$oo235 sheet ' $oo2.add"sheet34Gyperlin2s45 sheet.)rite3 0, 0, Mor#ula34GDP.09F?E3Ohttp:++))).python.orgOROPythonO545, style5 lin2 ' 4GDP.09F?E3O#ailto:pythonexcelZgooglegroups.co#OROhelpO54 sheet.)rite3 1,0, Mor#ula3lin25, style5 $oo2.sa(e3Ohyperlin2s.xlsO5 hyperlinks.py $mages 1ma&es can be inserted sin& the insert"$it#ap method of the /heet class: fro# xl)t i#port Sor2$oo2 ) ' Sor2$oo235 )s ' ).add"sheet34F#age45 )s.insert"$it#ap34python.$#p4, 0, 05 ).sa(e34i#ages.xls45 images.py =B: 1ma&es are not displayed by 2pen2ffice.or&

Simplistix Ltd 2009

(a&e -"

Merge% cells 3er&ed &ro ps of cells can be inserted sin& the )rite"#erge method of the /heet class: fro# xl)t i#port Sor2$oo2,easyxf style ' easyxf3 4pattern: pattern solid, fore"colour redR4 4align: (ertical center, horizontal centerR4 5 ) ' Sor2$oo235 )s ' ).add"sheet34Aerged45 )s.)rite"#erge31,<,1,<,4Aerged4,style5 ).sa(e34#erged.xls45 merged.py or%ers 5ritin& a sin&le cell with borders is simple eno &h, however applyin& a border to a &ro p of cells is painf l as shown in this example: fro# xl)t i#port Sor2$oo2,easyxf tl ' easyxf34$order: left thic2, top thic245 t ' easyxf34$order: top thic245 tr ' easyxf34$order: right thic2, top thic245 r ' easyxf34$order: right thic245 $r ' easyxf34$order: right thic2, $otto# thic245 $ ' easyxf34$order: $otto# thic245 $l ' easyxf34$order: left thic2, $otto# thic245 l ' easyxf34$order: left thic245 ) ' Sor2$oo235 )s ' ).add"sheet347order45 )s.)rite31,1,style'tl5 )s.)rite31, ,style't5 )s.)rite31,*,style'tr5 )s.)rite3 ,*,style'r5 )s.)rite3*,*,style'$r5 )s.)rite3*, ,style'$5 )s.)rite3*,1,style'$l5 )s.)rite3 ,1,style'l5 ).sa(e34$orders.xls45 borders.py =B: 'xtra care needs to be ta!en if yo @re pdatin& an existin& 'xcel fileK

Simplistix Ltd 2009

(a&e -,

&plit an% (ree5e panes 1t is fairly strai&ht forward to create fro%en panes sin& xl)t. The location of the split is specified sin& the inte&er (ert"split"pos and horz"split"pos properties of the /heet class. The first visible cells are specified sin& the inte&er (ert"split"first"(isi$le and horz"split"first"(isi$le properties of the Sheet class. The followin& example shows them all in action: fro# xl)t i#port Sor2$oo2 fro# xl)t.@tils i#port ro)col"to"cell ) ' Sor2$oo235 sheet ' ).add"sheet34Mreeze45 sheet.panes"frozen ' :rue sheet.re#o(e"splits ' :rue sheet.(ert"split"pos ' sheet.horz"split"pos ' 10 sheet.(ert"split"first"(isi$le ' < sheet.horz"split"first"(isi$le ' ;0 for col in range3 05: for ro) in range3>05: sheet.)rite3ro),col,ro)col"to"cell3ro),col55 ).sa(e34panes.xls45 panes.py Split panes are a less fre8 ently sed feat re and their s pport is less complete in xl)t. The proced re for creatin& split panes is exactly the same as for fro%en panes except that the panes"frozen attrib te of the 5or!sheet sho ld be set to Malse instead of :rue. ;owever, if yo really need split panes, yo @re advised to see professional help before proceedin&K

Simplistix Ltd 2009

(a&e --

)utlines These are a little !nown and little sed feat re of the 'xcel file format that can be very sef l when dealin& with cate&orised data. Their se is best shown by example: fro# xl)t i#port Sor2$oo2 data ' % %44,44,4 00>4,44,4 00=4&, %44,44,4[an4,4Me$4,4[an4,4Me$4&, %4Co#pany 84&, %44,41i(ision -4&, %44,44,100, 00,*00,;00&, %44,41i(ision 74&, %44,44,100,==,=>,<0&, %4Co#pany D4&, %44,41i(ision -4&, %44,44,100,100,100,100&, %44,41i(ision 74&, %44,44,100,101,10 ,10*&, & ) ' Sor2$oo235 )s ' ).add"sheet34Cutlines45 for i,ro) in enu#erate3data5: for 6,cell in enu#erate3ro)5: )s.)rite3i,6,cell5 )s.ro)3 5.le(el ' 1 )s.ro)3*5.le(el ' )s.ro)3;5.le(el ' * )s.ro)3<5.le(el ' )s.ro)3!5.le(el ' * )s.ro)375.le(el ' 1 )s.ro)3>5.le(el ' )s.ro)3=5.le(el ' * )s.ro)3105.le(el ' )s.ro)3115.le(el ' * )s.col3 5.le(el ' 1 )s.col3*5.le(el ' )s.col3;5.le(el ' 1 )s.col3<5.le(el ' ).sa(e34outlines.xls45 outlines.py

Simplistix Ltd 2009

(a&e -4

6oom magnification an% Page

reak Pre+iew

The %oom percenta&e sed when viewin& a sheet in normal mode can be controlled by settin& the normal?ma&n attrib te of a Sheet instance. The %oom percenta&e sed when viewin& a sheet in pa&e brea! preview mode can be controlled by settin& the preview?ma&n attrib te of a Sheet instance. 0 Sheet can also be made to show a pa&e brea! preview by settin& the pa&e?preview attrib te of the Sheet instance to Tr e. ;ere@s an example to show all three in action: fro# xl)t i#port Sor2$oo2 ) ' Sor2$oo235 )s ' ).add"sheet34?or#al45 )s.)rite30,0,4/o#e text45 )s.nor#al"#agn ' 7< )s ' ).add"sheet34Page 7rea2 Pre(ie)45 )s.)rite30,0,4/o#e text45 )s.pre(ie)"#agn ' 1<0 )s.page"pre(ie) ' :rue ).sa(e34zoo#.xls45 zoom.py

Simplistix Ltd 2009

(a&e -:

(iltering Excel (iles

0ny examples shown below can be fo nd in the xlutils directory of the co rse material.

)ther utilities in xlutils

The xlutils pac!a&e contains several tilities in addition to those for filterin&. The followin& are often sef l: xlutils0styles This mod le contains one class which, when instantiated with an xlrd.Sor2$oo2, will let yo discover the style name and information from a &iven cell in that wor!boo! as shown in the followin& example: fro# xlrd i#port open")or2$oo2 fro# xlutils.styles i#port /tyles $oo2 ' open")or2$oo234source.xls4,for#atting"info':rue5 styles ' /tyles3$oo25 sheet ' $oo2.sheet"$y"index305 print styles%sheet.cell31,15&.na#e print styles%sheet.cell31, 5&.na#e -1"style ' styles%sheet.cell30,05& -1"font ' $oo2.font"list%-1"style.xf.font"index& print $oo2.colour"#ap%-1"font.colour"index& styles.py =B: 9or obvio s reasons, open")or2$oo2 m st be called with for#atting"info':rue in order to se xlutils.styles. 9 ll doc mentation and examples can be fo nd in the styles.txt file in the docs folder of xlutils@ so rce distrib tion.

Simplistix Ltd 2009

(a&e -.

xlutils0%isplay This mod le contains tility f nctions for easy and safe display of information ret rned by xlrd. Wuoted"sheet"na#e is called with the na#e attrib te of an xlrd.sheet./heet instance and will ret rn an encoded strin& containin& a 8 oted version of the sheet@s name. cell"display is called with an xlrd.sheet.Cell instance and ret rns an encoded strin& containin& a sensible representation of the cells contents, even for Date and 'rror cells. 1f a date cell is to be displayed, cell"display must be called with the date#ode attrib te of the xlrd.7oo2 from which the cell came. The followin& examples show both f nctions in action: fro# xlrd i#port open")or2$oo2 fro# xlutils.display i#port Wuoted"sheet"na#e fro# xlutils.display i#port cell"display )$ ' open")or2$oo234source.xls45 print print print print Wuoted"sheet"na#e3)$.sheet"na#es35%0&5 repr3Wuoted"sheet"na#e3u4Price3\xa*54,4utf->455 Wuoted"sheet"na#e3u4Ay /heet45 Wuoted"sheet"na#e3uO[ohn4s /heetO5

sheet ' )$.sheet"$y"index305 print cell"display3sheet.cell31,155 print cell"display3sheet.cell31,*5,)$.date#ode5 display.py 9 ll doc mentation and examples can be fo nd in the display.txt file in the docs folder of xl tils@ so rce distrib tion.

Simplistix Ltd 2009

(a&e ->

xlutils0copy This mod le contains one f nction that will ta!e an xlrd.7oo2 and ret rns an xl)t.Sor2$oo2 pop lated with the data and formattin& fo nd in the xlrd.7oo2. This is extremely sef l for pdatin& an existin& spreadsheet as the followin& example shows: fro# xlrd i#port open")or2$oo2 fro# xl)t i#port easyxf fro# xlutils.copy i#port copy r$ rs )$ )s ' ' ' ' open")or2$oo234source.xls4,for#atting"info':rue5 r$.sheet"$y"index305 copy3r$5 )$.get"sheet305

plain ' easyxf3445 for i,cell in enu#erate3rs.col3 55: if not i: continue )s.)rite3i, ,cell.(alue,plain5 for i,cell in enu#erate3rs.col3;55: if not i: continue )s.)rite3i,;,cell.(alue-10005 )$.sa(e34output.xls45 copy.py 1t is important to note that some thin&s won@t be copied: 9orm lae =ames anythin& i&nored by xlrd

1n addition to the mod les described above, there are also xlutils.#argins and xlutils.sa(e, b t these are only sef l in certain sit ations. Jefer to their doc mentation in the xlutils so rce distrib tion.

Simplistix Ltd 2009

(a&e -$

&tructure of xlutils0filter
This framewor! is desi&ned to filter and split 'xcel files sin& a series of mod lar readers, filters and writers as shown in the dia&ram below:

process Reader Filter 1 Filter 2 Writer

The flow of information between the components is by method calls on the next component in the chain. The possible method calls are listed in the table below, where rd$oo2 is an xlrd.7oo2 instance, rdsheet is an xlrd.sheet./heet instance, rdro)x, rdcolx, )tro)x and )tcolx and inte&er indexes specifyin& the cell to read from and write to, )t$oo2"na#e is a strin& specifyin& the name of the 'xcel file to write to and )tsheet"na#e is a unicode specifyin& the name of the sheet to write to: startFG This method is called before processin& of a batch of inp t. 1t can be called at any time. 2ne common se is to reset all the filters in a chain in the event of an error d rin& the processin& of an rdboo!. This method is called every time processin& of a new wor!boo! starts This method is called every time processin& of a new sheet in the c rrent wor!boo! starts This method is called to indicate a chan&e for the so rce of cells mid)way thro &h writin& a sheet. The row method is called every time processin& of a new row in the c rrent sheet starts.

wor!boo!Frdboo!,wtboo!?nameG sheetFrdsheet,wtsheet?nameG set?rdsheetFrdsheetG rowFrdrowx,wtrowxG

cellFrdrowx,rdcolx,wtrowx,wtcolxG This is called for every cell in the sheet bein& processed. This is the most common method in which filterin& and 8 e in& of onward calls to the next component ta!es place. finish This method is called once processin& of all wor!boo!s has been completed.

Simplistix Ltd 2009

(a&e 4#

'ea%ers 0 reader@s 6ob is to obtain one or more xlrd.7oo2 ob6ects and iterate over those ob6ects iss in& appropriate calls to the next component in the chain. The order of callin& is expected to be as follows: start )or2$oo2, once for each xlrd.7oo2 ob6ect obtained sheet, once for each sheet fo nd in the c rrent boo! set"rdsheet, whenever the sheet from which cells to be read needs to be chan&ed. This method may not be called between calls to ro) and cell, and between m ltiple calls to cell. 1t may only be called once all cell calls for a row have been made. ro), once for each row in the c rrent sheet cell, once for each cell in the row finish, once all xlrd.7oo2 ob6ects have been processed )t$oo2"na#e sho ld be the filename of the file the xlrd.7oo2 ob6ect ori&inated from. )tsheet"na#e sho ld be rd$oo2.na#e )tro)x sho ld be e8 al to rdro)x rdcolx sho ld be e8 al to )tcolx 0lso, for method calls made by a reader, the followin& sho ld be tr e:

Beca se of these restrictions, an xlutils.filter.7ase0eader class is provided that will normally only need to have one of two methods overridden to &et any re8 ired f nctionality: get"filepaths N if implemented, this m st ret rn an iterable se8 ence of paths to excel files that can be opened with python@s b iltin file. get")or2$oo2s N if implemented, this m st ret rn an se8 ence of ")t ples. 'ach t ple m st contain an xlrd.7oo2 ob6ect followed by a strin& containin& the filename of the file from which the xlrd.7oo2 ob6ect was loaded.

Simplistix Ltd 2009

(a&e 4/

(ilters 1mplementin& these components is where the b l! of the wor! will be done by sers of the xlutils.filter framewor!. 0 9ilter@s responsibilities are to accept method calls from the precedin& component in the chain, do any processin& necessary and then emit appropriate method calls to the next component in the chain. There is very little constraint on what order 9ilters receive and emit method calls other than that the order of method calls emitted m st remain consistent with the str ct re &iven above. This enables components to be freely interchan&ed more easily. Beca se 9ilters may only need to implement few of the f ll set of method calls, an xlutils.filter.7aseMilter is provided that does nothin& b t pass the method calls on to the next component in the chain. The implementation of this filter is sef l to see when embar!in& on 9ilter implementation: class 7aseMilter: def start3self5: self.next.start35 def )or2$oo23self,rd$oo2,)t$oo2"na#e5: self.next.)or2$oo23rd$oo2,)t$oo2"na#e5 def sheet3self,rdsheet,)tsheet"na#e5: self.rdsheet ' rdsheet self.next.sheet3rdsheet,)tsheet"na#e5 def set"rdsheet3self,rdsheet5: self.rdsheet ' rdsheet self.next.set"rdsheet3rdsheet5 def ro)3self,rdro)x,)tro)x5: self.next.ro)3rdro)x,)tro)x5 def cell3self,rdro)x,rdcolx,)tro)x,)tcolx5: self.next.cell3rdro)x,rdcolx,)tro)x,)tcolx5 def finish3self5: self.next.finish35

Simplistix Ltd 2009

(a&e 4"

Writers These components do the &r nt wor! of act ally copyin& the appropriate information from the rd$oo2 and serialisin& it into an 'xcel file. This is a complicated process and not for the feint of hard to re)implement. 9or this reason, an xlutils.filter.7aseSriter component is provided that does all of the hard wor! and has one method that needs to be implemented. That method is get"strea# and it is called with the filename of the 'xcel file to be written. 1mplementations of this method are expected to ret rn a new file)li!e ob6ect that has a )rite and, by defa lt, a close method each time they are called. S bclasses may also override the boolean close"after")rite attrib te, which is :rue by defa lt, to indicate that the file)li!e ob6ects ret rned from get"strea# sho ld not have their close method called once serialisation of the 'xcel file data is complete. 1t is important to note that some thin&s won@t be copied from the rd$oo2 by 7aseSriter: 9orm lae =ames anythin& i&nored by xlrd

Process The process f nction is responsible for ta!in& a series of components as its ar& ments. The first of these sho ld be a Jeader. The last of these sho ld be a 5riter. The rest sho ld be the necessary 9ilters in the order of processin& re8 ired. The process method will wire these components to&ether by way of their next attrib tes and then !ic! the process off by callin& the Jeader and passin& the first 9ilter in the chain as its ar& ment.

Simplistix Ltd 2009

(a&e 4,

1 worke% example
S ppose we want to filter an existin& 'xcel file to omit rows that have an B in the first col mn. The followin& example shows possible components to do this and shows how they wo ld be instantiated and called to achieve this: i#port os fro# xlutils.filter i#port \ 7ase0eader,7aseMilter,7aseSriter,process class 0eader37ase0eader5: def get"filepaths3self5: return %os.path.a$spath34source.xls45& class Sriter37aseSriter5: def get"strea#3self,filena#e5: return file3filena#e,4)$45 class Milter37aseMilter5: pending"ro) ' ?one )tro)xi ' 0 def )or2$oo23self,rd$oo2,)t$oo2"na#e5: self.next.)or2$oo23rd$oo2,4filtered-4K)t$oo2"na#e5 def ro)3self,rdro)x,)tro)x5: self.pending"ro) ' 3rdro)x,)tro)x5 def cell3self,rdro)x,rdcolx,)tro)x,)tcolx5: if rdcolx''0: (alue ' self.rdsheet.cell3rdro)x,rdcolx5.(alue if (alue.strip35.lo)er35''4x4: self.ignore"ro) ' :rue self.)tro)xi -' 1 else: self.ignore"ro) ' Malse rdro)x, )tro)x ' self.pending"ro) self.next.ro)3rdro)x,)tro)xKself.)tro)xi5 elif not self.ignore"ro): self.next.cell3 rdro)x,rdcolx,)tro)xKself.)tro)xi,)tcolx-1 5 process30eader35,Milter35,Sriter355 filter.py 1n reality, we wo ld not need to implement the Jeader and 5riter components, as there are already s itable components incl ded.

Simplistix Ltd 2009

(a&e 4-

Existing components
The xl tils.filter framewor! comes with a wide ran&e of existin& components, each of which is briefly described below. 9or f ll descriptions and wor!ed examples of all these components, please see filter.txt in the docs folder of the xlutils so rce distrib tion. ,lo"'ea%er 1f yo @re processin& files that are on dis!, then this is probably the reader for yo . 1t ret rns all files matchin& the path specification it@s instantiated with. 2#'.'ea%er This reader can be sed at the start of a chain when yo already have an xlrd.7oo2 ob6ect and yo @ll loo!in& to process it with xlutils.filter. !est'ea%er This reader is specifically desi&ned for testin& filterimplementations with !nown sets of cells. .irectoryWriter 1f yo want files yo @re processin& to end p on dis!, then this is probably the writer for yo . 1t stores files in the directory it is instantiated with. &treamWriter 1f yo want to write exactly one wor!boo! to a stream, s ch as a te#pfile.:e#poraryMile or sys.stdout, then this is the writer for yo . 2#W!Writer 1f yo want to chan&e cells after the filterin& process is complete then this writer can be sed to obtain the xl)t.Sor2$oo2 ob6ects that Base5riter &enerates. Column!rimmer This filter will strip col mns containin& no sef l data from the end of sheets. The definition of Cno sef l dataD can be controlled d rin& instantiation of this filter. Error(ilter This filter caches all method calls in a file on dis! and will only pass them on the next component in the chain when its finish method has been called and no error messa&es have been lo&&ed to the python lo&&in& framewor!. 1f Boolean or error Cells are enco ntered, an error messa&e will be lo&&ed to the python lo&&in& framewor! will will also s ally mean that no methods will be emitted from this component to the next component in the chain. 9inally, cell method calls correspondin& to 'mpty cells in rdsheet will not be passed on to the next component in the chain. Callin& this component@s start method will reset it. Echo This filter will print calls to the methods confi& red when the filter is instantiated alon& with the ar& ments passed.

Simplistix Ltd 2009

(a&e 44

Memory#ogger This filter will d mp stats to the path it was confi& red with sin& the heapy pac!a&e if it is available. 1f it is not available, no operations are performed. 9or more information on heapy, please see http://& ppy)pe.so rcefor&e.net/O;eapy

Simplistix Ltd 2009

(a&e 4:

Possi"le !asks for Workshop

The followin& is a list of tas!s that can be attempted by any attendee who hasn@t bro &ht their own tas!s to attempt. $nstallation with $ronPython The libraries have been sed s ccessf lly with 1ron(ython, b t this has not been thoro &hly tests or doc mented. $nstallation with Jython The libraries sho ld all wor! with Aython, b t no one has so far attempted to do so. $nserting a row into a sheet Startin& with an existin& 'xcel file, attempt to create a new 'xcel file with a row inserted at a &iven position. &plitting a ook into its &heets Startin& with an existin& 'xcel file, create a directory containin& one file for each wor!sheet in the ori&inal file. 'eporting errors in a %irectory full on Excel files Scan a directory of 'xcel files and report the location of any error cells. 0 pro&ression of this tas! is to allow the passin& of options to indicate what types of error to report. 'emo+ing 'ows containing errors Startin& with an existin& 'xcel file, create a filterin& process that &enerates a new 'xcel file that excl des any rows containin& error cells. 0 pro&ression of this tas! is to &enerate a new 'xcel file that contains empty cells where there were errors in the ori&inal file. (iltering Excel files to an% from a we" ser+er This tas! is to create components for xl tils.filter that can read from a website and write bac! to that website. The tas! sho ld res lt in an ;TT(Jeader and an ;TT(5riter. Pro%ucing a report from a %ata"ase This tas! is to ta!e a typical database 8 ery and d mp it into an 'xcel file s ch that the headin& row is set p nicely with decent ali&nment in a fro%en pane. 0s a prec rsor to this tas!, yo may need to set p a typical databaseK

Simplistix Ltd 2009